Skip to content

Commit ee44f9a

Browse files
author
Gareth Aneurin Tribello
committed
Added new documentation for code in symfunc module
1 parent c3b9eb7 commit ee44f9a

15 files changed

+863
-348
lines changed

‎src/symfunc/AngularTetra.cpp

+21-1
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,27 @@
2828
/*
2929
Calculate the angular tetra CV
3030
31-
\par Examples
31+
This shortcut calculates a [symmetry function](https://www.plumed-tutorials.org/lessons/23/001/data/SymmetryFunction.html). The particular function that is being
32+
evaluated for the coordination sphere here is as follows:
33+
34+
$$
35+
s_i = 1 - \frac{3}{8}\sum_{j=2}^4 \sum_{k=1}^{j-1} \left( \cos(\theta_{jik} + \frac{1}{2} \right)^2
36+
$$
37+
38+
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
39+
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
40+
and small otherwise. The following example shows how you can use this action to measure the degree of tetrahedral order in a system.
41+
42+
```plumed
43+
# Calculate a vector that contains 64 values for the symmetry function.
44+
# Sum the elements of the vector and calculate the mean value on the atoms from this sum.
45+
acv: TETRA_ANGULAR SPECIES=1-64 SUM MEAN
46+
# Print out the positions of the 64 atoms for which the symmetry function was calculated
47+
# to an xyz file along with the values of the symmetry function
48+
DUMPATOMS ATOMS=1-64 ARG=acv FILE=mcolv.xyz
49+
# Print out the average value of the symmetry function and the sum of all the symmetry functions
50+
PRINT ARG=acv_sum,acv_mean FILE=colvar
51+
```
3252
3353
*/
3454
//+ENDPLUMEDOC

‎src/symfunc/AtomicSMAC.cpp

+28-7
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,30 @@
3030
/*
3131
Calculate the atomic smac CV
3232
33-
\par Examples
33+
This shortcut offers another example of a [symmetry function](https://www.plumed-tutorials.org/lessons/23/001/data/SymmetryFunction.html).
34+
This action was inspired by [SMAC](SMAC.md) and the distribution of angles in the first coordination sphere around an atom to determine if the
35+
environment around the atom is ordered. For atom $i$ the symmetry function is calculated using:
36+
37+
$$
38+
s_i = [ 1 - \gamma(c_i) ] \frac{ \sum_j \sum{k \ne j} \sigma(r_{ij})\sigma(r_{ik}) \sum_n G\left( \frac{ \theta_{jik} - \phi_n}{b_n}\right) }{\sum{k \ne j} \sigma(r_{ij})\sigma(r_{ik})} \qquad \textrm{where} \qquad c_i = \sum_j \sigma(r_{ij})
39+
$$
40+
41+
In this expression $r_{ij}$ is the distance between atom $i$ and atom $j$ and $\sigma$ is a switching function that acts upon this distance. $c_i$ is thus the number of atoms that are within
42+
a certain cutoff of atom $i$ and $\gamma$ is another switching function that acts upon this quantity. This switching function ensures that the symmetry function is zero for atoms that are
43+
regions where the density is low. $\theta_{jik}$ is the angle between the vector connecting atoms $i$ and $j$ and the vector connecting atoms $i$ and $k$. This angle is the argument for the
44+
set of Gaussian kernel functions, $G$, that are centered on $\phi_n$ and that have bandwidths of $b_n$. The function above is thus determining if the angles between the bonds in the first coordination
45+
sphere around atom $i$ are similar to the $\phi_n$ values that have been specified by the user or not.
46+
47+
The following example demonstrates how this symmetry function can be used in practise.
48+
49+
```plumed
50+
smac: ATOMIC_SMAC SPECIES=1-64 KERNEL1={GAUSSIAN CENTER=pi/2 SIGMA=1.0} KERNEL2={GAUSSIAN CENTER=pi/4 SIGMA=1.0} SWITCH_COORD={EXP R_0=4.0} SWITCH={RATIONAL R_0=2.0 D_0=2.0} SUM
51+
PRINT ARG=smac.* FILE=colvar
52+
```
53+
54+
The input above would calculate 64 instances of $s_i$ using the formula above. In each of these two Gaussian Kernels are used in the sum over $n$. The parameters for the switching function
55+
$\sigma$ are specified using the SWITCH keyword, while the parameters for $\gamma$ are specified using SWITCH_COORD. As you can see if you expand the shortcut in the input above, the 64 values
56+
for $s_i$ are stored in a vector. All the elements of this vector are then added together to produce the single quantity that is output in the colvar file.
3457
3558
*/
3659
//+ENDPLUMEDOC
@@ -48,12 +71,10 @@ PLUMED_REGISTER_ACTION(AtomicSMAC,"ATOMIC_SMAC")
4871

