Newer
Older
/**
\page Installation Installation
\section CompilingPlumed Compiling PLUMED
Since version 2.1, PLUMED can be configured using autoconf. Just type:
> ./configure
\endverbatim
This is going to generate a Makefile.conf file and a sourceme.sh file.
In PLUMED 2.0 these files where 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 find in trouble
with the new procedure, just put in place your old files. However,
it should be easy to enforce a similar setup on autoconf (by passing
the proper arguments on the command line) and we encourage this.
In case you have problems on your architecture, please
report to the mailing list.
Useful command line options for ./configure can be found typing
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.
Notice that when mpi search is enabled (by default) compilers
such as "mpic++" and "mpicxx" are searched first. On the other hand,
if mpi search is disabled ("./configure --disable-mpi") non-mpi
compilers are searched.
You can better control which compiler is used with the
variables CXX and CC. E.g., to use Intel compilers:
> ./configure CXX=icpc CC=icc
\endverbatim
Notice that in this example, since icpc is not an mpi compiler, mpi will not
be enabled.
You can also tune the compilation options
\verbatim
> ./configure CXXFLAGS=-O3
\endverbatim
In case you want to build with debug flags so as to do some checking you can use
\verbatim
> ./configure --enable-debug
\endverbatim
This will perform some extra check during execution (possibly slowing down PLUMED a bit)
and write full symbol table in the executable.
The main goal of the automatic configure is to find libraries.
In case they are stored in unconventional places you might have to
suggest their location.
E.g. if your matheval libraries is in /opt/local (this is where MacPorts put it)
use
\verbatim
> ./configure LDFLAGS=-L/opt/local/lib CPPFLAGS=-I/opt/local/include
\endverbatim
Notice that PLUMED will first try to link a routine from say matheval
directly, and then try to add "-lmatheval" to the library. So, if
your matheval library is called /opt/local/lib/libmymatheval.so you can
link it with
\verbatim
> ./configure LDFLAGS=-L/opt/local/lib CPPFLAGS=-I/opt/local/include LIBS=-lmymatheval
\endverbatim
This rule is true for all the libraries, so that you will always be able to link
a specific version of a library by adding it to the LIBS variable.
\warning On Linux you might have problems using the LDFLAGS option. In particular,
if you have problems in linking file 'src/lib/plumed-shared', try to set correctly
the runtime path with e.g.
\verbatim
> ./configure LDFLAGS="-L/opt/local/lib -Wl,-rpath,/opt/local/lib" CPPFLAGS=-I/opt/local/include LIBS=-lmymatheval
\endverbatim
Notice that PLUMED needs blas and lapack. The configure script
is first looking for them in the standard path, then with option "-lblas" and
"-llapack", respectively. Thus, if you want to use a specific version of them
you can just make them available to configure with
\verbatim
> ./configure LDFLAGS=-L/path/to/blas/lib LIBS=-lnameoflib
\endverbatim
The script is also finding out if function names have the final underscore added,
so this should be completely transparent to the user.
In case blas or lapack are not found, the internal versions are used.
As a final resort, you may also edit the resulting Makefile.conf file.
Notable variables there:
- 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 \ref BlasAndLapack 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 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:
If compilation is successful,
a "plumed" executable should be in your path. Try to type
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.
\verbatim
> cd regtest
> make
\endverbatim
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
\verbatim
> which plumed
\endverbatim
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
\verbatim
> plumed info --root
\endverbatim
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
\verbatim
> plumed help
ERROR: I cannot find /xxx/yyy/patches directory
\endverbatim
You can force plumed to run anyway using the option --standalone-executable:
\verbatim
> plumed --standalone-executable help
\endverbatim
Anyway, many features will not be available in this way.
This is currently the only way to use a PLUMED static executable on Windows.
\section BlasAndLapack 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 BLAS and LAPACK libraries.
In case you cannot manage to install blas and lapack, you can use the internal
ones. Just add to the CPPFLAGS the flags -D__PLUMED_INTERNAL_BLAS
-D__PLUMED_INTERNAL_LAPACK.
The automatic configure should be able to choose automatically the internal
libraries when necessary.
Some additional notes follow.
First of all, the DYNAMIC_LIB variable in the Makefile.conf
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.
\section Installing 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)
To install PLUMED one should first decide the location. Just set
the environment variable PLUMED_PREFIX, then type "make install"
\verbatim
> export PLUMED_PREFIX=$HOME/opt
> make install
\endverbatim
If PLUMED_PREFIX is not set, it will be assumed to be
the one set when configuring with autoconf. E.g. you could
have used
\verbatim
> ./configure --prefix=$HOME/opt
> make
> make install
\endverbatim
If not set, it defaults to /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
\verbatim
> export PLUMED_PREFIX=$HOME/opt
> export PLUMED_LIBSUFFIX=v2.0
> make install
\endverbatim
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.
\section Patching Patching your MD code
At the present times PLUMED can be added to the following list of codes:
@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:
\verbatim
\endverbatim
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
\verbatim
> plumed patch --help
\endverbatim
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
\verbatim
> plumed-patch
\endverbatim
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 <a href="../../developer-doc/html/index.html"> developer
manual </a>.
*/