Added new style documentation for everything in function

new-manual/parsing.md

@@ -27,8 +27,8 @@ t: METAD ARG=e1 SIGMA=0.15 PACE=10 HEIGHT=2 GRID_MIN=-pi GRID_MAX=pi GRID_BIN=20
 
 Notice here that the boundaries for `GRID_MIN` and `GRID_MAX` are `-pi` and `pi`. 
 
-Any real numbers that are read in from input are interpretted using the [Lepton library](Custom.md) so you can thus employ
-complicated expressions such as `1+2` or `exp(10)` as shown in the in the input as shown below:
+Any real numbers that are read in from input are interpretted using the [Lepton library] that is described in the documtation for the [CUSTOM](CUSTOM.md) 
+action. You can thus employ complicated expressions such as `1+2` or `exp(10)` as shown in the in the input as shown below:
 
 ```plumed
 #SETTINGS MOLFILE=regtest/basic/rt65/AA.pdb
@@ -37,7 +37,7 @@ e1: TORSION ATOMS=@epsilon-1
 RESTRAINT ARG=e1 AT=1+0.5
 ```
 
-The lepton library is able to interpret any of thse following constants:
+You can also also write expressions in terms of any of the following constants:
 
 | Symbol | Description | 
 | :----- |:------------|

src/function/Between.cpp

