Action: TORSIONS_MATRIX

Module	adjmat
Description	Usage
Calculate the matrix of torsions between two vectors of molecules
output value	type
the matrix of torsions between the two vectors of input directors	matrix

Details and examples

Calculate the matrix of torsions between two vectors of molecules

This action was implemented to ensure that we can calculate the SMAC collective variable that is discussed in this paper. This particular action tracks the relative orientations for all the pairs of molecules in a set much like the variables described in the crystdistrib module.

The orientations of molecules can be specified using either PLANE or DISTANCE. The example below shows how you can use internal vectors connecting two atoms in the molecules to define the orientation of that molecule. Three of these internal vectors are calculated using a DISTANCE command in the input below. The matrix of torsional angles between these various vectors is then computed:

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

d1The DISTANCE action with label d1 calculates the following quantities: Quantity    Type    Description  
d1.x vector the x-component of the vector connecting the two atoms
d1.y vector the y-component of the vector connecting the two atoms
d1.z vector the z-component of the vector connecting the two atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMS1the pair of atom that we are calculating the distance between=1,5 ATOMS2the pair of atom that we are calculating the distance between=11,15 ATOMS3the pair of atom that we are calculating the distance between=21,25 COMPONENTS calculate the x, y and z components of the distance separately and store them as label
sThe VSTACK action with label s calculates the following quantities: Quantity    Type    Description  
s 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=d1.x,d1.y,d1.z
sTThe TRANSPOSE action with label sT calculates the following quantities: Quantity    Type    Description  
sT 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=s
mThe TORSIONS_MATRIX action with label m calculates the following quantities: Quantity    Type    Description  
m matrix the matrix of torsions between the two vectors of input directors: TORSIONS_MATRIXCalculate the matrix of torsions between two vectors of molecules More details ARGan Nx3 and a 3xN matrix that contain the bond vectors that you would like to determine the torsion angles between=s,sT POSITIONS1the positions to use for the molecules specified using the first argument=1,11,21 POSITIONS2the positions to use for the molecules specified using the second argument=1,11,21
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=m FILEthe name of the file on which to output these quantities=matrix

In this example, the torsional angle in element $(1,2)$ of the matrix with label m is the angle between the plane containing atoms 1,5 and 10 and the plane connecting atoms 1,10 and 15. In other words, the elements in this matrix are the torsional angles between the vectors in the input matrices around the vector connecting the corresponding atomic positions that are specified using the POSTIONS keyword.

You can also calculate a matrix of torsional angles between two different groups of molecules by using an input like the one below:

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

pAThe PLANE action with label pA calculates the following quantities: Quantity    Type    Description  
pA.x vector the x-component of the vector that is normal to the plane containing the atoms
pA.y vector the y-component of the vector that is normal to the plane containing the atoms
pA.z vector the z-component of the vector that is normal to the plane containing the atoms: PLANECalculate the plane perpendicular to two vectors in order to represent the orientation of a planar molecule. More details ATOMS1the three or four atoms whose plane we are computing=1,2,3 ATOMS2the three or four atoms whose plane we are computing=11,12,13
sAThe VSTACK action with label sA calculates the following quantities: Quantity    Type    Description  
sA 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=pA.x,pA.y,pA.z
pBThe PLANE action with label pB calculates the following quantities: Quantity    Type    Description  
pB.x vector the x-component of the vector that is normal to the plane containing the atoms
pB.y vector the y-component of the vector that is normal to the plane containing the atoms
pB.z vector the z-component of the vector that is normal to the plane containing the atoms: PLANECalculate the plane perpendicular to two vectors in order to represent the orientation of a planar molecule. More details ATOMS1the three or four atoms whose plane we are computing=21,22,23 ATOMS2the three or four atoms whose plane we are computing=31,32,33 ATOMS3the three or four atoms whose plane we are computing=41,42,43
sBThe VSTACK action with label sB calculates the following quantities: Quantity    Type    Description  
sB 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=pB.x,pB.y,pB.z
sBTThe TRANSPOSE action with label sBT calculates the following quantities: Quantity    Type    Description  
sBT 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=sB
mThe TORSIONS_MATRIX action with label m calculates the following quantities: Quantity    Type    Description  
m matrix the matrix of torsions between the two vectors of input directors: TORSIONS_MATRIXCalculate the matrix of torsions between two vectors of molecules More details ARGan Nx3 and a 3xN matrix that contain the bond vectors that you would like to determine the torsion angles between=sA,sBT POSITIONS1the positions to use for the molecules specified using the first argument=1,11 POSITIONS2the positions to use for the molecules specified using the second argument=21,31,41
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=m FILEthe name of the file on which to output these quantities=matrix

