Action: DISTANCE_MATRIX

Module	adjmat
Description	Usage
Calculate a matrix of distances between atoms.
output value	type
a matrix containing the weights for the bonds between each pair of atoms	matrix

Output components

This action can calculate the values in the following table when the associated keyword is included in the input for the action. These values can be referenced elsewhere in the input by using this Action's label followed by a dot and the name of the value required from the list below.

Name	Type	Keyword	Description
w	matrix	COMPONENTS	a matrix containing the weights for the bonds between each pair of atoms
x	matrix	COMPONENTS	the projection of the bond on the x axis
y	matrix	COMPONENTS	the projection of the bond on the y axis
z	matrix	COMPONENTS	the projection of the bond on the z axis

Input

The atoms that serve as the input for this action are specified using one or more of the keywords in the following table.

Keyword	Type	Description
GROUP	atoms	the atoms for which you would like to calculate the adjacency matrix
GROUPA	atoms	when you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPB
GROUPB	atoms	when you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPA
ATOMS	atoms	the atoms for which you would like to calculate the adjacency matrix

Further details and examples

Calculate a matrix of distances between atoms.

To calculate the matrix of distances between every distinct pair of atoms in a single group you can use the following command:

Click on the labels of the actions for more information on what each action computes

d1The DISTANCE_MATRIX action with label d1 calculates the following quantities: Quantity    Type    Description  
d1 matrix a matrix containing the weights for the bonds between each pair of atoms: DISTANCE_MATRIXCalculate a matrix of distances between atoms. This action has hidden defaults. More details GROUPthe atoms for which you would like to calculate the adjacency matrix=1-7
d1: DISTANCE_MATRIXCalculate a matrix of distances between atoms. This action uses the defaults shown here. More details GROUPthe atoms for which you would like to calculate the adjacency matrix=1-7  NL_CUTOFF The cutoff for the neighbor list=0.0 NL_STRIDE The frequency with which we are updating the atoms in the neighbor list=1 CUTOFF ignore distances that have a value larger than this cutoff=-1

If you would like to calculate the matrix of distances between the atoms in two different groups of atoms you can use the following command:

Click on the labels of the actions for more information on what each action computes

d2The DISTANCE_MATRIX action with label d2 calculates the following quantities: Quantity    Type    Description  
d2 matrix a matrix containing the weights for the bonds between each pair of atoms: DISTANCE_MATRIXCalculate a matrix of distances between atoms. This action has hidden defaults. More details GROUPAwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPB=1-7 GROUPBwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPA=8-20
d2: DISTANCE_MATRIXCalculate a matrix of distances between atoms. This action uses the defaults shown here. More details GROUPAwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPB=1-7 GROUPBwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPA=8-20  NL_CUTOFF The cutoff for the neighbor list=0.0 NL_STRIDE The frequency with which we are updating the atoms in the neighbor list=1 CUTOFF ignore distances that have a value larger than this cutoff=-1

Once you have calculated your distance matrix in this way you can do many of the operations that were discussed for CONTACT_MATRIX with the output. For example, you can use the COMPONENTS flag to calcuate the $x$ , $y$ and $z$ components of the vectors connecting the atoms in your two groups by using an input like that shown below:

Click on the labels of the actions for more information on what each action computes

d1The DISTANCE_MATRIX action with label d1 calculates the following quantities: Quantity    Type    Description  
d1.w matrix a matrix containing the weights for the bonds between each pair of atoms
d1.x matrix the projection of the bond on the x axis
d1.y matrix the projection of the bond on the y axis
d1.z matrix the projection of the bond on the z axis: DISTANCE_MATRIXCalculate a matrix of distances between atoms. This action has hidden defaults. More details GROUPthe atoms for which you would like to calculate the adjacency matrix=1-7 COMPONENTS also calculate the components of the vectors connecting the atoms in the contact matrix
d1: DISTANCE_MATRIXCalculate a matrix of distances between atoms. This action uses the defaults shown here. More details GROUPthe atoms for which you would like to calculate the adjacency matrix=1-7 COMPONENTS also calculate the components of the vectors connecting the atoms in the contact matrix  NL_CUTOFF The cutoff for the neighbor list=0.0 NL_STRIDE The frequency with which we are updating the atoms in the neighbor list=1 CUTOFF ignore distances that have a value larger than this cutoff=-1

Optimisation details

If for some reaon, you only want to calculate the distances if they are less than a certain CUTOFF you can add the cutoff keyword as follows:

Click on the labels of the actions for more information on what each action computes

d3The DISTANCE_MATRIX action with label d3 calculates the following quantities: Quantity    Type    Description  
d3 matrix a matrix containing the weights for the bonds between each pair of atoms: DISTANCE_MATRIXCalculate a matrix of distances between atoms. This action has hidden defaults. More details GROUPthe atoms for which you would like to calculate the adjacency matrix=1-7 CUTOFF ignore distances that have a value larger than this cutoff=1.0
d3: DISTANCE_MATRIXCalculate a matrix of distances between atoms. This action uses the defaults shown here. More details GROUPthe atoms for which you would like to calculate the adjacency matrix=1-7 CUTOFF ignore distances that have a value larger than this cutoff=1.0  NL_CUTOFF The cutoff for the neighbor list=0.0 NL_STRIDE The frequency with which we are updating the atoms in the neighbor list=1

This command will only store those distances that are less than 1 nm. Notice, however, that the cutoff implemented here is not a continuous function. You should thus be careful when commands such as this one above to ensure that any quantities that are forced have continuous derivatives. If you use the CUTOFF keyword, however, many of the features that are used to optimise CONTACT_MATRIX are used for this action.

References

More information about how this action can be used is available in the following articles: - G. A. Tribello, F. Giberti, G. C. Sosso, M. Salvalaglio, M. Parrinello, Analyzing and Driving Cluster Formation in Atomistic Simulations. Journal of Chemical Theory and Computation. 13, 1317–1327 (2017)

Syntax

The following table describes the keywords and options that can be used with this action

Keyword	Type	Default	Description
GROUP	input	none	the atoms for which you would like to calculate the adjacency matrix
GROUPA	input	none	when you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPB
GROUPB	input	none	when you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPA
ATOMS	input	none	the atoms for which you would like to calculate the adjacency matrix
NL_CUTOFF	compulsory	0.0	The cutoff for the neighbor list
NL_STRIDE	compulsory	1	The frequency with which we are updating the atoms in the neighbor list
CUTOFF	compulsory	-1	ignore distances that have a value larger than this cutoff
SERIAL	optional	false	do the calculation in serial
COMPONENTS	optional	false	also calculate the components of the vectors connecting the atoms in the contact matrix
NOPBC	optional	false	don't use pbc

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

Quantity	Type	Description
d1	matrix	a matrix containing the weights for the bonds between each pair of atoms