Shortcut: MAHALANOBIS_DISTANCE

Module	refdist
Description	Usage
Calculate the Mahalanobis distance between two points in CV space
output value	type
the Mahalanobis distances between the input vectors	scalar/vector

Further details and examples

Calculate the Mahalanobis distance between two points in CV space

If we have two $n$ -dimensional vectors $u$ and $v$ we can calculate the Mahalanobis distance between the two points as

$d = \sqrt{ \sum_{i=1}^n \sum_{j=1}^n m_{ij} (u_i - v_i)(u_j - v_j) }$

which can be expressed in matrix form as:

$d^2 = (u-v)^T M (u-v)$

The inputs below shows an example where this is used to calculate the Mahalanobis distance between the instaneous values of some torsional angles and some reference values for these distances. The inverse covriance values are provided in the constant value with label m. In this first example the input values are vectors:

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

mThe CONSTANT action with label m calculates the following quantities: Quantity    Type    Description  
m matrix the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details VALUESthe numbers that are in your constant value=2.45960237E-0001,-1.30615381E-0001,-1.30615381E-0001,2.40239117E-0001 NROWS the number of rows in your input matrix=2 NCOLS the number of columns in your matrix=2
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
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  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
ddThe MAHALANOBIS_DISTANCE action with label dd calculates the following quantities: Quantity    Type    Description  
dd scalar the Mahalanobis distances between the input vectors: MAHALANOBIS_DISTANCECalculate the Mahalanobis distance between two points in CV space 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 METRICThe inverse covariance matrix that should be used when calculating the distance=m
# PLUMED interprets the command:
# dd: MAHALANOBIS_DISTANCE ARG1=c ARG2=d METRIC=m
# as follows (Click the red comment above to revert to the short version of the input):
dd_diffThe TRANSPOSE action with label dd_diff calculates the following quantities: Quantity    Type    Description  
dd_diff matrix the transpose of the input matrix: DISPLACEMENTCalculate the displacement vector between the pair of input vectors More details ARG1The point that we are calculating the distance from=c ARG2The point that we are calculating the distance to=d
dd_diffTThe TRANSPOSE action with label dd_diffT calculates the following quantities: Quantity    Type    Description  
dd_diffT vector 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_diff
dd_matvecThe MATRIX_VECTOR_PRODUCT action with label dd_matvec calculates the following quantities: Quantity    Type    Description  
dd_matvec 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=m,dd_diffT
dd_2The MATRIX_PRODUCT_DIAGONAL action with label dd_2 calculates the following quantities: Quantity    Type    Description  
dd_2 scalar a vector containing the diagonal elements of the matrix that obtaned by multiplying the two input matrices together: MATRIX_PRODUCT_DIAGONALCalculate the product of two matrices and return a vector that contains the diagonal elements of the ouptut vector More details ARGthe two vectors/matrices whose product are to be taken=dd_diff,dd_matvec
ddThe CUSTOM action with label dd calculates the following quantities: Quantity    Type    Description  
dd scalar an arbitrary function: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=dd_2 FUNCthe function you wish to evaluate=sqrt(x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# --- 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

while this second example does the same thing but uses scalars in input.

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

mThe CONSTANT action with label m calculates the following quantities: Quantity    Type    Description  
m matrix the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details VALUESthe numbers that are in your constant value=2.45960237E-0001,-1.30615381E-0001,-1.30615381E-0001,2.40239117E-0001 NROWS the number of rows in your input matrix=2 NCOLS the number of columns in your matrix=2
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
ddThe MAHALANOBIS_DISTANCE action with label dd calculates the following quantities: Quantity    Type    Description  
dd scalar the Mahalanobis distances between the input vectors: MAHALANOBIS_DISTANCECalculate the Mahalanobis distance between two points in CV space This action is a shortcut. More details ARG1The point that we are calculating the distance from=c1,c2 ARG2The point that we are calculating the distance to=d1,d2 METRICThe inverse covariance matrix that should be used when calculating the distance=m
# PLUMED interprets the command:
# dd: MAHALANOBIS_DISTANCE ARG1=c1,c2 ARG2=d1,d2 METRIC=m
# as follows (Click the red comment above to revert to the short version of the input):
dd_diffThe VSTACK action with label dd_diff calculates the following quantities: Quantity    Type    Description  
dd_diff matrix a matrix that contains the input vectors in its columns: DISPLACEMENTCalculate the displacement vector between the pair of input vectors More details ARG1The point that we are calculating the distance from=c1,c2 ARG2The point that we are calculating the distance to=d1,d2
dd_diffTThe TRANSPOSE action with label dd_diffT calculates the following quantities: Quantity    Type    Description  
dd_diffT vector 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_diff
dd_matvecThe MATRIX_VECTOR_PRODUCT action with label dd_matvec calculates the following quantities: Quantity    Type    Description  
dd_matvec 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=m,dd_diffT
dd_2The MATRIX_PRODUCT_DIAGONAL action with label dd_2 calculates the following quantities: Quantity    Type    Description  
dd_2 scalar a vector containing the diagonal elements of the matrix that obtaned by multiplying the two input matrices together: MATRIX_PRODUCT_DIAGONALCalculate the product of two matrices and return a vector that contains the diagonal elements of the ouptut vector More details ARGthe two vectors/matrices whose product are to be taken=dd_diff,dd_matvec
ddThe CUSTOM action with label dd calculates the following quantities: Quantity    Type    Description  
dd scalar an arbitrary function: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=dd_2 FUNCthe function you wish to evaluate=sqrt(x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# --- 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

Dealing with periodic variables

When you are calculating a distance from a reference point you need to be careful when the input variables are periodic. If you are calculating the distance using the EUCLIDEAN_DISTANCE and NORMALIZED_EUCLIDEAN_DISTANCE commands this is not a problem. The problems are specific to the Mahalanobis distance command and have been resolved in the papers that are cited below by defining the following alternatative to the Mahalanobis distance:

$d^2 = 2\sum_{i=1}^n m_{ii} \left[ 1 - \cos\left( \frac{2\pi(u_i-v_i)}{P_i} \right) \right] + \sum_{i\ne j} m_{ij} \sin\left( \frac{2\pi(u_i-v_i)}{P_i} \right) \sin\left( \frac{2\pi(u_j-v_j)}{P_j} \right)$

In this expression, $P_i$ indicates the periodicity of the domain for variable $i$ . If you would like to compute this distance with PLUMED you use the VON_MISSES shown below:

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

mThe CONSTANT action with label m calculates the following quantities: Quantity    Type    Description  
m matrix the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details VALUESthe numbers that are in your constant value=2.45960237E-0001,-1.30615381E-0001,-1.30615381E-0001,2.40239117E-0001 NROWS the number of rows in your input matrix=2 NCOLS the number of columns in your matrix=2
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
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  NROWS the number of rows in your input matrix=0 NCOLS the number of columns in your matrix=0
dThe TORSION action with label d calculates the following quantities: Quantity    Type    Description  
d 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
ddThe MAHALANOBIS_DISTANCE action with label dd calculates the following quantities: Quantity    Type    Description  
dd scalar the Mahalanobis distances between the input vectors: MAHALANOBIS_DISTANCECalculate the Mahalanobis distance between two points in CV space 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 METRICThe inverse covariance matrix that should be used when calculating the distance=m VON_MISSES Compute the mahalanobis distance in a way that is more sympathetic to the periodic boundary conditions
# PLUMED interprets the command:
# dd: MAHALANOBIS_DISTANCE ARG1=c ARG2=d METRIC=m VON_MISSES
# as follows (Click the red comment above to revert to the short version of the input):
dd_diffThe TRANSPOSE action with label dd_diff calculates the following quantities: Quantity    Type    Description  
dd_diff matrix the transpose of the input matrix: DISPLACEMENTCalculate the displacement vector between the pair of input vectors More details ARG1The point that we are calculating the distance from=c ARG2The point that we are calculating the distance to=d
dd_diffTThe TRANSPOSE action with label dd_diffT calculates the following quantities: Quantity    Type    Description  
dd_diffT vector 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_diff
dd_diagmetThe CONSTANT action with label dd_diagmet calculates the following quantities: Quantity    Type    Description  
dd_diagmet vector the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details VALUESthe numbers that are in your constant value=0.24596,0.240239
dd_offdiagmetThe CONSTANT action with label dd_offdiagmet calculates the following quantities: Quantity    Type    Description  
dd_offdiagmet matrix the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details NROWS the number of rows in your input matrix=2 NCOLS the number of columns in your matrix=2 VALUESthe numbers that are in your constant value=0,-0.130615,-0.130615,0
dd_scaledThe CUSTOM action with label dd_scaled calculates the following quantities: Quantity    Type    Description  
dd_scaled 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=dd_diffT FUNCthe function you wish to evaluate=2*pi*x/(pi--pi) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
dd_sinediffTThe CUSTOM action with label dd_sinediffT calculates the following quantities: Quantity    Type    Description  
dd_sinediffT 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=dd_scaled FUNCthe function you wish to evaluate=sin(x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
dd_sinediffThe TRANSPOSE action with label dd_sinediff calculates the following quantities: Quantity    Type    Description  
dd_sinediff 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_sinediffT
dd_matvecThe MATRIX_VECTOR_PRODUCT action with label dd_matvec calculates the following quantities: Quantity    Type    Description  
dd_matvec 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=m,dd_sinediffT
dd_offdiagThe MATRIX_PRODUCT_DIAGONAL action with label dd_offdiag calculates the following quantities: Quantity    Type    Description  
dd_offdiag scalar a vector containing the diagonal elements of the matrix that obtaned by multiplying the two input matrices together: MATRIX_PRODUCT_DIAGONALCalculate the product of two matrices and return a vector that contains the diagonal elements of the ouptut vector More details ARGthe two vectors/matrices whose product are to be taken=dd_sinediff,dd_matvec
dd_prodThe CUSTOM action with label dd_prod calculates the following quantities: Quantity    Type    Description  
dd_prod 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=dd_scaled,dd_diagmet FUNCthe function you wish to evaluate=2*(1-cos(x))*y PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
dd_matonesThe CONSTANT action with label dd_matones calculates the following quantities: Quantity    Type    Description  
dd_matones matrix the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details NROWS the number of rows in your input matrix=1 NCOLS the number of columns in your matrix=2 VALUESthe numbers that are in your constant value=1,1
dd_diagThe MATRIX_PRODUCT_DIAGONAL action with label dd_diag calculates the following quantities: Quantity    Type    Description  
dd_diag scalar a vector containing the diagonal elements of the matrix that obtaned by multiplying the two input matrices together: MATRIX_PRODUCT_DIAGONALCalculate the product of two matrices and return a vector that contains the diagonal elements of the ouptut vector More details ARGthe two vectors/matrices whose product are to be taken=dd_matones,dd_prod
dd_2The COMBINE action with label dd_2 calculates the following quantities: Quantity    Type    Description  
dd_2 scalar a linear compbination: COMBINECalculate a polynomial combination of a set of other variables. More details ARGthe values input to this function=dd_offdiag,dd_diag PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
ddThe CUSTOM action with label dd calculates the following quantities: Quantity    Type    Description  
dd scalar an arbitrary function: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=dd_2 FUNCthe function you wish to evaluate=sqrt(x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# --- 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

Calculating multiple distances

Suppose that we now have $m$ reference configurations we can define the following $m$ distances from these reference configurations:

$d_j^2 = (u-v_j)^T M (u-v_j)$

Lets suppose that we put the $m$ , $n$ -dimensional $(u-v_j)$ vectors in this expression into a $n\times m$ matrix, $A$ , by using the DISPLACEMENT command. It is then straightforward to show that the $d_j^2$ values in the above expression are the diagonal elements of the matrix product $A^T M A$ .

We can use this idea to calculate multiple MAHALANOBIS_DISTANCE values in the following inputs. This first example calculates the three distances between the instaneoues values of two torsions and three reference configurations.

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

mThe CONSTANT action with label m calculates the following quantities: Quantity    Type    Description  
m matrix the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details VALUESthe numbers that are in your constant value=2.45960237E-0001,-1.30615381E-0001,-1.30615381E-0001,2.40239117E-0001 NROWS the number of rows in your input matrix=2 NCOLS the number of columns in your matrix=2
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 MAHALANOBIS_DISTANCE action with label dd calculates the following quantities: Quantity    Type    Description  
dd vector the Mahalanobis distances between the input vectors: MAHALANOBIS_DISTANCECalculate the Mahalanobis distance between two points in CV space 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 METRICThe inverse covariance matrix that should be used when calculating the distance=m
# PLUMED interprets the command:
# dd: MAHALANOBIS_DISTANCE ARG1=psi,phi ARG2=ref_psi,ref_phi METRIC=m
# as follows (Click the red comment above to revert to the short version of the input):
dd_diffThe VSTACK action with label dd_diff calculates the following quantities: Quantity    Type    Description  
dd_diff matrix a matrix that contains the input vectors in its columns: DISPLACEMENTCalculate the displacement vector between the pair of input vectors 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
dd_diffTThe TRANSPOSE action with label dd_diffT calculates the following quantities: Quantity    Type    Description  
dd_diffT 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_diff
dd_matvecThe MATRIX_PRODUCT action with label dd_matvec calculates the following quantities: Quantity    Type    Description  
dd_matvec matrix the product of the two input matrices: MATRIX_PRODUCTCalculate the product of two matrices More details ARGthe label of the two matrices from which the product is calculated=m,dd_diffT
dd_2The MATRIX_PRODUCT_DIAGONAL action with label dd_2 calculates the following quantities: Quantity    Type    Description  
dd_2 vector a vector containing the diagonal elements of the matrix that obtaned by multiplying the two input matrices together: MATRIX_PRODUCT_DIAGONALCalculate the product of two matrices and return a vector that contains the diagonal elements of the ouptut vector More details ARGthe two vectors/matrices whose product are to be taken=dd_diff,dd_matvec
ddThe CUSTOM action with label dd calculates the following quantities: Quantity    Type    Description  
dd 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=dd_2 FUNCthe function you wish to evaluate=sqrt(x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# --- 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

This section example calculates the three distances between a single reference value for the two torsions and three instances of this pair of torsions.

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

mThe CONSTANT action with label m calculates the following quantities: Quantity    Type    Description  
m matrix the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details VALUESthe numbers that are in your constant value=2.45960237E-0001,-1.30615381E-0001,-1.30615381E-0001,2.40239117E-0001 NROWS the number of rows in your input matrix=2 NCOLS the number of columns in your matrix=2
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 MAHALANOBIS_DISTANCE action with label dd calculates the following quantities: Quantity    Type    Description  
dd vector the Mahalanobis distances between the input vectors: MAHALANOBIS_DISTANCECalculate the Mahalanobis distance between two points in CV space 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 METRICThe inverse covariance matrix that should be used when calculating the distance=m
# PLUMED interprets the command:
# dd: MAHALANOBIS_DISTANCE ARG1=psi,phi ARG2=ref_psi,ref_phi METRIC=m
# as follows (Click the red comment above to revert to the short version of the input):
dd_diffThe VSTACK action with label dd_diff calculates the following quantities: Quantity    Type    Description  
dd_diff matrix a matrix that contains the input vectors in its columns: DISPLACEMENTCalculate the displacement vector between the pair of input vectors 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
dd_diffTThe TRANSPOSE action with label dd_diffT calculates the following quantities: Quantity    Type    Description  
dd_diffT 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_diff
dd_matvecThe MATRIX_PRODUCT action with label dd_matvec calculates the following quantities: Quantity    Type    Description  
dd_matvec matrix the product of the two input matrices: MATRIX_PRODUCTCalculate the product of two matrices More details ARGthe label of the two matrices from which the product is calculated=m,dd_diffT
dd_2The MATRIX_PRODUCT_DIAGONAL action with label dd_2 calculates the following quantities: Quantity    Type    Description  
dd_2 vector a vector containing the diagonal elements of the matrix that obtaned by multiplying the two input matrices together: MATRIX_PRODUCT_DIAGONALCalculate the product of two matrices and return a vector that contains the diagonal elements of the ouptut vector More details ARGthe two vectors/matrices whose product are to be taken=dd_diff,dd_matvec
ddThe CUSTOM action with label dd calculates the following quantities: Quantity    Type    Description  
dd 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=dd_2 FUNCthe function you wish to evaluate=sqrt(x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# --- 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

This final example then computes three distances between three pairs of torsional angles and threee reference values for these three values.

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

mThe CONSTANT action with label m calculates the following quantities: Quantity    Type    Description  
m matrix the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details VALUESthe numbers that are in your constant value=2.45960237E-0001,-1.30615381E-0001,-1.30615381E-0001,2.40239117E-0001 NROWS the number of rows in your input matrix=2 NCOLS the number of columns in your matrix=2
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 MAHALANOBIS_DISTANCE action with label dd calculates the following quantities: Quantity    Type    Description  
dd vector the Mahalanobis distances between the input vectors: MAHALANOBIS_DISTANCECalculate the Mahalanobis distance between two points in CV space 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 METRICThe inverse covariance matrix that should be used when calculating the distance=m
# PLUMED interprets the command:
# dd: MAHALANOBIS_DISTANCE ARG1=psi,phi ARG2=ref_psi,ref_phi METRIC=m
# as follows (Click the red comment above to revert to the short version of the input):
dd_diffThe VSTACK action with label dd_diff calculates the following quantities: Quantity    Type    Description  
dd_diff matrix a matrix that contains the input vectors in its columns: DISPLACEMENTCalculate the displacement vector between the pair of input vectors 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
dd_diffTThe TRANSPOSE action with label dd_diffT calculates the following quantities: Quantity    Type    Description  
dd_diffT 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_diff
dd_matvecThe MATRIX_PRODUCT action with label dd_matvec calculates the following quantities: Quantity    Type    Description  
dd_matvec matrix the product of the two input matrices: MATRIX_PRODUCTCalculate the product of two matrices More details ARGthe label of the two matrices from which the product is calculated=m,dd_diffT
dd_2The MATRIX_PRODUCT_DIAGONAL action with label dd_2 calculates the following quantities: Quantity    Type    Description  
dd_2 vector a vector containing the diagonal elements of the matrix that obtaned by multiplying the two input matrices together: MATRIX_PRODUCT_DIAGONALCalculate the product of two matrices and return a vector that contains the diagonal elements of the ouptut vector More details ARGthe two vectors/matrices whose product are to be taken=dd_diff,dd_matvec
ddThe CUSTOM action with label dd calculates the following quantities: Quantity    Type    Description  
dd 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=dd_2 FUNCthe function you wish to evaluate=sqrt(x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# --- 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

Notice, finally, that you can also calculate multiple distances if you use the VON_MISSES option:

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

mThe CONSTANT action with label m calculates the following quantities: Quantity    Type    Description  
m matrix the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details VALUESthe numbers that are in your constant value=2.45960237E-0001,-1.30615381E-0001,-1.30615381E-0001,2.40239117E-0001 NROWS the number of rows in your input matrix=2 NCOLS the number of columns in your matrix=2
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 MAHALANOBIS_DISTANCE action with label dd calculates the following quantities: Quantity    Type    Description  
dd vector the Mahalanobis distances between the input vectors: MAHALANOBIS_DISTANCECalculate the Mahalanobis distance between two points in CV space 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 METRICThe inverse covariance matrix that should be used when calculating the distance=m VON_MISSES Compute the mahalanobis distance in a way that is more sympathetic to the periodic boundary conditions
# PLUMED interprets the command:
# dd: MAHALANOBIS_DISTANCE ARG1=psi,phi ARG2=ref_psi,ref_phi METRIC=m VON_MISSES
# as follows (Click the red comment above to revert to the short version of the input):
dd_diffThe VSTACK action with label dd_diff calculates the following quantities: Quantity    Type    Description  
dd_diff matrix a matrix that contains the input vectors in its columns: DISPLACEMENTCalculate the displacement vector between the pair of input vectors 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
dd_diffTThe TRANSPOSE action with label dd_diffT calculates the following quantities: Quantity    Type    Description  
dd_diffT 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_diff
dd_diagmetThe CONSTANT action with label dd_diagmet calculates the following quantities: Quantity    Type    Description  
dd_diagmet vector the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details VALUESthe numbers that are in your constant value=0.24596,0.240239
dd_offdiagmetThe CONSTANT action with label dd_offdiagmet calculates the following quantities: Quantity    Type    Description  
dd_offdiagmet matrix the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details NROWS the number of rows in your input matrix=2 NCOLS the number of columns in your matrix=2 VALUESthe numbers that are in your constant value=0,-0.130615,-0.130615,0
dd_scaledThe CUSTOM action with label dd_scaled calculates the following quantities: Quantity    Type    Description  
dd_scaled 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=dd_diffT FUNCthe function you wish to evaluate=2*pi*x/(pi--pi) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
dd_sinediffTThe CUSTOM action with label dd_sinediffT calculates the following quantities: Quantity    Type    Description  
dd_sinediffT 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=dd_scaled FUNCthe function you wish to evaluate=sin(x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
dd_sinediffThe TRANSPOSE action with label dd_sinediff calculates the following quantities: Quantity    Type    Description  
dd_sinediff 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_sinediffT
dd_matvecThe MATRIX_PRODUCT action with label dd_matvec calculates the following quantities: Quantity    Type    Description  
dd_matvec matrix the product of the two input matrices: MATRIX_PRODUCTCalculate the product of two matrices More details ARGthe label of the two matrices from which the product is calculated=dd_offdiagmet,dd_sinediffT
dd_offdiagThe MATRIX_PRODUCT_DIAGONAL action with label dd_offdiag calculates the following quantities: Quantity    Type    Description  
dd_offdiag vector a vector containing the diagonal elements of the matrix that obtaned by multiplying the two input matrices together: MATRIX_PRODUCT_DIAGONALCalculate the product of two matrices and return a vector that contains the diagonal elements of the ouptut vector More details ARGthe two vectors/matrices whose product are to be taken=dd_sinediff,dd_matvec
dd_onesThe CONSTANT action with label dd_ones calculates the following quantities: Quantity    Type    Description  
dd_ones vector the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details  VALUESthe numbers that are in your constant value=1,1,1
dd_mThe OUTER_PRODUCT action with label dd_m calculates the following quantities: Quantity    Type    Description  
dd_m matrix a matrix containing the outer product of the two input vectors that was obtained using the function that was input: OUTER_PRODUCTCalculate the outer product matrix of two vectors More details ARGthe labels of the two vectors from which the outer product is being computed=dd_diagmet,dd_ones
dd_prodThe CUSTOM action with label dd_prod calculates the following quantities: Quantity    Type    Description  
dd_prod 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=dd_scaled,dd_m FUNCthe function you wish to evaluate=2*(1-cos(x))*y PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
dd_matonesThe CONSTANT action with label dd_matones calculates the following quantities: Quantity    Type    Description  
dd_matones matrix the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details NROWS the number of rows in your input matrix=3 NCOLS the number of columns in your matrix=2 VALUESthe numbers that are in your constant value=1,1,1,1,1,1
dd_diagThe MATRIX_PRODUCT_DIAGONAL action with label dd_diag calculates the following quantities: Quantity    Type    Description  
dd_diag vector a vector containing the diagonal elements of the matrix that obtaned by multiplying the two input matrices together: MATRIX_PRODUCT_DIAGONALCalculate the product of two matrices and return a vector that contains the diagonal elements of the ouptut vector More details ARGthe two vectors/matrices whose product are to be taken=dd_matones,dd_prod
dd_2The COMBINE action with label dd_2 calculates the following quantities: Quantity    Type    Description  
dd_2 vector the vector obtained by doing an element-wise application of a linear compbination to the input vectors: COMBINECalculate a polynomial combination of a set of other variables. More details ARGthe values input to this function=dd_offdiag,dd_diag PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
ddThe CUSTOM action with label dd calculates the following quantities: Quantity    Type    Description  
dd 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=dd_2 FUNCthe function you wish to evaluate=sqrt(x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# --- 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

References

More information about how this action can be used is available in the following articles: - G. A. Tribello, M. Ceriotti, M. Parrinello, A self-learning algorithm for biased molecular dynamics. Proceedings of the National Academy of Sciences. 107, 17509–17514 (2010) - P. Gasparotto, R. H. Meißner, M. Ceriotti, Recognizing Local and Global Structural Motifs at the Atomic Scale. Journal of Chemical Theory and Computation. 14, 486–498 (2018)

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
METRIC	compulsory	none	The inverse covariance matrix that should be used when calculating the distance
SQUARED	optional	false	The squared distance should be calculated
VON_MISSES	optional	false	Compute the mahalanobis distance in a way that is more sympathetic to the periodic boundary conditions

Quantity	Type	Description
m	matrix	the constant value that was read from the plumed input