A few fixes in Gareth documentation

developer-doc/mdTemplate.txt

@@ -10,17 +10,43 @@ Plumed ships with scripts that can be used to add it to many of the standard MD
 
 \section makefile Modifying your makefile
 
-Once the plumed source code has been compiled a file called src/Plumed.inc will be created.  This file must be included in your MD code's makefile as it informs the code where to find all the plumed source.  In particular, within the code the three variables described below are defined one of which must be added to the command that does the linking for your MD engine:  
-
-- \$(PLUMED_OBJ) - This will statically link plumed to your MD engine
-- \$(PLUMD_SHARED_OBJ) - This will dynamically bind plumed to your MD engine.  Furthermore, plumed will not run if you move the libplumedKernel.so library to a new location after compilation.
-- \$(PLUMED_KERNEL) - This allows you to specify the location of plumed at runtime through the PLUMD_KERNEL environment variable.  Obviously, if at runtime this variable is not set, then none of plumed functionality will be available.
-
-For consistency with the other plumed patches please ensure that your new patch allows users to compile with all three options.  Other users should be able to select which compilation mode they require using the following flags:
-
-- --static for \$(PLUMED_OBJ)
-- --shared for \$(PLUMED_SHARED_OBJ)
-- --runtime for \$(PLUMED_WRAPPER)
+Once the plumed source code has been compiled a file src/Plumed.inc is
+generated. This file should be included in your MD code's makefile as it
+informs the code where to find all the plumed source. There are three possible
+ways to link PLUMED: static (linking the .o files directly), shared (linking
+the libPlumed.so library) or runtime (which links only a wrapper to plumed,
+whereas the location of the remaining part on plumed, i.e. the libPlumedKernel.so,
+can be specified at runtime). The relevant variables are
+- \$(PLUMED_OBJ) all the objects that form the plumed library
+- \$(PLUMED_SHARED_OBJ) a single shared library containing the full plumed library
+- \$(PLUMED_WRAPPER) an object containing only the plumed wrapper
+- \$(PLUMED_LIBS) are libraries which should be linked to the MD code (usually
+  just the library containing functions for dynamic loading)
+- \$(PLUMED_DYNAMIC_LIBS) are libraries on which plumed depends on (e.g.
+  matheval, etc), which should be linked explicitely only in case of static
+  linking.
+
+The libPlumedKernel.so basically contains the same objects as the
+\$(PLUMED_SHARED_OBJ) except for the \$(PLUMED_WRAPPER).
+
+The simplest approach is to take advantage of the three variants
+src/Plumed.inc.static , src/Plumed.inc.shared and src/Plumed.inc.runtime .
+Including one of those, it is sufficient to add to the linker line the macro
+\$(PLUMED_LOAD).
+
+The best way to patch your MD file is thus:
+
+- include in the MD Makefile a file "Plumed.inc" located in the root directory
+  of MD (e.g. with "include ../../Plumed.inc"). The patch script will provide
+  that file on patching
+
+- add "\$(PLUMED_LOAD)" to the linking command in the Makefile.
+
+The patching system will then link the proper variant of .inc file to
+MDROOT/Plumed.inc depending on the arguments to "plumed patch":
+- --static 
+- --shared 
+- --runtime 
 
 \section language Language dependence
 
@@ -138,6 +164,11 @@ plumed_cmd(plumedmain,"setAtomsContiguous",&start);         // Number the atoms
 plumed_cmd(plumedmain,"getApiVersion",api);                 // Pass the api version that plumed is using (what does this mean)???
 \endverbatim 
 
+\section Saving the diffs
+
+This is similar to plumed 1. All the files that you want to modify should be
+first copied to .preplumed files. Then use "plumed patch -s" to save the diff.
+
 \section Notes Notes
 
 Compiler options to use shared libraries on many architectures: 

developer-doc/plmdIntro.txt

@@ -32,14 +32,14 @@ This is roughly the way that plumed 1.0 operated.  Plumed 2.0 operates different
 
 - Iterate over the list of PLMD::Action objects, establish whether any contain PLMD::ActionPilot objects.  
 - For the PLMD::ActionPilot objects check if we are supposed to perform an action at this particular MD step.  If it is activate the action.
