Module: generic

Description	Usage
generic features of PLUMED many of which are for printing data to files
Authors: The PLUMED core developers

Details

This module contains a range of generic PLUMED actions that can be used in many different types of calculation. For example, many of the commands in this module are used to print data that has been calculated by PLUMED to files.

This module also contains functionalities such as WHOLEMOLECULES or WRAPAROUND that can be used to manipulate the positions that are passed from the MD code to PLUMED. Additionally, this module contains features such as CONSTANT and PDB2CONSTANT that can be used to store constant values.

Basic analysis

A molecular dynamics trajectory is in essence an ordered set of configurations of atoms. Trajectory analysis algorithms are methods that allow us to extract meaningful information from this extremely high-dimensionality information. They can be used either on the fly during an MD run or via post processing a trajectory using driver. In extracting this information much of the information in the trajectory will be discarded and assumed to be irrelevant to the problem at hand. For example, when we calculate a histogram from a trajectory we throw away all information on the order the frames were visited during the trajectory. We instead opt to display a time average that shows the parts of configuration space that were visited most frequently. There are many situations in which this is a reasonable thing to do as we know that time averages are equivalent to ensemble averages in the long timescale limit and that these average probabilities of being in different parts of configuration space, $P(s)$ , are thus related to the underlying free energy, $F(s)$ , via:

$F(s) = - k_B T \ln P(s)$

About the simplest form of analysis that PLUMED can perform involves printing information to a file. To print values to a file you can use PRINT or DUMPVECTOR.

UPDATE_IF allows you to do more complex things using the above print commands. As detailed in the documentation when you put any of the above actions within an UPDATE_IF block then data will only be output to the file if colvars are within particular ranges. In other words, if you use printing commandsin tandem
with UPDATE_IF you can identify the frames in your trajectory that satisfy some particular criteria and output information on those frames only.

Another useful command is the COMMITTOR command. As detailed in the documentation for COMMITTOR this command tells PLUMED (and the underlying MD code) to stop the calculation one some criteria is satisfied, alternatively one can use it to keep track of the number of times a criteria is satisfied.

Another important set of featuers in this module are COLLECT, ACCUMULATE, AVERAGE and GATHER_REPLICAS. These tools can be used to gather data from multiple frames in the trajectory or from multiple replicas for further analysis. In all these commands the STRIDE keyword is used to tell PLUMED how frequently to collect data from the trajectory. In all these methods the output from the analysis is a form of ensemble average. If you are running with a bias it is thus likely that you may want to reweight the trajectory frames in order to remove the effect the bias has on the static behavior of the system. The following section describes how to calculate weights for the various trajectory frames so that the final ensemble average is an average for the canonical ensemble at the appropriate
temperature.

Reweighting and Averaging

When you run an unbiased molecular dynamics calculation you can calculate time averages using:

$\langle A \rangle = \frac{1}{T} \sum_{t=0}^T A_t$

However, when a bias acts upon the system you typically want to counteract the effect of the bias so as to recover the true ensemble average. Typically each configuration is thus assigned a weight, $w_t$ so averages are computed as:

$\langle A \rangle = \frac{\sum_{t=0}^T w_t A_t}{\sum_{t=0}^T w_t}$

The methods for calculating these weights are discussed in the bias module and more information on these ideas can be found in the documentation for AVERAGE and HISTOGRAM.

Diagnostic tools

This module contains a number of diagnostic tools that can be used to check that new Actions are working correctly:

Action	Description
DUMPFORCES	Dump the force acting on one of a values in a file.
DUMPDERIVATIVES	Dump the derivatives with respect to the input parameters for a scalar.
DUMPMASSCHARGE	Dump masses and charges on a selected file.
DUMPPROJECTIONS	Dump the derivatives with respect to the input parameters for a scalar.

These commands allow you to test that derivatives and forces are calculated correctly within colvars and functions. One place where this is very useful is when you are testing whether or not you have implemented the derivatives of a new collective variables correctly. So for example if we wanted to do such a test on the distance CV we would employ an input file something like this:

Click on the labels of the actions for more information on what each action computes

d1The DISTANCE action with label d1 calculates the following quantities: Quantity    Type    Description  
d1 scalar the DISTANCE between this pair of atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2
d1nThe DISTANCE action with label d1n calculates the following quantities: Quantity    Type    Description  
d1n scalar the DISTANCE between this pair of atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2 NUMERICAL_DERIVATIVES calculate the derivatives for these quantities numerically
DUMPDERIVATIVESDump the derivatives with respect to the input parameters for scalar values (generally CVs, functions or biases). More details ARGthe labels of the values whose derivatives should be output=d1,d1n FILEthe name of the file on which to output the derivatives=derivatives

The first of these two distance commands calculates the analytical derivatives of the distance while the second calculates these derivatives numerically. Obviously, if your CV is implemented correctly these two sets of quantities should be nearly identical.

The above method is a good first check of the derivatives but it only works if you output value is a scalar. A more robust test of the derivatives is offered by using the --debug-forces option for driver. To test the distance CV using this method you would write a PLUMED input like this one:

Click on the labels of the actions for more information on what each action computes

