Added new style documentation to actions in vatom

src/setup/Load.cpp

@@ -107,7 +107,7 @@ Instead of the command:
 PLUMED_REGISTER_ACTION(Distance,"DISTANCE2")
 ```
 
-that was used in `Distance2.cpp. Consequently, when we load the `Distance3.cpp` file here we redefine the DISTANCE command.
+that was used in `Distance2.cpp`. Consequently, when we load the `Distance3.cpp` file here we redefine the DISTANCE command.
 The functions that compute `d` and `d2` in the above input are thus different.
 
 A final point to note is that, starting with PLUMED 2.10, the LOAD action can be used in contexts where

src/vatom/ArgsToVatom.cpp

@@ -31,7 +31,39 @@
 /*
 Create a virtual atom from the input scalars
 
-\par Examples
+This action takes five scalars that are computed by other actions in input and uses them to set the 
+x, y and z positions and the mass and charge of a virtual atom.  This action is used within the 
+[CENTER](CENTER.md) shortcut to compute a center of mass.  An example input that shows how you 
+can use this command to calculate the center of mass of atoms 1-10 is as follows:
+
+```plumed
+# Calculate the total mass of the atoms
+m: MASS ATOMS=1-10
+mass: SUM ARG=m PERIODIC=NO
+# Calculate the totla charge of the atoms
+q: CHARGE ATOMS=1-10
+charge: SUM ARG=q PERIODIC=NO
+# Now get the positions of the atoms
+pos: POSITION WHOLEMOLECULES ATOMS=1-10
+# Multiply each vector of positions by the masses
+xwvec: CUSTOM ARG=m,pos.x FUNC=x*y PERIODIC=NO
+ywvec: CUSTOM ARG=m,pos.y FUNC=x*y PERIODIC=NO
+zwvec: CUSTOM ARG=m,pos.z FUNC=x*y PERIODIC=NO
+# Sum the numerators in the expression for the center of mass
+xnum: SUM ARG=xwvec PERIODIC=NO
+ynum: SUM ARG=ywvec PERIODIC=NO
+znum: SUM ARG=zwvec PERIODIC=NO
+# And compute the x, y and z positions of the center of mass
+x: CUSTOM ARG=xnum,mass FUNC=x/y PERIODIC=NO
+y: CUSTOM ARG=ynum,mass FUNC=x/y PERIODIC=NO
+z: CUSTOM ARG=znum,mass FUNC=x/y PERIODIC=NO
+# And now create the virtual atom
+p: ARGS2VATOM XPOS=x YPOS=y ZPOS=z MASS=mass CHARGE=charge
+``` 
+
+This input provides a very slow way of providing a center of mass - PLUMED contains a faster implementation that does all this.
+This type of input is nevertheless useful if you are using arbitary weights when computing the sums in the numerator 
+and denominator of the expression for the center as is detailed in the documentation for the [CENTER](CENTER.md) command.
 
 */
 //+ENDPLUMEDOC

src/vatom/Center.cpp

