DISTANCE

This is part of the colvar module

Calculate the distance between a pair of atoms.

By default the distance is computed taking into account periodic boundary conditions. This behavior can be changed with the NOPBC flag. Moreover, single components in Cartesian space (x,y, and z, with COMPONENTS) or single components projected to the three lattice vectors (a,b, and c, with SCALED_COMPONENTS) can be also computed.

Notice that Cartesian components will not have the proper periodicity! If you have to study e.g. the permeation of a molecule across a membrane, better to use SCALED_COMPONENTS.

Examples

The following input tells plumed to print the distance between atoms 3 and 5, the distance between atoms 2 and 4 and the x component of the distance between atoms 2 and 4.

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

d1: DISTANCE ATOMSthe pair of atom that we are calculating the distance between. =3,5 The DISTANCE action with label d1 calculates a single scalar value
d2: DISTANCE ATOMSthe pair of atom that we are calculating the distance between. =2,4 The DISTANCE action with label d2 calculates a single scalar value
d2c: DISTANCE ATOMSthe pair of atom that we are calculating the distance between. =2,4 COMPONENTS( default=off ) calculate the x, y and z components of the distance separately and
store them as label.x,  The DISTANCE action with label d2c calculates the following quantities:

 Quantity   
 Description  
d2c.x
the x-component of the vector connecting the two atoms
d2c.y
the y-component of the vector connecting the two atoms
d2c.z
the z-component of the vector connecting the two atoms


PRINT ARGthe input for this action is the scalar output from one or more other actions. =d1,d2,d2c.x The PRINT action with label 

The following input computes 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

contract shortcuts

WHOLEMOLECULES ENTITY0the atoms that make up a molecule that you wish to align. =1-100 The WHOLEMOLECULES action with label 
e2e: DISTANCE ATOMSthe pair of atom that we are calculating the distance between. =1,100 NOPBC( default=off ) ignore the periodic boundary conditions when calculating distances
 The DISTANCE action with label e2e calculates a single scalar value
RESTRAINT ARGthe arguments on which the bias is acting. =e2e KAPPAcompulsory keyword ( default=0.0 )
specifies that the restraint is harmonic and what the values of the force constants
on each of the variables are =1 ATcompulsory keyword 
the position of the restraint =5 The RESTRAINT action with label 

WHOLEMOLECULES ENTITY0the atoms that make up a molecule that you wish to align. =1-100 The WHOLEMOLECULES action with label 
e2e: DISTANCE ATOMSthe pair of atom that we are calculating the distance between. =1,100 NOPBC( default=off ) ignore the periodic boundary conditions when calculating distances
 The DISTANCE action with label e2e calculates a single scalar value

Notice that NOPBC is used to be sure that if the end-to-end distance is larger than half the simulation box the distance is compute properly. 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

contract shortcuts

WHOLEMOLECULES 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 
e2e: DISTANCE ATOMSthe pair of atom that we are calculating the distance between. =1,100 NOPBC( default=off ) ignore the periodic boundary conditions when calculating distances
 The DISTANCE action with label e2e calculates a single scalar value
RESTRAINT ARGthe arguments on which the bias is acting. =e2e KAPPAcompulsory keyword ( default=0.0 )
specifies that the restraint is harmonic and what the values of the force constants
on each of the variables are =1 ATcompulsory keyword 
the position of the restraint =5 The RESTRAINT action with label 

WHOLEMOLECULES 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 
e2e: DISTANCE ATOMSthe pair of atom that we are calculating the distance between. =1,100 NOPBC( default=off ) ignore the periodic boundary conditions when calculating distances
 The DISTANCE action with label e2e calculates a single scalar value

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 into account periodicity e.g. in z-component of a distance

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

contract shortcuts

# this is a center of mass of a large group
c: COM ATOMSthe list of atoms which are involved the virtual atom's definition. =1-100 The COM action with label c calculates the following quantities:

 Quantity   
 Description  
c.x
the x coordinate of the virtual atom
c.y
the y coordinate of the virtual atom
c.z
the z coordinate of the virtual atom
c.mass
the mass of the virtual atom
c.charge
the charge of the virtual atom


