Merge branch 'v2.3'

src/cltools/Driver.cpp

@@ -101,47 +101,58 @@ will read a file produced by \ref DUMPMASSCHARGE .
 
 \par Examples
 
-The following command tells plumed to postprocess the trajectory contained in trajectory.xyz
- by performing the actions described in the input file plumed.dat.  If an action that takes the
+The following command tells plumed to postprocess the trajectory contained in `trajectory.xyz`
+ by performing the actions described in the input file `plumed.dat`.  If an action that takes the
 stride keyword is given a stride equal to \f$n\f$ then it will be performed only on every \f$n\f$th
-frame in the trajectory file.
+frames in the trajectory file.
 \verbatim
 plumed driver --plumed plumed.dat --ixyz trajectory.xyz
 \endverbatim
 
-The following command tells plumed to postprocess the trajectory contained in trajectory.xyz.
- by performing the actions described in the input file plumed.dat. Here though
---trajectory-stride is set equal to the frequency with which frames were output during the trajectory
-and the --timestep is equal to the simulation timestep.  As such the STRIDE parameters in the plumed.dat
-files are no longer ignored and any files output resemble those that would have been generated
-had we run the calculation we are running with driver when the MD simulation was running.
+Notice that `xyz` files are expected to be in internal PLUMED units, that is by default nm.
+You can change this behavior by using the `--length-units` option:
 \verbatim
-plumed driver --plumed plumed.dat --ixyz trajectory.xyz --trajectory-stride 100 --timestep 0.001
+plumed driver --plumed plumed.dat --ixyz trajectory.xyz --length-units A
 \endverbatim
-
-By default you have access to a subset of the trajectory file formats
-supported by VMD, e.g. xtc and dcd:
-
+The strings accepted by the `--length-units` options are the same ones accepted by the \ref UNITS action.
+Other file formats typically have their default coordinates (e.g., `gro` files are always in nm)
+and it thus should not be necessary to use the `--length-units` option. Additionally,
+consider that the units used by the `driver` might be different by the units used in the PLUMED input
+file `plumed.dat`. For instance consider the command:
 \verbatim
-plumed driver --plumed plumed.dat --pdb diala.pdb --mf_xtc traj.xtc --trajectory-stride 100 --timestep 0.001
+plumed driver --plumed plumed.dat --ixyz trajectory.xyz --length-units A
+\endverbatim
+where `plumed.dat` is
+\verbatim
+# no explicit UNITS action here
+d: DISTANCE ATOMS=1,2
+PRINT ARG=d FILE=colvar
 \endverbatim
+In this case, the driver reads the `xyz` file assuming it to contain coordinates in Angstrom units.
+However, the resulting `colvar` file contains a distance expressed in nm.
 
-where --mf_ prefixes the extension of one of the accepted molfile
-plugin format.
+The following command tells plumed to postprocess the trajectory contained in trajectory.xyz.
+ by performing the actions described in the input file plumed.dat.
+\verbatim
+plumed driver --plumed plumed.dat --ixyz trajectory.xyz --trajectory-stride 100 --timestep 0.001
+\endverbatim
+Here though
+`--trajectory-stride` is set equal to the frequency with which frames were output during the trajectory
+and the `--timestep` is equal to the simulation timestep.  As such the `STRIDE` parameters in the `plumed.dat`
+files are referred to the original timestep and any files output resemble those that would have been generated
+had we run the calculation we are running with driver when the MD simulation was running.
 
-To have support of all of VMD's plugins you need to recompile
-PLUMED. You need to download the SOURCE of VMD, which contains
-a plugins directory. Adapt build.sh and compile it. At
-the end, you should get the molfile plugins compiled as a static
-library libmolfile_plugin.a. Locate said file and libmolfile_plugin.h,
-and customize the configure command with something along
-the lines of:
+PLUMED can read natively xyz files (in PLUMED units) and gro files (in nm). In addition,
+PLUMED includes by default support for a 
+subset of the trajectory file formats supported by VMD, e.g. xtc and dcd:
 
 \verbatim