4972
void AtomicSMAC::registerKeywords(Keywords& keys) {
5073
ActionShortcut::registerKeywords( keys );
51-
keys.add("optional","SPECIES","");
52-
keys.add("optional","SPECIESA","");
53-
keys.add("optional","SPECIESB","");
54-
keys.add("optional","SWITCH","This keyword is used if you want to employ an alternative to the continuous swiching function defined above. "
55-
"The following provides information on the \\ref switchingfunction that are available. "
56-
"When this keyword is present you no longer need the NN, MM, D_0 and R_0 keywords.");
74+
keys.add("atoms-3","SPECIES","the list of atoms for which the symmetry function is being calculated and the atoms that can be in the environments");
75+
keys.add("atoms-4","SPECIESA","the list of atoms for which the symmetry function is being calculated. This keyword must be used in conjunction with SPECIESB, which specifies the atoms that are in the environment.");
76+
keys.add("atoms-4","SPECIESB","the list of atoms that can be in the environments of each of the atoms for which the symmetry function is being calculated. This keyword must be used in conjunction with SPECIESA, which specifies the atoms for which the symmetry function is being calculated.");
77+
keys.add("optional","SWITCH","the switching function that it used in the construction of the contact matrix");
5778
keys.add("numbered","KERNEL","The kernels used in the function of the angle");
5879
keys.add("optional","SWITCH_COORD","This keyword is used to define the coordination switching function.");
5980
keys.reset_style("KERNEL","optional");

‎src/symfunc/CoordShellVectorFunction.cpp

+110-31
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,57 @@ namespace symfunc {
3737
/*
3838
Calculate an arbitrary function of all the bond vectors in the first coordination sphere of an atom
3939
40-
\par Examples
40+
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.
41+
In other words, this action allows you to compute the following:
42+
43+
$$
44+
s_i = \sum_{i \ne j} \sigma(r_{ij}) f(x_{ij}, y_{ij}, z_{ij}, r_{ij}) )
45+
$$
46+
47+
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.
48+
$\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
49+
of atom $i$.
50+
51+
Below you can see a simple example that shows how this action can be used in practise.
52+
53+
```plumed
54+
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
55+
PRINT ARG=cv FILE=colvar
56+
```
57+
58+
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.
59+
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
60+
they can be excluded from your function.
61+
62+
As discussed in [this paper](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.92.180102) it is sometimes useful to rotate the bond vectors before computing the
63+
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
64+
expression above are then calculated as:
65+
66+
$$
67+
\left(
68+
\begin{matrix}
69+
x_{ij} \\
70+
y_{ij} \\
71+
z_{ij}
72+
\end{matrix}
73+
\right) =
74+
\left(
75+
\begin{matrix}
76+
\cos(\psi)\cos(\phi) - \cos(\theta)\sin(\phi)\sin(\psi) & \cos(\psi)*\sin(\phi)+\cos(\theta)*\cos(\phi)*\sin(\psi) & \sin(\psi)*sin(\theta) \\
77+
-\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) \\
78+
\sin(\theta)*\sin(\phi) & \sin(\theta)*\cos(\phi) & \cos(\theta)
79+
\end{matrix}
80+
\left(
81+
\begin{matrix}
82+
x_{ij}' \\
83+
y_{ij}' \\
84+
z_{ij}'
85+
\end{matrix}
86+
\right)
87+
$$
88+
89+
$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
90+
[rotation matrix](https://en.wikipedia.org/wiki/Rotation_matrix) that converts the lab frame to some frame of interest.
4191
4292
4393
*/
@@ -47,8 +97,30 @@ Calculate an arbitrary function of all the bond vectors in the first coordinatio
4797
/*
4898
Calculate an arbitrary function of all the bond vectors in the first coordination sphere of an atom and take an average
4999
50-
\par Examples
100+
This shortcut allows you to calculate the average for an arbitrary function of the bond vectors that connect an atom to each of its neighbours.
101+
In other words, this action allows you to compute the following:
102+
103+
$$
104+
s_i = \frac{\sum_{i \ne j} \sigma(r_{ij}) f(x_{ij}, y_{ij}, z_{ij}, r_{ij}) )}{\sum_{i \ne j} \sigma(r_{ij})}
105+
$$
51106
107+
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.
108+
$\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
109+
of atom $i$.
110+
111+
Below you can see a simple example that shows how this action can be used in practise.
112+
113+
```plumed
114+
cv: COORDINATION_SHELL_AVERAGE 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
115+
PRINT ARG=cv FILE=colvar
116+
```
117+
118+
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.
119+
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
120+
they can be excluded from your function.
121+
122+
Notice that you can you can rotate the bond vectors before computing the
123+
arbitrary function $f$ in the above expression as is discussed in the documentation for [COORDINATION_SHELL_FUNCTION](COORDINATION_SHELL_FUNCTION.md)
52124
53125
*/
54126
//+ENDPLUMEDOC
@@ -57,35 +129,38 @@ Calculate an arbitrary function of all the bond vectors in the first coordinatio
57129
/*
58130
Calculate whether or not the coordination spheres of atoms are arranged as they would be in a simple cubic structure.
59131
60-
We can measure how similar the environment around atom \f$i\f$ is to a simple cubic structure is by evaluating
132+
This shortcut is an example of a [COORDINATION_SHELL_AVERAGE](COORDINATION_SHELL_AVERAGE.md),
133+
which we can use to measure how similar the environment around atom $i$ is to a simple cubic structure. We perform this comparison by evaluating
61134
the following quantity:
62135
63-
\f[
136+
$$
64137
s_i = \frac{ \sum_{i \ne j} \sigma(r_{ij}) \left[ \frac{ x_{ij}^4 + y_{ij}^4 + z_{ij}^4 }{r_{ij}^4} \right] }{ \sum_{i \ne j} \sigma(r_{ij}) }
65-
\f]
138+
$$
66139
67-
In this expression \f$x_{ij}\f$, \f$y_{ij}\f$ and \f$z_{ij}\f$ are the \f$x\f$, \f$y\f$ and \f$z\f$ components of the vector connecting atom \f$i\f$ to
68-
atom \f$j\f$ and \f$r_{ij}\f$ is the magnitude of this vector. \f$\sigma(r_{ij})\f$ is a \ref switchingfunction that acts on the distance between atom \f$i\f$ and atom \f$j\f$ and its inclusion in the numerator and the denominator of the above expression as well as the fact that we are summing
140+
In this expression $x_{ij}$, $y_{ij}$ and $z_{ij}$ are the $x$, $y$ and $z$ components of the vector connecting atom $i$ to
141+
atom $j$ and $r_{ij}$ is the magnitude of this vector. $\sigma(r_{ij})$ is a switching function that acts on the distance between atom $i$ and atom $j$ and its inclusion in the numerator and the denominator of the above expression as well as the fact that we are summing
69142
over all of the other atoms in the system ensures that we are calculating an average
70-
of the function of \f$x_{ij}\f$, \f$y_{ij}\f$ and \f$z_{ij}\f$ for the atoms in the first coordination sphere around atom \f$i\f$.
143+
of the function of $x_{ij}$, $y_{ij}$ and $z_{ij}$ for the atoms in the first coordination sphere around atom $i$.
71144
This quantity is once again a multicolvar so you can compute it for multiple atoms using a single PLUMED action and then compute
72-
the average value for the atoms in your system, the number of atoms that have an \f$s_i\f$ value that is more that some target and
145+
the average value for the atoms in your system, the number of atoms that have an $s_i$ value that is more that some target and
73146
so on. Notice also that you can rotate the reference frame if you are using a non-standard unit cell.
74147
75-
76-
\par Examples
77-
78148
The following input tells plumed to calculate the simple cubic parameter for the atoms 1-100 with themselves.
79149
The mean value is then calculated.
80-
\plumedfile
150+
151+
```plumed
81152
SIMPLECUBIC SPECIES=1-100 R_0=1.0 MEAN
82-
\endplumedfile
153+
```
83154
84155
The following input tells plumed to look at the ways atoms 1-100 are within 3.0 are arranged about atoms
85156
from 101-110. The number of simple cubic parameters that are greater than 0.8 is then output
86-
\plumedfile
157+
158+
```plumed
87159
SIMPLECUBIC SPECIESA=101-110 SPECIESB=1-100 R_0=3.0 MORE_THAN={RATIONAL R_0=0.8 NN=6 MM=12 D_0=0}
88-
\endplumedfile
160+
```
161+
162+
Notice that you can you can rotate the bond vectors before computing the
163+
function in the above expression as is discussed in the documentation for [COORDINATION_SHELL_FUNCTION](COORDINATION_SHELL_FUNCTION.md)
89164
90165
*/
91166
//+ENDPLUMEDOC
@@ -94,40 +169,42 @@ SIMPLECUBIC SPECIESA=101-110 SPECIESB=1-100 R_0=3.0 MORE_THAN={RATIONAL R_0=0.8
94169
/*
95170
Calculate the degree to which the environment about ions has a tetrahedral order.
96171
97-
We can measure the degree to which the atoms in the first coordination shell around any atom, \f$i\f$ is
98-
is arranged like a tetrahedron using the following function.
172+
This shortcut is an example of a [COORDINATION_SHELL_AVERAGE](COORDINATION_SHELL_AVERAGE.md),
173+
which we can use to measure the degree to which the atoms in the first coordination shell around any atom, $i$ is
174+
is arranged like a tetrahedron. We perform this comparison by evaluating the following function.
99175
100-
\f[
176+
$$
101177
s(i) = \frac{1}{\sum_j \sigma( r_{ij} )} \sum_j \sigma( r_{ij} )\left[ \frac{(x_{ij} + y_{ij} + z_{ij})^3}{r_{ij}^3} +
102178
\frac{(x_{ij} - y_{ij} - z_{ij})^3}{r_{ij}^3} +
103179
\frac{(-x_{ij} + y_{ij} - z_{ij})^3}{r_{ij}^3} +
104180
\frac{(-x_{ij} - y_{ij} + z_{ij})^3}{r_{ij}^3} \right]
105-
\f]
181+
$$
106182
107-
Here \f$r_{ij}\f$ is the magnitude of the vector connecting atom \f$i\f$ to atom \f$j\f$ and \f$x_{ij}\f$, \f$y_{ij}\f$ and \f$z_{ij}\f$
108-
are its three components. The function \f$\sigma( r_{ij} )\f$ is a \ref switchingfunction that acts on the distance between
109-
atoms \f$i\f$ and \f$j\f$. The parameters of this function should be set so that the function is equal to one
110-
when atom \f$j\f$ is in the first coordination sphere of atom \f$i\f$ and is zero otherwise.
111-
112-
\par Examples
183+
Here $r_{ij}$ is the magnitude of the vector connecting atom $i$ to atom $j$ and $x_{ij}$, $y_{ij}$ and $z_{ij}$
184+
are its three components. The function $\sigma( r_{ij} )$ is a switching function that acts on the distance between
185+
atoms $i$ and $j$. The parameters of this function should be set so that the function is equal to one
186+
when atom $j$ is in the first coordination sphere of atom $i$ and is zero otherwise.
113187
114188
The following command calculates the average value of the TETRAHEDRAL parameter for a set of 64 atoms all of the same type
115189
and outputs this quantity to a file called colvar.
116190
117-
\plumedfile
191+
```plumed
118192
tt: TETRAHEDRAL SPECIES=1-64 SWITCH={RATIONAL D_0=1.3 R_0=0.2} MEAN
119193
PRINT ARG=tt.mean FILE=colvar
120-
\endplumedfile
194+
```
121195
122196
The following command calculates the number of TETRAHEDRAL parameters that are greater than 0.8 in a set of 10 atoms.
123197
In this calculation it is assumed that there are two atom types A and B and that the first coordination sphere of the
124198
10 atoms of type A contains atoms of type B. The formula above is thus calculated for ten different A atoms and within
125-
it the sum over \f$j\f$ runs over 40 atoms of type B that could be in the first coordination sphere.
199+
it the sum over $j$ runs over 40 atoms of type B that could be in the first coordination sphere.
126200
127-
\plumedfile
201+
```plumed
128202
tt: TETRAHEDRAL SPECIESA=1-10 SPECIESB=11-40 SWITCH={RATIONAL D_0=1.3 R_0=0.2} MORE_THAN={RATIONAL R_0=0.8}
129203
PRINT ARG=tt.* FILE=colvar
130-
\endplumedfile
204+
```
205+
206+
Notice that you can you can rotate the bond vectors before computing the
207+
function in the above expression as is discussed in the documentation for [COORDINATION_SHELL_FUNCTION](COORDINATION_SHELL_FUNCTION.md)
131208
132209
*/
133210
//+ENDPLUMEDOC
@@ -155,6 +232,8 @@ void CoordShellVectorFunction::registerKeywords( Keywords& keys ) {
155232
keys.setValueDescription("vector","the symmetry function for each of the specified atoms");
156233
keys.needsAction("CONTACT_MATRIX"); keys.needsAction("FCCUBIC_FUNC"); keys.needsAction("CUSTOM");
157234
keys.needsAction("ONES"); keys.needsAction("MATRIX_VECTOR_PRODUCT");
235+
keys.addDOI("10.1103/PhysRevB.81.125416"); keys.addDOI("10.1103/PhysRevB.92.180102");
236+
keys.addDOI("10.1063/1.4997180"); keys.addDOI("10.1063/1.5134461");
158237
}
159238

160239
CoordShellVectorFunction::CoordShellVectorFunction(const ActionOptions& ao):

0 commit comments

Comments
 (0)