Shortcut: DISPLACEMENT

Module	refdist
Description	Usage
Calculate the displacement vector between the pair of input vectors
output value	type
the differences between the input arguments	vector/matrix

Further details and examples

Calculate the displacement vector between the pair of input vectors

This shortcut can be used to calculate the vector of displacements between two input vectors as shown below.

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

cThe CONSTANT action with label c calculates the following quantities: Quantity    Type    Description  
c vector the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions This action has hidden defaults. More details VALUESthe numbers that are in your constant value=1,2,3
c: CONSTANTCreate a constant value that can be passed to actions This action uses the defaults shown here. More details VALUESthe numbers that are in your constant value=1,2,3  NROWS the number of rows in your input matrix=0 NCOLS the number of columns in your matrix=0
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
ddThe DISPLACEMENT action with label dd calculates the following quantities: Quantity    Type    Description  
dd matrix the differences between the input arguments: DISPLACEMENTCalculate the displacement vector between the pair of input vectors This action is a shortcut. More details ARG1The point that we are calculating the distance from=c ARG2The point that we are calculating the distance to=d
# PLUMED interprets the command:
# dd: DISPLACEMENT ARG1=c ARG2=d
# as follows (Click the red comment above to revert to the short version of the input):
dd_c_diffThe DIFFERENCE action with label dd_c_diff calculates the following quantities: Quantity    Type    Description  
dd_c_diff vector the vector obtained by doing an element-wise application of a function that measures the difference to the input vectors: DIFFERENCECalculate the differences between two scalars or vectors More details ARGthe values input to this function=c,d
ddThe TRANSPOSE action with label dd calculates the following quantities: Quantity    Type    Description  
dd matrix the transpose of the input matrix: TRANSPOSECalculate the transpose of a matrix More details ARGthe label of the vector or matrix that should be transposed=dd_c_diff
# --- End of included input --- PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=dd FILEthe name of the file on which to output these quantities=colvar

The output here, dd, is a $1 \times 3$ matrix for reasons that will become clear later in this documentation. Notice that we can obtain the same result by specifying the input vectors here as two sets of three scalars as shown below:

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

c1The CONSTANT action with label c1 calculates the following quantities: Quantity    Type    Description  
c1 scalar the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions This action has hidden defaults. More details VALUEthe single number that you would like to store=1
c1: CONSTANTCreate a constant value that can be passed to actions This action uses the defaults shown here. More details VALUEthe single number that you would like to store=1  NROWS the number of rows in your input matrix=0 NCOLS the number of columns in your matrix=0
d1The DISTANCE action with label d1 calculates the following quantities: Quantity    Type    Description  
d1 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
c2The CONSTANT action with label c2 calculates the following quantities: Quantity    Type    Description  
c2 scalar the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions This action has hidden defaults. More details VALUEthe single number that you would like to store=2
c2: CONSTANTCreate a constant value that can be passed to actions This action uses the defaults shown here. More details VALUEthe single number that you would like to store=2  NROWS the number of rows in your input matrix=0 NCOLS the number of columns in your matrix=0
d2The DISTANCE action with label d2 calculates the following quantities: Quantity    Type    Description  
d2 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=3,4
c3The CONSTANT action with label c3 calculates the following quantities: Quantity    Type    Description  
c3 scalar the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions This action has hidden defaults. More details VALUEthe single number that you would like to store=3
c3: CONSTANTCreate a constant value that can be passed to actions This action uses the defaults shown here. More details VALUEthe single number that you would like to store=3  NROWS the number of rows in your input matrix=0 NCOLS the number of columns in your matrix=0
d3The DISTANCE action with label d3 calculates the following quantities: Quantity    Type    Description  
d3 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=5,6
ddThe DISPLACEMENT action with label dd calculates the following quantities: Quantity    Type    Description  
dd matrix the differences between the input arguments: DISPLACEMENTCalculate the displacement vector between the pair of input vectors This action is a shortcut. More details ARG1The point that we are calculating the distance from=c1,c2,c3 ARG2The point that we are calculating the distance to=d1,d2,d3
# PLUMED interprets the command:
# dd: DISPLACEMENT ARG1=c1,c2,c3 ARG2=d1,d2,d3
# as follows (Click the red comment above to revert to the short version of the input):
dd_c1_diffThe DIFFERENCE action with label dd_c1_diff calculates the following quantities: Quantity    Type    Description  
dd_c1_diff scalar a function that measures the difference: DIFFERENCECalculate the differences between two scalars or vectors More details ARGthe values input to this function=c1,d1
dd_c2_diffThe DIFFERENCE action with label dd_c2_diff calculates the following quantities: Quantity    Type    Description  
dd_c2_diff scalar a function that measures the difference: DIFFERENCECalculate the differences between two scalars or vectors More details ARGthe values input to this function=c2,d2
dd_c3_diffThe DIFFERENCE action with label dd_c3_diff calculates the following quantities: Quantity    Type    Description  
dd_c3_diff scalar a function that measures the difference: DIFFERENCECalculate the differences between two scalars or vectors More details ARGthe values input to this function=c3,d3
ddThe VSTACK action with label dd calculates the following quantities: Quantity    Type    Description  
dd matrix a matrix that contains the input vectors in its columns: VSTACKCreate a matrix by stacking vectors together More details ARGthe values that you would like to stack together to construct the output matrix=dd_c1_diff,dd_c2_diff,dd_c3_diff
# --- End of included input --- PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=dd FILEthe name of the file on which to output these quantities=colvar

