Parsing - PLUMED manual

Parsing action input

The input to any PLUMED action consists of a series of keyword value pairs and flags that turn on or off various options.
In the example input below:

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 NOPBC ignore the periodic boundary conditions when calculating distances

d1 is the action's label and DISTANCE is the action's name. The input to the action is then the keyword value pair ATOMS and the flag NOPBC. Every example input you encounter in this manual, in the nest and the tutorials has tooltips that explain what options are turned on by flags and what the values provided in each keyword pair represents. You will also find details of all the keywords and flags that are available for an action on the manual page for that action.

By default the following units are used when reading the parameters that are specified using keywords.

Quantity	Unit
Length	nm
Energy	kj/mol
Time	ps
Mass	amu
Charge	e

These are also the units in any output files. If you would like to change these units you can use the UNITS command.

Writing input files

If you edit your PLUMED input files using VIM you can add the following to the .vimrc file:

" Enable syntax
:syntax on
" This allows including the proper PLUMED syntax file:
:let &runtimepath.=','.$PLUMED_VIMPATH
" The former command requires PLUMED_VIMPATH to be set. Alternatively, use this:
" let &runtimepath.=',/usr/local/lib/plumed/vim'
" properly adjusted to the path where PLUMED is installed.
" This makes autocompletion work in the expected way:
:set completeopt=longest,menuone
" This enables bindings of F2/F3/F4 to plumed specific commands:
:let plumed_shortcuts=1

Then when you open a PLUMED input file, you can enable syntax highlighting with:

:set ft=plumed

You can read more about the features that are available in vim for working with PLUMED input files here.

Reading constants

In the input to keywords that read real numbers you can use constants that are specified using strings rather than numbers. An example is the following

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

#SETTINGS MOLFILE=extras/AA.pdb
MOLINFOThis command is used to provide information on the molecules that are present in your system. More details STRUCTUREa file in pdb format containing a reference structure=extras/AA.pdb Click here to see an extract from this file.
    ×  FILE: extras/AA.pdb
    TITLE     Great Red Owns Many ACres of Sand 
REMARK    THIS IS A SIMULATION BOX
CRYST1    6.958   11.030   10.714  90.00  90.00  90.00 P 1           1
MODEL        1
ATOM     1   H5T   A     1      14.820  -3.670   5.260  1.00  0.00            
...
ATOM     63 2HO'   A     2      13.980   7.360   7.150  1.00  0.00            
ATOM     64  O3'   A     2      13.300   5.500   8.180  1.00  0.00            
ATOM     65  H3T   A     2      12.360   5.840   8.100  1.00  0.00            
TER
ENDMDL
  
  MOLTYPE what kind of molecule is contained in the pdb file - usually not needed since protein/RNA/DNA are compatible=rna
The MOLINFO action with label  calculates somethinge1The TORSION action with label e1 calculates the following quantities: Quantity    Type    Description  
e1 scalar the TORSION involving these atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=@epsilon-1the four atoms that are required to calculate the backbone epsilon dihedral for residue 1. Click here for more information. 
tThe METAD action with label t calculates the following quantities: Quantity    Type    Description  
t.bias scalar the instantaneous value of the bias potential: METADUsed to performed metadynamics on one or more collective variables. This action has hidden defaults. More details ARGthe labels of the scalars on which the bias will act=e1 SIGMAthe widths of the Gaussian hills=0.15 PACEthe frequency for hill addition=10 HEIGHTthe heights of the Gaussian hills=2 GRID_MINthe lower bounds for the grid=-pi GRID_MAXthe upper bounds for the grid=pi GRID_BINthe number of bins for the grid=200
t: METADUsed to performed metadynamics on one or more collective variables. This action uses the defaults shown here. More details ARGthe labels of the scalars on which the bias will act=e1 SIGMAthe widths of the Gaussian hills=0.15 PACEthe frequency for hill addition=10 HEIGHTthe heights of the Gaussian hills=2 GRID_MINthe lower bounds for the grid=-pi GRID_MAXthe upper bounds for the grid=pi GRID_BINthe number of bins for the grid=200  FILE a file in which the list of added hills is stored=HILLS

Notice here that the boundaries for GRID_MIN and GRID_MAX are -pi and pi.

Any real numbers that are read in from input are interpretted using the [Lepton library] that is described in the documtation for the CUSTOM action. You can thus employ complicated expressions such as 1+2 or exp(10) as shown in the in the input as shown below:

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

