driver

This is part of the cltools module

driver is a tool that allows one to to use plumed to post-process an existing trajectory.

The input to driver is specified using the command line arguments described below.

In addition, you can use the special READ command inside your plumed input to read in colvar files that were generated during your MD simulation. The values read in can then be treated like calculated colvars.

Warning

Notice that by default the driver has no knowledge about the masses and charges of your atoms! Thus, if you want to compute quantities depending charges (e.g. DHENERGY) or masses (e.g. COM) you should pass the proper information to the driver. You can do it either with the –pdb option or with the –mc option. The latter will read a file produced by DUMPMASSCHARGE .

The input trajectory is specified using one of the following

--ixyz	the trajectory in xyz format
--igro	the trajectory in gro format
--ixtc	the trajectory in xtc format (xdrfile implementation)
--itrr	the trajectory in trr format (xdrfile implementation)
--mf_dcd	molfile: the trajectory in dcd format
--mf_crd	molfile: the trajectory in crd format
--mf_crdbox	molfile: the trajectory in crdbox format
--mf_gro	molfile: the trajectory in gro format
--mf_g96	molfile: the trajectory in g96 format
--mf_trr	molfile: the trajectory in trr format
--mf_trj	molfile: the trajectory in trj format
--mf_xtc	molfile: the trajectory in xtc format
--mf_pdb	molfile: the trajectory in pdb format

The following must be present

--plumed	( default=plumed.dat ) specify the name of the plumed input file
--timestep	( default=1.0 ) the timestep that was used in the calculation that produced this trajectory in picoseconds
--trajectory-stride	( default=1 ) the frequency with which frames were output to this trajectory during the simulation (0 means that the number of the step is read from the trajectory file, currently working only for xtc/trr files read with –ixtc/–trr)
--multi	( default=0 ) set number of replicas for multi environment (needs mpi)

The following options are available

--help/-h	( default=off ) print this help
--help-debug	( default=off ) print special options that can be used to create regtests
--noatoms	( default=off ) don't read in a trajectory. Just use colvar files as specified in plumed.dat
--dump-full-virial	( default=off ) with –dump-forces, it dumps the 9 components of the virial
--length-units	units for length, either as a string or a number
--mass-units	units for mass in pdb and mc file, either as a string or a number
--charge-units	units for charge in pdb and mc file, either as a string or a number
--kt	set kBT, it will not be necessary to specify temperature in input file
--dump-forces	dump the forces on a file
--dump-forces-fmt	( default=%f ) the format to use to dump the forces
--pdb	provides a pdb with masses and charges
--mc	provides a file with masses and charges as produced with DUMPMASSCHARGE
--box	comma-separated box dimensions (3 for orthorombic, 9 for generic)
--natoms	provides number of atoms - only used if file format does not contain number of atoms
--initial-step	provides a number for the initial step, default is 0
--debug-forces	output a file containing the forces due to the bias evaluated using numerical derivatives and using the analytical derivatives implemented in plumed

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 stride keyword is given a stride equal to \(n\) then it will be performed only on every \(n\)th frames in the trajectory file.

plumed driver --plumed plumed.dat --ixyz trajectory.xyz

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:

plumed driver --plumed plumed.dat --ixyz trajectory.xyz --length-units A

The strings accepted by the --length-units options are the same ones accepted by the 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:

plumed driver --plumed plumed.dat --ixyz trajectory.xyz --length-units A

where plumed.dat is

# no explicit UNITS action here
d: DISTANCE ATOMS=1,2
PRINT ARG=d FILE=colvar

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.

The following command tells plumed to postprocess the trajectory contained in trajectory.xyz. by performing the actions described in the input file plumed.dat.

plumed driver --plumed plumed.dat --ixyz trajectory.xyz --trajectory-stride 100 --timestep 0.001

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.

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:

plumed driver --plumed plumed.dat --pdb diala.pdb --mf_xtc traj.xtc --trajectory-stride 100 --timestep 0.001

where --mf_ prefixes the extension of one of the accepted molfile plugin format. If PLUMED has been 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 if you rotate the coordinates in your trajectory before reading them in the driver. Also notice that some formats (e.g. amber crd) do not specify atom number. In this case you can use the --natoms option:

plumed driver --plumed plumed.dat --imf_crd trajectory.crd --natoms 128

Check the available molfile plugins and limitations at this link.

Additionally, you can use the xdrfile implementation of xtc and trr. To this aim, just download and install properly the xdrfile library (see this link). 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 DUMPATOMS to write compressed xtc files.