The DISPLACEMENT command that has been introduced in the above inputs is primarily used within the EUCLIDEAN_DISTANCE, NORMALIZED_EUCLIDEAN_DISTANCE and MAHALANOBIS_DISTANCE shortcuts. If the $1 \times N$ matrix of displacements that that we obtainfrom these commands is, $D$ , these three actions calculate

$d = D M D^T$

The $N \times N$ matrix $M$ here is the identity if you are using EUCLIDEAN_DISTANCE, a diagonal matrix if you are using NORMALIZED_EUCLIDEAN_DISTANCE and a full matrix if you are computing the MAHALANOBIS_DISTANCE.

Calculating multiple displacement vectors

The reason the output of DISPLACEMENT is a $1 \times 3$ matrix here becomes clearer once we consider the following input:

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

ref_psiThe CONSTANT action with label ref_psi calculates the following quantities: Quantity    Type    Description  
ref_psi scalar the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions This action has hidden defaults. More details VALUESthe numbers that are in your constant value=2.25
ref_psi: CONSTANTCreate a constant value that can be passed to actions This action uses the defaults shown here. More details VALUESthe numbers that are in your constant value=2.25  NROWS the number of rows in your input matrix=0 NCOLS the number of columns in your matrix=0
ref_phiThe CONSTANT action with label ref_phi calculates the following quantities: Quantity    Type    Description  
ref_phi scalar the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions This action has hidden defaults. More details VALUESthe numbers that are in your constant value=-1.91
ref_phi: CONSTANTCreate a constant value that can be passed to actions This action uses the defaults shown here. More details VALUESthe numbers that are in your constant value=-1.91  NROWS the number of rows in your input matrix=0 NCOLS the number of columns in your matrix=0

psiThe TORSION action with label psi calculates the following quantities: Quantity    Type    Description  
psi vector the TORSION for each set of specified atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMS1the four atoms involved in the torsional angle=1,2,3,4 ATOMS2the four atoms involved in the torsional angle=5,6,7,8 ATOMS3the four atoms involved in the torsional angle=9,10,11,12
phiThe TORSION action with label phi calculates the following quantities: Quantity    Type    Description  
phi vector the TORSION for each set of specified atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMS1the four atoms involved in the torsional angle=13,14,15,16 ATOMS2the four atoms involved in the torsional angle=17,18,19,20 ATOMS3the four atoms involved in the torsional angle=21,22,23,24

ddThe DISPLACEMENT action with label dd calculates the following quantities: Quantity    Type    Description  
dd matrix the differences between the input arguments: DISPLACEMENTCalculate the displacement vector between the pair of input vectors This action is a shortcut. More details ARG1The point that we are calculating the distance from=psi,phi ARG2The point that we are calculating the distance to=ref_psi,ref_phi
# PLUMED interprets the command:
# dd: DISPLACEMENT ARG1=psi,phi ARG2=ref_psi,ref_phi
# as follows (Click the red comment above to revert to the short version of the input):
dd_psi_diffThe DIFFERENCE action with label dd_psi_diff calculates the following quantities: Quantity    Type    Description  
dd_psi_diff vector the vector obtained by doing an element-wise application of a function that measures the difference to the input vectors: DIFFERENCECalculate the differences between two scalars or vectors More details ARGthe values input to this function=psi,ref_psi
dd_phi_diffThe DIFFERENCE action with label dd_phi_diff calculates the following quantities: Quantity    Type    Description  
dd_phi_diff vector the vector obtained by doing an element-wise application of a function that measures the difference to the input vectors: DIFFERENCECalculate the differences between two scalars or vectors More details ARGthe values input to this function=phi,ref_phi
ddThe VSTACK action with label dd calculates the following quantities: Quantity    Type    Description  
dd matrix a matrix that contains the input vectors in its columns: VSTACKCreate a matrix by stacking vectors together More details ARGthe values that you would like to stack together to construct the output matrix=dd_psi_diff,dd_phi_diff
# --- End of included input --- PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=dd FILEthe name of the file on which to output these quantities=colvar

