- GB1_native.pdb : A PDB file with the native structure of the GB1 protein.
- traj-whole.xtc: A trajectory in xtc format. To make the exercise easier, GB1 has been made whole already.
- traj-broken.xtc: The same trajectory as it was originally produced by GROMACS. Here GB1 is broken by periodic boundary conditions and should be fixed.
This tutorial has been tested on a pre-release version of PLUMED 2.6. However, it should also work with PLUMED version 2.5.
\section lugano-1-instructions Instructions
PLUMED is a library that can be incorporated into many MD codes by adding a relatively simple and well documented interface.
Once it is incorporated you can use PLUMED to perform a variety of different analyzes on the fly and to bias
the sampling in the molecular dynamics engine. PLUMED can also, however, be used as a standalone code for analyzing trajectories.
If you are using the code in this way you can, once PLUMED is compiled, run the plumed executable by issuing the command:
\verbatim
plumed <instructions>
\endverbatim
Let's start by getting a feel for the range of calculations that we can use PLUMED to perform. Issue the following command now:
\verbatim
plumed --help
\endverbatim
What is output when this command is run is a list of the tasks you can use PLUMED to perform. There are commands that allow you
to patch an MD code, commands that allow you to run molecular dynamics and commands that allow you to build the manual. In this
tutorial we will mostly be using PLUMED to analyze trajectories, however. As such most of the calculations we will perform will be performed
using the driver tool. Let's look at the options we can issue to plumed driver by issuing the following command:
\verbatim
plumed driver --help
\endverbatim
As you can see we can do a number of things with plumed driver. For all of these options, however, we are going to need to write
a PLUMED input file. The syntax of the PLUMED input file is the same that we will use later to run enhanced sampling simulations,
so all the things that you will learn now will be useful later when you will run PLUMED coupled to an MD code.
In the following we are going to see how to write an input file for PLUMED.
\subsection lugano-1-units PLUMED's internal units
By default the PLUMED inputs and outputs quantities in the following units:
- Energy - kJ/mol
- Length - nanometers
- Time - picoseconds
If you want to change these units you can do this using the \ref UNITS keyword.
\section lugano-1-structure The syntax of the PLUMED input file
The main goal of PLUMED is to compute collective variables, which are complex descriptors than can be used
to analyze a conformational change or a chemical reaction. This can be done either on-the-fly during
molecular dynamics or a posteriori, using PLUMED as a post-processing tool.
In both cases one, should create an input file with a specific PLUMED syntax. A sample input file is below:
\plumedfile
# Compute distance between atoms 1 and 10.
# Atoms are ordered as in the trajectory files and their numbering starts from 1.
# The distance is called "d" for future reference.
d: DISTANCE ATOMS=1,10
# Create a virtual atom in the center between atoms 20 and 30.
# The virtual atom only exists within PLUMED and is called "center" for future reference.
center: CENTER ATOMS=20,30
# Compute the torsional angle between atoms 1, 10, 20, and center.
# Notice that virtual atoms can be used as real atoms here.
# The angle is called "phi" for future reference.
phi1: TORSION ATOMS=1,10,20,center
# the same CV defined before can be split into multiple line
TORSION ...
LABEL=phi2
ATOMS=1,10,20,center
...
# Print d every 10 step on a file named "COLVAR1".
PRINT ARG=d STRIDE=10 FILE=COLVAR1
# Print phi1 and phi2 on another file names "COLVAR2" every 100 steps.
PRINT ARG=phi1,phi2 STRIDE=100 FILE=COLVAR2
\endplumedfile
In the input file above, each line defines a so-called action. An action could either compute a distance,
or the center between two or more atoms, or print some value on a file. Each action supports a number of keywords,
whose value is specified. Action names are highlighted in green and, clicking on them, you can go to the
corresponding page in the manual that contains a detailed description for each keyword.
Actions that support the keyword `STRIDE` are those that determine how frequently things are to be done.
Notice that the default value for `STRIDE` is always 1. In the example above, omitting `STRIDE` keywords
the corresponding COLVAR files would have been written for every frame of the analyzed trajectory.
All the other actions in the example above do not
support the `STRIDE` keyword and are only calculated when requested. That is, `d` will be computed
every 10 frames, and `phi1` and `phi2` every 100 frames.
In short, you can think that for every snapshot in the trajectory that you are analyzing PLUMED
is going to execute all the listed actions, though some of them are optimized out when `STRIDE` is different from 1.
Variables should be given a name (in the example above, `d`, `phi1`, and `phi2`), which is
then used to refer to these variables.
Lists of atoms should be provided as
comma separated numbers, with no space. Virtual atoms can be created and assigned a name for later use.
You can find more information on the PLUMED syntax
at \ref Syntax page of the manual. The complete documentation for all the supported
collective variables can be found at the \ref colvarintro page.
\section lugano-1-ex Exercises
\subsection lugano-1-ex-1 Exercise 1: Computing and printing simple collective variables
To analyze the trajectories provided here, you should:
- Create a PLUMED input file with a text editor (let us call it `plumed.dat`) similar to the one above.
- Run the command `plumed driver --mf_xtc traj.xtc --plumed plumed.dat`.
Here `traj.xtc` is the trajectory that you want to analyze. Notice that \ref driver
can read multiple file formats using embedded molfile plugins from VMD (that's where the `mf` letters come from).
Notice that you can also visualize trajectories with VMD directly. Trajectory `traj-whole.xtc` can be visualized with
the command `vmd GB1_native.pdb traj-whole.xtc`.
In this exercise, we will make practice with computing and printing collective variables.
In the previous sections we have seen how we can use PLUMED to calculate distances and how by plotting these distances we can begin to simplify the
high dimensional data contained in a trajectory. Obviously, calculating a \ref DISTANCE is not always the best way to simplify the information contained
in a trajectory and we often find we have to work with other more-complex quantities. PLUMED thus started as a library that was used to gather all the various
implementations people had written for different collective variables (CVs) that people had used to "analyze" trajectories over the years (analyze is in
inverted commas here because, as you will see if you continue to use PLUMED, we use CVs to do much more than simply analyze trajectories).
Now we will not have time to go over all the quantities that can be calculated in this tutorial. Once you understand the basic principles, however, you
should be able to use the manual to work out how to calculate other quantities of interest. With this in mind then lets learn how to calculate
a \ref TORSION. As with \ref DISTANCE the atoms that we specify in our \ref TORSION command can be real or virtual. In the example below two
real atoms and a virtual atom are used:
\verbatim
first: CENTER ATOMS=1-6
last: CENTER ATOMS=251-256
cvtor: TORSION ATOMS=first,102,138,last
PRINT ARG=cvtor STRIDE=1 FILE=COLVAR
ENDPLUMED
\endverbatim
Copy this input to a PLUMED input file and use it to analyze the trajectory you downloaded at the start of this exercise by using the commands
described in section \ref lugano-1-introinput then plot the CV output using gnuplot.
As you can hopefully see calculating \ref TORSION values and other CVs is no more difficult than calculating \ref DISTANCE values. In fact it is
easier as generally when you calculate the torsion angles of a protein you often wish to calculate particular, named torsion angles (i.e. the \f$\phi\f$ and \f$\psi\f$
angles). The \ref MOLINFO command makes it particularly easy to do this. For instance suppose that you want to calculate and print the \f$\phi\f$ angle
in the sixth residue of the protein and the \f$\psi\f$ angle in the eighth residue of the protein. You can do so using the following input:
\verbatim
MOLINFO STRUCTURE=template.pdb
phi6: TORSION ATOMS=@phi-6
psi8: TORSION ATOMS=@psi-8
PRINT ARG=phi6,psi8 FILE=colvar
\endverbatim
Copy this input to a PLUMED input file and use it to analyze the trajectory you downloaded at the start of this exercise by using the commands
described in section \ref lugano-1-introinput then plot the CV output using gnuplot. Notice that you will need the template.pdb file you downloaded
at the start of this exercise in order for this to run.
When calculating many collective variables it is useful to not think in terms of calculating them directly based on the positions of a number of atoms.
It is useful to instead think of them as being calculated from the position of one or more virtual atoms whose positions are generated based on the position
of a collection of other atoms. For example you might want to calculate the distance between the center of masses of two molecules. In this case it is useful
to calculate the two positions of the centers of mass first and to then calculate the distance between the centers of mass. The PLUMED input that you would use
for such a calculation reflects this way of thinking. An example of a PLUMED input that can be used to perform this sort of calculation is shown below:
\verbatim
# geometric center of mass of first residue
first: CENTER ATOMS=1,2,3,4,5,6,7,8
# geometric center of last residue
last: CENTER ATOMS=427-436
d1: DISTANCE ATOMS=first,last
d2: DISTANCE ATOMS=first,last NOPBC
PRINT ARG=d1,d2 STRIDE=1 FILE=COLVAR
ENDPLUMED
\endverbatim
Make a PLUMED input containing the above input and execute it on the trajectory `traj-broken.xtc` by making use of the following command:
Before we turn to analyzing what is output from this calculation there are a few things to note about this input file. Firstly, I should describe what this file
instructs PLUMED to do. It tells PLUMED to:
1. calculate the position of the Virtual Atom 'first' as the \ref CENTER of atoms from 1 to 8;
2. calculate the position of the Virtual Atom 'last' as the \ref CENTER of atoms from 427 to 436;
3. calculate the distance between the two atoms 'first' and 'last' and saves it in 'd1';
4. calculate the distance (ignoring periodic boundary conditions) between the two atoms 'first' and 'last' and saves it in 'd2';
5. print the content of 'd1' and 'd2' in the file COLVAR for every frame of the trajectory
Notice that in the input above we have used two different ways of writing the atoms used in the \ref CENTER calculation:
1. ATOMS=1,2,3,4,5,6,7,8 is the explicit list of the atoms we need
2. ATOMS=427-436 is the range of atoms needed
Notice also that ranges of atoms can be defined with a stride which can also be negative as shown by the commands below, which are both equivalent:
3. ATOMS=from,to:by (i.e.: 427-436:2)
4. ATOMS=to,from:-by (i.e.: 436-427:-2)
Lets now return to the business of analyzing what was output by the calculation. Lets begin by looking at the contents of the COLVAR file that was output.
When you do so you should find that the first few lines of this file read:
\verbatim
#! FIELDS time e2edist comdist
0.000000 2.516315 2.464043
\endverbatim
Lets now plot contents of the COLVAR file so we can compare the behavior of the distance between the
centers of the mass of the two terminal residues in this trajectory, with and without accounting for periodic boundary conditions. To plot this data
issue the following commands:
\verbatim
gnuplot
p 'COLVAR' u 1:2 w l, '' u 1:3 w l
\endverbatim
Given what you observe for the behavior of these two distance what do you now expect to see in the trajectory? Let's look at the trajectory to see if
we are right. To look at the trajectory issue the following commands:
\verbatim
vmd template.pdb trajectory-short.xyz
\endverbatim
\subsection lugano-1-ex-4 Exercise 4: Taking care of periodic boundary conditions
\subsection lugano-1-ex-5 Exercise 5: Using CVs that measure the distance from a reference conformation
\subsection lugano-1-ex-6 Exercise 6: Creating your own CV directly in the PLUMED input file
*/
link: @subpage lugano-1
description: This tutorial explains the syntax of the PLUMED input file and how to use PLUMED to analyze CVs