-- When any object is activated we must check whether or not it contains a PLMD::ActionWithArguments object.  These objects tell plumed that before performing a particular action we must perform some other action (for example before computing the bias in metadynamics we must compute the collective variables). If we find such arguments we activate all arguments listed in the PLMD::ActionWithArguments object belonging to this particular PLMD::Action (i.e. when peforming metadynamics one must make sure that all the collective coordinates on which the bias depends are calculated first).
-- Iterate over the list of all the active PLMD::Action objects calculating all values and derivatives and store them inside PLMD::ActionWithValue objects (N.B. a PLMD::ActionWithValue holds a vector of PLMD::Value objects). 
-- As already mentioned the dependencies of PLMD::Function and PLMD::Bias objects on the PLMD::Colvar objects is stored within a PLMD::ActionWithArguments object.  The reason for this apprantly-arbitrary, additional layer of complexity being that PLMD::Bias objects can depend on both PLMD::Function objects and PLMD::Colvar objects.  PLMD::ActionWithArguments is a list of PLMD::Values.  It is used to tell a PLMD::Action that it must wait for data to be loaded in the set of listed PLMD::Value (by other PLMD::Actions) prior to calculating the particlar PLMD::Action.  In practise this means that the order for the directives in the input matters in plumed 2 as the various PLMD::Actions are always passed through in the order they are read in from input.  
+- When any object is activated it automatically activates all objects that it depends on (for example before computing the bias in metadynamics we must compute the collective variables). The list of dependence is built based on the arguments of each objects as specified in the ARG keyword, which are stored in the PLMD::ActionWithArguments class (i.e. when peforming metadynamics one must make sure that all the collective coordinates on which the bias depends are calculated first).
+- Iterate over the list of all the active PLMD::Action objects calculating all values and derivatives and store them inside PLMD::ActionWithValue objects (N.B. a PLMD::ActionWithValue holds a vector of PLMD::Value objects), following the same order in which they are introduced in the input file. This is done by calling the virtual method PLMD::Action::apply().
+- As already mentioned the dependencies of PLMD::Function and PLMD::Bias objects on the PLMD::Colvar objects are given by the properties of the PLMD::ActionWithArguments class.  The reason for this apparently-arbitrary, additional layer of complexity being that PLMD::Bias objects can depend on both PLMD::Function objects and PLMD::Colvar objects.  PLMD::ActionWithArguments is a list of PLMD::Values.  It is used to tell a PLMD::Action that it must wait for data to be loaded in the set of listed PLMD::Value (by other PLMD::Actions) prior to calculating the particlar PLMD::Action.  In practise this means that the order for the directives in the input matters in plumed 2 as the various PLMD::Actions are always passed through in the order they are read in from input.  
 - By this stage we have computed \f$s(x)\f$, \f$f[s(x)]\f$, \f$B| f[s(x)] |\f$, \f$\frac{\textrm{d}B}{\textrm{d}f}\f$, \f$\frac{\textrm{d}f}{\textrm{d}s}\f$ and \f$\frac{\textrm{d}s}{\textrm{d}x}\f$.  This data has all been stored inside PLMD::Value objects.  In other words, unlike in the previously described workflows, the data is stored in a manner that does not descriminate between the results from calculations in PLMD::Colvar, PLMD::Function and PLMD::Bias.  Instead, all the data is stored in equivalent PLMD::Value objects. Plumed understands that one cannot compute \f$f[s(x)]\f$ or \f$B| f[s(x)] |\f$ without first computing \f$s(x)\f$ and \f$f[s(x)]\f$ as this information is stored inside the PLMD::ActionWithArguments objects.        
-- Next we apply the chain rule to calculate the derivative of the bias with respect to the atomic positions in three steps.  
-- In the first step we loop over all the PLMD::Bias objects and pass \f$-\frac{\textrm{d}B}{\textrm{d}v}\f$ to the PLMD::Value objects listed in the PLMD::ActionWithArguments object.   
-- In the second step we loop over all the PLMD::Function objects. If there is a bias on any of these objects we will have passed information on \f$-\frac{\textrm{d}B}{\textrm{d}f}\f$ to the relevant PLMD::Value objects in this classes PLMD::ActionWithValue class.  Hence, we can calculate \f$-\frac{\textrm{d}B}{\textrm{d}s} = -\frac{\textrm{d}B}{\textrm{d}f}\frac{\textrm{d}f}{\textrm{d}s}\f$ and pass this information to the PLMD::Value objects listed in PLMD::ActionWithArguments.
-- In the final step we calculate the forces on the atoms by looping over all PLMD::Colvar objects.  Once again if there is a bias (or a bias on a function of one of these values) \f$-\frac{\textrm{d}B}{\textrm{d}s}\f$ will have been passed to the relevant PLMD::Value class so that we can calculate \f$-\frac{\textrm{d}B}{\textrm{d}x} = -\frac{\textrm{d}B}{\textrm{d}f}\frac{\textrm{d}f}{\textrm{d}s}\frac{\textrm{d}s}{\textrm{d}s}\f$.  We now apply these forces to the atoms using the PLMD::ActionAtomistic class.
+- Next we apply the chain rule to calculate the derivative of the bias with respect to the atomic positions in three steps.   To this aim we just iterate over all the PLMD::Action objects in the reverse order and use the virtual method PLMD::Action::apply(), which behaves differently on bias, colvars, and functions.
+- For objects of type PLMD::Bias it passes \f$-\frac{\textrm{d}B}{\textrm{d}v}\f$ to the PLMD::Value objects listed in the PLMD::ActionWithArguments object.   
+- For object of type PLMD::Function it computes the forces on the argumetns. If there is a bias on any of these objects we will have passed information on \f$-\frac{\textrm{d}B}{\textrm{d}f}\f$ to the relevant PLMD::Value objects in this classes PLMD::ActionWithValue class.  Hence, we can calculate \f$-\frac{\textrm{d}B}{\textrm{d}s} = -\frac{\textrm{d}B}{\textrm{d}f}\frac{\textrm{d}f}{\textrm{d}s}\f$ and pass this information to the PLMD::Value objects listed in PLMD::ActionWithArguments.
+- For objects of type PLMD::Colvar it applies the forces to the atoms.  Once again if there is a bias (or a bias on a function of one of these values) \f$-\frac{\textrm{d}B}{\textrm{d}s}\f$ will have been passed to the relevant PLMD::Value class so that we can calculate \f$-\frac{\textrm{d}B}{\textrm{d}x} = -\frac{\textrm{d}B}{\textrm{d}f}\frac{\textrm{d}f}{\textrm{d}s}\frac{\textrm{d}s}{\textrm{d}s}\f$.  We now apply these forces to the atoms using the PLMD::ActionAtomistic class.
 
 The above list describes the function of the majority of the classes in the plumed core.  In practise to add to plumed you do not need to understand the details of how each of these classes functions as you shouldn't need to touch them.  It is perhaps useful to understand what each one is doing however so that you can better understand the code structure.  
 \section parallel Multiple Replicas