Shortcut: COORDINATION_SHELL_FUNCTION

Module	symfunc
Description	Usage
Calculate an arbitrary function of all the bond vectors in the first coordination sphere of an atom
output value	type
the symmetry function for each of the specified atoms	vector

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.

Input

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

Further details and examples

Calculate an arbitrary function of all the bond vectors in the first coordination sphere of an atom

This shortcut allows you to calculate the sum for an arbitrary function of the bond vectors that connect an atom to each of its neighbours. In other words, this action allows you to compute the following:

$$s_i = \sum_{i \ne j} \sigma(r_{ij}) f(x_{ij}, y_{ij}, z_{ij}, r_{ij}) )$$

In this expression, $x_{ij}, y_{ij}, z_{ij}$ are the components of the vector connecting atoms $i$ and $j$ and $r_{ij}$ is the magnitude of this vector. $\sigma(r_{ij})$ is then a switching function that ensures that the aritrary function $f$ is only evaluated for if atom $j$ is within a certain cutoff distance of atom $i$.

Below you can see a simple example that shows how this action can be used in practise.

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

cvThe COORDINATION_SHELL_FUNCTION action with label cv calculates the following quantities:
 Quantity   
 Type   
 Description  
cv
vector
the symmetry function for each of the specified atoms: COORDINATION_SHELL_FUNCTIONCalculate an arbitrary function of all the bond vectors in the first coordination sphere of an atom 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 SWITCHthe switching function that it used in the construction of the contact matrix. Options for this keyword are explained in the documentation for LESS_THAN.={RATIONAL D_0=3.0 R_0=1.5} FUNCTIONthe function of the bond vectors that you would like to evaluate=((x+y+z)/r)^3+((x-y-z)/r)^3+((-x+y-z)/r)^3+((-x-y+z)/r)^3
cv: COORDINATION_SHELL_FUNCTIONCalculate an arbitrary function of all the bond vectors in the first coordination sphere of an atom 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 SWITCHthe switching function that it used in the construction of the contact matrix. Options for this keyword are explained in the documentation for LESS_THAN.={RATIONAL D_0=3.0 R_0=1.5} FUNCTIONthe function of the bond vectors that you would like to evaluate=((x+y+z)/r)^3+((x-y-z)/r)^3+((-x+y-z)/r)^3+((-x-y+z)/r)^3  PHI The Euler rotational angle phi=0.0 THETA The Euler rotational angle theta=0.0 PSI The Euler rotational angle psi=0.0
# PLUMED interprets the command:
# cv: COORDINATION_SHELL_FUNCTION SPECIES=1-64 SWITCH={RATIONAL D_0=3.0 R_0=1.5} FUNCTION=((x+y+z)/r)^3+((x-y-z)/r)^3+((-x+y-z)/r)^3+((-x-y+z)/r)^3
# as follows (Click the red comment above to revert to the short version of the input):
cv_grpThe GROUP action with label cv_grp calculates the following quantities:
 Quantity   
 Type   
 Description  
cv_grp
atoms
indices of atoms specified in GROUP: GROUPDefine a group of atoms so that a particular list of atoms can be referenced with a single label in definitions of CVs or virtual atoms. More details ATOMSthe numerical indexes for the set of atoms in the group=1-64
cv_matThe CONTACT_MATRIX action with label cv_mat calculates the following quantities:
 Quantity   
 Type   
 Description  
cv_mat.w
matrix
a matrix containing the weights for the bonds between each pair of atoms
cv_mat.x
matrix
the projection of the bond on the x axis
cv_mat.y
matrix
the projection of the bond on the y axis
cv_mat.z
matrix
the projection of the bond on the z axis: 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-64 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 D_0=3.0 R_0=1.5} COMPONENTS also calculate the components of the vectors connecting the atoms in the contact matrix
cv_rThe CUSTOM action with label cv_r calculates the following quantities:
 Quantity   
 Type   
 Description  
