Reworked documentation for all actions in generic module to make this…

… module work with the new manual

new-manual/common.dat

@@ -0,0 +1 @@
+t: TORSION ATOMS=1,2,3,4

new-manual/groups.dat

@@ -0,0 +1,19 @@
+groupa: GROUP ...
+  ATOMS={
+    10
+    50
+    60
+    70
+    80
+    120
+  }
+...
+groupb: GROUP ...
+  ATOMS={
+    11
+    51
+    61
+    71
+    81
+    121
+  }

new-manual/other.0.inc

@@ -0,0 +1 @@
+RESTRAINT ARG=t AT=1.0 KAPPA=10

new-manual/other.1.inc

@@ -0,0 +1 @@
+RESTRAINT ARG=t AT=1.2 KAPPA=10

new-manual/pippo.dat

@@ -0,0 +1,2 @@
+c1: COM ATOMS=1-100
+c2: COM ATOMS=101-202

src/generic/Accumulate.cpp

@@ -30,7 +30,84 @@
 /*
 Sum the elements of this value over the course of the trajectory
 
-\par Examples
+This action is used to sum the outputs from another action over the course of the trajectory.  This is useful 
+if you want to calculate the average value that a CV took over the course of a simulation.  As an example, the following
+input can be used to calculate the average distance between atom 1 and atom 2.
+
+```plumed
+c: CONSTANT VALUE=1
+d: DISTANCE ATOMS=1,2
+# This adds together the value of the distance on every step
+s: ACCUMULATE ARG=d STRIDE=1
+# This adds one every time we add a new distance to the value s
+n: ACCUMULATE ARG=c STRIDE=1
+# This is thus the average distance
+a: CUSTOM ARG=s,n FUNC=x/y PERIODIC=NO
+# This prints out the average over the whole trajectory (STRIDE=0 means print at end only)
+PRINT ARG=a FILE=average STRIDE=0
+```
+
+You can use this action for block averaging by using the `CLEAR` keyword as shown below:
+
+```plumed
+c: CONSTANT VALUE=1
+d: DISTANCE ATOMS=1,2
+# This adds together the value of the distance on every step
+s: ACCUMULATE ARG=d STRIDE=1 CLEAR=1000
+# This adds one every time we add a new distance to the value s
+n: ACCUMULATE ARG=c STRIDE=1 CLEAR=1000
+# This is thus the average distance
+a: CUSTOM ARG=s,n FUNC=x/y PERIODIC=NO
+# This prints out the average over the whole trajectory (STRIDE=0 means print at end only)
+PRINT ARG=a FILE=average STRIDE=1000
+```
+
+The instructions `CLEAR=1000` in the above input tells PLUMED to set the values `s` and `n` back to 
+zero after 1000 new steps have been performed. The PRINT action will thus print a block average that 
+is taken from the first 1000 steps of the trajectory, a second block average from the second 1000 steps
+of the trajectory and so on.
+
+## Estimating histograms
+
+We can also use this action to construct histograms. The example below shows how you can estimate the 
+distribution of distances between atoms 1 and 2 that are sampled over the course of the trajectory.
+
+```plumed
+c: CONSTANT VALUE=1
+d: DISTANCE ATOMS=1,2
+# Construct the instantaneous histogram from the instantaneous value of the distance
+kde: KDE ARG=d BANDWIDTH=0.05 GRID_MIN=0 GRID_MAX=5 GRID_BIN=250 
+# Now add together all the instantaneous histograms
+hist: ACCUMULATE ARG=kde STRIDE=1 
+# And normalise the histogram
+n: ACCUMULATE ARG=c STRIDE=1
+a: CUSTOM ARG=hist,n FUNC=x/y PERIODIC=NO
+# And print out the final histogram
+DUMPGRID ARG=a FILE=histo.grid 
+```
+
+At first glance the fact that we use a [KDE](KDE.md) action to construct an instaneous histogram from a single 
+distance may appear odd.  The reason for doing this, however, is to introduce a clear distinction between 
+the syntaxes that are used for spatial and temporal averaging.  To see what I mean consider the following input:
+
+
+```plumed
+c: CONSTANT VALUE=5
+d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8 ATOMS5=9,10
+# Construct the instantaneous histogram from the instantaneous value of the distance
+kde: KDE ARG=d BANDWIDTH=0.05 GRID_MIN=0 GRID_MAX=5 GRID_BIN=250 
+# Now add together all the instantaneous histograms
+hist: ACCUMULATE ARG=kde STRIDE=1 
+# And normalise the histogram
+n: ACCUMULATE ARG=c STRIDE=1
+a: CUSTOM ARG=hist,n FUNC=x/y PERIODIC=NO
+# And print out the final histogram
+DUMPGRID ARG=a FILE=histo.grid 
+```
+
+This input computes 5 distances. Kernels correpsonding to all five of these distances are added to the instaneous 
+histogram that is constructed using the [KDE](KDE.md) action.  When we call the accumulate action here we are thus 
+not simply adding a single kernel to the accumulated grid when we add the the elements from `kde`.  
 
 */
 //+ENDPLUMEDOC