#SETTINGS MOLFILE=extras/AA.pdb
MOLINFOThis command is used to provide information on the molecules that are present in your system. More details STRUCTUREa file in pdb format containing a reference structure=extras/AA.pdb Click here to see an extract from this file.
    ×  FILE: extras/AA.pdb
    TITLE     Great Red Owns Many ACres of Sand 
REMARK    THIS IS A SIMULATION BOX
CRYST1    6.958   11.030   10.714  90.00  90.00  90.00 P 1           1
MODEL        1
ATOM     1   H5T   A     1      14.820  -3.670   5.260  1.00  0.00            
...
ATOM     63 2HO'   A     2      13.980   7.360   7.150  1.00  0.00            
ATOM     64  O3'   A     2      13.300   5.500   8.180  1.00  0.00            
ATOM     65  H3T   A     2      12.360   5.840   8.100  1.00  0.00            
TER
ENDMDL
  
  MOLTYPE what kind of molecule is contained in the pdb file - usually not needed since protein/RNA/DNA are compatible=rna
The MOLINFO action with label  calculates somethinge1The TORSION action with label e1 calculates the following quantities: Quantity    Type    Description  
e1 scalar the TORSION involving these atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=@epsilon-1the four atoms that are required to calculate the backbone epsilon dihedral for residue 1. Click here for more information. 
RESTRAINTAdds harmonic and/or linear restraints on one or more variables. More details ARGthe values the harmonic restraint acts upon=e1 ATthe position of the restraint=1+0.5

You can also also write expressions in terms of any of the following constants:

Symbol	Description
`e`	Euler's number - the base for the natural logarithm
`log2e`	$1 / \log(2)$
`log10e`	$1 / \log(10)$
`ln2`	$\log(2)$
`ln10`	$\log(10)$
`pi`	the circle constant $\pi$
`pi_2`	$\pi / 2$
`pi_4`	$\pi / 4$
`sqrt2`	$\sqrt(2)$
`sqrt1_2`	$\sqrt(0.5)$

Notice that this functionality cannot be used when the keyword takes integer numbers in input (e.g.: the PACE argument for METAD).

Special replica syntax

PLUMED provides a number of ways to prepare the multiple replicas with almost identical PLUMED files that are required to run a multiple replica simulation:

You can repare input files for such calculation using cut-and-paste but that is is very error prone.
You can write a smart bash or python script to generate all the inputs.
You can use different inputs for the various replicas that all contain an INCLUDE directive to include a file that contains the parts of the input that are common to all replicas

We think, however, the best option is to use features that have been available from PLUMED 2.4 onwards that allow you manipulate multiple replica inputs that have only tiny differences in the the input. The following example illustrates how the syntax for this option operates:

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

#SETTINGS NREPLICAS=3
# Compute a distance
d: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2

# Apply a restraint.
The DISTANCE action with label d calculates the following quantities: Quantity    Description  
d.value the DISTANCE between this pair of atomsRESTRAINTAdds harmonic and/or linear restraints on one or more variables. More details ARGthe values the harmonic restraint acts upon=d ATthe position of the restraint=@replicas:This keyword specifies that different replicas have different values for this quantity.  See here for more details.1.0,1.1,1.2 KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=1.0
# On replica 0, this means:
#   RESTRAINT ARG=d AT=1.0 KAPPA=1.0
# On replica 1, this means:
#   RESTRAINT ARG=d AT=1.1 KAPPA=1.0
# On replica 2, this means:
#   RESTRAINT ARG=d AT=1.2 KAPPA=1.0

If you prepare a single plumed.dat file like this one and feeds it to PLUMED while using 3 replicas, the 3 replicas will see PLUMED input files that are the same except for the AT keyword, that sets the position of the restraint. Replica 0 will see a restraint centered at 1.0, replica 1 centered at 1.1, and replica 2 centered at 1.2.

The @replicas: keyword is not specific to RESTRAINT and the AT keyword. Any keyword in PLUMED can accept that syntax. For instance, the following single input file can be used to setup a bias exchange metadynamics simulations:

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

#SETTINGS NREPLICAS=2 
# Compute distance between atoms 1 and 2
dThe DISTANCE action with label d calculates the following quantities: Quantity    Type    Description  
d 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

