From d2e140ccfa99a7077e2297fe21acb1ec88b1b680 Mon Sep 17 00:00:00 2001
From: Giovanni Bussi <giovanni.bussi@gmail.com>
Date: Thu, 23 Jul 2015 14:40:04 -0600
Subject: [PATCH] Added doc to p1 to p2 tutorial

[makedoc]
---
 user-doc/tutorials/moving.txt | 69 ++++++++++++++++++++++++++++++++++-
 1 file changed, 67 insertions(+), 2 deletions(-)

diff --git a/user-doc/tutorials/moving.txt b/user-doc/tutorials/moving.txt
index dd4d2937f..86efd4b46 100644
--- a/user-doc/tutorials/moving.txt
+++ b/user-doc/tutorials/moving.txt
@@ -11,7 +11,8 @@ executed in the order they are found in the input file.
 Because of this, you must e.g. first compute a collective variable and then print it
 later. More information can be found in the Section about \ref Syntax.
 
-Another very important change is in the way groups are used, discussed below.
+Other important changes are in the way groups and units are used,
+as discussed below.
 Finally, many features appear under a different name in the new version.
 
 \section moving-Syntax New syntax
@@ -92,11 +93,75 @@ PRINT STRIDE=100 FILE=COLVAR ARG=d,r.*
 
 Notice that virtual atoms are very powerful tools in PLUMED 2. Actually, they can be used
 in any collective variable where normal atoms can be used, just by calling them by name.
-In this example you can also appreciate the advantage of calling collective variables
+This allows to straightforwardly define variables such as coordination between centers
+of mass, which would have required an ad hoc implementation in PLUMED 1.
+
+In the example above you can also appreciate the advantage of calling collective variables
 by name. It is obvious here that \ref RESTRAINT is acting on distance `d`, whereas in PLUMED 1
 one had to keep track of the number of the collective variables. This was easy for a single collective variable,
 but could become cumbersome for complex input files.
 
+\section moving-Names Names in output files
+
+Another advantage of having names is that when PLUMED produces an output file
+it can insert explicit names in the file.
+Consider for example this PLUMED 1 input
+\verbatim
+DISTANCE LIST 1 2
+ANGLE    LIST 3 4 5
+PRINT W_STRIDE 100
+\endverbatim
+The first line of the COLVAR file was then
+\verbatim
+#!  FIELDS time cv1 cv2
+\endverbatim
+The equivalent input file in PLUMED 2 is
+\verbatim
+d: DISTANCE ATOMS=1,2
+a: ANGLE    ATOMS=3,4,5
+PRINT ARG=d,a FILE=COLVAR STRIDE=100
+\endverbatim
+The first line of the COLVAR file now is
+\verbatim
+#! FIELDS time d a
+\endverbatim
+This makes it easy to remember what's the meaning of each column of the COLVAR file
+without the need to always go back to the PLUMED input to check in which order
+the variables were declared.
+
+\section moving-Units Units
+
+In PLUMED 1 the input file of PLUMED was expected to be written using the same units
+of the MD code. This choice was made to allow users to adopt the same units they
+were used to. However, we realized later that this choice was not allowing the
+PLUMED input files to be ported between different MD code. Let's say
+that one was using this keyword with GROMACS (kj/mol - nm)
+\verbatim
+UMBRELLA CV 1 KAPPA 200 AT 1.0
+\endverbatim
+Let's assume the variable CV 1 was a distance.
+The same keyword in NAMD (kcal/mol - A) should have been converted to
+\verbatim
+UMBRELLA CV 1 KAPPA .4780 AT 10.0
+\endverbatim
+The conversion of `AT` is straightforward (1nm=10A), but the conversion on
+`KAPPA` is more error prone. This is because `KAPPA` is measured in units
+of energy divided by distance squared. Notice that a different factor should
+have been used if the CV was an angle.
+
+Learning from this, we designed PLUMED 2 in a way that units in the PLUMED input
+are independent of the MD code. Technically, this is achieved by doing the conversion
+when coordinates and forces are passed back and forth. In this way, the same
+PLUMED input could be used with GROMACS and NAMD.
+
+We decided to use as standard units in PLUMED kj/mol, nm, and ps. Perhaps
+this is because most of the developers are using GROMACS, which also
+adopts these units.
+However, we still allow
+the personalization of units by means of the \ref UNITS keyword.
+Since this keyword is included directly in the PLUMED input file,
+even when using personalized units the input files remains perfectly
+portable across different MD engines.
 
 \section moving-Directives Directives
 
-- 
GitLab