Added the new, rewritten manual together with all the scripts that generate

the parts that are contained in the code

user-doc/.gitignore

@@ -3,4 +3,6 @@
 /*.tmp
 /automatic
 /*PP.txt
+/errors
+/modifier_file
 

user-doc/Bias.txt

 /**
 
-\page Bias Bias
+\page Methods Methods
 
-The following keywords are available for all directives of this section:
+Once you have calculated a number of collective variables plumed allows you to either analyse
+your trajectory or to run a number of enhanced sampling algorithms.  The list of available 
+on-the-fly analysis tools contains:
 
-- ARG:
-  This keyword is used to specify on which variables the bias is acting.
-  It is a comma-separated list of labels. Here is an example with \ref RESTRAINT
-\verbatim
-DISTANCE  ATOMS=1,5 LABEL=d1
-DISTANCE  ATOMS=2,6 LABEL=d2
-RESTRAINT ARG=d1,d2 AT=5.0,6.0 KAPPA=100.0,50.0
-\endverbatim
-- STRIDE:
-  PLUMED implements a multiple-time-step scheme. Using the keyword STRIDE
-  one can set how frequently the bias should be applied, in units of time steps.
-  It can be used to decrease the impact of variables which are computationally heavy.
-  Here is an example with \ref RESTRAINT
-\verbatim
-DISTANCE  ATOMS=1,5 LABEL=d1
-RESTRAINT ARG=d1 AT=5.0 KAPPA=100.0 STRIDE=2
-\endverbatim
-
-\attention The rest of this page is automatically generated from the source
-files
+@ANALYSIS@
 
+while the list of available enhanced sampling algorithms contains: 
 
 @BIAS@
 

user-doc/Colvar.txt

@@ -2,17 +2,85 @@
 
 \page Colvar Collective Variables
 
-The following keywords are available for all directives of this section:
-- NUMERICAL_DERIVATIVES:
-  This flag can be used to enforce calculation of derivatives with respect to
-  atom positions and cell vectors by means of numerical differences
+Chemical systems contain an enormous number atoms, which, in most cases makes it simply impossible for
+us to understand anything by monitoring the atom postions directly.  Consquentially,
+we introduce Collective variables (CVs) that describe the chemical processes we are 
+interested in and monitor these simpler quantities instead.  These CVs are used in all of the methods 
+implemented in plumed - they're values can be monitored using \ref PRINT, \ref Function of them can be calculated
+or they can be analyzed or biased using the \ref Methods implemented in plumed.  Before doing any of these things
+however we first have to inform plumed how to calculate them.    
+ 
+\section atomSpecs Specifying Atoms
+
+The vast majority of the CVs implemented in plumed are calculated from a list of atom positions.  Within plumed
+atoms are always specified according to their numerical indices in the molecular dynamics input file.  This can
+be done either using a comma separated list of numbers or, if a long list atom of contiguous atoms is required, 
+by using the shortcut 10-100, which specifies all the atom indexes between 10 and 100 (including 10 and 100).  So for example:
+
+\verbatim
+TORSION ATOMS=1,2,3,4
+\endverbatim
+
+could also be specified using:
+
 \verbatim
-DISTANCE  ATOMS=1,5 LABEL=d1 NUMERICAL_DERIVATIVES
+TORIONS ATOMS=1-4
 \endverbatim
 
-\attention The rest of this page is automatically generated from the source
-files
+In addition, for certain colvars, pdb files can be read in using the following keywords:
+
+@TOPOLOGY@
+
+The read in pdb files are used by plumed to define things like residues, the backbone atoms and so on.  These can then be
+used within the input to colvars to make inputting the lists of atoms involved more straightforward.  Documentation for 
+how these shortcuts can be used can be found in the documentation for the various CVs.
+
+Lastly, if you have a list of colvar that is particularly laborious to write out that you need to use multiple times in the 
+input you can create a static group of atoms and then use the label of the group to specify the correpsonding list of 
+atoms in your various colvars.  For more details see \ref GROUP.
+
+\section vatoms Virtual Atoms
+
+Sometimes, when calculating a colvar, you may not want to use the positions of a number of atoms directly.  Instead
+ you may wish to use the position of a virtual atom whose position is generated based on the positions of a collection 
+of other atoms.  For example you might want to use the center of mass of a group of atoms.  Plumed has a number of routines
+for calculating the positions of these virtual atoms from lists of atoms:
+
+@VATOM@
+
+To specify to a colvar that you want to use the position of a virtual atom to calculate a colvar rather than one of the atoms
+in your system you simply use the label for your virtual atom in place of the usual numerical index.  Virtual
+atoms and normal atoms can be mixed together in the input to colvars as shown below:
+
+\verbatim
+COM ATOMS=1,10 LABEL=com1
+DISTANCE ATOMS=11,com1
+\endverbatim 
+
+If you don't want to calculate CVs from the virtual atom.  That is to say you just want to monitor the position of a virtual atom 
+(or any set of atoms) over the course of your trajectory you can do this using \ref DUMPATOMS.
+
+\section mols Molecules
+
+PLUMED is designed so that for the majority of the CVs implemented the periodic boundary conditions are treated 
+in the same manner as they would be treated in the host code.  In some codes this can be problematic when the colvars
+you are using involve some property of a molecule.  These codes allow the atoms in the molecules to become separated by 
+periodic boundaries, a fact which plumed could only deal with were the topology passed from the MD code to plumed.  Making this
+work would involve a lot laborious programming and goes against our original aim of having a general patch that can be implemented 
+in a wide variety of MD codes.  Consequentially, we have implemented a more pragmatic solution to this probem - the user specifies
+in input any molecules (or parts of molecules) that must be kept in tact throughout the simulation run.  In plumed 1.0 this was done
+using the ALIGN_ATOMS keyword.  In plumed 2.0 the same effect can be acchieved using any one from the following list of commands
+
+- \subpage WHOLEMOLECULES
+@TOPOLOGY@
+
+The most general of these is the \ref WHOLEMOLECULES keywords.  However, there are advantages in using the others as oftentimes
+by defining a topology using a pdb file you can take advantage of shortcuts when specifying other colvars.  For example, if you
+use the \ref PROTEIN_TOPOLOGY keyword you can then later refer to the atoms in a specific residue by the residue number.
+
+\section cvavail CV Documentation
 
+The following list contains all the colvars that are currently implemented in plumed 2.0.
 
 @COLVAR@
 

user-doc/Doxyfile

@@ -459,19 +459,14 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = Intro.txt \
-                         WhatsNew.txt \
-                         Installation.txt \
-                         BasicUsage.txt \
-                         AdvancedTopics.txt \
-                         Tools.txt \
-                         Reference.txt \
-                         InputDirectivesPP.txt \
-                         SetupPP.txt \
-                         ColvarPP.txt \
-                         FunctionsPP.txt \
+INPUT                  = IntroPP.txt \
                          BiasPP.txt \
-                         GenericDirectivesPP.txt
+                         ColvarPP.txt \ 
+                         FunctionsPP.txt \
+                         ToolsPP.txt \ 
+                         InstallationPP.txt \
+                         WhatsNew.txt \
+                         automatic
 
 # If the value of the INPUT tag contains directories, you can use the 
 # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 
@@ -480,7 +475,7 @@ INPUT                  = Intro.txt \
 # *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx 
 # *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py
 
-FILE_PATTERNS          = 
+FILE_PATTERNS          = *.txt
 
 # The RECURSIVE tag can be used to turn specify whether or not subdirectories 
 # should be searched for input files as well. Possible values are YES and NO. 

user-doc/Functions.txt

 /**
 \page Function Functions
 
-The following keywords are available for all directives of this section:
-- ARG:
-  This keyword is used to specify on which variables the function is computed
-  It is a comma-separated list of labels. Here is an example with \ref COMBINE
-\verbatim
-DISTANCE  ATOMS=1,5 LABEL=d1
-DISTANCE  ATOMS=2,6 LABEL=d2
-COMBINE   ARG=d1,d2 POWERS=2
-\endverbatim
-- NUMERICAL_DERIVATIVES:
-  This flag can be used to enforce calculation of derivatives with respect to
-  function arguments by means of numerical differences
-\verbatim
-DISTANCE  ATOMS=1,5 LABEL=d1
-DISTANCE  ATOMS=2,6 LABEL=d2
-COMBINE   ARG=d1,d2 POWERS=2 NUMERICAL_DERIVATIVES
-\endverbatim
-
-\attention The rest of this page is automatically generated from the source
-files
-
+When performing biased dynamics or analysing a trajectory you may wish to analyse/bias the value of
+some function of a set of collective variables rather than the values of the collective variables
+directly.  You can do this with plumed by using any one of the following list of functions: 
 
 @FUNCTION@
+
 */
 