@@ -41,50 +41,83 @@ Calculate the center for a group of atoms, with arbitrary weights.
 /*
 Calculate the center for a group of atoms, with arbitrary weights.
 
-The computed
-center is stored as a virtual atom that can be accessed in
-an atom list through the label for the CENTER action that creates it.
-Notice that the generated virtual atom has charge equal to the sum of the
-charges and mass equal to the sum of the masses. If used with the MASS flag,
-then it provides a result identical to \ref COM.
-
-When running with periodic boundary conditions, the atoms should be
-in the proper periodic image. This is done automatically since PLUMED 2.2,
-by considering the ordered list of atoms and rebuilding the molecule using a procedure
-that is equivalent to that done in \ref WHOLEMOLECULES . Notice that
-rebuilding is local to this action. This is different from \ref WHOLEMOLECULES
-which actually modifies the coordinates stored in PLUMED.
-
-In case you want to recover the old behavior you should use the NOPBC flag.
-In that case you need to take care that atoms are in the correct
-periodic image.
-
-\note As an experimental feature, CENTER also supports a keyword PHASES.
-This keyword finds the center of mass for sets of atoms that have been split by the period boundaries by computing scaled coordinates and average
-trigonometric functions, similarly to \ref CENTER_OF_MULTICOLVAR.
-Notice that by construction this center position is
-not invariant with respect to rotations of the atoms at fixed cell lattice.
-In addition, for symmetric Bravais lattices, it is not invariant with respect
-to special symmetries. E.g., if you have an hexagonal cell, the center will
-not be invariant with respect to rotations of 120 degrees.
-On the other hand, it might make the treatment of PBC easier in difficult cases.
+The position of the center ${r}_{\rm COM}$ given by:
 
-\par Examples
+$$
+{r}_{\rm COM}=\frac{\sum_{i=1}^{n} {r}_i\ w_i }{\sum_i^{n} w_i}
+$$
+
+In these expressions $r_i$ indicates the position of atom $i$ and $w_i$ is the weight for atom $i$. The following input
+shows how you can calculate the expressions for a set of atoms by using PLUMED:
 
-\plumedfile
-# a point which is on the line connecting atoms 1 and 10, so that its distance
-# from 10 is twice its distance from 1:
+```plumed
+# This action calculates the position of the point on the line connecting atoms 1 and 10 that is
+# twice as far atom 10 as it is from atom 1 
 c1: CENTER ATOMS=1,1,10
-# this is another way of stating the same:
+# this is another way of calculating this position
 c1bis: CENTER ATOMS=1,10 WEIGHTS=2,1
 
-# center of mass among these atoms:
-c2: CENTER ATOMS=2,3,4,5 MASS
+DUMPATOMS ATOMS=c1,c1bis FILE=atoms.xyz
+```
 
-d1: DISTANCE ATOMS=c1,c2
+Notice that center's position is stored as [a virtual atom](specifying_atoms.md). The positions of the centers in the above input
+used in the DUMPATOMS command by using the labels for the CENTER actions. Notice, furthermore, that the mass and charge of this new center 
+are equal to the sums of the masses and charges of the input atoms. 
 
-PRINT ARG=d1
-\endplumedfile
+The input below shows how you can use the CENTER action in place of the [COM](COM) action to calculate the center of mass for a group of atoms.
+
+```plumed
+c: CENTER ATOMS=1-5 MASS
+```
+
+Center is more powerful than COM because you can use arbitrary vectors of weights as in the first example above or vector of weights that are calculated by 
+another action as has been done in the input below.
+
+```plumed
+fcc: FCCUBIC SPECIES=1-1000 SWITCH={RATIONAL D_0=3.0 R_0=1.5}
+sfcc: MORE_THAN ARG=fcc SWITCH={RATIONAL R_0=0.5}
+c: CENTER ATOMS=1-1000 WEIGHTS=sfcc
+DUMPATOMS ATOMS=c FILE=atom.xyz
+```
+
+This input assumes you have a cluster of solid atoms in a liquid. The actions with labels `fcc` and `sfcc`
+are used to differentiate between atoms in solid-like and liquid-like atoms. `sfcc` is thus a vector with 
+one element for each atom. These elements are equal to one if the environment around the corresponding atom 
+are solid like and zero if the environment around the atom is liquid like.
+
+## A note on periodic boundary conditions
+
+If you run with periodic boundary conditions
+these are taken into account automatically when computing the center of mass. The way this is 
+handled is akin to the way molecules are rebuilt in the [WHOLEMOLECULES](WHOLEMOLECULES.md) command.
+However, at variance to [WHOLEMOLECULES](WHOLEMOLECULES.md), the copies of the atomic positions in this 
+action are modified.  The global positions (i.e. those that are used in all other actions) 
+are not changed when the alignment is performed.
+
+If you believe that PBC should not be applied when calculating the position fo the center of mass you can use the 
+NOPBC flag.
+
+An additional way of managing periodic boundary conditions is offered in CENTER by using the PHASES keyword as shown 
+in the example input below
+
+```plumed
+c: CENTER ATOMS=1-100 PHASES
+```
+
+The scaled value for the $x$ component of the position of the center is calculated from the scaled components of the input atoms, $x_i$, 
+using the following expression when the PHASES option is employed
+
+$$
+x_\textrm{com} = \frac{1}{2\pi} \atan\left( \frac{\sum_{i=1}^n w_i \sin(2 \pi x_i ) }{ \sum_{i=1}^n w_i \cos(2 \pi x_i ) } \right) 
+$$
+
+Similar, expressions are used to calculae the values of the scaled $y$ and $z$ components.  The final cartesian coordinates of the center are then computed 
+by multiplying these scaled components by the cell vectors.  Notice that by construction this center position is
+not invariant with respect to rotations of the atoms at fixed cell lattice.
+In addition, for symmetric Bravais lattices, it is not invariant with respect
+to special symmetries. E.g., if you have an hexagonal cell, the center will
+not be invariant with respect to rotations of 120 degrees.
+On the other hand, it might make the treatment of PBC easier in difficult cases.
 
 */
 //+ENDPLUMEDOC
