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 LINKCELL_CUTOFF use a link cells algorithm with this cutoff to optimise the calculation - distances (but not derivatives) for atoms that are further apart than this cutoff and that in the same link cells will still be computed=-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 LINKCELL_CUTOFF use a link cells algorithm with this cutoff to optimise the calculation - distances (but not derivatives) for atoms that are further apart than this cutoff and that in the same link cells will still be computed=-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 LINKCELL_CUTOFF use a link cells algorithm with this cutoff to optimise the calculation - distances (but not derivatives) for atoms that are further apart than this cutoff and that in the same link cells will still be computed=-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 LINKCELL_CUTOFF use a link cells algorithm with this cutoff to optimise the calculation - distances (but not derivatives) for atoms that are further apart than this cutoff and that in the same link cells will still be computed=-1

Optimisation details

If for some reaon, you only want to calculate the distances if they are less than a certain cutoff can add the LINKCELL_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 LINKCELL_CUTOFF use a link cells algorithm with this cutoff to optimise the calculation - distances (but not derivatives) for atoms that are further apart than this cutoff and that in the same link cells will still be computed=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 LINKCELL_CUTOFF use a link cells algorithm with this cutoff to optimise the calculation - distances (but not derivatives) for atoms that are further apart than this cutoff and that in the same link cells will still be computed=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

Using a LINKCELL_CUTOFF ensures that PLUMED can use the link cell technique that is described in the documentation for the CONTACT_MATRIX action to optimise the calculation. Using this technique ensures that many of the distance calculations are avoided. However, this does not mean that PLUMED will not evaluate and store the distances between pairs of atoms that are more than the cutoff apart. The distances for some of the values that are larger than the cutoff are are calculated and stored.

You can see how to work around this strange implementation detail in the following example input. Lets suppose that we want to calculate the average distances between atoms 1-10 and all the atoms that are within 1 nm of them. To do this we would use an input similar to the one shown below:

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

d5The DISTANCE_MATRIX action with label d5 calculates the following quantities: Quantity    Type    Description  
d5 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-10 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=1-250 LINKCELL_CUTOFF use a link cells algorithm with this cutoff to optimise the calculation - distances (but not derivatives) for atoms that are further apart than this cutoff and that in the same link cells will still be computed=1.0
d5: 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-10 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=1-250 LINKCELL_CUTOFF use a link cells algorithm with this cutoff to optimise the calculation - distances (but not derivatives) for atoms that are further apart than this cutoff and that in the same link cells will still be computed=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
# Apply a switching function to determine the elements in the matrix d5
# where the distance is less than the cutoff
cutThe CUSTOM action with label cut calculates the following quantities: Quantity    Type    Description  
cut matrix the matrix obtained by doing an element-wise application of an arbitrary function to the input matrix: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=d5 FUNCthe function you wish to evaluate=step(1-x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# Taking the element-wise product in the next command gives us a matrix
# where every element that is greater than the cutoff is zero.
d5cutThe CUSTOM action with label d5cut calculates the following quantities: Quantity    Type    Description  
d5cut matrix the matrix obtained by doing an element-wise application of an arbitrary function to the input matrix: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=d5,cut 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
# We can now calculate the average distances by multiplying these matrices by
# a vector of ones and thus summing the rows.
onesThe ONES action with label ones calculates the following quantities: Quantity    Type    Description  
ones vector a vector of ones with the required number of elements: ONESCreate a constant vector with all elements equal to one This action is a shortcut. More details SIZEthe number of ones that you would like to create=250
# PLUMED interprets the command:
# ones: ONES SIZE=250
# as follows (Click the red comment above to revert to the short version of the input):
onesThe CONSTANT action with label ones calculates the following quantities: Quantity    Type    Description  
ones vector the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details NOLOG do not report all the read in scalars in the log VALUESthe numbers that are in your constant value=1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1
# --- End of included input --- totdistThe MATRIX_VECTOR_PRODUCT action with label totdist calculates the following quantities: Quantity    Type    Description  
totdist vector the vector that is obtained by taking the product between the matrix and the vector that were input: MATRIX_VECTOR_PRODUCTCalculate the product of the matrix and the vector More details ARGthe label for the matrix and the vector/scalar that are being multiplied=d5cut,ones
ndistThe MATRIX_VECTOR_PRODUCT action with label ndist calculates the following quantities: Quantity    Type    Description  
ndist vector the vector that is obtained by taking the product between the matrix and the vector that were input: MATRIX_VECTOR_PRODUCTCalculate the product of the matrix and the vector More details ARGthe label for the matrix and the vector/scalar that are being multiplied=cut,ones
averageThe CUSTOM action with label average calculates the following quantities: Quantity    Type    Description  
average 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=totdist,ndist 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
DUMPATOMSDump selected atoms on a file. More details ATOMSthe atom indices whose positions you would like to print out=1-10 ARGthe labels of vectors that should be output in the xyz file=average FILEfile on which to output coordinates; extension is automatically detected=avdist.xyz

In short, if you use DISTANCE_MATRIX and LINKCELL_CUTOFF and what to ignore distances that are larger than the cutoff you need to use an additional CUSTOM command later in the input. You should thus only use this combination of action and keyword it you are certain it is necessary. Normally, you are far better using the CONTACT_MATRIX command in place of the DISTANCE_MATRIX command. To obtain a result similar to the one above using this command you would use the following input:

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 LINKCELL_CUTOFF use a link cells algorithm with this cutoff to optimise the calculation - distances (but not derivatives) for atoms that are further apart than this cutoff and that in the same link cells will still be computed=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 LINKCELL_CUTOFF use a link cells algorithm with this cutoff to optimise the calculation - distances (but not derivatives) for atoms that are further apart than this cutoff and that in the same link cells will still be computed=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
LINKCELL_CUTOFF	compulsory	-1	use a link cells algorithm with this cutoff to optimise the calculation - distances (but not derivatives) for atoms that are further apart than this cutoff and that in the same link cells will still be computed
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)