Moving from PLUMED 1 to PLUMED 2

Syntax in PLUMED 2 has been completely redesigned based on our experience using PLUMED 1, hopefully makeing 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:

all:  GROUP     ATOMS=1,5,6,7,9,11,15,16,17,19
rg:   GYRATION  ATOMS=all
t1:   TORSION ATOMS=5,7,9,15
METAD ...
LABEL=meta
ARG=t1 SIGMA=0.1 HEIGHT=0.4 PACE=600
BIASFACTOR=15 TEMP=300
... METAD
t2:   TORSION ATOMS=7,9,15,17
PRINT ARG=t1,t2,meta.bias  STRIDE=100   FILE=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 [22] .

# 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:

g1: COM ATOMS=17,20,22,30
g2: COM ATOMS=37-40
d:  DISTANCE ATOMS=g1,g2
r:  RESTRAINT ARG=d KAPPA=200 AT=1.0
PRINT STRIDE=100 FILE=COLVAR ARG=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

d: DISTANCE ATOMS=1,2
a: ANGLE    ATOMS=3,4,5
PRINT ARG=d,a FILE=COLVAR STRIDE=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 the personalization of 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 syntaxes 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 currently missing 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 (5 membered rings only) 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