@@ -93,33 +126,34 @@ PRINT ARG=d1
 /*
 Calculate the center of mass for a group of atoms.
 
-The computed
-center of mass is stored as a virtual atom that can be accessed in
-an atom list through the label for the COM action that creates it.
-
-For arbitrary weights (e.g. geometric center) see \ref CENTER.
+The following example input shows how you can use this shortcut to calculate the center of 
+mass for atoms  1,2,3,4,5,6,7 and for atoms 15,20.  You can then compute the distance between
+the two center of masses.
 
-When running with periodic boundary conditions, the atoms should be
-in the proper periodic image. This is done automatically since PLUMED 2.2,
-by considering the ordered list of atoms and rebuilding the molecule using a procedure
-that is equivalent to that done in \ref WHOLEMOLECULES . Notice that
-rebuilding is local to this action. This is different from \ref WHOLEMOLECULES
-which actually modifies the coordinates stored in PLUMED.
-
-In case you want to recover the old behavior you should use the NOPBC flag.
-In that case you need to take care that atoms are in the correct
-periodic image.
-
-\par Examples
-
-The following input instructs plumed to print the distance between the
-center of mass for atoms 1,2,3,4,5,6,7 and that for atoms 15,20:
-\plumedfile
+```plumed
 c1: COM ATOMS=1-7
 c2: COM ATOMS=15,20
 d1: DISTANCE ATOMS=c1,c2
 PRINT ARG=d1
-\endplumedfile
+```
+
+The center of mass is stored as a [virtual atom](specifying_atoms.md).  As you can see from the 
+above to refer to the position of the center of mass when specifying the atoms that should be used 
+when calculating some other action you use the lable of the COM action that computes the center of mass
+of interest.   
+
+The COM command is a shortcut because it is a wrapper to [CENTER](CENTER.md). CENTER is more powerful than
+comm as it allows you to use arbitrary weights in place of the masses.
+
+If you run with periodic boundary conditions
+these are taken into account automatically when computing the center of mass. The way this is 
+handled is akin to the way molecules are rebuilt in the [WHOLEMOLECULES](WHOLEMOLECULES.md) command.
+However, at variance to [WHOLEMOLECULES](WHOLEMOLECULES.md), the copies of the atomic positions in this 
+action are modified.  The global positions (i.e. those that are used in all other actions) 
+are not changed when the alignment is performed.
+
+If you believe that PBC should not be applied when calculating the position fo the center of mass you can use the 
+NOPBC flag.
 
 */
 //+ENDPLUMEDOC

src/vatom/FixedAtom.cpp

