All Pages

In this page you can learn how to configure, compile, and install PLUMED. For those of you who are impatient, the following might do the job:

> ./configure --prefix=/usr/local
> make -j 4
> make doc # this is optional and requires proper doxygen version installed
> make install

Notice that make install is not strictly necessary as plumed can be used from the compilation directory. This is very useful so as to quickly test the implementation of new features. However, we strongly recommend to perform a full install.

Once the above is completed the plumed executable should be in your execution path and you will be able to use PLUMED to analyze existing trajectories or play with the Lennard-Jones code that is included. However, because PLUMED is mostly used to bias on the fly simulations performed with serious molecular dynamics packages, you can find instructions about how to patch your favorite MD code so that it can be combined with PLUMED below. Again, if you are impatient, something like this will do the job:

> cd /md/root/dir
> plumed patch -p

Then compile your MD code. For some MD codes these instructions are insufficient. It is thus recommended that you read the instructions at the end of this page. Notice that MD codes could in principle be "PLUMED ready" in their official distribution. If your favorite MD code is available "PLUMED ready" you will have to compile PLUMED first, then (optionally) install it, then check the MD codes' manual to discover how to link it.

Configuring PLUMED

The "./configure" command just generates a Makefile.conf file and a file. In PLUMED 2.0 these files were pre-prepared and stored in the directory configurations/. The new ones generated by ./configure should be compatible with the old ones. In other words, if you have difficulties with the new procedure, you can use one of these old configuration files. However, it should be easy to enforce a similar setup on autoconf by passing the proper arguments on the command line. We strongly encourage you to configure plumed in this way. If you have problems on your architecture, please report them to the mailing list.

Useful command line options for ./configure can be found by typing

> ./configure --help

Notice that some functionalities of PLUMED depend on external libraries which are looked for by configure. You can typically avoid looking for a library using the "disable" syntax, e.g.

> ./configure --disable-mpi --disable-matheval

Notice that when mpi search is enabled (by default) compilers such as "mpic++" and "mpicxx" are searched for first. On the other hand, if mpi search is disabled ("./configure --disable-mpi") non-mpi compilers are searched for. Notice that only a few of the possible compiler name are searched. Thus, compilers such as "g++-mp-4.8" should be explicitly requested with the CXX option.

You can better control which compiler is used by setting the variables CXX and CC. E.g., to use Intel compilers use the following command:

> ./configure CXX=icpc CC=icc

Notice that we are using icpc in this example, which is not an mpi compiler as a result mpi will not be enabled. Also consider that this is different with respect to what some other configure script does in that variables such as MPICXX are completely ignored here. In case you work on a machine where CXX is set to a serial compiler and MPICXX to a MPI compiler, to compile with MPI you should use

> ./configure CXX="$MPICXX"

To tune the compilation options you can use the CXXFLAGS variable:

> ./configure CXXFLAGS=-O3

If you are implementing new functionality and want to build with debug flags in place so as to do some checking you can use

> ./configure --enable-debug

This will perform some extra check during execution (possibly slowing down PLUMED) and write full symbol tables in the executable (making the final executable much larger).

The main goal of the automatic configure is to find the libraries. When they are stored in unconventional places it is thus sensible to tell autoconf where to look! To do this there are some environment variable that can be used to instruct the linker which directories it should search for libraries inside. These variables are compiler dependent, but could have been set by the system administrator so that libraries are found without any extra flag. Our suggested procedure is to first try to configure without any additional flags and to then check the log so as to see whether or not the libraries were properly detected.

If a library is not found during configuration, you can try to use options to modify the search path. For example if your matheval libraries is in /opt/local (this is where MacPorts put it) and configure is not able to find it you can try

> ./configure LDFLAGS=-L/opt/local/lib CPPFLAGS=-I/opt/local/include

Notice that PLUMED will first try to link a routine from say matheval without any additional flag, and then in case of failure will retry adding "-lmatheval" to the LIBS options. If also this does not work, the matheval library will be disabled and some features will not be available. This procedure allows you to use libraries with custom names. So, if your matheval library is called /opt/local/lib/ you can link it with

> ./configure LDFLAGS=-L/opt/local/lib CPPFLAGS=-I/opt/local/include LIBS=-lmymatheval

In this example, the linker will directly try to link /opt/local/lib/ This rule is true for all the libraries, so that you will always be able to link a specific version of a library by specifying it using the LIBS variable.

