Some clarification in doc

src/colvar/Coordination.cpp

@@ -74,13 +74,20 @@ c: COORDINATION GROUPA=1 GROUPB=1 R_0=0.3
 PRINT ARG=c STRIDE=10
 \endplumedfile
 
+Here's an example that shows what happens when providing COORDINATION with
+a single group:
 \plumedfile
-c1: COORDINATION GROUPA=1-10 GROUPB=1-10 R_0=0.3
-x: COORDINATION GROUPA=1-10 R_0=0.3
+# define some huge group:
+group: GROUP ATOMS=1-1000
+# Here's coordination of a group against itself:
+c1: COORDINATION GROUPA=group GROUPB=group R_0=0.3
+# Here's coordination within a single group:
+x: COORDINATION GROUPA=group R_0=0.3
+# This is just multiplying times 2 the variable x:
 c2: COMBINE ARG=x COEFFICIENTS=2
+
 # the two variables c1 and c2 should be identical, but the calculation of c2 is twice faster
-# since it runs on half of the pairs. Notice that to get the same result you
-# should double it
+# since it runs on half of the pairs.
 PRINT ARG=c1,c2 STRIDE=10
 \endplumedfile
 

src/generic/DumpAtoms.cpp

@@ -74,6 +74,15 @@ The following input instructs plumed to print out the positions of atoms
 COM ATOMS=11-20 LABEL=c1
 DUMPATOMS STRIDE=10 FILE=file.xyz ATOMS=1-10,c1
 \endplumedfile
+Notice that the coordinates in the xyz file will be expressed in nm, since these
+are the defaults units in PLUMED. If you want the xyz file to be expressed in A, you should use the
+following input
+\plumedfile
+COM ATOMS=11-20 LABEL=c1
+DUMPATOMS STRIDE=10 FILE=file.xyz ATOMS=1-10,c1 UNITS=A
+\endplumedfile
+As an alternative, you might want to set all the lentght used by PLUMED to Angstrom using the \ref UNITS
+action. However, this latter choice will affect all your input and output.
 
 The following input is very similar but dumps a .gro (gromacs) file,
 which also contains atom and residue names.
@@ -88,6 +97,24 @@ DUMPATOMS STRIDE=10 FILE=file.gro ATOMS=1-10,c1
 # a correct name in the resulting gro file
 \endplumedfile
 
+The `file.gro` will contain coordinates expressed in nm, since this is the convention for gro files.
+
+In case you have compiled PLUMED with `xdrfile` library, you might even write xtc or trr files as follows
+\plumedfile
+COM ATOMS=11-20 LABEL=c1
+DUMPATOMS STRIDE=10 FILE=file.xtc ATOMS=1-10,c1
+\endplumedfile
+Notice that xtc files are significantly smaller than gro and xyz files.
+
+Finally, consider that gro and xtc file store coordinates with limited precision set by the
+`PRECISION` keyword. Default value is 3, which means "3 digits after dot" in nm (1/1000 of a nm).
+The following will write a larger xtc file with high resolution coordinates:
+\plumedfile
+COM ATOMS=11-20 LABEL=c1
+DUMPATOMS STRIDE=10 FILE=file.xtc ATOMS=1-10,c1 PRECISION=7
+\endplumedfile
+
+
 
 */
 //+ENDPLUMEDOC

src/generic/Group.cpp