src/generic/Average.cpp

@@ -28,61 +28,64 @@
 /*
 Calculate the ensemble average of a collective variable
 
-The ensemble average for a non-periodic, collective variable, \f$s\f$ is given by the following expression:
+The ensemble average for a non-periodic, collective variable, $s$ is given by the following expression:
 
-\f[
+$$
 \langle s \rangle = \frac{ \sum_{t'=0}^t w(t') s(t') }{ \sum_{t'=0}^t w(t') }
-\f]
+$$
 
-Here the sum runs over a the trajectory and \f$s(t')\f$ is used to denote the value of the collective variable
-at time \f$t'\f$.  The final quantity evaluated is a weighted
-average as the weights, \f$w(t')\f$, allow us to negate the effect any bias might have on the region of phase space
-sampled by the system.  This is discussed in the section of the manual on \ref Analysis.
+Here the sum runs over a the trajectory and $s(t')$ is used to denote the value of the collective variable
+at time $t'$.  The final quantity evaluated is a weighted
+average as the weights, If the simulation is unbiassed then all the $w(t')$ values in teh expression above are 
+zero.  If the simulation is biased then the $w(t')$ weights are set in a way that ensures the effect any bias 
+has on the region of phase space sampled by the system is negated.
 
-When the variable is periodic (e.g. \ref TORSION) and has a value, \f$s\f$, in \f$a \le s \le b\f$ the ensemble average is evaluated using:
+As the following example input shows you can use the AVERAGE shortcut to calculate the ensemble average of a CV using this formula:
 
-\f[
-\langle s \rangle = a + \frac{b - a}{2\pi} \arctan \left[ \frac{ \sum_{t'=0}^t w(t') \sin\left( \frac{2\pi [s(t')-a]}{b - a} \right) }{ \sum_{t'=0}^t w(t') \cos\left( \frac{2\pi [s(t')-a]}{b - a} \right) } \right]
-\f]
-
-\par Examples
-
-The following example calculates the ensemble average for the distance between atoms 1 and 2
-and output this to a file called COLVAR.  In this example it is assumed that no bias is acting
-on the system and that the weights, \f$w(t')\f$ in the formulas above can thus all be set equal
-to one.
-
-\plumedfile
+```plumed
 d1: DISTANCE ATOMS=1,2
 d1a: AVERAGE ARG=d1
 PRINT ARG=d1a FILE=colvar STRIDE=100
-\endplumedfile
+```
+
+In this example no bias is acting on the system so the weights, $w(t')$ in the formulas above can thus all be set equal
+to one. The shortcut illustrates how the averaging is achieved by using the [ACCUMULATE](ACCUMULATE.md) action.
+
+When the variable is periodic (e.g. [TORSION](TORSION.md)) and has a value, $s$, in $a \le s \le b$ the ensemble average is evaluated using:
+
+$$
+\langle s \rangle = a + \frac{b - a}{2\pi} \arctan \left[ \frac{ \sum_{t'=0}^t w(t') \sin\left( \frac{2\pi [s(t')-a]}{b - a} \right) }{ \sum_{t'=0}^t w(t') \cos\left( \frac{2\pi [s(t')-a]}{b - a} \right) } \right]
+$$
+
+You can see how [ACCUMULATE](ACCUMULATE.md) and [CUSTOM](CUSTOM.md) can be used to implement this formula by expanding the shortcuts in the following example input:
 
-The following example calculates the ensemble average for the torsional angle involving atoms 1, 2, 3 and 4.
-At variance with the previous example this quantity is periodic so the second formula in the above introduction
-is used to calculate the average.  Furthermore, by using the CLEAR keyword we have specified that block averages
+```plumed
+t1: TORSION ATOMS=1,2,3,4
+t1a: AVERAGE ARG=t1 CLEAR=100
+PRINT ARG=t1a FILE=colvar STRIDE=100
+```
+
+Notice that by using the `CLEAR` keyword we have specified that block averages
 are to be calculated.  Consequently, after 100 steps all the information acquired thus far in the simulation is
 forgotten and the process of averaging is begun again.  The quantities output in the colvar file are thus the
 block averages taken over the first 100 frames of the trajectory, the block average over the second 100 frames
 of trajectory and so on.
 
-\plumedfile
-t1: TORSION ATOMS=1,2,3,4
-t1a: AVERAGE ARG=t1 CLEAR=100
-PRINT ARG=t1a FILE=colvar STRIDE=100
-\endplumedfile
 
-This third example incorporates a bias.  Notice that the effect the bias has on the ensemble average is removed by taking
-advantage of the \ref REWEIGHT_BIAS method.  The final ensemble averages output to the file are thus block ensemble averages for the
-unbiased canonical ensemble at a temperature of 300 K.
+If a bias is acting upon the system then the $w(t')$ values in the expression above are non-zero.  You can calculate the $w(t') values
+by using [REWEIGHT_BIAS](REWEIGHT_BIAS.md) or similar.  To pass these weights to the average action you would then use an input something 
+like the following:
 
-\plumedfile
+```plumed
 t1: TORSION ATOMS=1,2,3,4
 RESTRAINT ARG=t1 AT=pi KAPPA=100.
 ww: REWEIGHT_BIAS TEMP=300
 t1a: AVERAGE ARG=t1 LOGWEIGHTS=ww CLEAR=100
 PRINT ARG=t1a FILE=colvar STRIDE=100
-\endplumedfile
+```
+
+This AVERAGE action in this input is a shortcut once again so by expanding it you can obtain a better understanding of how the 
+formulas above are applied in this case.
 
 */
 //+ENDPLUMEDOC