d1The DISTANCE action with label d1 calculates the following quantities: Quantity    Type    Description  
d1 scalar the DISTANCE between this pair of atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2
BIASVALUETakes the value of one variable and use it as a bias More details ARGthe labels of the scalar/vector arguments whose values will be used as a bias on the system=d1

You then run a calculation using driver with the following input:

plumed driveranalyze trajectories with plumed This action has hidden defaults. More details --debug-forcesoutput a file containing the forces due to the bias evaluated using numerical derivatives and using the analytical derivatives implemented in plumed forces.num --ixyzthe trajectory in xyz format trajectory.xyz

The driver action with label plumed calculates somethingplumed driveranalyze trajectories with plumed This action uses the defaults shown here. More details --debug-forcesoutput a file containing the forces due to the bias evaluated using numerical derivatives and using the analytical derivatives implemented in plumed forces.num --ixyzthe trajectory in xyz format trajectory.xyz
 --plumed specify the name of the plumed input file plumed.dat --timestep the timestep that was used in the calculation that produced this trajectory in picoseconds 1.0 --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) 1 --multi set number of replicas for multi environment (needs MPI) 0 --dump-forces-fmt the format to use to dump the forces %%f

This will produce a file called forces.num. The second column in this file contains the values of the forces calculated analytically. The third column contains the numerical forces.

Storing data for analysis

All the analysis methods described in previous sections accumulate averages or output diagnostic information on the fly. That is to say these methods calculate something given the instantaneous positions of the atoms or the instantaneous values of a set of collective variables. Many methods (e.g. dimensionality reduction and clustering) will not work like this, however, as information from multiple trajectory frames is required at the point when the analysis is performed. In other words the output from these types of analysis cannot be accumulated one frame at time. When using these methods you must therefore store trajectory frames for later analysis using either COLLECT or COLLECT_FRAMES.

Actions

The following actions are part of this module

Name	Description	Tags
ACCUMULATE	Sum the elements of this value over the course of the trajectory	GRIDCALC
AVERAGE	Calculate the ensemble average of a collective variable	GRIDCALC
COLLECT	Collect data from the trajectory for later analysis	ANALYSIS
COMMITTOR	Does a committor analysis.	PRINTANALYSIS
CONSTANT	Create a constant value that can be passed to actions	COLVAR
CREATE_MASK	Create a mask vector to use for landmark selection	DIMRED
DEBUG	Set some debug options.	GENERIC
DUMPATOMS	Dump selected atoms on a file.	PRINTANALYSIS
DUMPDERIVATIVES	Dump the derivatives with respect to the input parameters for scalar values (generally CVs, functions or biases).	PRINTANALYSIS
DUMPFORCES	Dump the force acting on one of a values in a file.	PRINTANALYSIS
DUMPMASSCHARGE	Dump masses and charges on a selected file.	PRINTANALYSIS
DUMPPDB	Output PDB file.	PRINTANALYSIS
DUMPPROJECTIONS	Dump the derivatives with respect to the input parameters for one or more objects (generally CVs, functions or biases).	PRINTANALYSIS
DUMPVECTOR	Print a vector to a file	PRINTANALYSIS
EFFECTIVE_ENERGY_DRIFT	Print the effective energy drift	GENERIC
ENDPLUMED	Terminate plumed input.	GENERIC
FIT_TO_TEMPLATE	This action is used to align a molecule to a template.	GENERIC
FLUSH	This command instructs plumed to flush all the open files with a user specified frequency.	GENERIC
GATHER_REPLICAS	Create a vector that contains the copies of the input quantities from all replicas	ANALYSIS
INCLUDE	Includes an external input file, similar to #include in C preprocessor.	GENERIC
MOLINFO	This command is used to provide information on the molecules that are present in your system.	TOPOLOGY
ONES	Create a constant vector with all elements equal to one	COLVAR
PDB2CONSTANT	Create a constant value from a PDB input file	COLVAR
PLUMED	Embed a separate PLUMED instance.	GENERIC
PRINT	Print quantities to a file.	PRINTANALYSIS
PRINT_NDX	Print an ndx file	PRINTANALYSIS
RANDOM_EXCHANGES	Set random pattern for exchanges.	GENERIC
READ	Read quantities from a colvar file.	GENERIC
READMASSCHARGE	Set the masses and charges from an input PDB file.	COLVAR
RESET_CELL	This action is used to rotate the full cell	GENERIC
TIME	retrieve the time of the simulation to be used elsewhere	GENERIC
UPDATE_IF	Conditional update of other actions.	PRINTANALYSIS
WHOLEMOLECULES	This action is used to rebuild molecules that can become split by the periodic boundary conditions.	GENERIC
WRAPAROUND	Rebuild periodic boundary conditions around chosen atoms.	GENERIC

References

More information about this module is available in the following articles:

G. A. Tribello, M. Bonomi, D. Branduardi, C. Camilloni, G. Bussi, PLUMED 2: New feathers for an old bird. Computer Physics Communications. 185, 604–613 (2014)

Quantity	Type	Description
d1	scalar	the DISTANCE between this pair of atoms