cv_r
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=cv_mat.x,cv_mat.y,cv_mat.z PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO FUNCthe function you wish to evaluate=sqrt(x*x+y*y+z*z)
cv_vfuncThe CUSTOM action with label cv_vfunc calculates the following quantities:
 Quantity   
 Type   
 Description  
cv_vfunc
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=cv_mat.x,cv_mat.y,cv_mat.z,cv_r VARthe names to give each of the arguments in the function=x,y,z,r PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO FUNCthe function you wish to evaluate=((x+y+z)/r)^3+((x-y-z)/r)^3+((-x+y-z)/r)^3+((-x-y+z)/r)^3
cv_wvfuncThe CUSTOM action with label cv_wvfunc calculates the following quantities:
 Quantity   
 Type   
 Description  
cv_wvfunc
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=cv_vfunc,cv_mat.w 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
cv_onesThe CONSTANT action with label cv_ones calculates the following quantities:
 Quantity   
 Type   
 Description  
cv_ones
vector
the constant value that was read from the plumed input: ONESCreate a constant vector with all elements equal to one More details SIZEthe number of ones that you would like to create=64
cvThe MATRIX_VECTOR_PRODUCT action with label cv calculates the following quantities:
 Quantity   
 Type   
 Description  
cv
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=cv_wvfunc,cv_ones
# --- 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=cv FILEthe name of the file on which to output these quantities=colvar

The above input calculates 64 $s_i$ values - one $s_i$ values for each of the atoms specified using the SPECIES keyword. These 64 numbers are then output to a file. The function of x, y, z and r to be evaluated is specified using the FUNCTION keyword. Obviously, if your function does not depend on all four of these variables they can be excluded from your function.

As discussed in this paper it is sometimes useful to rotate the bond vectors before computing the arbitrary function $f$ in the above expression. To perform such rotations you use the PHI, THETA and PSI keywords. The $x_{ij}, y_{ij}$ and $z_{ij}$ values that enter $f$ in the expression above are then calculated as:

$$\left( \begin{matrix} x_{ij} \\ y_{ij} \\ z_{ij} \end{matrix} \right) = \left( \begin{matrix} \cos(\psi)\cos(\phi) - \cos(\theta)\sin(\phi)\sin(\psi) & \cos(\psi)*\sin(\phi)+\cos(\theta)*\cos(\phi)*\sin(\psi) & \sin(\psi)*sin(\theta) \\ -\sin(\psi)*\cos(\phi)-\cos(\theta)*\sin(\phi)*\cos(\psi) & -\sin(\psi)*\sin(\phi)+\cos(\theta)*\cos(\phi)*std::cos(\psi), & \cos(\psi)*\sin(\theta) \\ \sin(\theta)*\sin(\phi) & \sin(\theta)*\cos(\phi) & \cos(\theta) \end{matrix} \left( \begin{matrix} x_{ij}' \\ y_{ij}' \\ z_{ij}' \end{matrix} \right)$$

$x_{ij}', y_{ij}'$ and $z_{ij}'$ in this expression are the bond vectors that are calculated in the lab frame. The matrix in the above expression is thus just a rotation matrix that converts the lab frame to some frame of interest.

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) - S. Angioletti-Uberti, M. Ceriotti, P. D. Lee, M. W. Finnis, Solid-liquid interface free energy through metadynamics simulations. Physical Review B. 81 (2010) - B. Cheng, G. A. Tribello, M. Ceriotti, Solid-liquid interfacial free energy out of equilibrium. Physical Review B. 92 (2015) - B. Cheng, G. A. Tribello, M. Ceriotti, The Gibbs free energy of homogeneous nucleation: From atomistic nuclei to the planar limit. The Journal of Chemical Physics. 147 (2017) - B. Cheng, M. Ceriotti, G. A. Tribello, Classical nucleation theory predicts the shape of the nucleus in homogeneous solidification. The Journal of Chemical Physics. 152 (2020)

Syntax

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