# Compute a torsional angle 
tThe TORSION action with label t calculates the following quantities: Quantity    Type    Description  
t scalar the TORSION involving these atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=30,31,32,33

# Metadynamics.
METADUsed to performed metadynamics on one or more collective variables. More details ...
  ARGthe labels of the scalars on which the bias will act=@replicas:This keyword specifies that different replicas have different values for this quantity.  See here for more details.d,t
  HEIGHTthe heights of the Gaussian hills=1.0
  PACEthe frequency for hill addition=100
  SIGMAthe widths of the Gaussian hills=@replicas:This keyword specifies that different replicas have different values for this quantity.  See here for more details.0.1,0.3
  GRID_MINthe lower bounds for the grid=@replicas:This keyword specifies that different replicas have different values for this quantity.  See here for more details.0.0,-pi
  GRID_MAXthe upper bounds for the grid=@replicas:This keyword specifies that different replicas have different values for this quantity.  See here for more details.2.0,pi
...
# On replica 0, this means:
#  METAD ARG=d HEIGHT=1.0 PACE=100 SIGMA=0.1 GRID_MIN=0.0 GRID_MAX=2.0
# On replica 1, this means:
#  METAD ARG=t HEIGHT=1.0 PACE=100 SIGMA=0.3 GRID_MIN=-pi GRID_MAX=pi

This input contains a typical setup for a bias exchange simulation. Notice that even though the actions with labels d and t are read for both replicas, d is only computed on replica 0 (and t is only computed on replica 1). This is because variables that are defined but not used are never actually calculated by PLUMED.

If the value that should be provided for each replica is a vector, you should use curly braces as delimiters. For instance, if you have a restraint that acts on two variables, you can use the following input:

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

#SETTINGS NREPLICAS=3
# Compute distance between atoms 1 and 2
d: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=10,20

# Compute a torsional angle
The DISTANCE action with label d calculates the following quantities: Quantity    Description  
d.value the DISTANCE between this pair of atomst: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=30,31,32,33

# Apply a restraint:
The TORSION action with label t calculates the following quantities: Quantity    Description  
t.value the TORSION involving these atomsRESTRAINTAdds harmonic and/or linear restraints on one or more variables. More details ...
 ARGthe values the harmonic restraint acts upon=d,t
 ATthe position of the restraint=@replicas:This keyword specifies that different replicas have different values for this quantity.  See here for more details.{{1.0,2.0} {3.0,4.0} {5.0,6.0}}
 KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=1.0,3.0
...
# On replica 0 this means:
#  RESTRAINT ARG=d AT=1.0,2.0 KAPPA=1.0,3.0
# On replica 1 this means:
#  RESTRAINT ARG=d AT=3.0,4.0 KAPPA=1.0,3.0
# On replica 2 this means:
#  RESTRAINT ARG=d AT=5.0,6.0 KAPPA=1.0,3.0

Notice the double curly braces. The outer ones are used by PLUMED to know where the argument of the AT keyword ends, whereas the inner ones are used to group the values corresponding to each replica. Also notice that the last example can be split in multiple lines exploiting the fact that within multi-line statements (enclosed by pairs of ...) newlines are replaced with simple spaces:

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

#SETTINGS NREPLICAS=3
dThe DISTANCE action with label d calculates the following quantities: Quantity    Type    Description  
d 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=10,20
tThe TORSION action with label t calculates the following quantities: Quantity    Type    Description  
t scalar the TORSION involving these atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=30,31,32,33
RESTRAINTAdds harmonic and/or linear restraints on one or more variables. More details ...
 ARGthe values the harmonic restraint acts upon=d,t
# indentation is not required (this is not python!)
# but makes the input easier to read
 ATthe position of the restraint=@replicas:This keyword specifies that different replicas have different values for this quantity.  See here for more details.{
   {1.0,2.0}
   {3.0,4.0}
   {5.0,6.0}
 }
 KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=1.0,3.0
...

In short, whenever there are keywords that should vary across replicas, you should set them using the @replicas: keyword. As mentioned above, you can always use the old syntax with separate input files and this is fact recommended when the differences in the inputs for the various replicas are substantial.

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

Quantity	Type	Description
t	scalar	the TORSION involving these atoms

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

Quantity	Type	Description
t	scalar	the TORSION involving these atoms

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

Quantity	Description
d.value	the DISTANCE between this pair of atoms

Quantity	Description
t.value	the TORSION involving these atoms