-configure [...] LDFLAGS="-ltcl8.5 -L/mypathtomolfilelibrary/ -L/mypathtotcl" CPPFLAGS="-I/mypathtolibmolfile_plugin.h/"
+plumed driver --plumed plumed.dat --pdb diala.pdb --mf_xtc traj.xtc --trajectory-stride 100 --timestep 0.001
 \endverbatim
 
-and rebuild.
+where `--mf_` prefixes the extension of one of the accepted molfile plugin format.
+If PLUMED has been \ref Installation "installed" with full molfile support, other formats will be available.
+Just type `plumed driver --help` to see which plugins are available.
 
 Molfile plugin require periodic cell to be triangular (i.e. first vector oriented along x and
 second vector in xy plane). This is true for many MD codes. However, it could be false
@@ -152,14 +163,15 @@ the `--natoms` option:
 plumed driver --plumed plumed.dat --imf_crd trajectory.crd --natoms 128
 \endverbatim
 
-Check the available molfile plugins and limitations at http://www.ks.uiuc.edu/Research/vmd/plugins/molfile/.
+Check the available molfile plugins and limitations at [this link](http://www.ks.uiuc.edu/Research/vmd/plugins/molfile/).
 
 Additionally, you can use the xdrfile implementation of xtc and trr. To this aim, just
-download and install properly the xdrfile library (see here: http://www.gromacs.org/Developer_Zone/Programming_Guide/XTC_Library).
+download and install properly the xdrfile library (see [this link](http://www.gromacs.org/Developer_Zone/Programming_Guide/XTC_Library)).
 If the xdrfile library is installed properly the PLUMED configure script should be able to
 detect it and enable it.
 Notice that the xdrfile implementation of xtc and trr
 is more robust than the molfile one, since it provides support for generic cell shapes.
+In addition, it allows \ref DUMPATOMS to write compressed xtc files.
 
 
 */

user-doc/Installation.txt

@@ -271,6 +271,23 @@ in the configuration file.
   -DF77_NO_UNDERSCORE to CPPFLAGS
   Notice that "./configure" should automatically try this solution.
 
+\subsection installation-vmdplugins VMD trajectory plugins
+
+If you configure PLUMED with VMD's plugins you will be able to read
+many more trajectory formats. To this aim,
+you need to download the SOURCE of VMD, which contains
+a plugins directory. Adapt build.sh and compile it. At
+the end, you should get the molfile plugins compiled as a static
+library `libmolfile_plugin.a`. Locate said file and `libmolfile_plugin.h`,
+and customize the configure command with something along
+the lines of:
+
+\verbatim
+./configure LDFLAGS="-ltcl8.5 -L/mypathtomolfilelibrary/ -L/mypathtotcl" CPPFLAGS="-I/mypathtolibmolfile_plugin.h/"
+\endverbatim
+
+and rebuild.
+
 \section CompilingPlumed Compiling PLUMED
 
 Once configured, PLUMED can be compiled using the following command:
@@ -455,12 +472,12 @@ There are different options available when patching. You can check all of them u
 > plumed patch --help
 \endverbatim
 Particularly interesting options include:
-- --static (default) just link PLUMED as a collection of object files. This is only suggested if for external reasons you
+- --static just link PLUMED as a collection of object files. This is only suggested if for external reasons you
   absolutely need a static executable. Notice that with this setting it is often more complicated to configure
   properly the MD code, since all the libraries that PLUMED depends on should be properly specified. The `./configure` script
   does its best in this sense, but sometime it cannot solve the problem. Additionally, this patching mode has been reported
   not to work properly on OSX.
-- --shared allows you to link PLUMED as a shared library. As a result when PLUMED is updated, there will be no need to recompile the MD code.
+- --shared (default) allows you to link PLUMED as a shared library. As a result when PLUMED is updated, there will be no need to recompile the MD code.
   This is way better than --static since the libraries that PLUMED depends on should be automatically linked.
   Notice that if you later remove the directory where PLUMED is installed also the MD code will not run anymore.
 - --runtime allows you to choose the location of the PLUMED library at runtime by setting the variable PLUMED_KERNEL.