 |
 |
 |
PLUMED is a plugin that works with a large number of molecular dynamics codes. It can be used to analyse features of the dynamics on-the-fly or to perform a wide variety of free energy methods. The original PLUMED 1 [plumed1] was highly successful and had over 1000 users. PLUMED 2 [14] constitues an extensive rewrite of the original in a way that makes it more modular and thus easier to implement new methods, more straightforward to add it to MD codes and hopefully simpler to use. This is the user manual - if you want to modify PLUMED or to understand how it works internally, have a look at the developer manual .
To understand the difference between PLUMED 1 and PLUMED 2, and to follow the development of PLUMED 2, you can look at the detailed changelog:
A short tutorial explaining how to move from PLUMED 1 to PLUMED 2 is also available (see Moving from Plumed 1 to Plumed 2)
To install PLUMED 2, see this page: Installation
To run PLUMED 2 you need to provide one input file. In this file you specify what it is that PLUMED should do during the course of the run. Typically this will involve calculating one or more collective variables, perhaps calculating a function of these CVs and then doing some analysis of values of your collective variables/functions or running some free energy method. A very brief introduction to the syntax used in the PLUMED input file is provided in this 10-minute video .
More information on the input syntax as well as details on the the various trajectory analsyis tools that come with PLUMED are given in:
PLUMED can be used in one of two ways. It can be incorporated into any one of the MD codes listed on the Installation page and used to analyse or bias a molecular dynamics run on the fly. Alternatively, one can use it as a standalone tool for postprocessing the results from molecular dynamics or enhanced sampling calculations. To use PLUMED in this second way you will issue a command something like:
plumed <toolname> <list of input flags for that tool>
The following is a list of the various standalone tools that PLUMED contains.
| driver | driver is a tool that allows one to to use plumed to post-process an existing trajectory. |
| gentemplate | gentemplate is a tool that you can use to construct template inputs for the various actions |
| info | This tool allows you to obtain information about your plumed version |
| manual | manual is a tool that you can use to construct the manual page for a particular action |
| simplemd | simplemd allows one to do molecular dynamics on systems of Lennard-Jones atoms. |
| sum_hills | sum_hills is a tool that allows one to to use plumed to post-process an existing hills/colvar file |
For all these tools and to use PLUMED as a plugin in an MD calculation you will need an input file. Within this input file every line is an instruction for PLUMED to perform some particular action. This could be the calculation of a colvar, an occasional analysis of the trajectory or a biassing of the dynamics. The first word in these lines specify what particular action is to be performed. This is then followed by a number of keywords which provide PLUMED with more details as to how the action is to be performed. These keywords are either single words (in which they tell PLUMED to do the calculation in a particular way - for example NOPBC tells PLUMED to not use the periodic bounadry conditions when calculating a particular colvar) or they can be words followed by an equals sign and a comma separated list - WITH NO SPACES - of numbers or characters (so for example ATOMS=1,2,3,4 tells PLUMED to use atom numbers 1,2,3 and 4 in the calculation of a particular colvar). Space separated lists can be used instead of commma separated list if the entire list is enclosed in curly braces (e.g. ATOMS={1 2 3 4}).
The most important of these keywords is the label keyword as it is only by using these labels that we can pass data from one action to another. As an example if you do:
DISTANCE ATOMS=1,2
(see DISTANCE)
Then PLUMED will do nothing other than read in your input file. In contrast if you do:
DISTANCE ATOMS=1,2 LABEL=d1 PRINT ARG=d1 FILE=colvar STRIDE=10
(see PRINT)
then PLUMED will print out the value of the distance between atoms 1 and 2 every 10 steps to the file colvar as you have told PLUMED to take the value calculated by the action d1 and to print it. Notice that if a word followed by a column is added at the beginning of the line (e.g. pippo:), PLUMED automatically removes it and adds an equivalent label (LABEL=pippo). Thus, a completely equivalent result can be obtained with the following shortcut:
d1: DISTANCE ATOMS=1,2 PRINT ARG=d1 FILE=colvar STRIDE=10
Also notice that all the actions can be labeled, and that many actions besides normal collective variables can define one or more value, which can be then referred using the corresponding label.
Actions can be referred also with POSIX regular expressions (see Regular Expressions). For this you need to compile PLUMED with the appropriate flag.
By default the PLUMED inputs and outputs quantities in the following units:
Unlike PLUMED 1 the units used are independent of the MD engine you are using. If you want to change these units you can do this using the UNITS keyword.
Those are the essentials but there are a few other tricks that we didn't know where else to put in the manual so we stuck them here.
If you are an organised 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):
# This is the distance between two atoms: DISTANCE ATOM=1,2 LABEL=d1 UPPER_WALLS ARG=d1 AT=3.0 KAPPA=3.0 LABEL=Snout # In this same interlude it doth befall. That I, one Snout by name, present a wall.
(see DISTANCE and UPPER_WALLS)
An alternative to including comments in this way is to use line starting ENDPLUMED. Everything in the PLUMED input after this keyword will be ignored.
If your input lines get very long then editing them using vi and other such text editors becomes a massive pain in the arse. We at PLUMED are aware of this fact and thus have provided a way of doing line continuations so as to make your life that much easier - aren't we kind? Well no not really, we have to use this code too. Anyway, you can do continuations by using the "..." syntax as this makes this:
DISTANCES ATOMS1=1,300 ATOMS2=1,400 ATOMS3=1,500
(see DISTANCES)
equivalent to this:
DISTANCES ... # we can also insert comments here ATOMS1=1,300 # multiple kewords per line are allowed ATOMS2=1,400 ATOMS3=1,500 #empty lines are also allowed ... DISTANCES
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, a single "plumed.dat" file:
DISTANCE ATOMS=0,1 LABEL=dist RESTRAINT ARG=dist
could be split up into two files as shown below:
DISTANCE ATOMS=0,1 LABEL=dist INCLUDE FILE=toBeIncluded.dat
plus a "toBeIncluded.dat" file
RESTRAINT ARG=dist
However, when you do this it is important to recognise 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:
# this is wrong: DISTANCE INCLUDE FILE=options.dat RESTRAINT ARG=dist
You can introduce new functionality into PLUMED by placing it directly into the src directory and recompiling the PLUMED libraries. Alternatively, if you want to keep your code independent from the rest of PLUMED (perhaps so you can release it independely - we won't be offended), then you can create your own dynamic library. To use this in conjuction with PLUMED you can then load it at runtime by using the LOAD keyword as shown below:
LOAD FILE=library.so
N.B. If your system uses a different suffix for dynamic libraries (e.g. macs use .dylib) then PLUMED will try to automatically adjust the suffix accordingly.
The DEBUG action provides some functionality for debugging the code that may be useful if you are doing very intensive development of the code of if you are running on a computer with a strange architecture.
Hosted by GitHub
|
1.8.8
|
