Action: DISTANCE

Module	colvar
Description	Usage
Calculate the distance/s between pairs of atoms.
output value	type
the DISTANCE between this pair of atoms	scalar/vector

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.

Input

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

Further details and examples

Calculate the distance/s between pairs of atoms.

The following example illustrates how this action can be used to calculate and print the distance between atom 1 and atom 2.

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

dThe DISTANCE action with label d calculates the following quantities:
 Quantity   
 Type   
 Description  
d
scalar
the DISTANCE between this pair of atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=d FILEthe name of the file on which to output these quantities=colvar

By default the distance is computed in a way that takes periodic boundary conditions in account. This behavior can be changed by using the NOPBC flag. Furthermore, if you wish to calculate the vector connecting a pair of atoms you can use the COMPONENTS flag as shown below:

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

dThe DISTANCE action with label d calculates the following quantities:
 Quantity   
 Type   
 Description  
d.x
scalar
the x-component of the vector connecting the two atoms
d.y
scalar
the y-component of the vector connecting the two atoms
d.z
scalar
the z-component of the vector connecting the two atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2 COMPONENTS calculate the x, y and z components of the distance separately and store them as label
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=d.x,d.y,d.z FILEthe name of the file on which to output these quantities=colvar

Alternatively, you can calculate the components projected on the lattice vector by using the SCALED_COMPONENTS flag as shown below;

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

dThe DISTANCE action with label d calculates the following quantities:
 Quantity   
 Type   
 Description  
d.a
scalar
the normalized projection on the first lattice vector of the vector connecting the two atoms
d.b
scalar
the normalized projection on the second lattice vector of the vector connecting the two atoms
d.c
scalar
the normalized projection on the third lattice vector of the vector connecting the two atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2 SCALED_COMPONENTS calculate the a, b and c scaled components of the distance separately and store them as label
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=d.a,d.b,d.c FILEthe name of the file on which to output these quantities=colvar

The advantage of using SCALED_COMPONENTS over COMPONENTS is that the a, b and c variables that are calculated when SCALED_COMPONENTS is employed have the proper periodicity. This feature is useful if you wish to study the motion of a molecule across a membrane.

You can also use this command to calculate multiple indistinguishable distances or vectors with a single line of PLUMED input. For example, the following input calculates and outputs the distances between four pairs of atoms:

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

dThe DISTANCE action with label d calculates the following quantities:
 Quantity   
 Type   
 Description  
d
vector
the DISTANCE for each set of specified atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMS1the pair of atom that we are calculating the distance between=1,2 ATOMS2the pair of atom that we are calculating the distance between=3,4 ATOMS3the pair of atom that we are calculating the distance between=5,6 ATOMS4the pair of atom that we are calculating the distance between=7,8
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=d FILEthe name of the file on which to output these quantities=colvar

By a similar token, the following input outputs three four dimensional vectors that contain the x, y and z components of the vectors connecting the four atoms:

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

dThe DISTANCE action with label d calculates the following quantities:
 Quantity   
 Type   
 Description  
d.x
vector
the x-component of the vector connecting the two atoms
d.y
vector
the y-component of the vector connecting the two atoms
d.z
vector
the z-component of the vector connecting the two atoms: DISTANCECalculate the distance/s between pairs of atoms. More details COMPONENTS calculate the x, y and z components of the distance separately and store them as label ATOMS1the pair of atom that we are calculating the distance between=1,2 ATOMS2the pair of atom that we are calculating the distance between=3,4 ATOMS3the pair of atom that we are calculating the distance between=5,6 ATOMS4the pair of atom that we are calculating the distance between=7,8
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=d.x,d.y,d.z FILEthe name of the file on which to output these quantities=colvar

You can also replace COMPONENTS with SCALED_COMPONENTS in the above input and obtain the projects of these vectors on the lattice vectors.

Managing periodic boundary conditions

When using the DISTANCE command to calculate the end-to-end distance for a large polymer you need to ensure that you are managing PBCs correctly. This problems that can occur with these calculations are explained at length in the early parts of the document that is referenced in the bibliography. Notice, however, that the input provides an example of an input that could be used to compute the end-to-end distance for a polymer of 100 atoms and keeps it at a value around 5.

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