In this example, the orientations of the molecules are specified using the PLANE action and is given by a normal to the plane containing the three atoms from the molecule that was specified. The final output is $2 \times 3$ matrix that contains all the torsional angles between the molecules defined by the two PLANE actions.

Performance considerations

Suppose that you are using an input like the one shown below to calculate the average torsion angle between neighboring molecules:

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

# Notice that in a realistic version of this calculation you would likely
# by calculating the orientations of many more molecules using this command
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,5 ATOMS2the pair of atom that we are calculating the distance between=11,15 ATOMS3the pair of atom that we are calculating the distance between=21,25 ATOMS4the pair of atom that we are calculating the distance between=31,35
sThe VSTACK action with label s calculates the following quantities: Quantity    Type    Description  
s 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=d.x,d.y,d.z
sTThe TRANSPOSE action with label sT calculates the following quantities: Quantity    Type    Description  
sT 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=s
#  Calculate a contact matrix in which element i,j is 1 if molecules
# i and j are neighbors.
cThe CONTACT_MATRIX action with label c calculates the following quantities: Quantity    Type    Description  
c matrix a matrix containing the weights for the bonds between each pair of atoms: CONTACT_MATRIXAdjacency matrix in which two atoms are adjacent if they are within a certain cutoff. More details GROUPspecifies the list of atoms that should be assumed indistinguishable=1,11,21,35 SWITCHthe input for the switching function that acts upon the distance between each pair of atoms. Options for this keyword are explained in the documentation for LESS_THAN.={RATIONAL R_0=0.1 D_MAX=0.3}
# Now calculate all the torsions
tThe TORSIONS_MATRIX action with label t calculates the following quantities: Quantity    Type    Description  
t matrix the matrix of torsions between the two vectors of input directors: TORSIONS_MATRIXCalculate the matrix of torsions between two vectors of molecules More details ARGan Nx3 and a 3xN matrix that contain the bond vectors that you would like to determine the torsion angles between=s,sT POSITIONS1the positions to use for the molecules specified using the first argument=1,11,21,31 POSITIONS2the positions to use for the molecules specified using the second argument=1,11,21,31
# And the product between the contact matrix and the torsions
tcThe CUSTOM action with label tc calculates the following quantities: Quantity    Type    Description  
tc 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=c,t FUNCthe function you wish to evaluate=x*y PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# Total of all the torsional angles in the first coordination sphere
tsumThe SUM action with label tsum calculates the following quantities: Quantity    Type    Description  
tsum scalar the SUM of the elements in the input value: SUMCalculate the sum of the arguments More details ARGthe vector/matrix/grid whose elements shuld be added together=tc PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# Total number of neighbouring atoms
bsumThe SUM action with label bsum calculates the following quantities: Quantity    Type    Description  
bsum scalar the SUM of the elements in the input value: SUMCalculate the sum of the arguments More details ARGthe vector/matrix/grid whose elements shuld be added together=c PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# And finally the average torsion angle
avtThe CUSTOM action with label avt calculates the following quantities: Quantity    Type    Description  
avt 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=tc,c FUNCthe function you wish to evaluate=x/y PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO

If you have a large number of molecules the most expensive part of this calculation will be the evalulation of the TORSIONS_MATRIX as you need to evaluate one torsion anlge for every pair of molecules. Furthermore, this computation is unecessary as most pairs of molecules will not be neighbors. In other words, for the majority of the molecular pairs element the corresponding element of the CONTACT_MATRIX will be zero. Consequently, when you compute the the corresponding element tc by multiplying the torsion $i,j$ by the crresponding $i,j$ element of the CONTACT_MATRIX you will get zero.

