Moving from PLUMED 1 to PLUMED 2

Syntax in PLUMED 2 has been completely redesigned based on our experience using PLUMED 1, hopefully making it clearer, more flexible, and less error prone. The main difference is that whereas in PLUMED 1 lines could be inserted in any order, in PLUMED 2 the order of the lines matters. This is due to a major change in the internal architecture of PLUMED. In version 2, commands (or "actions") are executed in the order they are found in the input file. Because of this, you must e.g. first compute a collective variable and then print it later. More information can be found in the Section about Getting Started.

Other important changes are in the way groups and units are used, as discussed below. Finally, many features appear under a different name in the new version.

New syntax

We know that changing the input syntax requires a lot of work from the user side to update their input files. However, we believe that the new syntax is easier to read and that it allows for more flexibility. As an example, something that in PLUMED 1.3 was:

HILLS HEIGHT 0.4 W_STRIDE 600
WELLTEMPERED SIMTEMP 300  BIASFACTOR 15
RGYR LIST <all>
all->
1   5  6  7   9  11  15  16  17 19
all<-
TORSION LIST 5 7 9 15 SIGMA  0.1
TORSION LIST 7 9 15 17
PRINT W_STRIDE 100

in PLUMED 2.x becomes:

Click on the labels of the actions for more information on what each action computes
tested on v2.9
all: GROUP 
ATOMS
the numerical indexes for the set of atoms in the group.
=1,5,6,7,9,11,15,16,17,19 rg: GYRATION
ATOMS
the group of atoms that you are calculating the Gyration Tensor for.
=all t1: TORSION
ATOMS
the four atoms involved in the torsional angle
=5,7,9,15 meta: METAD ...
ARG
the input for this action is the scalar output from one or more other actions.
=t1
SIGMA
compulsory keyword the widths of the Gaussian hills
=0.1
HEIGHT
the heights of the Gaussian hills.
=0.4
PACE
compulsory keyword the frequency for hill addition
=600
BIASFACTOR
use well tempered metadynamics and use this bias factor.
=15
TEMP
the system temperature - this is only needed if you are doing well-tempered metadynamics
=300 ... t2: TORSION
ATOMS
the four atoms involved in the torsional angle
=7,9,15,17 PRINT
ARG
the input for this action is the scalar output from one or more other actions.
=t1,t2,meta.bias
STRIDE
compulsory keyword ( default=1 ) the frequency with which the quantities of interest should be output
=100
FILE
the name of the file on which to output these quantities
=COLVAR

Giving all quantities an explicit name makes the input easier to interpret. Additionally, all the parameters related to METAD are placed on a single line (actually, this is done here exploiting continuation lines). Also notice that one can customize the name of the COLVAR file. By specifying to PRINT which collective variables should be printed, one can easily decide what to print exactly and using which stride. By repeating the PRINT line one can also monitor very expensive variables with a larger stride, just putting the result on a separate file.

You might have noticed that ideas that were very difficult to implement in PLUMED 1.3 now become immediately available. As an example, one can now apply concurrently several METAD potentials [58] .

Groups

In PLUMED 1 groups (lists) were used for two tasks:

  • To provide centers of masses to collective variables such as distances, angles, etc. This is now done by defining virtual atoms using either CENTER or COM
  • To provide lists of atoms to collective variables such as coordination, gyration radius, etc. This is now done directly in the line that defines the collective variable.

If you would still like to use groups you can use the GROUP commands. Whenever the label for a GROUP action appears in the input it is replaced by the list of atoms that were specified in the GROUP.

A restraint on the distance between centers of mass in PLUMED 1 was something like:

DISTANCE LIST <g1> <g2>
g1->
17 20 22 30
g1<-
g2->
LOOP 37 40
g2<-
UMBRELLA CV 1 KAPPA 200 AT 1.0
PRINT W_STRIDE 100

The same in PLUMED 2.x reads:

Click on the labels of the actions for more information on what each action computes
tested on v2.9
g1: COM 
ATOMS
the list of atoms which are involved the virtual atom's definition.
=17,20,22,30 g2: COM
ATOMS
the list of atoms which are involved the virtual atom's definition.
=37-40 d: DISTANCE
ATOMS
the pair of atom that we are calculating the distance between.
=g1,g2 r: RESTRAINT
ARG
the input for this action is the scalar output from one or more other actions.
=d
KAPPA
compulsory keyword ( default=0.0 ) specifies that the restraint is harmonic and what the values of the force constants on each of the variables are
=200
AT
compulsory keyword the position of the restraint
=1.0 PRINT
STRIDE
compulsory keyword ( default=1 ) the frequency with which the quantities of interest should be output
=100
FILE
the name of the file on which to output these quantities
=COLVAR
ARG
the input for this action is the scalar output from one or more other actions.
=d,r.*

Notice that virtual atoms are very powerful tools in PLUMED 2. Actually, they can be used in any collective variable where normal atoms can be used, just by calling them by name. This allows to straightforwardly define variables such as coordination between centers of mass, which would have required an ad hoc implementation in PLUMED 1.

