Added documentation for Adaptive path

CHANGES/v2.4.txt

@@ -24,6 +24,7 @@ Changes from version 2.3 which are relevant for users:
 - New collective variables:
   - \ref DIMER (thanks to Marco Nava).
   - \ref IMPLICIT : EEF1-SB implicit solvent solvation energy
+  - \ref ADAPTIVE_PATH : Adaptive path variables using the method from \cite BerndAdaptivePath
 - New actions:
   - \ref INENVELOPE
 - Other changes:
@@ -40,6 +41,7 @@ Changes from version 2.3 which are relevant for users:
   - Internal molfile implementation has been updated to VMD 1.9.3.
   - Examples in the documentation now have syntax highlighting and links to the documentation of used actions.
   - \ref COORDINATIONNUMBER : Added option to have pairwise distance moments of coordination number in the multicolvar module
+  - \ref pesmd : Tool for performing Langevin dynamics on an energy landscape that is specified using a PLUMED input file
 
 Changes from version 2.3 which are relevant for developers:
   - A few fixes has been made to improve exception safety. Although we still cannot declare

src/mapping/AdaptivePath.cpp

@@ -21,16 +21,57 @@
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ */
 #include "Mapping.h"
 #include "TrigonometricPathVessel.h"
-#include "reference/PathReparameterization.h"
+#include "PathReparameterization.h"
 #include "reference/Direction.h"
 #include "core/ActionRegister.h"
 
 //+PLUMEDOC COLVAR ADAPTIVE_PATH
 /*
-Adaptive path cvs.
+Compute path collective variables that adapt to the lowest free energy path connecting states A and B.
+
+The Path Collective Variables developed by Branduardi and co-workers \cite brand07 allow one
+to compute the progress along a high-dimensional path and the distance from the high-dimensional
+path.  The progress along the path (s) is computed using:
+
+\f[
+s = i_2 + \textrm{sign}(i_2-i_1) \frac{ \sqrt{( \mathbf{v}_1\cdot\mathbf{v}_2 )^2 - |\mathbf{v}_3|^2(|\mathbf{v}_1|^2 - |\mathbf{v}_2|^2) } }{2|\mathbf{v}_3|^2} - \frac{\mathbf{v}_1\cdot\mathbf{v}_3 - |\mathbf{v}_3|^2}{2|\mathbf{v}_3|^2}
+\f]
+
+In this expression \f$\mathbf{v}_1\f$ and \f$\mathbf{v}_3\f$ are the vectors connecting the current position to the closest and second closest node of the path,
+respectfully and \f$i_1\f$ and \f$i_2\f$ are the projections of the closest and second closest frames of the path. \f$\mathbf{v}_2\f$, meanwhile, is the
+vector connecting the closest frame to the second closest frame.  The distance from the path, \f$z\f$ is calculated using:
+
+\f[
+z = \sqrt{ \left[ |\mathbf{v}_1|^2 - |\mathbf{v}_2| \left( \frac{ \sqrt{( \mathbf{v}_1\cdot\mathbf{v}_2 )^2 - |\mathbf{v}_3|^2(|\mathbf{v}_1|^2 - |\mathbf{v}_2|^2) } }{2|\mathbf{v}_3|^2} - \frac{\mathbf{v}_1\cdot\mathbf{v}_3 - |\mathbf{v}_3|^2}{2|\mathbf{v}_3|^2} \right) \right]^2 }
+\f]
+
+Notice that these are the definitions of \f$s\f$ and \f$z\f$ that are used by \ref PATH when the GPATH option is employed.  The reason for this is that
+the adaptive path method implemented in this action was inspired by the work of Diaz and Ensing in which these formula were used \cite BerndAdaptivePath.
+To learn more about how the path is adapted we strongly recommend reading this paper.
 
 \par Examples
 
+The input below provides an example of how the adaptive path works in practise. The path is updated every 50 steps of 
+MD based on the data accumulated during the preceding 50 time steps.   
+
+\plumedfile
+d1: DISTANCE ATOMS=1,2 COMPONENTS
+pp: ADAPTIVE_PATH TYPE=EUCLIDEAN FIXED=5,15 UPDATE=50 WFILE=out-path.pdb WSTRIDE=50 REFERENCE=mypath.pdb
+PRINT ARG=d1.x,d1.y,pp.* FILE=colvar
+\endplumedfile
+
+In the case above the distance between frames is calculated based on the \f$x\f$ and \f$y\f$ components of the vector connecting
+atoms 1 and 2.  As such an extract from the input reference path (mypath.pdb) would look as follows:
+
+\verbatim
+REMARK ARG=d1.x,d1.y d1.x=1.12 d1.y=-.60
+END
+REMARK ARG=d1.x,d1.y d1.x=.99 d1.y=-.45
+END
+\endverbatim
+
+Notice that one can also use RMSD frames in place of arguments like those above.
+
 */
 //+ENDPLUMEDOC