WHOLEMOLECULESThis action is used to rebuild molecules that can become split by the periodic boundary conditions. More details ENTITY0the atoms that make up a molecule that you wish to align=1-100
The WHOLEMOLECULES action with label  calculates somethinge2eThe DISTANCE action with label e2e calculates the following quantities:
 Quantity   
 Type   
 Description  
e2e
scalar
the DISTANCE between this pair of atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,100 NOPBC ignore the periodic boundary conditions when calculating distances
RESTRAINTAdds harmonic and/or linear restraints on one or more variables. More details ARGthe values the harmonic restraint acts upon=e2e KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=1 ATthe position of the restraint=5

Notice that NOPBC is used here so as to ensure that the distance is calculated correctely even if the end-to-end distance is larger than half the simulation Also notice that, since many MD codes break molecules across cell boundary, it might be necessary to use the WHOLEMOLECULES keyword (also notice that it should be before distance). The list of atoms provided to WHOLEMOLECULES here contains all the atoms between 1 and 100. Strictly speaking, this is not necessary. If you know for sure that atoms with difference in the index say equal to 10 are not going to be farther than half cell you can e.g. use

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

WHOLEMOLECULESThis action is used to rebuild molecules that can become split by the periodic boundary conditions. More details ENTITY0the atoms that make up a molecule that you wish to align=1,10,20,30,40,50,60,70,80,90,100
The WHOLEMOLECULES action with label  calculates somethinge2eThe DISTANCE action with label e2e calculates the following quantities:
 Quantity   
 Type   
 Description  
e2e
scalar
the DISTANCE between this pair of atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,100 NOPBC ignore the periodic boundary conditions when calculating distances
RESTRAINTAdds harmonic and/or linear restraints on one or more variables. More details ARGthe values the harmonic restraint acts upon=e2e KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=1 ATthe position of the restraint=5

Just be sure that the ordered list provide to WHOLEMOLECULES has the following properties:

• Consecutive atoms should be closer than half-cell throughout the entire simulation.
• Atoms required later for the distance (e.g. 1 and 100) should be included in the list

The following example shows how to take periodicity into account when computing the z-component of a distance

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

# this is a center of mass of a large group
cThe COM action with label c calculates the following quantities:
 Quantity   
 Type   
 Description  
c
atoms
virtual atom calculated by COM action: COMCalculate the center of mass for a group of atoms. More details ATOMSthe list of atoms which are involved the virtual atom's definition=1-100
# this is the distance between atom 101 and the group
dThe DISTANCE action with label d calculates the following quantities:
 Quantity   
 Type   
 Description  
d.x
scalar
the x-component of the vector connecting the two atoms
d.y
scalar
the y-component of the vector connecting the two atoms
d.z
scalar
the z-component of the vector connecting the two atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=c,101 COMPONENTS calculate the x, y and z components of the distance separately and store them as label
# this makes a new variable, dd, equal to d and periodic, with domain -10,10
# this is the right choise if e.g. the cell is orthorombic and its size in
# z direction is 20.
dzThe COMBINE action with label dz calculates the following quantities:
 Quantity   
 Type   
 Description  
dz
scalar
a linear compbination: COMBINECalculate a polynomial combination of a set of other variables. More details ARGthe values input to this function=d.z PERIODICif the output of your function is periodic then you should specify the periodicity of the function=-10,10
# metadynamics on dd
METADUsed to performed metadynamics on one or more collective variables. More details ARGthe labels of the scalars on which the bias will act=dz SIGMAthe widths of the Gaussian hills=0.1 HEIGHTthe heights of the Gaussian hills=0.1 PACEthe frequency for hill addition=200

You can use the same input even if the DISTANCE command is calculating the vectors connecting multiple pairs of atoms. However, using SCALED_COMPONENTS ensures this problem does not arise because these variables are always periodic with domain (-0.5,+0.5).

References

More information about how this action can be used is available in the following articles:

• G. Bussi, G. A. Tribello, "Analyzing and Biasing Simulations with PLUMED" in Biomolecular Simulations (Springer New York, 2019; http://dx.doi.org/10.1007/978-1-4939-9608-7_21), pp. 529–578

Syntax

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