In the example above you can also appreciate the advantage of calling collective variables by name. It is obvious here that RESTRAINT is acting on distance d, whereas in PLUMED 1 one had to keep track of the number of the collective variables. This was easy for a single collective variable, but could become cumbersome for complex input files.

Names in output files

Another advantage of having names is that when PLUMED produces an output file it can insert explicit names in the file. Consider for example this PLUMED 1 input

DISTANCE LIST 1 2
ANGLE    LIST 3 4 5
PRINT W_STRIDE 100

The first line of the COLVAR file was then

#!  FIELDS time cv1 cv2

The equivalent input file in PLUMED 2 is

Click on the labels of the actions for more information on what each action computes
tested on v2.9
d: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between.
=1,2 a: ANGLE
ATOMS
the list of atoms involved in this collective variable (either 3 or 4 atoms).
=3,4,5 PRINT
ARG
the input for this action is the scalar output from one or more other actions.
=d,a
FILE
the name of the file on which to output these quantities
=COLVAR
STRIDE
compulsory keyword ( default=1 ) the frequency with which the quantities of interest should be output
=100

The first line of the COLVAR file now is

#! FIELDS time d a

This makes it easy to remember what's the meaning of each column of the COLVAR file without the need to always go back to the PLUMED input to check in which order the variables were declared.

Units

In PLUMED 1 the input file of PLUMED was expected to be written using the same units of the MD code. This choice was made to allow users to adopt the same units they were used to. However, we realized later that this choice was not allowing the PLUMED input files to be ported between different MD code. Let's say that one was using this keyword with GROMACS (kj/mol - nm)

UMBRELLA CV 1 KAPPA 200 AT 1.0

Let's assume the variable CV 1 was a distance. The same keyword in NAMD (kcal/mol - A) should have been converted to

UMBRELLA CV 1 KAPPA .4780 AT 10.0

The conversion of AT is straightforward (1nm=10A), but the conversion on KAPPA is more error prone. This is because KAPPA is measured in units of energy divided by distance squared. Notice that a different factor should have been used if the CV was an angle.

Learning from this, we designed PLUMED 2 in a way that units in the PLUMED input are independent of the MD code. Technically, this is achieved by doing the conversion when coordinates and forces are passed back and forth. In this way, the same PLUMED input could be used with GROMACS and NAMD.

We decided to use as standard units in PLUMED kj/mol, nm, and ps. Perhaps this is because most of the developers are using GROMACS, which also adopts these units. However, we still allow users to change units by means of the UNITS keyword. Since this keyword is included directly in the PLUMED input file, even when using personalized units the input files remains perfectly portable across different MD engines.

Directives

What follows is a list of all the documented directives of PLUMED 1 together with their plumed 2 equivalents. Be aware that the input syntax for these directives are not totally equivalent. You should read the documentation for the PLUMED 2 Action.

HILLS METAD
WELLTEMPERED METAD with BIASFACTOR
GRID METAD with GRID_MIN, GRID_MAX, and GRID_BIN
WRITE_GRID METAD with GRID_WFILE, GRID_WSTRIDE
READ_GRID METAD with GRID_RFILE
MULTIPLE_WALKERS METAD with options WALKERS_ID, WALKERS_N, WALKERS_DIR, and WALKERS_RSTRIDE
NOHILLS not needed (collective variables are not biased by default)
INTERVAL METAD with INTERVAL
INVERT currently missing
PTMETAD not needed (replica exchange detected from MD engine)
BIASXMD not needed (replica exchange detected from MD engine); one should anyway use RANDOM_EXCHANGES to get the normal behavior
UMBRELLA RESTRAINT
STEER MOVINGRESTRAINT
STEERPLAN MOVINGRESTRAINT
ABMD ABMD
UWALL UPPER_WALLS
LWALL LOWER_WALLS
EXTERNAL EXTERNAL
COMMITMENT COMMITTOR
PROJ_GRAD DUMPPROJECTIONS
DAFED a similar method using a Langevin thermostat, with EXTENDED_LAGRANGIAN
DISTANCE DISTANCE - POINT_FROM_AXIS and PROJ_ON_AXIS can be reproduced with DISTANCE and MATHEVAL
POSITION POSITION
MINDIST DISTANCES with keyword MIN
ANGLE ANGLE
TORSION TORSION
COORD COORDINATION
HBOND currently missing , can be emulated with COORDINATION
WATERBRIDGE BRIDGE
RGYR GYRATION
DIPOLE DIPOLE
DIHCOR DIHCOR
ALPHABETA ALPHABETA
ALPHARMSD ALPHARMSD
ANTIBETARMSD ANTIBETARMSD
PARABETARMSD PARABETARMSD
ELSTPOT currently missing, but a related quantity can be obtained with DHENERGY
PUCKERING PUCKERING
S_PATH PATHMSD, s component
Z_PATH PATHMSD, z component
TARGETED RMSD
ENERGY ENERGY
HELIX currently missing
PCA PCARMSD
SPRINT SPRINT
RDF DISTANCES, used in combination with HISTOGRAM / BETWEEN keyword
ADF ANGLES, used in combination with HISTOGRAM / BETWEEN keyword
POLY COMBINE
FUNCTION MATHEVAL
ALIGN_ATOMS WHOLEMOLECULES