user-doc/Installation.txt

@@ -2,6 +2,10 @@
 
 \page Installation Installation
 
+At the present times plumed can be added to the following list of codes:
+
+@CODES@
+
 \section CompilingPlumed Compiling Plumed
 
 [Configuration]

user-doc/Intro.txt

 /**
 \mainpage Introduction
 
-This is the user manual. If you want to modify PLUMED or to understand how it works internally,
-have a look at the <a href="../../developer-doc/html/index.html"> developer manual </a>.
-
-PLUMED 2.0 is a major rewriting of PLUMED. (...)
+Plumed is a plugin that works with a large number of molecular dynamics codes.  It can be used
+to analyse features of the dynamics on-the-fly or to perform a wide variety of free energy methods.
+The original plumed 1.0 was highly successful and had over 1000 users.  Plumed 2.0 constitues an 
+extensive rewrite of the original in a way that makes it more modular and thus easier to implement 
+new methods, more straightforward to add it to MD codes and hopefully simpler to use.  
+This is the user manual -  i f you want to modify PLUMED or to understand how it works internally, have a look at the 
+<a href="../../developer-doc/html/index.html"> developer manual </a>.  Alternatively, to look at a list of the new 
+features available in plumed 2.0 and to work out how to install plumed 2.0 in your MD code check out:
 
 - \subpage WhatsNew
-- \subpage Installation
-- \subpage BasicUsage
-- \subpage AdvancedTopics
-- \subpage Tools
-- \subpage Reference
+- \subpage Installation 
+
+\section qintro A quick introduction
+
+To run plumed 2.0 you need to provide one input file.  In this file you specify what it
+is that plumed should do during the course of the run.  Typically this will involve calculating 
+one or more collective variables, perhaps calculating a function of these CVs
+ and then doing some analysis of values of your collective variables/functions or running
+some free energy method.  Details as to how to perform all these tasks and how to use the various trajectory
+analsyis tools that come with plumed are given in:
+
+- \subpage Colvar
+- \subpage Function
+- \subpage Methods
+
+Plumed can be used in one of two ways.  It can be incorporated into any one of the MD codes listed on the
+\ref Installation page and used to analyse or bias a molecular dynamics run on the fly.  Alternatively, one
+can use it as a standalone tool for postprocessing the results from molecular dynamics or enhanced sampling calculations.
+To use plumed in this second way you will issue a command something like:
+
+\verbatim
+plumed <toolname> <list of input flags for that tool>
+\endverbatim
+
+The following is a list of the various standalone tools that plumed contains.
+
+@TOOLS@
+
+For all these tools and to use plumed as a pluggin in an MD calculation you will need an input file.  Within
+this input file every line is an instruction for plumed to perform some particular action.  This could be
+ the calculation of a colvar, an occasional analysis of the trajectory or a biassing of the dynamics.  The first
+word in these lines specify what particular action is to be performed.  This is then followed by a number of keywords
+which provide plumed with more details as to how the action is to be performed.  These keywords are either single words
+(in which they tell plumed to do the calculation in a particular way - for example NOPBC tells plumed to not use the periodic
+bounadry conditions when calculating a particular colvar) or they can be words followed by an equals sign and a comma separated 
+list - WITH NO SPACES - of numbers or characters (so for example ATOMS=1,2,3,4 tells plumed to use atom numbers 1,2,3 and 4 in 
+the calculation of a particular colvar).  
+
+The most important of these keywords is the label keyword as it is only by using these labels that we can pass data 
+from one action to another.  As an example if you do:
+
+\verbatim
+DISTANCE ATOMS=1,2
+\endverbatim
+
+Then plumed will do nothing other than read in your input file.  In contrast if you do:
+
+\verbatim
+DISTANCE ATOMS=1,2 LABEL=d1
+PRINT ARG=d1 FILE=colvar STRIDE=10
+\endverbatim
+
+then plumed will print out the value of the distance between atoms 1 and 2 every 10 steps to the file colvar as you have told
+plumed to take the value calculated by the action d1 and to print it.  
+
+By default the plumed inputs and outputs quantities in the following units:
+
+- Energy - kJ/mol
+- Length - nanometers
+- Time - picoseconds
+
+Unlike plumed 1.0 the units used are independent of the MD engine you are using.  If you want to change these units you can do this using the 
+\subpage UNITS keyword. 
+
+Those are the essentials but there are a few other tricks that we didn't know where else to put in the manual so we stuck them here.
+
+\section comments Comments
+
+If you are an organised sort of person who likes to remember what the hell you were trying to do when you ran a 
+particular simulation you might find it useful to put comments in your input file.  In plumed you can do this as 
+comments can be added using a # sign.  On any given line everything after the # sign is ignored so 
+erm... yes add lines of comments or trailing comments to your hearts content as shown below (using Shakespeare is optional):
+
+\verbatim
+# This is the distance between two atoms:
+DISTANCE ATOM=1,2 LABEL=d1
+UPPER_WALL ARG=d1 AT=3.0 KAPPA=3.0 LABEL=Snout # In this same interlude it doth befall. That I, one Snout by name, present a wall.
+\endverbatim
+
+An alternative to including comments in this way is to use line starting ENDPLUMED.  Everything in the plumed input after this
+keyword will be ignored.
+
+\section ContinuationLines Continuation lines
+
+If your input lines get very long then editing them using vi and other such text editors becomes a massive pain in the arse.  
+We at plumed are aware of this fact and thus have provided a way of doing line continuations so as to make your life that much 
+easier - aren't we kind?  Well no not really, we have to use this code too.  Anyway, you can do continuations by using the "..." syntax
+as this makes this: 
+
+\verbatim
+DISTANCE ATOMS1=1,300 ATOMS2=1,400 ATOMS3=1,500
+\endverbatim
+
+equivalent to this:
+
+\verbatim
+DISTANCE ...
+# we can also insert comments here
+  ATOMS1=1,300
+# multiple kewords per line are allowed
+  ATOMS2=1,400 ATOMS3=1,500
+#empty lines are also allowed
+
+... DISTANCE
+\endverbatim
+
+\section includes Including other files in the plumed input
+
+If, for some reason, you want to spread your plumed input over a number of files you can use INCLUDE as shown below:
+
+\verbatim
+INCLUDE filename
+\endverbatim
+
+So, for example, a single "plumed.dat" file:
+
+\verbatim
+DISTANCE ATOMS=0,1 LABEL=dist
+RESTRAINTG ARG=dist
+\endverbatim
+
+could be split up into two files as shown below:
+ 
+\verbatim
+DISTANCE ATOMS=0,1 LABEL=dist
+INCLUDE toBeIncluded.dat
+\endverbatim
+plus a "toBeIncluded.dat" file
+\verbatim
+RESTRAINTG ARG=dist
+\endverbatim
+
+However, when you do this it is important to recognise that INCLUDE is a real directive that is only resolved
+after all the \ref Comments have been stripped and the \ContinuationLines have been unrolled.  This means it
+is not possible to do things like:
+
+\verbatim
+# this is wrong:
+DISTANCE INCLUDE options.dat
+RESTRAINTG ARG=dist
+\endverbatim
+
+\section load Loading shared libraries
+
+You can introduce new functionality into plumed by placing it directly into the src directory and recompiling the 
+plumed libraries.  Alternatively, if you want to keep your code independent from the rest of plumed (perhaps
+so you can release it independely - we won't be offended), then you can create your own dynamic library.  To use this 
+in conjuction with plumed you can then load it at runtime by using the LOAD keyword as shown below:
 
+\verbatim
+LOAD library.so
+\endverbatim
+ 
+N.B.  If your system uses a different suffix for dynamic libraries (e.g. macs use .dylib) then PLUMED will try to 
+automatically adjust the suffix accordingly.
 
 */
 

