Added new style documentation for stuff in volume module

src/volumes/VolumeAround.cpp

@@ -42,10 +42,10 @@ The 100 elements of the vector `a` that is returned from the AROUND action in th
 w(x_i,y_i,z_i) = \int_{xl}^{xu} \int_{yl}^{yu} \int_{zl}^{zu} \textrm{d}x\textrm{d}y\textrm{d}z K\left( \frac{x - x_i}{\sigma} \right)K\left( \frac{y - y_i}{\sigma} \right)K\left( \frac{z - z_i}{\sigma} \right)
 $$ 
 
-where \f$K\f$ is one of the kernel functions described in the documentation for the function [BETWEEN](BETWEEN.md), $\sigma$ is a bandwidth parameter and the limits
+where $K$ is one of the kernel functions described in the documentation for the function [BETWEEN](BETWEEN.md), $\sigma$ is a bandwidth parameter and the limits
 for the integrals are the values specified using the keywords XLOWER, XUPPER, YLOWER, YUPPER, YUPPER, ZLOWER and ZUPPER.  $x_i$, $y_i$ and $z_i$ are then the components
 of the vector that connects the $i$th atom that was specified using the ATOMS keyword to the atom that was specified using the ORIGIN keyword.  In other words, 
-$w((x_i,y_i,z_i)$ is 1 if the atom is within a rectangular box that is centered on the atom that is specified as the origin and zero otherwise.
+$w(x_i,y_i,z_i)$ is 1 if the atom is within a rectangular box that is centered on the atom that is specified as the origin and zero otherwise.
 
 ## Calculating the number of atoms in a particular part of the box
 

src/volumes/VolumeBetweenContours.cpp

@@ -31,29 +31,32 @@
 /*
 This quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a region where the density of a certain type of atom is high.
 
-This collective variable can be used to determine whether colvars are within region where the density
-of a particular atom is high.  This is achieved by calculating the following function at the point where
-the atom is located \f$(x,y,z)\f$:
+This collective variable can be used to determine whether atoms are within region where the density
+of a particular atom type is high.  This is achieved by calculating the following function at the point where
+each atom is located $(x_i,y_i,z_i)$:
 
-\f[
-w_j = 1 - \sigma\left[ \sum_{i=1}^N K\left( \frac{x-x_i}{\sigma_x},\frac{y-y_i}{\sigma_y},\frac{z-z_i}{\sigma_z} \right) \right]
-\f]
+$$
+w_i = 1 - \sigma\left[ \sum_{i=1}^N K\left( \frac{x-x_i}{\sigma_x},\frac{y-y_i}{\sigma_y},\frac{z-z_i}{\sigma_z} \right) \right]
+$$
 
-Here \f$\sigma\f$ is a \ref switchingfunction and \f$K\f$ is a \ref kernelfunctions.  The sum runs over the atoms
-specified using the ATOMS keyword and a \f$w_j\f$ value is calculated for each of the central atoms of the input
+Here $\sigma$ is one of the switching functions that is discussed in the documentation for the action [LESS_THAN](LESS_THAN.md) and $K$ is 
+one of the kernel functions that is discussed in the documentation for the action [BETWEEN](BETWEEN.md).  The sum runs over the atoms
+specified using the FIELD_ATOMS keyword and a $w_j$ value is calculated for each of the central atoms of the input
 multicolvar.
 
-\par Examples
-
-The input below calculates a density field from the positions of atoms 1-14400.  The number of the atoms
-that are specified in the DENSITY action that are within a region where the density field is greater than
-2.0 is then calculated.
+The input below shows how this action works in practise.  This input calculates a density field from the positions of atoms 1-14400. A vector which has 
+as many elements as atoms that were specified using the ATOMS keyword.  The $i$th element of this vector is calculated using the expression above with $(x_i,y_i,z_i)$
+being the position of the $i$th atom that was specified using that ATOMS keyword.
 
-\plumedfile
-d1: DENSITY SPECIES=14401-74134:3 LOWMEM
-fi: INENVELOPE DATA=d1 ATOMS=1-14400 CONTOUR={RATIONAL D_0=2.0 R_0=1.0} BANDWIDTH=0.1,0.1,0.1 LOWMEM
+```plumed
+fi: INENVELOPE ATOMS=14401-74134:3 FIELD_ATOMS=1-14400 CONTOUR={RATIONAL D_0=2.0 R_0=1.0} BANDWIDTH=0.1,0.1,0.1 
 PRINT ARG=fi FILE=colvar
-\endplumedfile
+```
+
+This particular action was developed with the intention of determining whether water molecules had penetrated a membrane or not. The FIELD_ATOMS were thus the atoms of the 
+lipid molecules that made up the membrane and the ATOMS were the oxygens of the water molecules. The vector that is output by this action can be used in all the ways that the 
+vector that is output by the [AROUND](AROUND.md) action is used.  In other words, this action can be used to calculate the number of water molecules in the membrane or the average
+values for a symmetry function for those atoms that are within the membrane.
 
 */
 //+ENDPLUMEDOC

src/volumes/VolumeCavity.cpp

@@ -30,74 +30,78 @@
 /*
 This quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a box defined by the positions of four atoms.
 
-Each of the base quantities calculated by a multicolvar can can be assigned to a particular point in three
-dimensional space. For example, if we have the coordination numbers for all the atoms in the
-system each coordination number can be assumed to lie on the position of the central atom.
-Because each base quantity can be assigned to a particular point in space we can calculate functions of the
-distribution of base quantities in a particular part of the box by using:
-
-\f[
-\overline{s}_{\tau} = \frac{ \sum_i f(s_i) w(u_i,v_i,w_i) }{ \sum_i w(u_i,v_i,w_i) }
-\f]
-
-where the sum is over the collective variables, \f$s_i\f$, each of which can be thought to be at \f$ (u_i,v_i,z_i)\f$.
-The function \f$(s_i)\f$ can be any of the usual LESS_THAN, MORE_THAN, WITHIN etc that are used in all other multicolvars.
-Notice that here (at variance with what is done in \ref AROUND) we have transformed from the usual \f$(x_i,y_i,z_i)\f$
-position to a position in \f$ (u_i,v_i,z_i)\f$.  This is done using a rotation matrix as follows:
-
-\f[
+This action can be used similarly to the way [AROUND](AROUND.md) is used.  Like [AROUND](AROUND.md) this action returns a vector
+with elements that tell you whether an input atom is within a part of the box that is of particular interest or not. However, for this action
+the elements of this vector are calculated using:
+
+$$
+w(u_i,v_i,w_i) = \int_{0}^{u'} \int_{0}^{v'} \int_{0}^{w'} \textrm{d}u\textrm{d}v\textrm{d}w
+   K\left( \frac{u - u_i}{\sigma} \right)K\left( \frac{v - v_i}{\sigma} \right)K\left( \frac{w - w_i}{\sigma} \right)
+$$
+
+with $u_i,v_i,w_i$ being calculated from the positon of the $i$th atom, $(x_i,y_i,z_i)$, by performing the following transformation.
+
+$$
 \left(
 \begin{matrix}
  u_i \\
  v_i \\
  w_i
 \end{matrix}
-\right) = \mathbf{R}
+\right) = R
 \left(
 \begin{matrix}
  x_i - x_o \\
  y_i - y_o \\
  z_i - z_o
 \end{matrix}
 \right)
-\f]
+$$
 
-where \f$\mathbf{R}\f$ is a rotation matrix that is calculated by constructing a set of three orthonormal vectors from the
+In this expression $R$ is a rotation matrix that is calculated by constructing a set of three orthonormal vectors from the
 reference positions specified by the user. The first of these unit vectors points from the first reference atom to the second.
 The second is then the normal to the plane containing atoms 1,2 and 3 and the the third is the unit vector orthogonal to
-these first two vectors.  \f$(x_o,y_o,z_o)\f$, meanwhile, specifies the position of the first reference atom.
-
-In the previous function \f$ w(u_i,v_i,w_i) \f$ measures whether or not the system is in the subregion of interest. It
-is equal to:
-
-\f[
-w(u_i,v_i,w_i) = \int_{0}^{u'} \int_{0}^{v'} \int_{0}^{w'} \textrm{d}u\textrm{d}v\textrm{d}w
-   K\left( \frac{u - u_i}{\sigma} \right)K\left( \frac{v - v_i}{\sigma} \right)K\left( \frac{w - w_i}{\sigma} \right)
-\f]
-
-where \f$K\f$ is one of the kernel functions described on \ref histogrambead and \f$\sigma\f$ is a bandwidth parameter.
-The vector connecting atom 1 to atom 4 is used to define the extent of the box in each of the \f$u\f$, \f$v\f$ and \f$w\f$
-directions.  Essentially the vector connecting atom 1 to atom 4 is projected onto the three unit vectors
-described above and the resulting projections determine the \f$u'\f$, \f$v'\f$ and \f$w'\f$ parameters in the above expression.
-
-\par Examples
-
-The following commands tell plumed to calculate the number of atoms in an ion channel in a protein.
-The extent of the channel is calculated from the positions of atoms 1, 4, 5 and 11. The final value will be labeled cav.
-
-\plumedfile
-d1: DENSITY SPECIES=20-500
-CAVITY DATA=d1 ATOMS=1,4,5,11 SIGMA=0.1 LABEL=cav
-\endplumedfile
-
-The following command tells plumed to calculate the coordination numbers (with other water molecules) for the water
-molecules in the protein channel described above.  The average coordination number and the number of coordination
-numbers more than 4 is then calculated.  The values of these two quantities are given the labels cav.mean and cav.morethan
-
-\plumedfile
-d1: COORDINATIONNUMBER SPECIES=20-500 R_0=0.1
-CAVITY DATA=d1 ATOMS=1,4,5,11 SIGMA=0.1 MEAN MORE_THAN={RATIONAL R_0=4} LABEL=cav
-\endplumedfile
+these first two vectors.  $(x_o,y_o,z_o)$, meanwhile, specifies the position of the first reference atom.
+
+In the first expression above $K$ is one of the kernel functions described in the documentation for the action [BETWEEN](BETWEEN.md) 
+and $\sigma$ is a bandwidth parameter.  Furthermore, The vector connecting atom 1 to atom 4 is used to define the extent of the box in 
+each of the $u$, $v$ and $w$ directions.  This vector connecting atom 1 to atom 4 is projected onto the three unit vectors
+described above and the resulting projections determine the $u'$, $v'$ and $w'$ parameters in the above expression.
+
+The following commands illustrate how this works in practise.  We are using PLUMED here to calculate the number of atoms from the group specified using the ATOMS keyword below are 
+in an ion channel in a protein.  The extent of the channel is calculated from the positions of atoms 1, 4, 5 and 11. 
+
+```plumed
+cav: CAVITY ATOMS=20-500 BOX=1,4,5,11 SIGMA=0.1 
+s: SUM ARG=cav PERIODIC=NO
+PRINT ARG=s FILE=colvar
+```
+
+By contrst the following command tells plumed to calculate the coordination numbers (with other water molecules) for the water
+molecules in the protein channel described above. The average coordination number and the number of coordination
+numbers more than 4 is then calculated for those molecules that are in the region of interest.  
+
+```plumed
+# Calculate the atoms that are in the cavity
+cav: CAVITY ATOMS=20-500 BOX=1,4,5,11 SIGMA=0.1
+# Calculate the coordination numbers of all the atoms
+d1: COORDINATIONNUMBER SPECIES=20-500 SWITCH={RATIONAL R_0=0.1}
+# Do atoms have a coordination number that is greater than 4
+fd1: MORE_THAN ARG=d1 SWITCH={RATIONAL R_0=4}
+# Calculate the mean coordination number in the channel
+nnn: CUSTOM ARG=cav,d1 FUNC=x*y PERIODIC=NO
+numer: SUM ARG=nnn PERIODIC=NO
+denom: SUM ARG=cav PERIODIC=NO
+mean: CUSTOM ARG=numer,denom FUNC=x/y PERIODIC=NO
+# Calculate the number of atoms that are in the channel and that have a coordination number that is greater than 4
+sss: CUSTOM ARG=fd1,cav FUNC=x*y PERIODIC=NO
+mt: SUM ARG=sss PERIODIC=NO
+# And print these two quantities to a file
+PRINT ARG=mean,mt FILE=colvar
+```
+
+As with [AROUND](AROUND.md) earlier version of PLUMED used a different syntax for doing these types of calculations, which can 
+still be used with this new version of the command.  However, we strongly recommend using the newer syntax.
 
 */
 //+ENDPLUMEDOC

src/volumes/VolumeInCylinder.cpp

@@ -29,41 +29,48 @@
 /*
 This 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.
 
-Each of the base quantities calculated by a multicolvar can can be assigned to a particular point in three
-dimensional space. For example, if we have the coordination numbers for all the atoms in the
-system each coordination number can be assumed to lie on the position of the central atom.
-Because each base quantity can be assigned to a particular point in space we can calculate functions of the
-distribution of base quantities in a particular part of the box by using:
-
-\f[
-\overline{s}_{\tau} = \frac{ \sum_i f(s_i) \sigma(r_{xy}) }{ \sum_i \sigma(r_{xy}) }
-\f]
-
-where the sum is over the collective variables, \f$s_i\f$, each of which can be thought to be at \f$ (x_i,y_i,z_i)\f$.
-The function \f$\sigma\f$ is a \ref switchingfunction that acts on the distance between the point at which the
-collective is located \f$(x_i,y_i,z_i)\f$ and the position of the atom that was specified using the ORIGIN keyword
-projected in the xy plane if DIRECTION=z is used.  In other words:
-\f[
-r_{xy} = sqrt{ ( x_i - x_0)^2 + ( y_i - y_0)^2 }
-\f]
-In short this function, \f$\sigma(r_{xy})\f$, measures whether or not the CV is within a cylinder that
-runs along the axis specified using the DIRECTION keyword and that is centered on the position of the atom specified using
-ORIGIN.
-
-The function \f$(s_i)\f$ can be any of the usual LESS_THAN, MORE_THAN, WITHIN etc that are used in all other multicolvars.
-
-When INCYLINDER is used with the \ref DENSITY action the number of atoms in the specified region is calculated
+This action can be used to calculate whether each of the atoms are within a particular part of the simulation box or not as illustrated by the following example:
 
-\par Examples
+```plumed
+f: FIXEDATOM AT=0,0,0
+a: INCYLINDER ATOMS=1-100 CENTER=f DIRECTION=Z RADIUS={TANH R_0=1.5} SIGMA=0.1 LOWER=-1.0 UPPER=1.0 
+PRINT ARG=a FILE=colvar
+```
+
+The 100 elements of the vector `a` that is returned from the INCYLINDER action in the above input are calculated using:
+
+$$
+w(x_i,y_i,z_i) = s\left( r_{xy} \right) \int_{zl}^{zu} \textrm{d}z K\left( \frac{z - z_i}{\sigma} \right)
+$$
+
+where
+
+$$
+r_{xy} = \sqrt{ x_i^2 + y_i^2 }
+$$
+
+In these expressions $K$ is one of the kernel functions described in the documentation for the function [BETWEEN](BETWEEN.md), $\sigma$ is a bandwidth parameter and the limits
+for the integrals are the values specified using the keywords `LOWER` and `UPPER`. $x_i$, $y_i$ and $z_i$ are then the components
+of the vector that connects the $i$th atom that was specified using the `ATOMS` keyword to the atom that was specified using the `CENTER` keyword.  In other words, 
+$w(x_i,y_i,z_i)$ is 1 if the atom is within a cylinder that is centered on the $z$ axis that has an extent along the $z$ direction around the position of atom `f` that 
+is determined by the values specified by `LOWER` and `UPPER` keywords.  The radial extent of this cylinder is determined by the parameters of the switching function that is 
+specified using the `RADIUS` keyword. 
+
+If you want to caluclate and print the number of atoms in the cylinder of interest you can use an input like the one shown below:
+
+```plumed
+f: FIXEDATOM AT=0,0,0
+a: INCYLINDER ATOMS=1-100 CENTER=f DIRECTION=X RADIUS={TANH R_0=1.5} SIGMA=0.1 LOWER=-1.0 UPPER=1.0 
+s: SUM ARG=a PERIODIC=NO
+PRINT ARG=s FILE=colvar
+```
+
+Notice that now the cylinder is centered on the `x` axis rather than the `z` axis as we have changed the input for the `DIRECTION` keyword.  
 
-The input below can be use to calculate the average coordination numbers for those atoms that are within a cylindrical tube
-of radius 1.5 nm that is centered on the position of atom 101 and that has its long axis parallel to the z-axis.
+You can also calculate the average values of symmetry functions in the cylinder of interest by using inputs similar to those described the documentation for the [AROUND](AROUND.md) 
+action. In other words, you can swap out AROUND actions for an INCLYLINDER actions. Also as with [AROUND](AROUND.md), earlier versions of PLUMED used a different syntax for doing these 
+types of calculations, which can still be used with this new version of the command.  However, we strongly recommend using the newer syntax.
 
-\plumedfile
-c1: COORDINATIONNUMBER SPECIES=1-100 SWITCH={RATIONAL R_0=0.1}
-d2: INCYLINDER ATOM=101 DATA=c1 DIRECTION=Z RADIUS={TANH R_0=1.5} SIGMA=0.1 LOWER=-0.1 UPPER=0.1 MEAN
-PRINT ARG=d2.* FILE=colvar
-\endplumedfile
 
 */
 //+ENDPLUMEDOC

src/volumes/VolumeInSphere.cpp

@@ -29,40 +29,38 @@
 /*
 This 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.
 
-Each of the base quantities calculated by a multicolvar can can be assigned to a particular point in three
-dimensional space. For example, if we have the coordination numbers for all the atoms in the
-system each coordination number can be assumed to lie on the position of the central atom.
-Because each base quantity can be assigned to a particular point in space we can calculate functions of the
-distribution of base quantities in a particular part of the box by using:
-
-\f[
-\overline{s}_{\tau} = \frac{ \sum_i f(s_i) \sigma(r) }{ \sum_i \sigma(r) }
-\f]
-
-where the sum is over the collective variables, \f$s_i\f$, each of which can be thought to be at \f$ (x_i,y_i,z_i)\f$.
-The function \f$\sigma\f$ is a \ref switchingfunction that acts on the distance between the point at which the
-collective is located \f$(x_i,y_i,z_i)\f$ and the position of the atom that was specified using the ORIGIN keyword.
-In other words:
-\f[
-r = sqrt{ ( x_i - x_0)^2 + ( y_i - y_0)^2 + ( z_i - z_0)^2}
-\f]
-In short this function, \f$\sigma(r_{xy})\f$, measures whether or not the CV is within a sphere that is
-centered on the position of the atom specified using the keyword ORIGIN.
-
-The function \f$(s_i)\f$ can be any of the usual LESS_THAN, MORE_THAN, WITHIN etc that are used in all other multicolvars.
-
-When INCYLINDER is used with the \ref DENSITY action the number of atoms in the specified region is calculated
+This action can be used to calculate whether each of the atoms are within a particular part of the simulation box or not as illustrated by the following example:
 
-\par Examples
+```plumed
+f: FIXEDATOM AT=0,0,0
+a: INSPHERE ATOMS=1-100 CENTER=f RADIUS={GAUSSIAN R_0=1.5}  
+PRINT ARG=a FILE=colvar
+```
+
+The 100 elements of the vector `a` that is returned from the INSPHERE action in the above input are calculated using:
+
+$$
+w(x_i,y_i,z_i) = \sigma\left( \sqrt{ x_i^2 + y_i^2 + z_i^2}  \right) 
+$$
+
+In this expression $x_i$, $y_i$ and $z_i$ are the components of the vector that connects the $i$th atom that was specified using the `ATOMS` keyword to the atom that was specified using the `CENTER` keyword and
+$\sigma$ is one of the switching functions that is described that in the documentation for the action [LESS_THAN](LESS_THAN.md).  In other words, 
+$w(x_i,y_i,z_i)$ is 1 if atom $i$ is within a sphere with a radial extent that is determined by the parameters of the specified switching function 
+and zero otherwise.
+
+If you want to caluclate and print the number of atoms in the sphere of interest you can use an input like the one shown below:
+
+```plumed
+f: FIXEDATOM AT=0,0,0
+a: INSPHERE ATOMS=1-100 CENTER=f RADIUS={GAUSSIAN R_0=1.5}
+s: SUM ARG=a PERIODIC=NO
+PRINT ARG=s FILE=colvar
+```
 
-The input below can be use to calculate the average coordination numbers for those atoms that are within a sphere
-of radius 1.5 nm that is centered on the position of atom 101.
+You can also calculate the average values of symmetry functions in the sphere of interest by using inputs similar to those described the documentation for the [AROUND](AROUND.md) 
+action. In other words, you can swap out AROUND actions for an INSPHERE actions.  Also as with [AROUND](AROUND.md), earlier versions of PLUMED used a different syntax for doing these types of calculations, which can 
+still be used with this new version of the command.  However, we strongly recommend using the newer syntax.
 
-\plumedfile
-c1: COORDINATIONNUMBER SPECIES=1-100 SWITCH={RATIONAL R_0=0.1}
-d2: INSPHERE ATOM=101 DATA=c1 RADIUS={TANH R_0=1.5} MEAN
-PRINT ARG=d2.* FILE=colvar
-\endplumedfile
 
 */
 //+ENDPLUMEDOC