@@ -31,52 +31,35 @@ namespace vatom {
 /*
 Add a virtual atom in a fixed position.
 
-This action creates a virtual atom at a fixed position.
-The coordinates can be specified in Cartesian components (by default)
-or in scaled coordinates (SCALED_COMPONENTS).
-It is also possible to assign a predefined charge or mass to the atom.
-
-\attention
-Similar to \ref POSITION this variable is not invariant for translation
-of the system. Adding a force on it can create serious troubles.
-
-Notice that the distance between two atoms created
-using FIXEDATOM is invariant for translation.
-Additionally, if one first align atoms to a reference using \ref FIT_TO_TEMPLATE,
-then it is safe to add further fixed atoms without breaking translational invariance.
-
-\par Examples
+This action creates [a virtual atom](specifying_atoms.md) at a fixed position.  The example input below illustrates
+how this idea can be used to compute the angle between the vector connecting atoms 15 and 20 and the z axis and how this 
+quantity can then be restrained so that the angle stays close to zero.
 
-The following input instructs plumed to compute the angle between
-distance of atoms 15 and 20 and the z axis and keeping it close to zero.
-\plumedfile
+```plumed
 a: FIXEDATOM AT=0,0,0
 b: FIXEDATOM AT=0,0,1
 an: ANGLE ATOMS=a,b,15,20
 RESTRAINT ARG=an AT=0.0 KAPPA=100.0
-\endplumedfile
+```
 
-The following input instructs plumed to align a protein to a template
-and to then compute the distance between one of the atoms in the protein and the point
-(10,20,30).
-\plumedfile
-FIT_TO_TEMPLATE STRIDE=1 REFERENCE=ref.pdb TYPE=SIMPLE
-a: FIXEDATOM AT=10,20,30
-d: DISTANCE ATOMS=a,20
-PRINT ARG=d FILE=colvar
-\endplumedfile
+By default PLUMED assumes that any coordinates specified using the AT keyword specified are the cartesian coordinates of the fixed atom. 
+However, if you use the SCALED_COMPONENTS flag the coordinates specified using the AT keyword are interpretted as scaled coordinates.
+It is also possible to assign a predefined charge or mass to the atom by using the `SET_MASS` and `SET_CHARGE` keywords.
 
-The reference structure to align to is provided in a pdb file called ref.pdb as shown below:
+> [!CAUTION]
+> This action, like [POSITION](POSITION.md) is not invariant for translation of the system so adding a force on it can cause trouble.
 
-\auxfile{ref.pdb}
-ATOM      8  HT3 ALA     2      -1.480  -1.560   1.212  1.00  1.00      DIA  H
-ATOM      9  CAY ALA     2      -0.096   2.144  -0.669  1.00  1.00      DIA  C
-ATOM     10  HY1 ALA     2       0.871   2.385  -0.588  1.00  1.00      DIA  H
-ATOM     12  HY3 ALA     2      -0.520   2.679  -1.400  1.00  1.00      DIA  H
-ATOM     14  OY  ALA     2      -1.139   0.931  -0.973  1.00  1.00      DIA  O
-END
-\endauxfile
+The problem is that the vector connecting any atom and a virtual atom created using the FIXEDATOM atoms command is not invariant to translation.
+However, if, as has been done in the following example input, one first aligns atoms to a reference using [FIT_TO_TEMPLATE](FIT_TO_TEMPLATE.md),
+then it is safe to add further fixed atoms without breaking translational invariance.
 
+```plumed
+#SETTINGS INPUTFILES=regtest/basic/rt63/align.pdb
+FIT_TO_TEMPLATE STRIDE=1 REFERENCE=regtest/basic/rt63/align.pdb TYPE=SIMPLE
+a: FIXEDATOM AT=10,20,30
+d: DISTANCE ATOMS=a,20
+PRINT ARG=d FILE=colvar
+```
 
 */
 //+ENDPLUMEDOC

src/vatom/Ghost.cpp

@@ -32,30 +32,39 @@ namespace vatom {
 /*
 Calculate the absolute position of a ghost atom with fixed coordinates in the local reference frame formed by three atoms.
 
-The computed ghost atom is stored as a virtual atom that can be accessed in
- an atom list through the the label for the GHOST action that creates it.
+This action allows you to create a virtual atom that has a fixed set of coordinates in a local reference 
+frame that is formed by three atoms.  The way that this action is used is illustrated below:
 
-When running with periodic boundary conditions, the atoms should be
-in the proper periodic image. This is done automatically since PLUMED 2.10,
-by considering the ordered list of atoms and rebuilding the molecule using a procedure
-that is equivalent to that done in \ref WHOLEMOLECULES . Notice that
-rebuilding is local to this action. This is different from \ref WHOLEMOLECULES
-which actually modifies the coordinates stored in PLUMED.
-
-In case you want to recover the old behavior you should use the NOPBC flag.
-In that case you need to take care that atoms are in the correct
-periodic image.
-
-\par Examples
-
-The following input instructs plumed to print the distance between the
-ghost atom and the center of mass for atoms 15,20:
-\plumedfile
+```plumed
 c1: GHOST ATOMS=1,5,10 COORDINATES=10.0,10.0,10.0
 c2: COM ATOMS=15,20
 d1: DISTANCE ATOMS=c1,c2
 PRINT ARG=d1
-\endplumedfile
+```
+
+Notice that ghost atom's position is stored as [a virtual atom](specifying_atoms.md). The position of this atom can thus be 
+used in the DISTANCE command by using the label for the GHOST action.
+
+The position of the ghost atom `c1` for the input above is:
+
+$$
+r_{c1} = r_1 + 10\hat{a} + 10c + 10 \hat{b} 10\hat{c} 
+$$
+
+where unit vectors, $\hat{a}$, $\hat{b}$ and $\hat{c}$ in the expression above are obtained by dividing each 
+of the three (orthogonal) vectors below by their magnitudes:
+
+$$
+a = (r_5-r_1) \quad b = (r_5-r_1) \time (r_{10}-r_1) \quad (r_5-r_1)\times b
+$$
+
+In all these expressions $r_i$ is used to indicate the position of atom $i$. If you run with periodic boundary conditions
+these are taken into account automatically when computing the differences between position vectors above.  The way this is 
+handled is akin to the way molecules are rebuilt in the [WHOLEMOLECULES](WHOLEMOLECULES.md) command.  For the example above
+this would ensure that atom 5 is shifted to the periodic image where it is closest to atom 1 and atom 10 is shifted to the
+periodic image where it is closest to atom 10.  If you wish to 
+turn off this behaviour and you wish to disregard the periodic boundaries when computing these differences you should use 
+the NOPBC flag.  
 
 */
 //+ENDPLUMEDOC