On Linux you might have problems using the LDFLAGS option. In particular, if makefile complaints that it cannot link the file 'src/lib/plumed-shared', try to set correctly the runtime path by using
> ./configure LDFLAGS="-L/opt/local/lib -Wl,-rpath,/opt/local/lib" \
  CPPFLAGS=-I/opt/local/include LIBS=-lmymatheval
Notice that although the file 'src/lib/plumed-shared' is not necessary, being able to produce it means that it will be possible to link PLUMED dynamically with MD codes later.

PLUMED needs blas and lapack. These are treated slighty different from other libraries. The search is done in the usual way (i.e., first look for them without any link flag, then add "-lblas" and "-llapack", respectively). As such if you want to use a specific version of blas or lapack you can make them available to configure by using

> ./configure LDFLAGS=-L/path/to/blas/lib LIBS=-lnameoflib

If the functions of these libraries are not found, the compiler looks for a version with a final underscore added. Finally, since blas and lapack are compulsory in PLUMED, you can use a internal version of these libraries that comes as part of PLUMED. If all else fails the internal version of BLAS and LAPACK are the ones that will be used by PLUMED. If you wish to disable any search for external libraries (e.g. because the system libraries have problems) this can be done with

> ./configure --disable-external-lapack

As a final resort, you can also edit the resulting Makefile.conf file. Notable variables in this file include:

  • DYNAMIC_LIB : these are the libraries needed to compile the PLUMED library (e.g. -L/path/to/matheval -lmatheval etc). Notice that for the PLUMED shared library to be compiled properly these should be dynamic libraries. Also notice that PLUMED preferentially requires BLAS and LAPACK library; see BLAS and LAPACK for further info. Notice that the variables that you supply with configure LIBS=something will end up in this variable. This is a bit misleading but is required to keep the configuration files compatible with PLUMED 2.0.
  • LIBS : these are the libraries needed when patching an MD code; typically only "-ldl" (needed to have functions for dynamic loading).
  • CPPFLAGS : add here definition needed to enable specific optional functions; e.g. use -D__PLUMED_HAS_MATHEVAL to enable the matheval library
  • SOEXT : this gives the extension for shared libraries in your system, typically "so" on unix, "dylib" on mac; If your system does not support dynamic libraries or, for some other reason, you would like only static executables you can just set this variable to a blank ("SOEXT=").


We tried to keep PLUMED as independent as possible from external libraries and as such those features that require external libraries (e.g. Almost and Matheval) are optional. However, to have a properly working version of plumed PLUMED you need BLAS and LAPACK libraries. We would strongly recommend you download these libraries and install them separately so as to have the most efficient possible implementations of the functions contained within them. However, if you cannot install blas and lapack, you can use the internal ones. Since version 2.1, PLUMED uses a configure script to detect libraries. In case system LAPACK or BLAS are not found on your system, PLUMED will use the internal replacement.

We have had a number of emails (and have struggled ourselves) with ensuring that PLUMED can link BLAS and LAPACK. The following describes some of the pitfalls that you can fall into and a set of sensible steps by which you can check whether or not you have set up the configuration correctly.

Notice first of all that the DYNAMIC_LIB variable in the Makefile.conf should contain the flag necessary to load the BLAS and LAPACK libraries. Typically this will be -llapack -lblas, in some case followed by -lgfortran. Full path specification with -L may be necessary and on some machines the blas and lapack libraries may not be called -llapack and -lblas. Everything will depend on your system configuration.

Some simple to fix further problems include:

  • If the linker complains and suggests recompiling lapack with -fPIC, it means that you have static lapack libraries. Either install dynamic lapack libraries or switch to static compilation of PLUMED by unsetting the SOEXT variable in the configuration file.
  • If the linker complains about other missing functions (typically starting with "for_" prefix) then you should also link some Fortran libraries. PLUMED is written in C++ and often C++ linkers do not include Fortran libraries by default. These libraries are required for lapack and blas to work. Please check the documentation of your compiler.
  • If the linker complains that dsyevr_ cannot be found, try adding -DF77_NO_UNDERSCORE to CPPFLAGS Notice that "./configure" should automatically try this solution.

Compiling PLUMED

Once configured, PLUMED can be compiled using the following command:

> make -j 4

This will compile the entire code and produce a number of files in the 'src/lib' directory, including the executable 'src/lib/plumed'. When shared libraries are enabled, a shared libraries called 'src/lib/' should also be present. Notice that the extension could be '.dylib' on a Mac.

In case you want to run PLUMED without installing it (i.e. from the compilation directory), you can use the file '' that has been created by the configure script in the main PLUMED directory. This file can be "sourced" (presently only working for bash shell) if you want to use PLUMED before installing it (i.e. from the compilation directory). It is a good idea to source it now, so that you can play with the just compiled PLUMED:

