Compiling PLUMED

PLUMED does not yet have any automatic configuration procedure and most of the decisions should be taken by the user. As a first step configure with the command:

> ./configure.sh

You will have to choose among a set of available preconfigured files. Choose the one closest to your machine, then edit the resulting Makefile.conf file. Notable variables there:

LIBS : these are the libraries needed when patching an MD code; typically only "-ldl" (needed to have functions for dynamic loading).
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 requires BLAS and LAPACK library; see BLAS and LAPACK for further info.
CPPFLAGS : add here definition needed to enable specific optional functions; e.g. use -D__PLUMED_HAS_MATHEVAL to enable matheval library
SOEXT : this gives the extension for shared libraries in your system, typically "so" on unix, "dylib" on mac; in case 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=").

Also notice that a new file sourceme.sh appears in the main PLUMED directory. This file should be "sourced" (presently only working for bash shell) if you want to use PLUMED without installing it (i.e. from the compilation directory. It is a good idea to source it now:

> source sourceme.sh

Then compile PLUMED

> make -j 4

If compilation is successful, a "plumed" executable should be in your path. Try to type

> plumed -h

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

> cd regtest
> make

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

> which plumed

This means that if you do not source "sourceme.sh" file, tests will fails. Moreover, in case you have another version of PLUMED installed somewhere regtests might use that one instead of the just-compiled one.

Also 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, and one should not rename or delete it. The path to the PLUMED root directory is indeed hardcoded in the plumed executable and can be verified with

> 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 using the option –standalone-executable:

> plumed --standalone-executable help

Anyway, many features will not be available in this way. This is currently the only way to use a PLUMED static executable on Windows.

BLAS and LAPACK

We tried to keep PLUMED as independent as possible from external libraries. Moreover, some libraries (e.g. Almost and Matheval) providing extra features are optional. However, to have a properly working PLUMED you need to link BLAS and LAPACK libraries. Here you find some note.

First of all, the DYNAMIC_LIB variable in the configuration file should contain the flag necessary to load these libraries (typically -llapack -lblas, in some case followed by -lgfortran but full path specification with -L should be necessary depending on your system configuration).

Even though you can incur in some problem.

If the linker complains and suggest to recompiled 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 configuration file).
If the linker complains that dsyevr_ cannot be found, try to add -DF77_NO_UNDERSCORE to CPPFLAGS
If the linker complains about other missing functions (typically starting with "for_" prefix) then you should link also Fortran libraries. Indeed, PLUMED is written in C++ and often C++ linkers do not include by default Fortran libraries which are required for lapack and blas to work. Please check the documentation of your compiler.

Installing PLUMED

It might be convenient to install PLUMED in a predefined location. This will allow you to remove the original compilation directory, or to recompile e.g. a different PLUMED version in the same place. Notice that installation is optional. Even from the compilation directory, if environment is properly set (see sourceme.sh file) PLUMED should work.

To install PLUMED one should first decide the location. Just set the environment variable PLUMED_PREFIX, then type "make install"

> export PLUMED_PREFIX=$HOME/opt
> make install

If PLUMED_PREFIX is not set, it will be assumed to be /usr/local. The install command should be executed with root permissions (e.g. "sudo make install") in case you want to install PLUMED on a system directory. 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 (http://modules.sourceforge.net). An ad hoc generated module file for PLUMED can then be found in $PLUMED_PREFIX/lib/plumed/src/lib/modulefile Just edit it at your will and put it in your modulefile directory. This will also allow you to install several PLUMED versions alongside and switch among 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 "plumed" executable from the command line. this is also possible before installing.
link against the PLUMED library using "-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 also usefule to exploit the PLUMED library in general purpose programs

As a final note, one may want to install several PLUMED version alongside without using modules. An alternative is to also define the environment variable PLUMED_LIBSUFFIX. E.g. with

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

will install plumed executable with name "plumed-v2.0". All the other files will be renamed accordingly, 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 think using modules (see above) is more flexible.

Patching your MD code

At the present times PLUMED can be added to the following list of codes:

To patch your MD code, you should have PLUMED already properly working. In particular, you should have the command "plumed" in your execution path, either because it is installed or because you are using it from the compilation directory. Then, follow these steps

Configure and compile your MD enginge
Test if it is working properly
Go to the root diretory of the MD engine
Patch:
```
> plumed patch -p
```
The script will interactively ask which MD engine you are patching.
Recompile the MD code (if dependencies are set up properly in the MD engine, only modified files will be recompiled)

There are different options when patching, check them using

> plumed patch --help

Interesing ones:

–shared allows you to link PLUMED as a shared library. when PLUMED is updated, there will be no need to recompile the MD code
–runtime allows you to choose the location of the PLUMED library at runtime, setting the variable PLUMED_KERNEL.
–static (default) just link PLUMED as a collection of object files

A note for cross compiling: in case you are compiling an executable from a different machine, then "plumed" executable will not be available in the compilation environment. You can thus use the following command

> plumed-patch

as a replacement of "plumed patch". This trick only works with those commands which are implemented as pure scripts (e.g. there is no "plumed-help" available...).

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