src/generic/Collect.cpp

@@ -30,7 +30,89 @@
 /*
 Collect data from the trajectory for later analysis
 
-\par Examples
+The way this command can be used is illustrated by the following example:
+
+```plumed
+d: DISTANCE ATOMS=1,2
+c: COLLECT ARG=d STRIDE=1
+DUMPVECTOR ARG=c FILE=timeseries
+```
+
+The COLLECT command in the input above stores the time series of distances over the whole 
+trajectory. The STRIDE keyword controls how frequently data is stored and the [DUMPVECTOR](DUMPVECTOR.md) 
+command then outputs the full time series of `d` values at the end of the calculation.
+
+The above example is not particularly useful as you can achieve the same result by using simply 
+a DISTANCE command and the [PRINT](PRINT.md) command.  The COLLECT command is useful if you want 
+use the whole trajectory to perform a analysis such as  dimensionality reduction (see [dimred](dimred.md)).
+The shortcut command [COLLECT_FRAMES](COLLECT_FRAMES.md) uses this action heavily and allows one to easily 
+deal with the fact that COLLECT can only collect the time series for one PLUMED Value at a time.
+
+## Collecting a part of the trajectory
+
+You can use the CLEAR keyword to collect a subset of the trajectory as illustrated below:
+
+```plumed
+d: DISTANCE ATOMS=1,2
+c: COLLECT ARG=d STRIDE=1 CLEAR=1000
+DUMPVECTOR ARG=c FILE=timeseries STRIDE=1000
+```  
+
+This outputs files contain from this input contain 1000-frame blocks of the trajectory for the distance between atom 1 and 2. 
+This type of input might proove useful if you wish to perform separate analysis on different parts of the trajectory for 
+later comparison.
+
+## Collecting vectors
+
+You can use the collect command even if the input value has a rank that is greater than zero.  For example, the following
+input collects vectors of distances from the trajectory:
+
+```plumed
+d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8
+c: COLLECT ARG=d TYPE=vector STRIDE=1 CLEAR=100
+DUMPVECTOR ARG=c FILE=timeseries STRIDE=100
+```
+
+Notice that if the input to the collect action is a value with rank>0 you __must__ use the TYPE keyword to specify whether 
+the output Value is a vector or matrix.  In the above input we are storing a vector so the DUMPVECTOR command outputs 
+a list of 400 distances - 4 distances for each frame.  The assumption in the input above is that the four distances that have
+been computed by the DISTANCES command are indistinguishable. 
+
+By using the following input we can ensure the the four distances are treated as distinguishable when we do any analysis:
+
+```plumed
+d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8
+c: COLLECT ARG=d TYPE=matrix STRIDE=1 CLEAR=100
+DUMPVECTOR ARG=c FILE=timeseries STRIDE=100
+```
+
+The value `c` is now a $100\times 4$ matrix.  Furthermore, when we use DUMPVECTOR to output the output file will contain 
+four columns of data.
+
+## Collecting matrices 
+
+You can also use this action to collect a matrix as illustrated by the following example:
+
+```plumed
+d: DISTANCE_MATRIX GROUPA=1,2 GROUPB=3,4,5 
+c: COLLECT ARG=d TYPE=vector STRIDE=1 CLEAR=100
+DUMPVECTOR ARG=c FILE=timeseries STRIDE=100
+```
+
+The value `c` here is a vector with 600 elements as the input matrix is converted to a vector. These vectors are then stored in 
+one contiguous object.
+ 
+If by contrast we use `TYPE=matrix` as shown below:
+
+```plumed
+d: DISTANCE_MATRIX GROUPA=1,2 GROUPB=3,4,5 
+c: COLLECT ARG=d TYPE=matrix STRIDE=1 CLEAR=100
+DUMPVECTOR ARG=c FILE=timeseries STRIDE=100
+```
+
+A $100 \times 6$ matrix is stored.  Each row of this matrix contains a vectorized version of the input matrix.  
+There is currently no way to store the collected data in a way that recognises that each of the input PLUMED Value
+was a matrix. You also cannot use this action to store functions evaluated on a grid.
 
 */
 //+ENDPLUMEDOC

src/generic/Committor.cpp

@@ -32,13 +32,12 @@ namespace generic {
 /*
 Does a committor analysis.
 
-\par Examples
-
 The following input monitors two torsional angles during a simulation,
 defines two basins (A and B) as a function of the two torsion angles and
-stops the simulation when it falls in one of the two. In the log
-file will be shown the latest values for the CVs and the basin reached.
-\plumedfile
+stops the simulation when it falls in one of the two. The log
+file shows the latest values for the CVs and the basin reached.
+
+```plumed
 TORSION ATOMS=1,2,3,4 LABEL=r1
 TORSION ATOMS=2,3,4,5 LABEL=r2
 COMMITTOR ...
@@ -49,7 +48,7 @@ COMMITTOR ...
   BASIN_LL2=-0.25,-0.40
   BASIN_UL2=-0.15,-0.20
 ... COMMITTOR
-\endplumedfile
+```
 
 */
 //+ENDPLUMEDOC