> source

Now a "plumed" executable should be in your path. Try to type

> plumed -h
If you are cross compiling, the plumed executable will not work. As a consequence, you won't be able to run regtests or compile the manual. This is not a problem.

You can also check if PLUMED is correctly compiled by performing our regression tests. Be warned that some of them fail because of the different numerical accuracy on different machines.

> cd regtest
> make

Notice that regtests are performed using the "plumed" executable that is currenty in the path. You can check the exact version they will use by using the command

> which plumed

This means that if you do not source "", the tests will fails. This does not mean that plumed is not working it just means that you haven't told them shell where to find plumed!

Notice that the compiled executable, which now sits in 'src/lib/plumed', relies on other resource files present in the compilation directory. This directory should thus stay in the correct place. One should thus not rename or delete it. In fact the path to the PLUMED root directory is hardcoded in the plumed executable as can be verified using

> plumed info --root

In case you try to use the plumed executable without the compilation directory in place (e.g. you move away the src/lib/plumed static executable and delete or rename the compilation directory) PLUMED will not work correctly and will give you an error message

> plumed help
ERROR: I cannot find /xxx/yyy/patches directory

You can force plumed to run anyway by using the option –standalone-executable:

> plumed --standalone-executable help

Many features will not be available if you run in this way. However, this is currently the only way to use the PLUMED static executable on Windows.

Installing PLUMED

It is strongly suggested to install PLUMED in a predefined location. This is done using

> make install

This will allow you to remove the original compilation directory, or to recompile a different PLUMED version in the same place.

To install PLUMED one should first decide the location. The standard way to do it is during the configure step:

> ./configure --prefix=$HOME/opt
> make
> make install

However, you can also change it after compilation setting the environment variable PLUMED_PREFIX.

> ./configure
> make
> export PLUMED_PREFIX=$HOME/opt
> make install

If you didn't specify the –prefix option during configure, and you did not set the PLUMED_PREFIX environment variable, PLUMED will be installed in /usr/local. The install command should be executed with root permissions (e.g. "sudo make install") if you want to install PLUMED on a system directory. Notice that upon installation PLUMED currently needs to relink a library. If root user does not have access to compilers, "sudo -E make install" might solve the issue. An almost full copy of the compilation directory will be installed into $PLUMED_PREFIX/lib/plumed/ directory. A link to the proper PLUMED executable will be set up in $PLUMED_PREFIX/bin, PLUMED include files will be copied to $PLUMED_PREFIX/include/plumed and PLUMED libraries will be linked to $PLUMED_PREFIX/lib.