# this is the distance between atom 101 and the group
d: DISTANCE ATOMSthe pair of atom that we are calculating the distance between. =c,101 COMPONENTS( default=off ) calculate the x, y and z components of the distance separately and
store them as label.x,  The DISTANCE action with label d calculates the following quantities:

 Quantity   
 Description  
d.x
the x-component of the vector connecting the two atoms
d.y
the y-component of the vector connecting the two atoms
d.z
the z-component of the vector connecting the two atoms


# 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.
dz: COMBINE ARGthe input to this function. =d.z PERIODICcompulsory keyword 
if the output of your function is periodic then you should specify the periodicity
of the function. =-10,10 The COMBINE action with label dz calculates a single scalar value
# metadynamics on dd
METAD ARGthe input for this action is the scalar output from one or more other actions. =dz SIGMAcompulsory keyword 
the widths of the Gaussian hills =0.1 HEIGHTthe heights of the Gaussian hills. =0.1 PACEcompulsory keyword 
the frequency for hill addition =200 The METAD action with label 

# this is a center of mass of a large group
c: COM ATOMSthe list of atoms which are involved the virtual atom's definition. =1-100 The COM action with label c calculates the following quantities:

 Quantity   
 Description  
c.x
the x coordinate of the virtual atom
c.y
the y coordinate of the virtual atom
c.z
the z coordinate of the virtual atom
c.mass
the mass of the virtual atom
c.charge
the charge of the virtual atom


# this is the distance between atom 101 and the group
d: DISTANCE ATOMSthe pair of atom that we are calculating the distance between. =c,101 COMPONENTS( default=off ) calculate the x, y and z components of the distance separately and
store them as label.x,  The DISTANCE action with label d calculates the following quantities:

 Quantity   
 Description  
d.x
the x-component of the vector connecting the two atoms
d.y
the y-component of the vector connecting the two atoms
d.z
the z-component of the vector connecting the two atoms


# 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.
# metadynamics on dd
METAD ARGthe input for this action is the scalar output from one or more other actions. =dz SIGMAcompulsory keyword 
the widths of the Gaussian hills =0.1 HEIGHTthe heights of the Gaussian hills. =0.1 PACEcompulsory keyword 
the frequency for hill addition =200 The METAD action with label 
Using SCALED_COMPONENTS this problem should not arise because they are always periodic with domain (-0.5,+0.5).
Glossary of keywords and components

Description of components

By default the value of the calculated quantity can be referenced elsewhere in the input file by using the label of the action. Alternatively this Action can be used to calculate the following quantities by employing the keywords listed below. These quantities can be referenced elsewhere in the input by using this Action's label followed by a dot and the name of the quantity required from the list below.


 Quantity   
 Description    

 .#!value  
the DISTANCE between this pair of atoms   

In addition the following quantities can be calculated by employing the keywords listed below


 Quantity   
 Keyword   
 Description    

 x  
 COMPONENTS   
the x-component of the vector connecting the two atoms   

 y  
 COMPONENTS   
the y-component of the vector connecting the two atoms   

 z  
 COMPONENTS   
the z-component of the vector connecting the two atoms   

 a  
 SCALED_COMPONENTS   
the normalized projection on the first lattice vector of the vector connecting the two atoms   

 b  
 SCALED_COMPONENTS   
the normalized projection on the second lattice vector of the vector connecting the two atoms   

 c  
 SCALED_COMPONENTS   
the normalized projection on the third lattice vector of the vector connecting the two atoms   

The atoms involved can be specified using



 ATOMS  
the pair of atom that we are calculating the distance between. For more information on how to specify lists of atoms see Groups and Virtual Atoms   

Options



 NUMERICAL_DERIVATIVES  
( default=off ) calculate the derivatives for these quantities numerically   

 NOPBC  
( default=off ) ignore the periodic boundary conditions when calculating distances   

 COMPONENTS  
( default=off ) calculate the x, y and z components of the distance separately and store them as label.x, label.y and label.z   

 SCALED_COMPONENTS  
( default=off ) calculate the a, b and c scaled components of the distance separately and store them as label.a, label.b and label.c