Installation.txt

/**

\page Installation Installation

\section CompilingPlumed Compiling PLUMED

Since version 2.1, PLUMED can be configured using autoconf. Just type:
\verbatim
> ./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.

You can provide hints to the configure script. In particular,
you can state which compiler you wish to use, e.g. to use Intel compilers:
\verbatim
> ./configure CXX=icpc CC=icc
\endverbatim
You can also tune the compilation options
\verbatim
> ./configure CXXFLAGS=-O3
\endverbatim

In case you want an MPI build, just use the proper name of the MPI compiler.
\verbatim
> ./configure CXX=mpic++ CC=mpicc
\endverbatim
The configure will figure out that MPI library is available and instruct PLUMED
to use it.

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.
Other useful command line options for ./configure can be found typing
\verbatim
> ./configure --help
\endverbatim

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.

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.

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 installin it* (i.e. from the compilation
directory). It is a good idea to source it now:
\verbatim
> source sourceme.sh
\endverbatim

Then compile PLUMED
\verbatim
> make -j 4
\endverbatim

If compilation is successful, 
a "plumed" executable should be in your path. Try to type
\verbatim
> plumed -h
\endverbatim

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 to link BLAS and LAPACK libraries.
In case you cannot install proper BLAS and LAPACK libraries on your machine,
you have the possibility of using an internally compiled (possibly slower) versionx .
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, 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.

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


\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)
PLUMED should work.

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
> plumed patch -p
\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>.


*/