user-doc/Makefile

+# include the machine dependent configuration
+-include ../Makefile.conf
 
 .PHONY: all clean
 
-all:
+all: 
 	./extract
 	doxygen
+	./report_errors  
 
 clean:
-	rm -fr html latex automatic *~ *PP.txt
+	rm -fr html latex automatic *~ *PP.txt errors 

user-doc/extract

 #! /bin/bash
+rm -rf automatic
 mkdir automatic
 
+# Check for files that register actions with no documentation
+touch errors
+for file in ../src/*.cpp
+do
+  nreg=`grep "PLUMED_REGISTER_ACTION" $file | wc -l | awk '{print $1}'`
+  if [ $nreg -gt 0 ] ; then
+       ndoc=`grep PLUMEDOC $file | wc -l | awk '{print $1}'`
+       if [ $ndoc -eq 0 ] ; then
+          echo The following file registered an action but provided no documentation: $file >> errors
+       fi
+  fi 
+done
+
+# Create the list of codes that plumed works with from the set of available patches
+for file in ../patches/*.config
+do
+   echo "- $file" | sed -e 's/.config//' | sed -e 's/..\/patches\///' >> automatic/codes.list
+done
+
+## Check for utilities that register actions with no documentation
+#for file in ../utilities/*.cpp
+#do
+#  ndoc=`grep PLUMEDOC $file | grep TOOL | wc -l | awk '{print $1}'`
+#  if [ $ndoc -eq 0 ] ; then
+#     echo The following utility has been provided without documentation: $file >> errors
+#  fi
+#done
+
+# Generate all the documentation pages for colvar modifiers
+#rm -f modifier_file
+#echo "\\section mod Working with distributions" > modifier_file
+#echo "As described above you can use this colvar to calculate one or multiple CVs.  Obviously, if you have calculated multiple CVs then you have a distribution of CVs.  As such plumed allows you to calculate a number of functions of this distribution.  These quantities and their derivatives are then stored as the values of the colvar.  N.B.  You cannot calcualte the values of the colvars and these functions of the distribution from a single line in input.  You can however calculate multiple functions of the distribution." >> modifier_file
+#cat ../*/*cpp |
+#awk '{
+#  if($1=="//+ENDPLUMEDOC"){
+#     inside=0
+#  }
+#  if(inside && $1!="/**" && $1!="*/") print $0 >> "modifier_file"
+#  if($1=="//+PLUMEDOC"){
+#     if($2=="MODIFIER"){
+#        print "\\par " $3 >> "modifier_file"   
+#        inside=1;
+#     }
+#  } 
+#}'  
+
+# Generate all the documentation pages from comments
 cat ../*/*cpp |
 awk '{
-  if($1=="//+ENDPLUMEDOC") inside=0;
+  if($1=="//+ENDPLUMEDOC"){
+     inside=0;
+     print "*/" >output
+  }
   if(inside && $1!="/**" && $1!="*/") print $0 >output
   if($1=="//+PLUMEDOC"){
-    if($2=="COLVAR" || $2=="FUNCTION" || $2=="BIAS" || $2=="GENERIC" || $2=="SETUP"){
-      output="automatic/"$2".txt";
-      print "\\section "$3 > output
+    if( $2=="TOPOLOGY" || $2=="COLVAR" || $2=="FUNCTION" || $2=="ANALYSIS" || $2=="BIAS" || $2=="VATOM" || $2=="GENERIC" || $2=="TOOLS" ){
+      lfile="automatic/"$2".list"
+      print "- \\subpage "$3 > lfile
+      output="automatic/"$3".tmp";
+      print "/**" > output
+      print "\\page "$3 > output
+      print "\\section "$3 >output
       inside=1;
     }
   }
 }'
 