Thankfully PLUMED allows you to exploit this fact through the MASK keyword as illustrated below:

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

# Notice that in a realistic version of this calculation you would likely
# by calculating the orientations of many more molecules using this command
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,5 ATOMS2the pair of atom that we are calculating the distance between=11,15 ATOMS3the pair of atom that we are calculating the distance between=21,25 ATOMS4the pair of atom that we are calculating the distance between=31,35
sThe VSTACK action with label s calculates the following quantities: Quantity    Type    Description  
s 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=d.x,d.y,d.z
sTThe TRANSPOSE action with label sT calculates the following quantities: Quantity    Type    Description  
sT 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=s
#  Calculate a contact matrix in which element i,j is 1 if molecules
# i and j are neighbors.
cThe CONTACT_MATRIX action with label c calculates the following quantities: Quantity    Type    Description  
c matrix a matrix containing the weights for the bonds between each pair of atoms: CONTACT_MATRIXAdjacency matrix in which two atoms are adjacent if they are within a certain cutoff. More details GROUPspecifies the list of atoms that should be assumed indistinguishable=1,11,21,35 SWITCHthe input for the switching function that acts upon the distance between each pair of atoms. Options for this keyword are explained in the documentation for LESS_THAN.={RATIONAL R_0=0.1 D_MAX=0.3}
# Now calculate all the torsions
tThe TORSIONS_MATRIX action with label t calculates the following quantities: Quantity    Type    Description  
t matrix the matrix of torsions between the two vectors of input directors: TORSIONS_MATRIXCalculate the matrix of torsions between two vectors of molecules More details ...
   MASKa matrix that is used to used to determine which elements of this matrix to compute=c ARGan Nx3 and a 3xN matrix that contain the bond vectors that you would like to determine the torsion angles between=s,sT
   POSITIONS1the positions to use for the molecules specified using the first argument=1,11,21,31 POSITIONS2the positions to use for the molecules specified using the second argument=1,11,21,31
...
# And the product between the contact matrix and the torsions
tcThe CUSTOM action with label tc calculates the following quantities: Quantity    Type    Description  
tc 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=c,t FUNCthe function you wish to evaluate=x*y PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# Total of all the torsional angles in the first coordination sphere
tsumThe SUM action with label tsum calculates the following quantities: Quantity    Type    Description  
tsum scalar the SUM of the elements in the input value: SUMCalculate the sum of the arguments More details ARGthe vector/matrix/grid whose elements shuld be added together=tc PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# Total number of neighbouring atoms
bsumThe SUM action with label bsum calculates the following quantities: Quantity    Type    Description  
bsum scalar the SUM of the elements in the input value: SUMCalculate the sum of the arguments More details ARGthe vector/matrix/grid whose elements shuld be added together=c PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# And finally the average torsion angle
avtThe CUSTOM action with label avt calculates the following quantities: Quantity    Type    Description  
avt 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=tc,c FUNCthe function you wish to evaluate=x/y PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO

Adding the instruction MASK=c to the TORSIONS_MATRIX command here ensures that element $i,j$ of the matrix t is only computed if the corresponding element of c is non-zero. By using this command you thus avoid the computational expense associated with evaluating the full set of pairwise torsions.

Input

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

Keyword	Type	Description
MASK	matrix	a matrix that is used to used to determine which elements of this matrix to compute
ARG	matrix	an Nx3 and a 3xN matrix that contain the bond vectors that you would like to determine the torsion angles between
POSITIONS1	atoms	the positions to use for the molecules specified using the first argument
POSITIONS2	atoms	the positions to use for the molecules specified using the second argument

Full list of keywords

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

Keyword	Type	Default	Description
MASK	input	none	a matrix that is used to used to determine which elements of this matrix to compute
ARG	input	none	an Nx3 and a 3xN matrix that contain the bond vectors that you would like to determine the torsion angles between
POSITIONS1	input	none	the positions to use for the molecules specified using the first argument
POSITIONS2	input	none	the positions to use for the molecules specified using the second argument
SERIAL	optional	false	do the calculation in serial. Further information about this flag can be found here.
USEGPU	optional	false	run this calculation on the GPU. Further information about this flag can be found here.

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