Skip to content

PLUMED manual

Action: DISTANCE_MATRIX

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

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

For both these inputs the distances between atoms are calculated in a way that takes the periodic boundary conditions into account. If you want to ignore the periodic boundaries when calculating distances you use the NOPBC flag as shown below:

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 NOPBC don't use pbc
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 NOPBC don't use pbc  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 vector 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 vector 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.

Also notice that you can use MASK to calculate a subset of the rows in the DISTANCE matrix as is done in the following example:

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

# The atoms that are of interest
owThe GROUP action with label ow calculates the following quantities: Quantity    Type    Description  
ow atoms indices of atoms specified in GROUP: GROUPDefine a group of atoms so that a particular list of atoms can be referenced with a single label in definitions of CVs or virtual atoms. More details ATOMSthe numerical indexes for the set of atoms in the group=1-16500
# Fixed virtual atom which serves as the probe volume's center (pos. in nm)
centerThe FIXEDATOM action with label center calculates the following quantities: Quantity    Type    Description  
center atoms virtual atom calculated by FIXEDATOM action: FIXEDATOMAdd a virtual atom in a fixed position. This action has hidden defaults. More details ATcoordinates of the virtual atom=2.5,2.5,2.5
center: FIXEDATOMAdd a virtual atom in a fixed position. This action uses the defaults shown here. More details ATcoordinates of the virtual atom=2.5,2.5,2.5  SET_MASS mass of the virtual atom=1 SET_CHARGE charge of the virtual atom=0
# Vector in which element i is one if atom i is in sphere of interest and zero otherwise
sphereThe INSPHERE action with label sphere calculates the following quantities: Quantity    Type    Description  
sphere vector vector of numbers between 0 and 1 that measure the degree to which each atom is within the volume of interest: INSPHEREThis quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a particular, user-specified part of of the cell. More details ATOMSthe group of atoms that you would like to investigate=ow CENTERthe atom whose vicinity we are interested in examining=center RADIUSthe switching function that tells us the extent of the sphereical region of interest. Options for this keyword are explained in the documentation for LESS_THAN.={GAUSSIAN D_0=0.5 R_0=0.01 D_MAX=0.52}
# The distance matrix
dmapThe DISTANCE_MATRIX action with label dmap calculates the following quantities: Quantity    Type    Description  
dmap.w matrix a matrix containing the weights for the bonds between each pair of atoms
dmap.x matrix the projection of the bond on the x axis
dmap.y matrix the projection of the bond on the y axis
dmap.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 COMPONENTS also calculate the components of the vector connecting the atoms in the contact matrix GROUPthe atoms for which you would like to calculate the adjacency matrix=ow CUTOFF ignore distances that have a value larger than this cutoff=1.0 MASKa vector that is used to used to determine which rows of the adjancency matrix to compute=sphere
dmap: DISTANCE_MATRIXCalculate a matrix of distances between atoms. This action uses the defaults shown here. More details COMPONENTS also calculate the components of the vector connecting the atoms in the contact matrix GROUPthe atoms for which you would like to calculate the adjacency matrix=ow CUTOFF ignore distances that have a value larger than this cutoff=1.0 MASKa vector that is used to used to determine which rows of the adjancency matrix to compute=sphere  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
# Find the four nearest neighbors
acv_neighThe NEIGHBORS action with label acv_neigh calculates the following quantities: Quantity    Type    Description  
acv_neigh matrix a matrix in which the ij element is one if the ij-element of the input matrix is one of the NLOWEST/NHIGHEST elements on that row of the input matrix and zero otherwise: NEIGHBORSBuild a matrix with ones in for the N nearest neighbours of an atom This action has hidden defaults. More details ARGthe label of an adjacency/distance matrix that will be used to find the nearest neighbors=dmap.w NLOWEST in each row of the output matrix set the elements that correspond to the n lowest elements in each row of the input matrix equal to one=4 MASKa vector that is used to used to determine which rows of the neighbors matrix to compute=sphere
acv_neigh: NEIGHBORSBuild a matrix with ones in for the N nearest neighbours of an atom This action uses the defaults shown here. More details ARGthe label of an adjacency/distance matrix that will be used to find the nearest neighbors=dmap.w NLOWEST in each row of the output matrix set the elements that correspond to the n lowest elements in each row of the input matrix equal to one=4 MASKa vector that is used to used to determine which rows of the neighbors matrix to compute=sphere  NHIGHEST in each row of the output matrix set the elements that correspond to the n highest elements in each row of the input matrix equal to one=0
# Compute a function for the atoms that are in the first coordination sphere
acv_g8The GSYMFUNC_THREEBODY action with label acv_g8 calculates the following quantities: Quantity    Type    Description  
acv_g8.g8 vector the function defined by the FUNCTION1 keyword: GSYMFUNC_THREEBODYCalculate functions of the coordinates of the coordinates of all pairs of bonds in the first coordination sphere of an atom More details ...
  WEIGHTthe matrix that contains the weights that should be used for each connection=acv_neigh ARGthree matrices containing the bond vectors of interest=dmap.x,dmap.y,dmap.z
  FUNCTION1the parameters of the function you would like to compute={FUNC=(cos(ajik)+1/3)^2 LABEL=g8}
  MASKa vector that is used to used to determine which symmetry functions should be calculated=sphere
...
# Now compute the value of the function above for those atoms that are in the
# sphere of interest
acvThe CUSTOM action with label acv calculates the following quantities: Quantity    Type    Description  
acv vector the vector obtained by doing an element-wise application of an arbitrary function to the input vectors: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=acv_g8.g8,sphere FUNCthe function you wish to evaluate=y*(1-(3*x/8)) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# And now compute the final average
acv_sumThe SUM action with label acv_sum calculates the following quantities: Quantity    Type    Description  
acv_sum scalar the SUM of the elements in the input value: SUMCalculate the sum of the arguments More details ARGthe vector/matrix/grid whose elements shuld be added together=acv PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
acv_normThe SUM action with label acv_norm calculates the following quantities: Quantity    Type    Description  
acv_norm scalar the SUM of the elements in the input value: SUMCalculate the sum of the arguments More details ARGthe vector/matrix/grid whose elements shuld be added together=sphere PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
meanThe CUSTOM action with label mean calculates the following quantities: Quantity    Type    Description  
mean scalar an arbitrary function: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=acv_sum,acv_norm FUNCthe function you wish to evaluate=x/y PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=mean FILEthe name of the file on which to output these quantities=colvar

This input calculates the average value for measure of tetrahedral order that is introduced in the documentation for the TETRA_ANGULAR shortcut for those atom that are within a sphere that is centered on the point $(2.5,2.5,2.5)$ .

Input

The arguments and 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
MASK	vector	a vector that is used to used to determine which rows of the adjancency matrix to compute
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

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

Full list of keywords

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

Keyword	Type	Default	Description
MASK	input	none	a vector that is used to used to determine which rows of the adjancency matrix to compute
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
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
COMPONENTS	optional	false	also calculate the components of the vector connecting the atoms in the contact matrix
NOPBC	optional	false	don't use pbc
SERIAL	optional	false	do the calculation in serial. Further information about this flag can be found here.
USEGPU	optional	false	run this calculation on the GPU. Further information about this flag can be found here.

deprecated keywords

The keywords in the following table can still be used with this action but have been deprecated

Keyword	Description
ATOMS	You should use GROUP instead of this keyword which was used in older versions of PLUMED and is provided for back compatibility only

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)