The output from the input above is a $3\times 2$ matrix. The rows of this matrix run over the 3 different torsion values that have been specified in the psi and phi commands. The first column of the matrix contains the differences between each of the instantaneous psi aingles and the reference value for this angle, while the second columns contains the differences between the phi angles and the reference.

In other words, we can calculate multiple displacement vectors at once as each row of the final output matrix will contain a vector of displacements between two vectors. Notice that we can use a similar input to calculate the differences between the instantaneous value of a pair of torsions and 3 reference values as shown below:

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

ref_psiThe CONSTANT action with label ref_psi calculates the following quantities: Quantity    Type    Description  
ref_psi vector the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions This action has hidden defaults. More details VALUESthe numbers that are in your constant value=2.25,1.3,-1.5
ref_psi: CONSTANTCreate a constant value that can be passed to actions This action uses the defaults shown here. More details VALUESthe numbers that are in your constant value=2.25,1.3,-1.5  NROWS the number of rows in your input matrix=0 NCOLS the number of columns in your matrix=0
ref_phiThe CONSTANT action with label ref_phi calculates the following quantities: Quantity    Type    Description  
ref_phi vector the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions This action has hidden defaults. More details VALUESthe numbers that are in your constant value=-1.91,-0.6,2.4
ref_phi: CONSTANTCreate a constant value that can be passed to actions This action uses the defaults shown here. More details VALUESthe numbers that are in your constant value=-1.91,-0.6,2.4  NROWS the number of rows in your input matrix=0 NCOLS the number of columns in your matrix=0

psiThe TORSION action with label psi calculates the following quantities: Quantity    Type    Description  
psi scalar the TORSION involving these atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=1,2,3,4
phiThe TORSION action with label phi calculates the following quantities: Quantity    Type    Description  
phi scalar the TORSION involving these atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=13,14,15,16

ddThe DISPLACEMENT action with label dd calculates the following quantities: Quantity    Type    Description  
dd matrix the differences between the input arguments: DISPLACEMENTCalculate the displacement vector between the pair of input vectors This action is a shortcut. More details ARG1The point that we are calculating the distance from=psi,phi ARG2The point that we are calculating the distance to=ref_psi,ref_phi
# PLUMED interprets the command:
# dd: DISPLACEMENT ARG1=psi,phi ARG2=ref_psi,ref_phi
# as follows (Click the red comment above to revert to the short version of the input):
dd_psi_diffThe DIFFERENCE action with label dd_psi_diff calculates the following quantities: Quantity    Type    Description  
dd_psi_diff vector the vector obtained by doing an element-wise application of a function that measures the difference to the input vectors: DIFFERENCECalculate the differences between two scalars or vectors More details ARGthe values input to this function=psi,ref_psi
dd_phi_diffThe DIFFERENCE action with label dd_phi_diff calculates the following quantities: Quantity    Type    Description  
dd_phi_diff vector the vector obtained by doing an element-wise application of a function that measures the difference to the input vectors: DIFFERENCECalculate the differences between two scalars or vectors More details ARGthe values input to this function=phi,ref_phi
ddThe VSTACK action with label dd calculates the following quantities: Quantity    Type    Description  
dd matrix a matrix that contains the input vectors in its columns: VSTACKCreate a matrix by stacking vectors together More details ARGthe values that you would like to stack together to construct the output matrix=dd_psi_diff,dd_phi_diff
# --- End of included input --- PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=dd FILEthe name of the file on which to output these quantities=colvar

The output here will again be a $3\times 2$ matrix with each of the three rows holding a vector of displacements between the 2 instananeous values and one of the three sets of reference values.

Lastly, we can use two sets of vectors in the input to DISPLACEMENT as shown below:

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

