Action: GSYMFUNC_THREEBODY

Module	symfunc
Description	Usage
Calculate functions of the coordinates of the coordinates of all pairs of bonds in the first coordination sphere of an atom

Details and examples

Calculate functions of the coordinates of the coordinates of all pairs of bonds in the first coordination sphere of an atom

This shortcut can be used to calculate symmetry function that are like those defined by Behler in the paper that is cited in the bibliography below. The particular symmetry functions that are computed by this shortcut are the angular ones that are functions of the set pairs of atoms in the coordination sphere of the central atom. One of the angular symmetry functions that Behler introduces is:

$G^5_i = 2^{1-\zeta} \sum_{j,k\ne i} (1 + \lambda\cos\theta_{ijk})^\zeta e^{-\nu(R_{ij}^2 + R_{ik}^2)} f_c(R_{ij}) f_c(R_{ik})$

In this expression $\zeta$ , $\nu$ and $\lambda$ are all parameters. $f_c$ is a switching function which acts upon $R_{ij}$ , the distance between atom $i$ and atom $j$ , and $R_{ik}$ , the distance between atom $i$ and atom $k$ . $\theta_{ijk}$ is then the angle between the vector that points from atom $i$ to atom $j$ and the vector that points from atom $i$ to atom $k$ . THe input below can be used to get PLUMED to calculate the 100 values for this symmetry function for the 100 atoms in a system.

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

# Calculate the contact matrix and the x,y and z components of the bond vectors
# This action calculates 4 100x100 matrices
cmatThe CONTACT_MATRIX action with label cmat calculates the following quantities: Quantity    Type    Description  
cmat.w matrix a matrix containing the weights for the bonds between each pair of atoms
cmat.x matrix the projection of the bond on the x axis
cmat.y matrix the projection of the bond on the y axis
cmat.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-100 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.={CUSTOM R_0=4.5 D_MAX=4.5 FUNC=0.5*(cos(pi*x)+1)} COMPONENTS also calculate the components of the vector connecting the atoms in the contact matrix

# Compute the symmetry function for the 100 atoms from the 4 100x100 matrices output
# by cmat.  The output from this action is a vector with 100 elements
beh3The GSYMFUNC_THREEBODY action with label beh3 calculates the following quantities: Quantity    Type    Description  
beh3.g5 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=cmat.w ARGthree matrices containing the bond vectors of interest=cmat.x,cmat.y,cmat.z
    FUNCTION1the parameters of the function you would like to compute={FUNC=0.25*exp(-0.1*(rij+rik))*(1+3*cos(ajik))^3 LABEL=g5}
...

# Print the 100 symmetry function values to a file
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=beh3.g5 FILEthe name of the file on which to output these quantities=colvar

The GSYMFUNC_THREEBODY action sums over all the distinct triples of atoms that are identified in the contact matrix. This action uses the same functionality as CUSTOM and can thus compute any function of the following four quantities:

rij - the distance between atom $i$ and atom $j$
rik - the distance between atom $i$ and atom $k$
rjk - the distance between atom $j$ and atom $k$
ajik - the angle between the vector connecting atom $i$ to atom $j$ and the vector connecting atom $i$ to atom $k$ .

Furthermore we can calculate more than one function of these four quantities at a time as illustrated by the input below:

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

# Calculate the contact matrix and the x,y and z components of the bond vectors
# This action calculates 4 100x100 matrices
cmatThe CONTACT_MATRIX action with label cmat calculates the following quantities: Quantity    Type    Description  
cmat.w matrix a matrix containing the weights for the bonds between each pair of atoms
cmat.x matrix the projection of the bond on the x axis
cmat.y matrix the projection of the bond on the y axis
cmat.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-100 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.={CUSTOM R_0=4.5 D_MAX=4.5 FUNC=0.5*(cos(pi*x)+1)} COMPONENTS also calculate the components of the vector connecting the atoms in the contact matrix

# Compute the 4 symmetry function below for the 100 atoms from the 4 100x100 matrices output
# by cmat.  The output from this action is a vector with 100 elements
beh3The GSYMFUNC_THREEBODY action with label beh3 calculates the following quantities: Quantity    Type    Description  
beh3.g4 vector the function defined by the FUNCTION1 keyword
beh3.g5 vector the function defined by the FUNCTION2 keyword
beh3.g6 vector the function defined by the FUNCTION3 keyword
beh3.g7 vector the function defined by the FUNCTION4 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=cmat.w ARGthree matrices containing the bond vectors of interest=cmat.x,cmat.y,cmat.z
    FUNCTION1the parameters of the function you would like to compute={FUNC=0.25*(cos(pi*sqrt(rjk)/4.5)+1)*exp(-0.1*(rij+rik+rjk))*(1+2*cos(ajik))^2 LABEL=g4}
    FUNCTION2the parameters of the function you would like to compute={FUNC=0.25*exp(-0.1*(rij+rik))*(1+3.5*cos(ajik))^3 LABEL=g5}
    FUNCTION3the parameters of the function you would like to compute={FUNC=0.125*(1+6.6*cos(ajik))^4 LABEL=g6}
    FUNCTION4the parameters of the function you would like to compute={FUNC=sin(3.0*(ajik-1)) LABEL=g7}
...

