Actions

Every command in a PLUMED input file gives the input for an action or a shortcut. The input for an action can all be on a single line as shown 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.x
scalar
the x-component of the vector connecting the two atoms
d1.y
scalar
the y-component of the vector connecting the two atoms
d1.z
scalar
the z-component of the vector connecting the two atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2 COMPONENTS calculate the x, y and z components of the distance separately and store them as label

Alternatively, you can split the input for an action over multiple lines by using a continuation as shown 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.x
scalar
the x-component of the vector connecting the two atoms
d1.y
scalar
the y-component of the vector connecting the two atoms
d1.z
scalar
the z-component of the vector connecting the two atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ...
   ATOMSthe pair of atom that we are calculating the distance between=1,2 
   COMPONENTS calculate the x, y and z components of the distance separately and store them as label
...

Adding comments

If you are an organized sort of person who likes to remember what the hell you were trying to do when you ran a particular simulation you might find it useful to put comments in your input file. In PLUMED you can do this as comments can be added using a # sign. On any given line everything after the # sign is ignored so erm... yes add lines of comments or trailing comments to your hearts content as shown below (using Shakespeare is optional):

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

# This is the distance between two atoms:
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
SnoutThe UPPER_WALLS action with label Snout calculates the following quantities:
 Quantity   
 Type   
 Description  
Snout.bias
scalar
the instantaneous value of the bias potential
Snout.force2
scalar
the instantaneous value of the squared force due to this bias potential: UPPER_WALLSDefines a wall for the value of one or more collective variables, More details ARGthe arguments on which the bias is acting=d1 ATthe positions of the wall=3.0 KAPPAthe force constant for the wall=3.0   # In this same interlude it doth befall.
# That I, one Snout by name, present a wall.

PLUMED ignores any text in comments. Consequently, if you provide the input for an action in a comment like this:

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

# d1: DISTANCE ATOMS=1,2 COMPONENTS

a DISTANCE command is not created. Similar behaviour is observed when you use the ENDPLUMED comand. For example, if your input is as follows:

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.x
scalar
the x-component of the vector connecting the two atoms
d1.y
scalar
the y-component of the vector connecting the two atoms
d1.z
scalar
the z-component of the vector connecting the two atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2 COMPONENTS calculate the x, y and z components of the distance separately and store them as label
ENDPLUMEDTerminate plumed input. More details
d2: DISTANCE ATOMS=3,4

PLUMED will evaluate the distance between atom 1 and 2 but will not evaluate the distance between atoms 3 and 4.

Using INCLUDE files

If, for some reason, you want to spread your PLUMED input over a number of files you can use INCLUDE as shown below:

INCLUDE FILE=filename

So, for example, instead of having a single "plumed.dat" file:

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

DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2 LABELa label for the action so that its output can be referenced in the input to other actions=distThe DISTANCE action with label dist calculates the following quantities:
 Quantity   
 Type   
 Description  
dist
scalar
the DISTANCE between this pair of atoms
RESTRAINTAdds harmonic and/or linear restraints on one or more variables. More details ARGthe values the harmonic restraint acts upon=dist ATthe position of the restraint=2.0 KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=1.0

you can split the input over a file like the one below and a file called extras/toBeIncluded.inc

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

DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2 LABELa label for the action so that its output can be referenced in the input to other actions=distThe DISTANCE action with label dist calculates the following quantities:
 Quantity   
 Type   
 Description  
dist
scalar
the DISTANCE between this pair of atoms
INCLUDEIncludes an external input file, similar to #include in C preprocessor. More details. Show included file FILEfile to be included=extras/toBeIncluded.inc
# The command:
# INCLUDE FILE=extras/toBeIncluded.inc
# ensures PLUMED loads the contents of the file called extras/toBeIncluded.inc
# The contents of this file are shown below (click the red comment to hide them).
The INCLUDE action with label extras/toBeIncluded.inc calculates somethingRESTRAINTAdds harmonic and/or linear restraints on one or more variables. More details ARGthe values the harmonic restraint acts upon=dist ATthe position of the restraint=2.0 KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=1.0
# --- End of included input --- 

However, when you do this it is important to recognize that INCLUDE is a real directive that is only resolved after all the comments have been stripped and the continuation lines have been unrolled. This means it is not possible to do things like:

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

