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.
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 [45] .
In PLUMED 1 groups (lists) were used for two tasks:
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.
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.
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.
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 | 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 |