Fixed to new style documentation in setup

new-manual/parsing.md

@@ -13,6 +13,18 @@ Every example input you encounter in this manual, in the [nest](www.plumed-nest.
 that explain what options are turned on by flags and what the values provided in each keyword pair represents.  You will also find details of
 all the keywords and flags that are available for an action on the manual page for that action.
 
+By default the following units are used when reading the parameters that are specified using keywords.  
+
+| Quantity | Unit   |
+|:---------|:-------|
+| Length   | nm     |
+| Energy   | kj/mol |
+| Time     | ps     | 
+| Mass     | amu    |
+| Charge   | e      |
+
+These are also the units in any output files.  If you would like to change these units you can use the [UNITS](UNITS.md) command.
+
 ## Reading constants
 
 In the input to keywords that read real numbers you can use constants that are specified using strings rather than numbers.

src/setup/Load.cpp

@@ -31,88 +31,92 @@ namespace setup {
 /*
 Loads a library, possibly defining new actions.
 
-It is available only
-on systems allowing for dynamic loading. It can also be fed with a cpp file,
-in which case the file is compiled first.
-
-\par Examples
-
-If you have a shared object named extensions.so and want to
-use the functions implemented within it within PLUMED you can
-load it with the following syntax
-
-\plumedfile
-LOAD FILE=extensions.so
-\endplumedfile
-
-As a more practical example, imagine that you want to make a
-small change to one collective variable that is already implemented
-in PLUMED, say \ref DISTANCE . Copy the file `src/colvar/Distance.cpp`
-into your work directory, rename it as `Distance2.cpp`
-and  edit it as you wish. It might be better
-to also replace any occurrence of the string DISTANCE within the file
-with DISTANCE2, so that both old and new implementation will be available
-with different names. Then you can compile it into a shared object using
-\verbatim
-> plumed mklib Distance2.cpp
-\endverbatim
-This will generate a file `Distance2.so` (or `Distance2.dylib` on a mac)
-that can be loaded.
-Now you can use your new implementation with the following input
-\plumedfile
-# load the new library
-LOAD FILE=Distance2.so
-# compute standard distance
-d: DISTANCE ATOMS=1,10
-# compute modified distance
-d2: DISTANCE2 ATOMS=1,10
-# print them on a file
-PRINT ARG=d,d2 FILE=compare-them
-\endplumedfile
+The LOAD action is only available on systems that allow dynamic loading.
+This action allows you load new funcionality into PLUMED at runtime.
+This new functionality can be in a .so file or a .cpp file. If the 
+new functionality is in a cpp file then the code is compiled and the
+the resulting object is loaded.
+
+Using the LOAD action is useful for making quick tests while developing your own
+actions. Of course, once your implementation is ready you should 
+add it to the PLUMED source tree and recompile PLUMED.
 
-You can even skip the initial step and directly feed PLUMED
-with the `Distance2.cpp` file: it will be compiled on the fly.
-\plumedfile
+One way to use the LOAD action is to directly load a cpp file as illustrated in the input below.
+
+```plumed
+#SETTINGS INPUTFILES=regtest/basic/rt15/Distance2.cpp
 # load the new definition
 # this is a cpp file so it will be compiled
-LOAD FILE=Distance2.cpp
+LOAD FILE=regtest/basic/rt15/Distance2.cpp
 # compute standard distance
 d: DISTANCE ATOMS=1,10
 # compute modified distance
 d2: DISTANCE2 ATOMS=1,10
 # print them on a file
 PRINT ARG=d,d2 FILE=compare-them
-\endplumedfile
+```
+
+When PLUMED reads the input above it first compiles the code in `Distance2.cpp`. The resulting object file
+is then loaded into PLUMED. If you look at the cpp file that is input in the command above you can see that 
+a new action called `DISTANCE2` is defined within it.  We can thus use this new action in the input above.
 
-This will allow to make quick tests while developing your own
-variables. Of course, after your implementation is ready you might
-want to add it to the PLUMED source tree and recompile
-the whole PLUMED.
+Instead of compiling the code at runtime you can construct a shared object from the Distance2.cpp file and LOAD the shared library instead of 
+the cpp file.  To construct the shared object you would use the following command:
 
-Starting with PLUMED 2.10, the LOAD action can be placed in any point of the input
-file, and will only affect commands that are placed after the LOAD action.
-In other words, you can create a file named `Distance.cpp` and that reimplement
-the \ref DISTANCE action and use it like this:
+````
+> plumed mklib Distance2.cpp
+```` 
 
-\plumedfile
+When you run this command a new file called `Distance2.so` (or `Distance2.dylib` on a mac) is created.
+You can then load this shared object in PLUMED by using the following LOAD command
+
+````
+LOAD FILE=Distance2.so
+````
+
+The new functionality within the Distance2.cpp file can then be used in the remainder of the input in the same way it was 
+used in the previous example.
+(Notice that the only reason for not using the usual PLUMED syntax highlightling in the example above is that we have no 
+file called Distance2.so.)
+
+From PLUMED 2.10 onwards the LOAD action can be placed at any point of the input
+file. The loaded functionality will then only affect commands that are placed after the LOAD action.
+These features are illustrated in the input below:
+
+```plumed
+#SETTINGS INPUTFILES=regtest/basic/rt15/Distance3.cpp
 # compute standard distance
 d: DISTANCE ATOMS=1,10
 # load the new definition
-LOAD FILE=Distance.so
+LOAD FILE=regtest/basic/rt15/Distance3.cpp
 # compute modified distance
 d2: DISTANCE ATOMS=1,10
 # print them on a file
 PRINT ARG=d,d2 FILE=compare-them
-\endplumedfile
+```
+
+Notice that the `Distance3.cpp` uses the command:
 
-In addition, starting with PLUMED 2.10 the LOAD action can be used in contexts where
+```c++
+PLUMED_REGISTER_ACTION(Distance,"DISTANCE")
+```
+
+Instead of the command:
+
+```c++
+PLUMED_REGISTER_ACTION(Distance,"DISTANCE2")
+```
+
+that was used in `Distance2.cpp. Consequently, when we load the `Distance3.cpp` file here we redefine the DISTANCE command.
+The functions that compute `d` and `d2` in the above input are thus different.
+
+A final point to note is that, starting with PLUMED 2.10, the LOAD action can be used in contexts where
 multiple Plumed objects exist. A possible example is multithreading: loading an action
 from a Plumed object used in one thread will not affect other threads.
 Another example is if multiple Plumed objects are created in the C/C++ or Python interface.
 If a LOAD command is used in one of these objects, the loaded action will not affect
 the other objects.
 
-
 */
 //+ENDPLUMEDOC
 

src/setup/Restart.cpp

@@ -31,58 +31,92 @@ namespace setup {
 /*
 Activate restart.
 
-This is a Setup directive and, as such, should appear
-at the beginning of the input file. It influences the way
-PLUMED treat files open for writing (see also \ref Files).
-
-Notice that it is also possible to enable or disable restart on a per-action
-basis using the RESTART keyword on a single action. In this case,
-the keyword should be assigned a value. RESTART=AUTO means that global
-settings are used, RESTART=YES or RESTART=NO respectively enable
-and disable restart for that single action.
-
-\attention
-This directive can have also other side effects, e.g. on \ref METAD
-and \ref PBMETAD and on some analysis action.
-
-\par Examples
-
-Using the following input:
-\plumedfile
+Many MD calculations are run on supercomputer facilities that limit the amount of 
+time an individual calculation can run for.  As MD simulations take a long time to 
+complete, you often have to restart your calculations and build up your trajectories by 
+running a chain of sub-runs. Some MD codes tell PLUMED if the MD has restarted
+the calculation from a checkpoint file while others do not. To avoid problems we recommend
+using the RESTART commands and keywords in your input files whenever you are generating 
+trajetories by restarting calculations from a checkpoint file.
+
+RESTART is a Setup directive and, as such, should appear
+at the beginning of the input file. When you include the RESTART command
+in your plumed.dat file you are telling PLUMED that you want to restart all
+the actions. Restarting these actions ensures that that PLUMED appends
+all the files that are open for writing. Appending to these files makes it 
+easier to analyze results from simulations that have been performed as a 
+chain of several sub-runs.
+
+To consider what this means in practise consider the following input:
+
+```plumed
 d: DISTANCE ATOMS=1,2
 PRINT ARG=d FILE=out
-\endplumedfile
-a new 'out' file will be created. If an old one is on the way, it will be automatically backed up.
+```
+
+If you run a plumed calculation in a directory which already contains a file called 
+`out` that file called `out` will be renamed `bck.0.out` so that the data from the new
+calculation can be output to a new version of the file `out` and so that the data in the 
+old version of the file is not lost.
 
-On the other hand, using the following input:
-\plumedfile
+If by contrast you run the calculation in that same directory with the following input:
+
+```plumed
 RESTART
 d: DISTANCE ATOMS=1,2
 PRINT ARG=d FILE=out
-\endplumedfile
-the file 'out' will be appended.
+```
+
+The data from the new simulation simulation will be appended to the file called `out` that 
+was already present in the data. 
+
+Notice that it is also possible to enable or disable restart on a per-action
+basis using the RESTART keyword as illustrated below:
+
+```plumed
+d1: DISTANCE ATOMS=1,2
+d2: DISTANCE ATOMS=1,2
+PRINT ARG=d1 FILE=out1 
+PRINT ARG=d2 FILE=out2 RESTART=YES
+```
+
+If this input is used any files called `out1` are backed up to `bck.0.out1`.  Data from the 
+new calculation is then appended to any file called `out2`  that is present in the working directory.
+
+Notice that the RESTART keyword is assigned one of three values:
+
+- `RESTART=AUTO` is the default and means that global settings are used
+- `RESTART=YES` means that the action is restarted
+- `RESTART=NO` means that the action is not restarted even if there is a global restart command
+
+The following input is thus equivalent to the first input that introduced the RESTART keyword.
 
-In the following case, file out1 will be backed up and file out2 will be concatenated
-\plumedfile
+```plumed
 RESTART
 d1: DISTANCE ATOMS=1,2
 d2: DISTANCE ATOMS=1,2
 PRINT ARG=d1 FILE=out1 RESTART=NO
-PRINT ARG=d2 FILE=out2
-\endplumedfile
+PRINT ARG=d2 FILE=out2 
+```
 
-In the following case, file out will backed up even if the MD code thinks that we
-are restarting. Notice that not all the MD code send to PLUMED information about restarts.
-If you are not sure, always put `RESTART` when you are restarting and nothing when you aren't
-\plumedfile
+[!CAUTION]
+The RESTART directive can have also other important side effects. For methods such as [METAD](METAD.md) 
+or [PBMETAD](PBMETAD.md) when the action is told to restart all the hills from the previous run are read
+in at the start of the calculation so that the bias potential at the start of the restarted simulation is
+identical to the bias potential at the end of the previous run.
+
+If you are absolutely certain that you do not want to restart any of the actions in your input you 
+can use an input like the example below:
+
+```plumed
 RESTART NO
 d1: DISTANCE ATOMS=1,2
 PRINT ARG=d1 FILE=out1
-\endplumedfile
-
-
-
+```
 
+The `RESTART NO` command in this input tells PLUMED that no actions are to be restarted even if the MD
+code has told PLUMED that the initial configuration came from a checkpoint file and that the trajectory 
+is being restarted.
 
 */
 //+ENDPLUMEDOC

src/setup/Units.cpp

@@ -31,57 +31,61 @@ namespace setup {
 /*
 This command sets the internal units for the code.
 
-A new unit can be set by either
-specifying a conversion factor from the plumed default unit or by using a string
-corresponding to one of the defined units given below.  This directive MUST
-appear at the BEGINNING of the plumed.dat file.  The same units must be used
-throughout the plumed.dat file.
-
-Notice that all input/output will then be made using the specified units.
-That is: all the input parameters, all the output files, etc. The only
-exceptions are file formats for which there is a specific convention concerning
-the units. For example, trajectories written in .gro format (with \ref DUMPATOMS)
-are going to be always in nm.
-
-The following strings can be used to specify units. Note that the strings are
-case sensitive.
-- LENGTH: nm (default), A (for Angstrom), um (for micrometer), Bohr (0.052917721067 nm)
-- ENERGY: kj/mol (default), j/mol, kcal/mol (4.184 kj/mol), eV (96.48530749925792 kj/mol), Ha (for Hartree, 2625.499638 kj/mol)
-- TIME: ps (default), fs, ns, atomic (2.418884326509e-5 ps)
-- MASS: amu (default)
-- CHARGE: e (default)
-
-
-\par Examples
-
-\plumedfile
+The default units in the plumed input and output files are discussed [here](parsing.md). If you would like 
+to use units that are different from these defaults you can use the UNITS command. This directive MUST
+appear at the BEGINNING of the plumed.dat file and same units must be used throughout the plumed.dat file. 
+
+The following input demonstrates one way that you can use the UNITS command to change the units.
+
+```plumed
 # this is using Angstrom - kj/mol - fs
 UNITS LENGTH=A TIME=fs
 
 # compute distance between atoms 1 and 4
 d: DISTANCE ATOMS=1,4
 
 # print time and distance on a COLVAR file
+# times and distances in this file will be in fs and A respectively
 PRINT ARG=d FILE=COLVAR
 
 # dump atoms 1 to 100 on a 'out.gro' file
+# The positions in the gro file here will be written 
+# in nm because this is the convention for gro files.
 DUMPATOMS FILE=out.gro STRIDE=10 ATOMS=1-100
 
 # dump atoms 1 to 100 on a 'out.xyz' file
+# The position in the xyz file here will be written 
+# in A as there is no conventional units for xyz files
+# and the plumed length units has been set to Angstroms.
 DUMPATOMS FILE=out.xyz STRIDE=10 ATOMS=1-100
-\endplumedfile
+```
+
+In the example input above strings are used to set the units. The following table details all the strings
+that can be used when setting units.  Note that the strings are case sensitive.
 
-In the `COLVAR` file, time and distance will appear in fs and A respectively, *irrespective* of which units
-you are using in the host MD code. The coordinates in the `out.gro` file will be expressed in nm,
-since `gro` files are by convention written in nm. The coordinates in the `out.xyz` file
-will be written in Angstrom *since we used the UNITS command setting Angstrom units*.
-Indeed, within PLUMED xyz files are using internal PLUMED units and not necessarily Angstrom!
+| Quantity | Default | Alternatives |
+|:---------|:--------|:-------------|
+| Length   | nm      | A (for Angstrom), um (for micrometer), Bohr (0.052917721067 nm) |
+| Energy   | kj/mol  | j/mol, kcal/mol (4.184 kj/mol), eV (96.48530749925792 kj/mol), Ha (for Hartree, 2625.499638 kj/mol) |
+| Time     | ps      | fs, ns, atomic (2.418884326509e-5 ps) |
+| Mass     | amu     | |
+| Charge   | e       | |
 
-If a number, x, is found instead of a string, the new unit is equal to x times the default units.
-Using the following command as first line of the previous example would have lead to an identical result:
-\plumedfile
+If you want to use a unit that is not specified in the table above you can specify a factor for converting the default unit to 
+your chosen unit.  As an example of how this works in practice the example below converts lengths and times into A and fs by 
+giving explicit values for the conversion factors.
+
+```plumed
 UNITS LENGTH=0.1 TIME=0.001
-\endplumedfile
+```
+
+The input above tells PLUMED that lengths in nm should be divided by 0.1 so as to convert them to Anstroms. Times in ps
+should be divded by 0.001 to convert them from ps to fs.  
+
+To reitterate, the default or the units specified in the UNITS command are used in all input and output
+files.  The only exceptions are file formats for which there is a specific convention concerning
+the units. For example, trajectories written in .gro format (with [DUMPATOMS](DUMPATOMS.md)) will 
+always in nm.
 
 */
 //+ENDPLUMEDOC