One should then set the environment properly. We suggest to do it using the module framework ( An ad hoc generated module file for PLUMED can be found in $PLUMED_PREFIX/lib/plumed/src/lib/modulefile Just edit it as you wish and put it in your modulefile directory. This will also allow you to install multiple PLUMED versions on your machine and to switch amongst them. If you do not want to use modules, you can still have a look at the modulefile we did so as to know which environment variables should be set for PLUMED to work correctly.

If the environment is properly configured one should be able to do the following things:

  • use the "plumed" executable from the command line. This is also possible before installing.
  • link against the PLUMED library using the "-lplumed" flag for the linker. This allows one to use PLUMED library in general purpose programs
  • use the PLUMED internal functionalities (C++ classes) including header files such as "#include <plumed/tools/Vector.h>". This is useful as it may be expedient to exploit the PLUMED library in general purpose programs

As a final note, if you want to install several PLUMED versions without using modules then you can define the environment variable PLUMED_LIBSUFFIX using:

> export PLUMED_PREFIX=$HOME/opt
> export PLUMED_LIBSUFFIX=v2.0
> make install

This will install a plumed executable named "plumed_v2.0". All the other files will be renamed similarly, e.g. the PLUMED library will be loaded with "-lplumed_v2.0" and the PLUMED header files will be included with "#include <plumed_v2.0/tools/Vector.h>". This trick is useful if you do not want to set up modules, but we believe that using modules as described above is more flexible.

Until version 2.1.3, the added suffix was in the form -suffix instead of _suffix. This could cause clashes with the fact that plumed reserved names with a -something appended for scripts used in cross compiling (see below). As a consequence, by doing
> make install PLUMED_LIBSUFFIX=v2.0
> make install
The second install would remove all the executables installed by the first install.

Patching your MD code

In case your MD code is not supporting PLUMED already, you should modify it. We provide scripts to adjust some of the most popular MD codes so as to provide PLUMED support. At the present times we support patching the following list of codes:

  • amber14
  • gromacs-4-5-7
  • gromacs-4-6-7
  • gromacs-5-0-4
  • gromacs-5-1-0
  • lammps-6Apr13
  • namd-2-8
  • namd-2-9
  • qespresso-5-0-2

In the section Code specific notes you can find information specific for each MD code.

To patch your MD code, you should have already installed PLUMED properly. This is necessary as you need to have the command "plumed" in your execution path. As described above this executible will be in your paths if plumed was installed or if you have run

Once you have a compiled and working version of plumed, follow these steps to add it to an MD code

  • Configure and compile your MD enginge (look for the instructions in its documentation).
  • Test if the MD code is working properly.
  • Go to the root directory for the source code of the MD engine.
  • Patch with PLUMED using:
    > plumed patch -p
    The script will interactively ask which MD engine you are patching.
  • Once you have patched recompile the MD code (if dependencies are set up properly in the MD engine, only modified files will be recompiled)

There are different options available when patching. You can check all of them using

> plumed patch --help

Particularly interesting options include:

  • –static (default) just link PLUMED as a collection of object files. This is only suggested if for external reasons you absolutely need a static executable. Notice that with this setting it is often more complicated to configure properly the MD code, since all the libraries that PLUMED depends on should be properly specified. The ./configure script does its best in this sense, but sometime it cannot solve the problem. Additionally, this patching mode has been reported not to work properly on OSX.
  • –shared allows you to link PLUMED as a shared library. As a result when PLUMED is updated, there will be no need to recompile the MD code. This is way better than –static since the libraries that PLUMED depends on should be automatically linked. Notice that if you later remove the directory where PLUMED is installed also the MD code will not run anymore.
  • –runtime allows you to choose the location of the PLUMED library at runtime by setting the variable PLUMED_KERNEL. This is probably the most flexible option, and we encourage system administrators to use this option when installing PLUMED on shared facilities. Indeed, using this setting it will be possible to update separately the PLUMED library and the MD code, leaving to the user the possibility to combine different versions at will. We also recommend to use the provided modulefile (see above) to properly set the runtime environment.

Notice that it is not currently possible to link PLUMED as a static library (something like 'libplumed.a'). The reason for this is that PLUMED heavily relies on C++ static constructors that do not behave well in static libraries. For this reason, to produce a static executable with an MD code + PLUMED we link PLUMED as a collection of object files.

If your MD code is not supported, you may want to implement an interface for it. Refer to the developer manual .

Cross compiling

If you are compiling an executable from a different machine, then plumed executable will not be available in the compilation environment. This means that you won't be able to perform regtests on the machine nor to compile the manual. You can try to run the regtests on the computing nodes, but this might require some tweak since often machines where people do cross compiling have architectures with limited capabilities on the compute nodes. Also notice that many of the plumed options (e.g. patch) are implemented as shell scripts launched from within the plumed executable. If the compute nodes have some limitation (e.g. they do not allow to fork new processes) these options will not work. Anyway, the PLUMED library in combination with an MD software should work if both PLUMED and the MD software have been properly compiled.

Also notice that it will not be possible to use the command plumed patch on the machine where you are compiling. You should thus use plumed-patch instead of plumed patch (notice that it should be written as a single word). Try e.g.:

> plumed-patch --help

This script provides a "shell only" implementation of plumed patch that will skip the launch of the plumed executable.

Installing PLUMED with ALMOST

In order to used some of the NMR based collective variables (CS2BACKBONE and CH3SHIFTS) PLUMED needs to be linked with ALMOST. To do this the free package ALMOST v.2.1 MUST be dowloaded via SVN (svn checkout svn:// almost-code). ALMOST 2.1 can be found in branches/almost-2.1/ and can be compiled:

ALMOST needs SQLITE3 and GZIP installed on your computer.
ALMOST cannot be installed in the same folder of the source code, use –prefix to install it in a different folder
> ./configure --prefix="wherever you want it" CXXFLAGS="-O3 -fPIC" CFLAGS="-O3 -fPIC" 
> make
> make install

Sometimes ALMOST can give errors related to the automake tools. To fix them it is often enough to execute

> autoreconf -fi
> automake

and then repeat the configuration and compilation instructions.

PLUMED will not use the RDCs module of ALMOST so you can ignore the warning about LAPACK.

Once ALMOST is installed, PLUMED 2 can then be configured with ALMOST enabled:

> ./configure --enable-almost CPPFLAGS="-I/ALMOST_INSTALL_PATH/include \

with ALMOST_INSTALL_PATH set to the full path to the ALMOST installation folder.