Shortcut: TETRA_ANGULAR

Module	symfunc
Description	Usage
Calculate the angular tetra CV
output value	type
the value of the angular tetehedrality parameter for each of the input atoms	vector

Details and examples

Calculate the angular tetra CV

This shortcut calculates a symmetry function. The particular function that is being evaluated for the coordination sphere here is as follows:

$s_i = 1 - \frac{3}{8}\sum_{j=2}^4 \sum_{k=1}^{j-1} \left( \cos(\theta_{jik} + \frac{1}{2} \right)^2$

In this expression the 4 atoms in the sums over $j$ and $k$ are the four atoms that are nearest to atom $i$ . $\theta_{jik}$ is the angle between the vectors connecting atoms $i$ and $j$ and the vector connecting atoms $i$ and $k$ . The CV is large if the four atoms nearest atom $i$ are arranged on the vertices of a regular tetrahedron and small otherwise. The following example shows how you can use this action to measure the degree of tetrahedral order in a system.

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

# Calculate a vector that contains 64 values for the symmetry function.
acvThe TETRA_ANGULAR action with label acv calculates the following quantities: Quantity    Type    Description  
acv vector the value of the angular tetehedrality parameter for each of the input atoms: TETRA_ANGULARCalculate the angular tetra CV This action is a shortcut and it has hidden defaults. More details SPECIESthe list of atoms for which the symmetry function is being calculated and the atoms that can be in the environments=1-64
acv: TETRA_ANGULARCalculate the angular tetra CV This action is a shortcut and uses the defaults shown here. More details SPECIESthe list of atoms for which the symmetry function is being calculated and the atoms that can be in the environments=1-64  CUTOFF ignore distances that have a value larger than this cutoff=-1
# PLUMED interprets the command:
# acv: TETRA_ANGULAR SPECIES=1-64
# as follows (Click the red comment above to revert to the short version of the input):
acv_matThe DISTANCE_MATRIX action with label acv_mat calculates the following quantities: Quantity    Type    Description  
acv_mat.w matrix a matrix containing the weights for the bonds between each pair of atoms
acv_mat.x matrix the projection of the bond on the x axis
acv_mat.y matrix the projection of the bond on the y axis
acv_mat.z matrix the projection of the bond on the z axis: DISTANCE_MATRIXCalculate a matrix of distances between atoms. More details COMPONENTS also calculate the components of the vector connecting the atoms in the contact matrix GROUPthe atoms for which you would like to calculate the adjacency matrix=1-64 CUTOFF ignore distances that have a value larger than this cutoff=-1
acv_neighThe NEIGHBORS action with label acv_neigh calculates the following quantities: Quantity    Type    Description  
acv_neigh matrix a matrix in which the ij element is one if the ij-element of the input matrix is one of the NLOWEST/NHIGHEST elements on that row of the input matrix and zero otherwise: NEIGHBORSBuild a matrix with ones in for the N nearest neighbours of an atom More details ARGthe label of an adjacency/distance matrix that will be used to find the nearest neighbors=acv_mat.w NLOWEST in each row of the output matrix set the elements that correspond to the n lowest elements in each row of the input matrix equal to one=4
acv_g8The GSYMFUNC_THREEBODY action with label acv_g8 calculates the following quantities: Quantity    Type    Description  
acv_g8.g8 vector the function defined by the FUNCTION1 keyword: GSYMFUNC_THREEBODYCalculate functions of the coordinates of the coordinates of all pairs of bonds in the first coordination sphere of an atom More details WEIGHTthe matrix that contains the weights that should be used for each connection=acv_neigh ARGthree matrices containing the bond vectors of interest=acv_mat.x,acv_mat.y,acv_mat.z FUNCTION1the parameters of the function you would like to compute={FUNC=(cos(ajik)+1/3)^2 LABEL=g8}
acvThe CUSTOM action with label acv calculates the following quantities: Quantity    Type    Description  
acv 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=acv_g8.g8 FUNCthe function you wish to evaluate=(1-(3*x/8)) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# --- End of included input --- # Sum the elements of the vector and calculate the mean value on the atoms from this sum.
acv_sumThe SUM action with label acv_sum calculates the following quantities: Quantity    Type    Description  
acv_sum 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=acv PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
acv_meanThe MEAN action with label acv_mean calculates the following quantities: Quantity    Type    Description  
acv_mean scalar the MEAN of the elements in the input value: MEANCalculate the arithmetic mean of the elements in a vector More details ARGthe vector/matrix/grid whose elements shuld be added together=acv PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# Print out the positions of the 64 atoms for which the symmetry function was calculated
# to an xyz file along with the values of the symmetry function
DUMPATOMSDump selected atoms on a file. More details ATOMSthe atom indices whose positions you would like to print out=1-64 ARGthe labels of vectors that should be output in the xyz file=acv FILEfile on which to output coordinates; extension is automatically detected=mcolv.xyz
# Print out the average value of the symmetry function and the sum of all the symmetry functions
The DUMPATOMS action with label  calculates somethingPRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=acv_sum,acv_mean FILEthe name of the file on which to output these quantities=colvar

In the input above we have only one type of atom. If you want to measure the degree of tetrahedral order amongst the bonds from atoms of SPECIESA to atoms of SPECIESB you use an input like the one shown below:

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

acvThe TETRA_ANGULAR action with label acv calculates the following quantities: Quantity    Type    Description  
acv vector the value of the angular tetehedrality parameter for each of the input atoms: TETRA_ANGULARCalculate the angular tetra CV This action is a shortcut and it has hidden defaults. More details SPECIESAthe list of atoms for which the symmetry function is being calculated=1-64 SPECIESBthe list of atoms that can be in the environments of each of the atoms for which the symmetry function is being calculated=65-128
acv: TETRA_ANGULARCalculate the angular tetra CV This action is a shortcut and uses the defaults shown here. More details SPECIESAthe list of atoms for which the symmetry function is being calculated=1-64 SPECIESBthe list of atoms that can be in the environments of each of the atoms for which the symmetry function is being calculated=65-128  CUTOFF ignore distances that have a value larger than this cutoff=-1
# PLUMED interprets the command:
# acv: TETRA_ANGULAR SPECIESA=1-64 SPECIESB=65-128
# as follows (Click the red comment above to revert to the short version of the input):
acv_matThe DISTANCE_MATRIX action with label acv_mat calculates the following quantities: Quantity    Type    Description  
acv_mat.w matrix a matrix containing the weights for the bonds between each pair of atoms
acv_mat.x matrix the projection of the bond on the x axis
acv_mat.y matrix the projection of the bond on the y axis
acv_mat.z matrix the projection of the bond on the z axis: DISTANCE_MATRIXCalculate a matrix of distances between atoms. More details COMPONENTS also calculate the components of the vector connecting the atoms in the contact matrix GROUPAwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPB=1-64 GROUPBwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPA=65-128 CUTOFF ignore distances that have a value larger than this cutoff=-1
acv_neighThe NEIGHBORS action with label acv_neigh calculates the following quantities: Quantity    Type    Description  
acv_neigh matrix a matrix in which the ij element is one if the ij-element of the input matrix is one of the NLOWEST/NHIGHEST elements on that row of the input matrix and zero otherwise: NEIGHBORSBuild a matrix with ones in for the N nearest neighbours of an atom More details ARGthe label of an adjacency/distance matrix that will be used to find the nearest neighbors=acv_mat.w NLOWEST in each row of the output matrix set the elements that correspond to the n lowest elements in each row of the input matrix equal to one=4
acv_g8The GSYMFUNC_THREEBODY action with label acv_g8 calculates the following quantities: Quantity    Type    Description  
acv_g8.g8 vector the function defined by the FUNCTION1 keyword: GSYMFUNC_THREEBODYCalculate functions of the coordinates of the coordinates of all pairs of bonds in the first coordination sphere of an atom More details WEIGHTthe matrix that contains the weights that should be used for each connection=acv_neigh ARGthree matrices containing the bond vectors of interest=acv_mat.x,acv_mat.y,acv_mat.z FUNCTION1the parameters of the function you would like to compute={FUNC=(cos(ajik)+1/3)^2 LABEL=g8}
acvThe CUSTOM action with label acv calculates the following quantities: Quantity    Type    Description  
acv 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=acv_g8.g8 FUNCthe function you wish to evaluate=(1-(3*x/8)) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# --- End of included input --- acv_sumThe SUM action with label acv_sum calculates the following quantities: Quantity    Type    Description  
acv_sum 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=acv PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
acv_meanThe MEAN action with label acv_mean calculates the following quantities: Quantity    Type    Description  
acv_mean scalar the MEAN of the elements in the input value: MEANCalculate the arithmetic mean of the elements in a vector More details ARGthe vector/matrix/grid whose elements shuld be added together=acv PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
DUMPATOMSDump selected atoms on a file. More details ATOMSthe atom indices whose positions you would like to print out=1-64 ARGthe labels of vectors that should be output in the xyz file=acv FILEfile on which to output coordinates; extension is automatically detected=mcolv.xyz
The DUMPATOMS action with label  calculates somethingPRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=acv_sum,acv_mean FILEthe name of the file on which to output these quantities=colvar

By default the vectors connecting atoms that appear in the expression above are calculated in a way that takes periodic boundary conditions into account. If you want not to take the periodic boundary conditions into account for any reason you use the NOPBC flag as shown below:

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

acvThe TETRA_ANGULAR action with label acv calculates the following quantities: Quantity    Type    Description  
acv vector the value of the angular tetehedrality parameter for each of the input atoms: TETRA_ANGULARCalculate the angular tetra CV This action is a shortcut and it has hidden defaults. More details SPECIESthe list of atoms for which the symmetry function is being calculated and the atoms that can be in the environments=1-64 NOPBC ignore the periodic boundary conditions when calculating distances
acv: TETRA_ANGULARCalculate the angular tetra CV This action is a shortcut and uses the defaults shown here. More details SPECIESthe list of atoms for which the symmetry function is being calculated and the atoms that can be in the environments=1-64 NOPBC ignore the periodic boundary conditions when calculating distances  CUTOFF ignore distances that have a value larger than this cutoff=-1
# PLUMED interprets the command:
# acv: TETRA_ANGULAR SPECIES=1-64 NOPBC
# as follows (Click the red comment above to revert to the short version of the input):
acv_matThe DISTANCE_MATRIX action with label acv_mat calculates the following quantities: Quantity    Type    Description  
acv_mat.w matrix a matrix containing the weights for the bonds between each pair of atoms
acv_mat.x matrix the projection of the bond on the x axis
acv_mat.y matrix the projection of the bond on the y axis
acv_mat.z matrix the projection of the bond on the z axis: DISTANCE_MATRIXCalculate a matrix of distances between atoms. More details COMPONENTS also calculate the components of the vector connecting the atoms in the contact matrix GROUPthe atoms for which you would like to calculate the adjacency matrix=1-64 CUTOFF ignore distances that have a value larger than this cutoff=-1 NOPBC don't use pbc
acv_neighThe NEIGHBORS action with label acv_neigh calculates the following quantities: Quantity    Type    Description  
acv_neigh matrix a matrix in which the ij element is one if the ij-element of the input matrix is one of the NLOWEST/NHIGHEST elements on that row of the input matrix and zero otherwise: NEIGHBORSBuild a matrix with ones in for the N nearest neighbours of an atom More details ARGthe label of an adjacency/distance matrix that will be used to find the nearest neighbors=acv_mat.w NLOWEST in each row of the output matrix set the elements that correspond to the n lowest elements in each row of the input matrix equal to one=4
acv_g8The GSYMFUNC_THREEBODY action with label acv_g8 calculates the following quantities: Quantity    Type    Description  
acv_g8.g8 vector the function defined by the FUNCTION1 keyword: GSYMFUNC_THREEBODYCalculate functions of the coordinates of the coordinates of all pairs of bonds in the first coordination sphere of an atom More details WEIGHTthe matrix that contains the weights that should be used for each connection=acv_neigh ARGthree matrices containing the bond vectors of interest=acv_mat.x,acv_mat.y,acv_mat.z FUNCTION1the parameters of the function you would like to compute={FUNC=(cos(ajik)+1/3)^2 LABEL=g8}
acvThe CUSTOM action with label acv calculates the following quantities: Quantity    Type    Description  
acv 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=acv_g8.g8 FUNCthe function you wish to evaluate=(1-(3*x/8)) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# --- End of included input --- acv_sumThe SUM action with label acv_sum calculates the following quantities: Quantity    Type    Description  
acv_sum 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=acv PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
acv_meanThe MEAN action with label acv_mean calculates the following quantities: Quantity    Type    Description  
acv_mean scalar the MEAN of the elements in the input value: MEANCalculate the arithmetic mean of the elements in a vector More details ARGthe vector/matrix/grid whose elements shuld be added together=acv PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
DUMPATOMSDump selected atoms on a file. More details ATOMSthe atom indices whose positions you would like to print out=1-64 ARGthe labels of vectors that should be output in the xyz file=acv FILEfile on which to output coordinates; extension is automatically detected=mcolv.xyz
The DUMPATOMS action with label  calculates somethingPRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=acv_sum,acv_mean FILEthe name of the file on which to output these quantities=colvar

Deprecated syntax

More information on the deprecated keywords that are given below is available in the documentation for the DISTANCES command.

Input

The 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
SPECIES	atoms	the list of atoms for which the symmetry function is being calculated and the atoms that can be in the environments
SPECIESA	atoms	the list of atoms for which the symmetry function is being calculated
SPECIESB	atoms	the list of atoms that can be in the environments of each of the atoms for which the symmetry function is being calculated

Output components

This action can calculate the values in the following table when the associated keyword is included in the input for the action. These values can be referenced elsewhere in the input by using this Action's label followed by a dot and the name of the value required from the list below.

Name	Type	Keyword	Description
lessthan	scalar	LESS_THAN	the number of colvars that have a value less than a threshold
morethan	scalar	MORE_THAN	the number of colvars that have a value more than a threshold
altmin	scalar	ALT_MIN	the minimum value of the cv
min	scalar	MIN	the minimum colvar
max	scalar	MAX	the maximum colvar
between	scalar	BETWEEN	the number of colvars that have a value that lies in a particular interval
highest	scalar	HIGHEST	the largest of the colvars
lowest	scalar	LOWEST	the smallest of the colvars
sum	scalar	SUM	the sum of the colvars
mean	scalar	MEAN	the mean of the colvars

Full list of keywords

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

Keyword	Type	Default	Description
SPECIES	input	none	the list of atoms for which the symmetry function is being calculated and the atoms that can be in the environments
SPECIESA	input	none	the list of atoms for which the symmetry function is being calculated
SPECIESB	input	none	the list of atoms that can be in the environments of each of the atoms for which the symmetry function is being calculated
CUTOFF	compulsory	-1	ignore distances that have a value larger than this cutoff
NOPBC	optional	false	ignore the periodic boundary conditions when calculating distances

deprecated keywords

The keywords in the following table can still be used with this action but have been deprecated

Keyword	Description
LESS_THAN	calculate the number of variables that are less than a certain target value
MORE_THAN	calculate the number of variables that are more than a certain target value
ALT_MIN	calculate the minimum value
MIN	calculate the minimum value
MAX	calculate the maximum value
BETWEEN	calculate the number of values that are within a certain range
HIGHEST	this flag allows you to recover the highest of these variables
HISTOGRAM	calculate a discretized histogram of the distribution of values
LOWEST	this flag allows you to recover the lowest of these variables
SUM	calculate the sum of all the quantities
MEAN	calculate the mean of all the quantities

References

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

A. D. White, G. A. Voth, Efficient and Minimal Method to Bias Molecular Simulations with Experimental Data. Journal of Chemical Theory and Computation. 10, 3023–3030 (2014)

Quantity	Type	Description
acv	vector	the value of the angular tetehedrality parameter for each of the input atoms