Command line tool: driver
| Module | cltools |
|---|---|
| Description | Input |
| analyze trajectories with plumed | command line args |
Details
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 from the file can then be treated like calculated colvars.
masses and chages
Notice that by default the driver has no knowledge about the masses and charges of your atoms! Thus, if you want to compute quantities that depend on charges (e.g. DHENERGY) or masses (e.g. COM) you need to pass masses and charges to driver. You can do this by either using --pdb option or the --mc option. The latter will read a file produced by DUMPMASSCHARGE.
Examples
The following command tells plumed to post process 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 then it will be performed only on every th
frame in the trajectory file.
plumed driveranalyze trajectories with plumed This action has hidden defaults. More details --plumed specify the name of the plumed input file plumed.dat --ixyzthe trajectory in xyz format trajectory.xyz
Notice that xyz files are expected to be in the internal PLUMED unit of nm.
You can change this behavior by using the --length-units option as shown below
plumed driveranalyze trajectories with plumed This action has hidden defaults. More details --plumed specify the name of the plumed input file plumed.dat --ixyzthe trajectory in xyz format trajectory.xyz --length-unitsunits for length, either as a string or a number 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 driveranalyze trajectories with plumed This action has hidden defaults. More details --plumed specify the name of the plumed input file plumed.dat --ixyzthe trajectory in xyz format trajectory.xyz --length-unitsunits for length, either as a string or a number A
which uses the following plumed.dat file
# no explicit UNITS action here d: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2 PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=d FILEthe name of the file on which to output these quantities=colvar
In this case, the driver reads the xyz file assuming it to contain coordinates in Angstroms.
However, the resulting colvar file contains a distance expressed in nm.
The following command tells plumed to post process the trajectory contained in trajectory.xyz. by performing the actions described in the input file plumed.dat.
plumed driveranalyze trajectories with plumed This action has hidden defaults. More details --plumed specify the name of the plumed input file plumed.dat --ixyzthe trajectory in xyz format trajectory.xyz --trajectory-stride 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) 100 --timestep the timestep that was used in the calculation that produced this trajectory in picoseconds 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 xyz files (in PLUMED units) and gro files (in nm). In addition, PLUMED includes support for a subset of the trajectory file formats supported by VMD, e.g. xtc and dcd:
plumed driveranalyze trajectories with plumed This action has hidden defaults. More details --plumed specify the name of the plumed input file plumed.dat --pdbprovides a pdb with masses and charges diala.pdb --mf_xtc molfile: the trajectory in xtc format traj.xtc --trajectory-stride 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) 100 --timestep the timestep that was used in the calculation that produced this trajectory in picoseconds 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 file formats you can use.
Molfile plugin requires the periodic cell to be triangular (i.e. the 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 the total number of atoms. In this case you can use
the --natoms option as shown below
plumed driveranalyze trajectories with plumed This action has hidden defaults. More details --plumed specify the name of the plumed input file plumed.dat --mf_crd molfile: the trajectory in crd format trajectory.crd --natomsprovides number of atoms - only used if file format does not contain number of atoms 128
Check the available molfile plugins and limitations at this link.
You can also use the xdrfile implementation of xtc and trr with plumed driver. If you want to do so you 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, if you install xdrfile you can then use the DUMPATOMS command to write compressed xtc files.
Multiple replicas
When PLUMED is compiled with MPI support, you can emulate a multi-simulation setup with driver by providing the --multi
option with the appropriate number of ranks. This allows you to use the ref special-replica-syntax that is discussed here to analyze multiple
trajectories (see this tutorial). PLUMED will also automatically append a numbered suffix to output files
(e.g. COLVAR.0, COLVAR.1, …) as discussed here. Similarly, each replica will search for the corresponding suffixed input file (e.g. traj.0.xtc, …)
or default to the unsuffixed one.
Syntax
The following table describes the command line options that are available for this tool
| Keyword | Description |
|---|---|
| --help/-h | print this help |
| --help-debug | print special options that can be used to create regtests |
| --plumed | specify the name of the plumed input file |
| --timestep | the timestep that was used in the calculation that produced this trajectory in picoseconds |
| --trajectory-stride | 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 | set number of replicas for multi environment (needs MPI) |
| --noatoms | don't read in a trajectory |
| --parse-only | read the plumed input file and stop |
| --restart | makes driver behave as if restarting |
| --ixyz | the trajectory in xyz format |
| --igro | the trajectory in gro format |
| --idlp4 | the trajectory in DL_POLY_4 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 |
| --shortcut-ofile | the name of the file to output info on the way shortcuts have been expanded |
| --valuedict-ofile | output a dictionary giving information about each value in the input file |
| --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 kT it will not be necessary to specify temperature in input file |
| --dump-forces | dump the forces on a file |
| --dump-forces-fmt | the format to use to dump the forces |
| --dump-full-virial | with --dump-forces, it dumps the 9 components of the virial |
| --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 orthorhombic, 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 |
| --debug-float | [yes/no] turns on the single precision version (to check float interface) |
| --debug-dd | [yes/no] use a fake domain decomposition |
| --debug-pd | [yes/no] use a fake particle decomposition |
| --debug-grex | use a fake gromacs-like replica exchange, specify exchange stride |
| --debug-grex-log | log file for debug=grex |