@@ -34,58 +34,106 @@ namespace function {
 /*
 Use a switching function to determine how many of the input variables are within a certain range.
 
-If we have multiple instances of a variable we can estimate the probability density function
-for that variable using a process called kernel density estimation:
+This action takes one argument, $s$ and evaluates the following function:
 
-\f[
-P(s) = \sum_i K\left( \frac{s - s_i}{w} \right)
-\f]
+$$
+w(s) = \int_a^b K\left( \frac{x - s}{\sigma} \right) \textrm{d}x
+$$
 
-In this equation \f$K\f$ is a symmetric function that must integrate to one that is often
-called a kernel function and \f$w\f$ is a smearing parameter.  From a probability density function calculated using
-kernel density estimation we can calculate the number/fraction of values between an upper and lower
-bound using:
+In this equation $K$ is a symmetric function that must integrate to one and that is often
+called a [kernel function](https://en.wikipedia.org/wiki/Kernel_(statistics)) and $\sigma$ is a smearing parameter.  
+The above function can be used to evaluate whether $s$ is between $a$ and $b$. The advantage of using the function above is that
+the resulting quantity has continuous derivatives. It can thus be used when calculating a collective variable upon which a simulation 
+bias will be applied.
 
-\f[
-w(s) = \int_a^b \sum_i K\left( \frac{s - s_i}{w} \right)
-\f]
+The following example, shows how we can apply the function above on the instantaneous value of the distance between atom 1 and 2. 
+The BETWEEN action here is used to determine whether the input distance is between 0.1 and 0.2 nm.
 
-All the input to calculate a quantity like \f$w(s)\f$ is generally provided through a single
-keyword that will have the following form:
+```plumed
+d: DISTANCE ATOMS=1,2
+b: BETWEEN ARG=d SWITCH={GAUSSIAN LOWER=0.1 UPPER=0.2 SMEAR=0.5}
+```
 
-KEYWORD={TYPE UPPER=\f$a\f$ LOWER=\f$b\f$ SMEAR=\f$\frac{w}{b-a}\f$}
+## The Kernel function
 
-This will calculate the number of values between \f$a\f$ and \f$b\f$.  To calculate
-the fraction of values you add the word NORM to the input specification.  If the
-function keyword SMEAR is not present \f$w\f$ is set equal to \f$0.5(b-a)\f$. Finally,
-type should specify one of the kernel types that is present in plumed. These are listed
-in the table below:
+The $\sigma$ values in the expressions above is calculated from the parameters $a$, $b$ and $s$ that are provided using the 
+`LOWER`, `UPPER` and `SMEAR` parameters respectively using the following function:
 
-<table align=center frame=void width=95%% cellpadding=5%%>
-<tr>
-<td> TYPE </td> <td> FUNCTION </td>
-</tr> <tr>
-<td> GAUSSIAN </td> <td> \f$\frac{1}{\sqrt{2\pi}w} \exp\left( -\frac{(s-s_i)^2}{2w^2} \right)\f$ </td>
-</tr> <tr>
-<td> TRIANGULAR </td> <td> \f$ \frac{1}{2w} \left( 1. - \left| \frac{s-s_i}{w} \right| \right) \quad \frac{s-s_i}{w}<1 \f$ </td>
-</tr>
-</table>
+$$
+\sigma = s(b-a)
+$$
 
-Some keywords can also be used to calculate a discrete version of the histogram.  That
-is to say the number of values between \f$a\f$ and \f$b\f$, the number of values between
-\f$b\f$ and \f$c\f$ and so on.  A keyword that specifies this sort of calculation would look
-something like
+Also note that the Kernel function $K$ that is used in the first example is a Gaussian. The actual integral that is evaluated is thus:
 
-KEYWORD={TYPE UPPER=\f$a\f$ LOWER=\f$b\f$ NBINS=\f$n\f$ SMEAR=\f$\frac{w}{n(b-a)}\f$}
+$$
+w(s) = \frac{1}{\sqrt{2\pi}\sigma} \int_a^b \exp\left( -\frac{(x-s)^2}{2\sigma^2} \textrm{d}x
+$$
 
-This specification would calculate the following vector of quantities:
+The Gaussian kernel in this expression can be replaced by a triangular Kernel by changing the input to:
 
-\f[
-w_j(s) = \int_{a + \frac{j-1}{n}(b-a)}^{a + \frac{j}{n}(b-a)} \sum_i K\left( \frac{s - s_i}{w} \right)
-\f]
+```plumed
+d: DISTANCE ATOMS=1,2
+b: BETWEEN ARG=d SWITCH={TRIANGULAR LOWER=0.1 UPPER=0.2 SMEAR=0.5}
+```
 
+With this input the integral is then evaluated using:
 
-\par Examples
+$$
+w(s) = \frac{1}{2\sigma} \int_a^b 1 - H\left( \frac{x-s}{\sigma} \right) \textrm{d}x
+$$
+
+where: 
+
+$$
+H(x) = \begin{cases}
+x & \textrm{if} \quad x<1 \\
+0 & \textrm{otherwise}
+\end{cases}
+$$
+
+## Non rank zero arguments
+
+Instead of passing a single scalar in the input to the `BETWEEN` action you can pass a single vector as shown here:
+
+```plumed
+d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8
+b: BETWEEN ARG=d SWITCH={GAUSSIAN LOWER=0.1 UPPER=0.2 SMEAR=0.5}
+```
+
+The input to the `BETWEEN` action here is a vector with four elements. The output from the action `b` is similarly 
+a vector with four elements. In calculating the elements of this vector PLUMED applies the function described in the previous 
+section on each of the distances in turn. The first element of `b` thus tells you if the distance between atoms 1 and 2 is between
+0.1 and 0.2 nm, the second element tells you if the distance between atoms 3 and 4 is between 0.1 and 0.2 nm and so on.
+
+You can use the commands in the above example input to evaluate the number of distances that are within the range of interest as follows:
+
+```plumed
+d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8
+b: BETWEEN ARG=d SWITCH={GAUSSIAN LOWER=0.1 UPPER=0.2 SMEAR=0.5}
+s: SUM ARG=b PERIODIC=NO
+PRINT ARG=s FILE=colvar
+```
+
+The final scalar that is output here is evaluated using the following summation:
+
+$$
+s = \sum_i \int_a^b \left( \frac{x - d_i}{\sigma} \right) \textrm{d}x
+$$
+
+where the sum over $i$ here runs over the four distances in the above expression. This scalar tells you the number of distances that are 
+between 0.1 and 0.2.
+
+Notice that you can do something similar with a matrix as input as shown below:
+
+```plumed
+d: DISTANCE_MATRIX GROUPA=1-10 GROUPB=11-20
+b: BETWEEN ARG=d SWITCH={GAUSSIAN LOWER=0.1 UPPER=0.2 SMEAR=0.5}
+s: SUM ARG=b PERIODIC=NO
+PRINT ARG=s FILE=colvar
+```
+
+This input tells PLUMED to calculate the 100 distances between the atoms in the two input groups. The final value that is printed to the colvar file then 
+tells you how many of these distances are between 0.1 and 0.2 nm. 
 
 */
 //+ENDPLUMEDOC

src/function/Combine.cpp

@@ -34,45 +34,119 @@ namespace function {
 /*
 Calculate a polynomial combination of a set of other variables.
 
-The functional form of this function is
+This action takes in $N_{arg}$ arguments ($x_i$) and computes the following function of them:
+
 \f[
 C=\sum_{i=1}^{N_{arg}} c_i (x_i-a_i)^{p_i}
 \f]
 
-The coefficients c, the parameters a and the powers p are provided as vectors.
+The $c_i$, $a_i$ and $p_i$ values in this expression are provided through the COEFFICIENTS, PARAMETERS and POWERS keywords respectively. 
+The following example illustrates how this action can be used to calculate and print the square of the distance between atom 1 and atom 2.
 
-Notice that COMBINE is not able to predict which will be periodic domain
-of the computed value automatically. The user is thus forced to specify it
-explicitly. Use PERIODIC=NO if the resulting variable is not periodic,
-and PERIODIC=A,B where A and B are the two boundaries if the resulting variable
-is periodic.
+```plumed
+d: DISTANCE ATOMS=1,2 COMPONENTS
+c: COMBINE ARG=d.x,d.y,d.z COEFFICIENTS=1,1,1 PARAMETERS=0,0,0 POWERS=2,2,2 PERIODIC=NO
+PRINT ARG=c FILE=colvar
+```
 
+Notice that if the COEFFICIENTS keyword is absent all the $c_i$ values are set equal to 1.
+Furthermore, if the PARAMETERS keyword is absent all the $a_i$ values are set equal to 0.
+We can thus make use of these defaults and rewrite the input above as:
 
+```plumed
+d: DISTANCE ATOMS=1,2 COMPONENTS
+c: COMBINE ARG=d.x,d.y,d.z POWERS=2,2,2 PERIODIC=NO
+PRINT ARG=c FILE=colvar
+```
 
-\par Examples
+Notice that we cannot remove the POWERS keyword here as if it is absent all the $p_i$ values are set equal to 1.
+
+## Periodic arguments
 
-The following input tells plumed to print the distance between atoms 3 and 5
-its square (as computed from the x,y,z components) and the distance
-again as computed from the square root of the square.
-\plumedfile
-DISTANCE LABEL=dist      ATOMS=3,5 COMPONENTS
-COMBINE  LABEL=distance2 ARG=dist.x,dist.y,dist.z POWERS=2,2,2 PERIODIC=NO
-COMBINE  LABEL=distance  ARG=distance2 POWERS=0.5 PERIODIC=NO
-PRINT ARG=distance,distance2
-\endplumedfile
-(See also \ref PRINT and \ref DISTANCE).
-
-The following input tells plumed to add a restraint on the
-cube of a dihedral angle. Notice that since the angle has a
-periodic domain
--pi,pi its cube has a domain -pi**3,pi**3.
-\plumedfile
+The COMBINE action is not able to predict the periodic domain for the function that is computed from the arguments 
+automatically.  The user is thus forced to specify it explicitly. Use PERIODIC=NO if the resulting variable is not periodic,
+and PERIODIC=A,B where A and B are the two boundaries for the periodic domain if the resulting variable is periodic.
+The following provides an example where the output from combine has a periodic domain.  In this input we are taking the 
+cube of a dihedral angle.  The dihedral angle has a periodic domain that runs from $-\pi$ to $\pi$.  The cube of this variable
+thus has a periodic domain that runs from $-\pi^3$ to $\pi^3$ as indicated in the following input.
+
+```plumed
 t: TORSION ATOMS=1,3,5,7
-c: COMBINE ARG=t POWERS=3 PERIODIC=-31.0062766802998,31.0062766802998
-RESTRAINT ARG=c KAPPA=10 AT=0
-\endplumedfile
+#c: COMBINE ARG=t POWERS=3 PERIODIC=-31.0062766802998,31.0062766802998
+c: COMBINE ARG=t POWERS=3 PERIODIC=-pi^3,pi^3
+PRINT ARG=c FILE=colvar
+```
+
+## Vector arguments
+
+The two examples in the previous section demonstrate how to use the COMBINE action with scalar arguments.  However, you can also
+pass arguments to this action that have a rank greater than zero.  For example, in the example below COMBINE accepts three 
+vectors with 4 elements in input:
+
+```plumed
+d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8 COMPONENTS
+c: COMBINE ARG=d.x,d.y,d.z POWERS=2,2,2 PERIODIC=NO
+PRINT ARG=c FILE=colvar
+```
+
+The output from the COMBINE action here is also a vector with four elements. The first element of this vector is the square of the 
+distance betwen atoms 1 and 2, the secton is the square of the distance between atoms 3 and 4 and so on.
+
+The COMBINE action can also take a mixture of scalars and vectors in input.  The following input illustrates an 
+COMBINE action that takes vectors and scalars in input.
+
+```plumed
+p: CONSTANT VALUE=2
+d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8
+c: COMBINE ARG=d,p COEFFICIENTS=4,-1 POWERS=2.5,1 
+PRINT ARG=c FILE=colvar
+```
+
+The elements of the vector that is calculated by the COMBINE action here are given by:
+
+$$
+c_i = 4d_i^{2.5} - 2 
+$$
+
+The $d_i$ in this expression are the distances that were calculated by the DISTANCE action. The 2 comes 
+from the scalar `p` that passed to the ARG action in input.  As a single scalar is passed the same number is 
+used when calculating all 4 elements of the output vector.  In other words, the scalar behaves as if it is a 
+vector with four components that all have the same value.
+
+Lastly, notice that if you pass a single vector in input to COMBINE as in the following example, the output is still a vector:
+
+```plumed
+d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8
+c: COMBINE ARG=d COEFFICIENTS=4 POWERS=2.5 PARAMETERS=0.5
+PRINT ARG=c FILE=colvar
+```
+
+To calculate the 4-dimensional output by the COMBINE action here we subtract 0.5 from each of the input distances, raise
+the result from this subtraction to the power 2.5 and then multiply the result by 4.
+
+If you want to calculate a linear combination of the elements of a vector using the formula at the top of the page you should use
+the [CUSTOM](CUSTOM.md) action to transform all the components of the input vector.  You can then add all the results from these 
+transformations together using [SUM](SUM.md).
+
+## Matrix arguments
+
+You can also use matrices in the input to the COMBINE action as illustrated below:
+
+```plumed
+d: DISTANCE_MATRIX GROUPA=1,2 GROUPB=3,4,5 COMPONENTS
+c: COMBINE ARG=d.x,d.y,d.z POWERS=2,2,2 PERIODIC=NO
+PRINT ARG=c FILE=colvar
+```
+
+The input to the combine action here consists of three $2\times3$ matrices. The output is thus a $2\times3$ matrix that contains the squares of the 
+distances between the atoms in GROUPA and the atoms in GROUPB.  Notice that all the input matrices must have the same size as the elements of the final
+matrix are calculated by applying the formula in the first section of this input to each set of elements to the input matrices in turn.
 
+The input to this action can be a combination of matrices and scalars.  If your input arguments are an $N\times M$ matrix and a scalar the scalar is treated as if 
+it is a $N\times M$ matrix which has all its elements equal to the input scalar. You __cannot__ use a mixture of vectors and matrices in the input to this action.
 
+Furthermore, if you pass a single matrix to COMBINE the output is a matrix.  To calculate a linear combination of all the elements in a matrix using the formula at the top of the page you should use
+the [CUSTOM](CUSTOM.md) action to transform all the components of the input vector.  You can then add all the results from these transformations together using [SUM](SUM.md).
 
 */
 //+ENDPLUMEDOC