-for file in Bias Colvar Functions GenericDirectives InputDirectives Setup
+# Generate all the documentation from keywords
+source ../sourceme.sh
+for file in automatic/*.tmp
+do
+  foundexample=`grep "\par Examples" $file | wc -l | awk '{print $1}'`
+  flag=`echo $file | sed -e 's/.tmp//g' | sed -e 's/automatic\///g'`
+  ../src/plumed manual --action=$flag > automatic/$flag.man 2> shit
+  rm shit 
+  check=`wc -l automatic/$flag.man | awk '{print $1}'`
+  if [ $check -eq 0 ] ; then 
+     echo Full manual for action $flag will not be generated as you are building the manual from a code where this action was not compiled >> errors
+  elif [ $foundexample -eq 0 ] 
+  then
+    echo There are no examples inside documentation for action: $flag >> errors
+  fi
+  cat automatic/$flag.tmp |
+    { 
+     while read -r LINE ;
+      do
+        if [ "$LINE" = "\par Examples" ]
+        then
+          cat automatic/$flag.man 
+          iscol=`grep $flag automatic/COLVAR.list | wc -l`
+          if [ $iscol -gt 0 ] ; then
+               fname=`grep PLUMED_REGISTER_ACTION ../src/*.cpp | grep $flag | sed -e 's/:/ /g' | awk '{print $1}'`
+               hasmod=`grep ColvarWithModifiers $fname | wc -l | awk '{print $1}'` 
+               if [ $hasmod -gt 0 ] ; then
+                    cat modifier_file
+               fi
+          fi
+          echo -E "$LINE"
+        else
+          echo -E "$LINE"
+        fi
+      done
+    } > automatic/$flag.txt
+done
+
+for file in Bias Colvar Functions Installation Intro
 do
 
 cat $file.txt |
 {
-  while read -r LINE ;
+ while read -r LINE ;
   do
   if [ "$LINE" = "@COLVAR@" ]
   then
-    cat automatic/COLVAR.txt
+    cat automatic/COLVAR.list
+  elif [ "$LINE" = "@ANALYSIS@" ]
+  then
+    cat automatic/ANALYSIS.list
   elif [ "$LINE" = "@BIAS@" ]
   then
-    cat automatic/BIAS.txt
+    cat automatic/BIAS.list
   elif [ "$LINE" = "@FUNCTION@" ]
   then
-    cat automatic/FUNCTION.txt
-  elif [ "$LINE" = "@GENERIC@" ]
+    cat automatic/FUNCTION.list
+  elif [ "$LINE" = "@TOPOLOGY@" ]
+  then
+    cat automatic/TOPOLOGY.list
+  elif [ "$LINE" = "@VATOM@" ]
   then
-    cat automatic/GENERIC.txt
-  elif [ "$LINE" = "@SETUP@" ]
+    cat automatic/VATOM.list
+  elif [ "$LINE" = "@TOOLS@" ]
   then
-    cat automatic/SETUP.txt
+    cat automatic/TOOLS.list
+  elif [ "$LINE" = "@CODES@" ]
+  then
+    cat automatic/codes.list
   else
     echo -E "$LINE"
   fi
-  done
+   done
 } > ${file}PP.txt
 done
-

user-doc/report_errors

+#!/bin/bash
+
+nerrors=`wc -l errors | awk '{print NF}'`
+if [ $nerrors -eq 0 ] ; then
+  rm errors
+else
+  echo "************************************************"
+  echo "Found the following errors in your documentation"
+  echo ""
+  cat errors
+  echo "************************************************"
+fi