# this is wrong:
DISTANCECalculate the distance/s between pairs of atoms. More details INCLUDE FILE=options.dat
The DISTANCE action with label  calculates the following quantities:
 Quantity   
 Description  
.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=dist ATthe position of the restraint=2.0 KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=1.0

Parallelism

PLUMED uses parallelism to improve the performance of many actions. Within PLUMED parallelisation is done using a combination of MPI and OpenMP. In addition, we are starting to use openACC in some actions in order to write code than can run on GPUs.

Importantly, all parallism within PLUMED is implemented within actions. We do not parallelise over actions. Consequently, if you run this input with MPI or openMP:

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
d2The DISTANCE action with label d2 calculates the following quantities:
 Quantity   
 Type   
 Description  
d2
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=3,4
d3The DISTANCE action with label d3 calculates the following quantities:
 Quantity   
 Type   
 Description  
d3
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=5,6
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=d1,d2,d3 FILEthe name of the file on which to output these quantities=colvar

all the three distances will be calculated on "the same processor/thread." If, however, you run the following input with MPI or openMP:

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

dThe DISTANCE action with label d calculates the following quantities:
 Quantity   
 Type   
 Description  
d
vector
the DISTANCE for each set of specified atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMS1the pair of atom that we are calculating the distance between=1,2 ATOMS2the pair of atom that we are calculating the distance between=3,4 ATOMS3the pair of atom that we are calculating the distance between=5,6
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=d FILEthe name of the file on which to output these quantities=colvar

the three distances are calculated by different processors/threads.

MPI

Unless you disable it by using the option --disable-mpi during configuration, PLUMED will search for an MPI installation during configuration. If an MPI installation is found then PLUMED will build with MPI when you run make. To run a PLUMED driver calculation with MPI you will run a command something like this:

mpirun -npRun instances of PLUMED on this number of MPI processes 4 plumed driveranalyze trajectories with plumed This action has hidden defaults. More details --ixyzthe trajectory in xyz format traj.xyz

mpirun -npRun instances of PLUMED on this number of MPI processes 4 The driver action with label plumed calculates somethingplumed driveranalyze trajectories with plumed This action uses the defaults shown here. More details --ixyzthe trajectory in xyz format traj.xyz
 --plumed specify the name of the plumed input file plumed.dat --timestep the timestep that was used in the calculation that produced this trajectory in picoseconds 1.0 --trajectory-stride the frequency with which frames were output to this trajectory during the simulation (0 means that the number of the step is read from the trajectory file, currently working only for xtc/trr files read with --ixtc/--trr) 1 --multi set number of replicas for multi environment (needs MPI) 0 --dump-forces-fmt the format to use to dump the forces %%f 

When this command is run, any actions that can use MPI will run on four MPI processes.

OpenMP

If your compiler supports openMP then the features of PLUMED that use it have it enabled by default. However, if you want to disable these features you can do so by configuring PLUMED with the option --disable-openmp.

When you use PLUMED with some MD codes the number of OpenMD threads is set automatically by the MD code. If, however, you are using driver, another command line tool or an MD code that does not set the number of OpenMD threads to be used you will need to set the environment variable PLUMED_NUM_THREADS equal to the number of threads you wish PLUMED to use at runtime. To be clear, you can use the PLUMED_NUM_THREADS to set the number of threads to use with PLUMED even if your MD code has an option for setting the number of threads. With gromacs for instance you can ensure that PLUMED runs on 8 threads by using the following commands:

export PLUMED_NUM_THREADS=8
mdrun -plumed

or by using this single command:

mdrun -plumed -ntomp 8

In the first case PLLUMED uses 8 OpenMP threads while gromacs only uses 1 (this is usually sub optimal). In the second case GROMACS and plumed will the same number of OpenMP threads.

Notice that:

• Using OpenMP is likely to improve the performance, but could also slow down the code in some case.
• Using OpenMP can give results that are slightly different because of numerical round off and different order in summations. This should be harmless.
• The optimum number of threads is not necessary "all of them", nor should be equal to the number of threads used to parallelize the MD calculation.
• Not all CVs are parallelized with openMP.
• You might also want to tune the environmental variable PLUMED_CACHELINE_SIZE. The default of 512 is the size of cache lines on your machine. The PLUMED_CACHELINE_SIZE variable is used by PLUMED to decrease the number of threads to be used in each loop so as to avoid clashes in memory access. This variable is expected to affect performance only, not results.