Special replica syntax

(this part of the manual is based on trieste-5-replica-special-syntax).

In many cases, we need to run multiple replicas with almost identical PLUMED files. These files might be prepared with cut-and-paste, which is very error prone, or could be set up with some smart bash or python script. Additionally, one can take advantage of the INCLUDE keyword so as to have a shared input file with common definitions and specific input files with replica-dependent keywords. However, as of PLUMED 2.4, we introduced a simpler manner to manipulate multiple replica inputs with tiny differences. Look at the following example:

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

contract shortcuts

#SETTINGS NREPLICAS=3
# Compute a distance
d: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=1,2 The DISTANCE action with label d calculates a single scalar value
# Apply a restraint.
RESTRAINT 
ARG
the values the harmonic restraint acts upon. 
=d 
AT
compulsory keyword 
the position of the restraint 
=@replicas:1.0,1.1,1.2 
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 
=1.0 The RESTRAINT action with label 
# 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

#SETTINGS NREPLICAS=3
# Compute a distance
d: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=1,2 The DISTANCE action with label d calculates a single scalar value
# Apply a restraint.
# 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 the very same input 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 special for RESTRAINT or for 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 [88] 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
d: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=1,2 The DISTANCE action with label d calculates a single scalar value
# Compute a torsional angle
t: TORSION 
ATOMS
the four atoms involved in the torsional angle 
=30,31,32,33 The TORSION action with label t calculates a single scalar value
# Metadynamics.
METAD ...
   
ARG
compulsory keyword 
the labels of the scalars on which the bias will act 
=@replicas:d,t 
   
HEIGHT
the heights of the Gaussian hills. 
=1.0 
   
PACE
compulsory keyword 
the frequency for hill addition 
=100 
   
SIGMA
compulsory keyword 
the widths of the Gaussian hills 
=@replicas:0.1,0.3 
   
GRID_MIN
the lower bounds for the grid 
=@replicas:0.0,-pi 
   
GRID_MAX
the upper bounds for the grid 
=@replicas:2.0,pi 
...The METAD action with label 
# 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 would be a typical setup for a bias exchange simulation. Notice that even though variables d and t are both read in 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 the restraint 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

contract shortcuts

#SETTINGS NREPLICAS=3
# Compute distance between atoms 1 and 2
d: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=10,20 The DISTANCE action with label d calculates a single scalar value
# Compute a torsional angle
t: TORSION 
ATOMS
the four atoms involved in the torsional angle 
=30,31,32,33 The TORSION action with label t calculates a single scalar value
# Apply a restraint:
RESTRAINT ...
   
ARG
the values the harmonic restraint acts upon. 
=d,t 
   
AT
compulsory keyword 
the position of the restraint 
=@replicas:{{1.0,2.0} {3.0,4.0} {5.0,6.0}}  
   
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 
=1.0,3.0 
...The RESTRAINT action with label 
# 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

#SETTINGS NREPLICAS=3
# Compute distance between atoms 1 and 2
d: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=10,20 The DISTANCE action with label d calculates a single scalar value
# Compute a torsional angle
t: TORSION 
ATOMS
the four atoms involved in the torsional angle 
=30,31,32,33 The TORSION action with label t calculates a single scalar value
# Apply a restraint:
# 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 there 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

contract shortcuts

#SETTINGS NREPLICAS=3
d: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=10,20 The DISTANCE action with label d calculates a single scalar value
t: TORSION 
ATOMS
the four atoms involved in the torsional angle 
=30,31,32,33 The TORSION action with label t calculates a single scalar value
RESTRAINT ...
   
ARG
the values the harmonic restraint acts upon. 
=d,t 
   # indentation is not required (this is not python!) 
   # but makes the input easier to read 
   
AT
compulsory keyword 
the position of the restraint 
=@replicas:{ 
     {1.0,2.0} 
     {3.0,4.0} 
     {5.0,6.0} 
   }  
   
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 
=1.0,3.0 
...The RESTRAINT action with label 

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 file, and this is recommended when the number of keywords that are different is large.