@@ -39,21 +39,21 @@ namespace generic {
 Define a group of atoms so that a particular list of atoms can be referenced with a single label
 in definitions of CVs or virtual atoms.
 
-Atoms can be listed as comma separated numbers (i.e. 1,2,3,10,45,7,9,..) , simple positive ranges
-(i.e. 20-40), ranges with a stride either positive or negative (i.e. 20-40:2 or 80-50:-2) or as
-combinations of all the former methods (1,2,4,5,10-20,21-40:2,80-50:-2).
+Atoms can be listed as comma separated numbers (i.e. `1,2,3,10,45,7,9`) , simple positive ranges
+(i.e. `20-40`), ranges with a stride either positive or negative (i.e. `20-40:2` or `80-50:-2`) or as
+comma separated combinations of all the former methods (`1,2,4,5,10-20,21-40:2,80-50:-2`).
 
-Moreover, lists can be imported from ndx files (GROMACS format). Use NDX_FILE to set the name of
-the index file and NDX_GROUP to set the name of the group to be imported (default is first one).
+Moreover, lists can be imported from ndx files (GROMACS format). Use `NDX_FILE` to set the name of
+the index file and `NDX_GROUP` to set the name of the group to be imported (default is first one).
 
-It is also possible to remove atoms from a list and or sort them using keywords REMOVE, SORT, and UNIQUE.
+It is also possible to remove atoms from a list and or sort them using keywords `REMOVE`, `SORT`, and `UNIQUE`.
 The flow is the following:
-- If ATOMS is present take the ordered list of atoms from the ATOMS keyword.
-- If NDX_FILE is present append the list from the the gromacs group.
-- If REMOVE is present remove the first occurence of each of these atoms from the list.
+- If `ATOMS` is present take the ordered list of atoms from the `ATOMS` keyword.
+- If `NDX_FILE` is present append the list from the the gromacs group.
+- If `REMOVE` is present remove the first occurence of each of these atoms from the list.
   If one tries to remove an atom that was not listed plumed adds a notice in the output.
-- If SORT is present resulting list is sorted.
-- If UNIQUE is present the resuling list is sorted and duplicate elements are removed.
+- If `SORT` is present resulting list is sorted.
+- If `UNIQUE` is present the resuling list is sorted and duplicate elements are removed.
 
 Notice that this command just creates a shortcut, and does not imply any real calculation.
 So, having a huge group defined does not slow down your calculation in any way.
@@ -63,8 +63,8 @@ the \ref INCLUDE command so as to store long group definitions in a separate fil
 
 \par Examples
 
-This command create a group of atoms containing atoms 1,4,7,11 and 14 (labeled 'o'), and another containing
-atoms 2,3,5,6,8,9,12,13 (labeled 'h'):
+This command create a group of atoms containing atoms 1, 4, 7, 11 and 14 (labeled 'o'), and another containing
+atoms 2, 3, 5, 6, 8, 9, 12, and 13 (labeled 'h'):
 \plumedfile
 o: GROUP ATOMS=1,4,7,11,14
 h: GROUP ATOMS=2,3,5,6,8,9,12,13
@@ -78,7 +78,7 @@ PRINT ARG=c FILE=colvar
 \endplumedfile
 
 Groups can be conveniently stored in a separate file.
-E.g. one could create a file named 'groups.dat' which reads
+E.g. one could create a file named `groups.dat` which reads
 \plumedfile
 o: GROUP ATOMS=1,4,7,11,14
 h: GROUP ATOMS=2,3,5,6,8,9,12,13
@@ -91,7 +91,7 @@ c: COORDINATION GROUPA=o GROUPB=h R_0=0.3
 # print the coordination on file 'colvar'
 PRINT ARG=c FILE=colvar
 \endplumedfile
-The groups.dat file could be very long and include lists of thousand atoms without cluttering the main plumed.dat file.
+The `groups.dat` file could be very long and include lists of thousand atoms without cluttering the main plumed.dat file.
 
 A GROMACS index file can also be imported
 \plumedfile
@@ -101,11 +101,13 @@ pro: GROUP NDX_FILE=index.ndx NDX_GROUP=protein
 DUMPATOMS ATOMS=pro FILE=traj.gro
 \endplumedfile
 
-A list can be edited with REMOVE
+A list can be edited with `REMOVE`. For instance, if you
+are using a water model with three atoms per molecule, you can
+easily construct the list of hydrogens in this manner
 \plumedfile
-# take one atom every three
+# take one atom every three, that is oxygens
 ox: GROUP ATOMS=1-90:3
-# take the remaining atoms
+# take the remaining atoms, that is hydrogens
 hy: GROUP ATOMS=1-90 REMOVE=ox
 DUMPATOMS ATOMS=ox FILE=ox.gro
 DUMPATOMS ATOMS=hy FILE=hy.gro

src/setup/Restart.cpp

@@ -74,6 +74,16 @@ PRINT ARG=d1 FILE=out1 RESTART=NO
 PRINT ARG=d2 FILE=out2
 \endplumedfile
 
+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
+RESTART NO
+d1: DISTANCE ATOMS=1,2
+PRINT ARG=d1 FILE=out1
+\endplumedfile
+
+
 
 
 

src/setup/Units.cpp

@@ -44,14 +44,35 @@ the units. For example, trajectories written in .gro format (with \ref DUMPATOMS
 are going to be always in nm.
 
 \par Examples
+
+
 \plumedfile
 # this is using nm - kj/mol - fs
-UNITS LENGTH=nm TIME=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
+PRINT ARG=d FILE=COLVAR
+
+# dump atoms 1 to 100 on a 'out.gro' file
+DUMPATOMS FILE=out.gro STRIDE=10 ATOMS=1-100
+
+# dump atoms 1 to 100 on a 'out.xyz' file
+DUMPATOMS FILE=out.xyz STRIDE=10 ATOMS=1-100
 \endplumedfile
-If a number, x, is found, the new unit is equal to x (default units)
+
+In the `COLVAR` file, time and distance will appear in fs and A respectively, *irrespectively* of which units
+you are using the 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!
+
+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
-# this is using nm - kj/mol - fs
-UNITS LENGTH=nm TIME=0.001
+UNITS LENGTH=0.1 TIME=0.001
 \endplumedfile
 
 */