# Print the 4 sets of 100 symmetry function values to a file
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=beh3.g4,beh3.g5,beh3.g6,beh3.g7 FILEthe name of the file on which to output these quantities=colvar

You can even use this action in tandem with the features that are in the volumes module as shown below:

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

# The atoms that are of interest
owThe GROUP action with label ow calculates the following quantities: Quantity    Type    Description  
ow 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-16500
# Fixed virtual atom which serves as the probe volume's center (pos. in nm)
centerThe FIXEDATOM action with label center calculates the following quantities: Quantity    Type    Description  
center atoms virtual atom calculated by FIXEDATOM action: FIXEDATOMAdd a virtual atom in a fixed position. This action has hidden defaults. More details ATcoordinates of the virtual atom=2.5,2.5,2.5
center: FIXEDATOMAdd a virtual atom in a fixed position. This action uses the defaults shown here. More details ATcoordinates of the virtual atom=2.5,2.5,2.5  SET_MASS mass of the virtual atom=1 SET_CHARGE charge of the virtual atom=0
# Vector in which element i is one if atom i is in sphere of interest and zero otherwise
sphereThe INSPHERE action with label sphere calculates the following quantities: Quantity    Type    Description  
sphere vector vector of numbers between 0 and 1 that measure the degree to which each atom is within the volume of interest: INSPHEREThis quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a particular, user-specified part of of the cell. More details ATOMSthe group of atoms that you would like to investigate=ow CENTERthe atom whose vicinity we are interested in examining=center RADIUSthe switching function that tells us the extent of the sphereical region of interest. Options for this keyword are explained in the documentation for LESS_THAN.={GAUSSIAN D_0=0.5 R_0=0.01 D_MAX=0.52}
# The distance matrix
dmapThe DISTANCE_MATRIX action with label dmap calculates the following quantities: Quantity    Type    Description  
dmap.w matrix a matrix containing the weights for the bonds between each pair of atoms
dmap.x matrix the projection of the bond on the x axis
dmap.y matrix the projection of the bond on the y axis
dmap.z matrix the projection of the bond on the z axis: DISTANCE_MATRIXCalculate a matrix of distances between atoms. This action has hidden defaults. 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=ow CUTOFF ignore distances that have a value larger than this cutoff=1.0 MASKa vector that is used to used to determine which rows of the adjancency matrix to compute=sphere
dmap: DISTANCE_MATRIXCalculate a matrix of distances between atoms. This action uses the defaults shown here. 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=ow CUTOFF ignore distances that have a value larger than this cutoff=1.0 MASKa vector that is used to used to determine which rows of the adjancency matrix to compute=sphere  NL_CUTOFF The cutoff for the neighbor list=0.0 NL_STRIDE The frequency with which we are updating the atoms in the neighbor list=1
# Find the four nearest neighbors
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 This action has hidden defaults. More details ARGthe label of an adjacency/distance matrix that will be used to find the nearest neighbors=dmap.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 MASKa vector that is used to used to determine which rows of the neighbors matrix to compute=sphere
acv_neigh: NEIGHBORSBuild a matrix with ones in for the N nearest neighbours of an atom This action uses the defaults shown here. More details ARGthe label of an adjacency/distance matrix that will be used to find the nearest neighbors=dmap.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 MASKa vector that is used to used to determine which rows of the neighbors matrix to compute=sphere  NHIGHEST in each row of the output matrix set the elements that correspond to the n highest elements in each row of the input matrix equal to one=0
# Compute a function for the atoms that are in the first coordination sphere
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=dmap.x,dmap.y,dmap.z
  FUNCTION1the parameters of the function you would like to compute={FUNC=(cos(ajik)+1/3)^2 LABEL=g8}
  MASKa vector that is used to used to determine which symmetry functions should be calculated=sphere
...
# Now compute the value of the function above for those atoms that are in the
# sphere of interest
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,sphere FUNCthe function you wish to evaluate=y*(1-(3*x/8)) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# And now compute the final average
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_normThe SUM action with label acv_norm calculates the following quantities: Quantity    Type    Description  
acv_norm 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=sphere PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
meanThe CUSTOM action with label mean calculates the following quantities: Quantity    Type    Description  
mean scalar an arbitrary function: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=acv_sum,acv_norm 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
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=mean FILEthe name of the file on which to output these quantities=colvar

You can read more about how to calculate more Behler-type symmetry functions here.

Input

The arguments 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	vector	a vector that is used to used to determine which symmetry functions should be calculated
ARG	matrix	three matrices containing the bond vectors of interest
WEIGHT	matrix	the matrix that contains the weights that should be used for each connection

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 vector that is used to used to determine which symmetry functions should be calculated
ARG	input	none	three matrices containing the bond vectors of interest
WEIGHT	input	none	the matrix that contains the weights that should be used for each connection
FUNCTION	optional	not used	the parameters of the function you would like to compute
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.

References

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

J. Behler, Atom-centered symmetry functions for constructing high-dimensional neural network potentials. The Journal of Chemical Physics. 134 (2011)

Quantity	Type	Description
cmat.w	matrix	a matrix containing the weights for the bonds between each pair of atoms
cmat.x	matrix	the projection of the bond on the x axis
cmat.y	matrix	the projection of the bond on the y axis
cmat.z	matrix	the projection of the bond on the z axis