ref_psiThe CONSTANT action with label ref_psi calculates the following quantities: Quantity    Type    Description  
ref_psi vector the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions This action has hidden defaults. More details VALUESthe numbers that are in your constant value=2.25,1.3,-1.5
ref_psi: CONSTANTCreate a constant value that can be passed to actions This action uses the defaults shown here. More details VALUESthe numbers that are in your constant value=2.25,1.3,-1.5  NROWS the number of rows in your input matrix=0 NCOLS the number of columns in your matrix=0
ref_phiThe CONSTANT action with label ref_phi calculates the following quantities: Quantity    Type    Description  
ref_phi vector the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions This action has hidden defaults. More details VALUESthe numbers that are in your constant value=-1.91,-0.6,2.4
ref_phi: CONSTANTCreate a constant value that can be passed to actions This action uses the defaults shown here. More details VALUESthe numbers that are in your constant value=-1.91,-0.6,2.4  NROWS the number of rows in your input matrix=0 NCOLS the number of columns in your matrix=0

psiThe TORSION action with label psi calculates the following quantities: Quantity    Type    Description  
psi vector the TORSION for each set of specified atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMS1the four atoms involved in the torsional angle=1,2,3,4 ATOMS2the four atoms involved in the torsional angle=5,6,7,8 ATOMS3the four atoms involved in the torsional angle=9,10,11,12
phiThe TORSION action with label phi calculates the following quantities: Quantity    Type    Description  
phi vector the TORSION for each set of specified atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMS1the four atoms involved in the torsional angle=13,14,15,16 ATOMS2the four atoms involved in the torsional angle=17,18,19,20 ATOMS3the four atoms involved in the torsional angle=21,22,23,24

ddThe DISPLACEMENT action with label dd calculates the following quantities: Quantity    Type    Description  
dd matrix the differences between the input arguments: DISPLACEMENTCalculate the displacement vector between the pair of input vectors This action is a shortcut. More details ARG1The point that we are calculating the distance from=psi,phi ARG2The point that we are calculating the distance to=ref_psi,ref_phi
# PLUMED interprets the command:
# dd: DISPLACEMENT ARG1=psi,phi ARG2=ref_psi,ref_phi
# as follows (Click the red comment above to revert to the short version of the input):
dd_psi_diffThe DIFFERENCE action with label dd_psi_diff calculates the following quantities: Quantity    Type    Description  
dd_psi_diff vector the vector obtained by doing an element-wise application of a function that measures the difference to the input vectors: DIFFERENCECalculate the differences between two scalars or vectors More details ARGthe values input to this function=psi,ref_psi
dd_phi_diffThe DIFFERENCE action with label dd_phi_diff calculates the following quantities: Quantity    Type    Description  
dd_phi_diff vector the vector obtained by doing an element-wise application of a function that measures the difference to the input vectors: DIFFERENCECalculate the differences between two scalars or vectors More details ARGthe values input to this function=phi,ref_phi
ddThe VSTACK action with label dd calculates the following quantities: Quantity    Type    Description  
dd matrix a matrix that contains the input vectors in its columns: VSTACKCreate a matrix by stacking vectors together More details ARGthe values that you would like to stack together to construct the output matrix=dd_psi_diff,dd_phi_diff
# --- End of included input --- PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=dd FILEthe name of the file on which to output these quantities=colvar

The output here is still a $3 \times 2$ matrix. Now, however, each of the three instantaneous angles we have calculated has its own set of reference values. A different pair of instaneous and reference values is used to calculate each element of the resulting matrix.

DISPLACEMENT actions that compute $M\times N$ matrices, $D$ , are used within the EUCLIDEAN_DISTANCE, NORMALIZED_EUCLIDEAN_DISTANCE and MAHALANOBIS_DISTANCE shortcuts. Doing so is useful as if you take the diagonal elements of a product of matrices that is similar to the product of vectors and matrices that we introduced earlier:

$d = D M D^T$

you can calculate $M$ values for the EUCLIDEAN_DISTANCE, NORMALIZED_EUCLIDEAN_DISTANCE and MAHALANOBIS_DISTANCE.

Syntax

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

Keyword	Type	Default	Description
ARG1	compulsory	none	The point that we are calculating the distance from
ARG2	compulsory	none	The point that we are calculating the distance to

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

Quantity	Type	Description
c	vector	the constant value that was read from the plumed input