Doc.txt

// This document is formatted for Doxygen
/**
\mainpage Plumed 2

Roadmap:
- Cloning most PLUMED1 features (to be defined)
- Public beta release (to be defined)
- 2.0 public release (to be defined)

\section FeaturesAndChanges Features and changes

This are some comments about the structure of the code:
- Re-designed from scratch, hopefully better.
- Input is conceptually similar but NON compatible. It is difficult to automatically
  convert old input files, but we could provide a short transition guide.
  The new plumed.dat is a sort of script containing a list of actions to be performed at each step.
  Notable differences in input:
  - An Action is composed of a line (possibly with continuations) of
    space-separated words, and corresponds more-or-less to a directive in PLUMED1.
\verbatim
DISTANCE ATOMS=0,300 LABEL=dist NOPBC
\endverbatim
    The first word (DISTANCE here) defines the directive type, all other words are arguments
    Most arguments are named, and has the form "NAME=VALUE" (ATOMS and LABEL in the example).
    Others are flags (NOPBC in the example).
  - Continuation can be done with "..." syntax (notice the space between DISTANCE and dots):
\verbatim
DISTANCE ...
  ATOMS=0,300
  LABEL=dist
  NOPBC
... DISTANCE
\endverbatim
  - All directives can be labeled (LABEL=dist in the example)
  - A bias can only act on a labeled colvar:
\verbatim
DISTANCE ATOMS=0,300 LABEL=dist
# This is a harmonic restraint
RESTRAINT ARG=dist KAPPA=1.0 AT=1.0
\endverbatim
  - Some colvars have extra named values, which can be accessed with "." syntax
\verbatim
DISTANCE ATOMS=1,10 LABEL=dist COMPONENTS
RESTRAINT ARG=dist.x KAPPA=1.0 AT=1.0
\endverbatim
    Here COMPONENTS is telling to DISTANCE to also compute the three components.
    This is expected to be useful for variables which have multiple components
    but that are heavy and we would like to compute only once (e.g. components
    of the inertia tensor of a large molecule).
    Also methods can have extra named values, such as the energy for a restraint.
  - to print a COLVAR-like file (name can be changed), use PRINT directive
\verbatim
PRINT ARG=d1,d1.x,d1.y,d1.z STRIDE=100 FILE=COLVAR
# or
PRINT ARG=d1.* STRIDE=100 FILE=COLVAR1
# or, to print all the variables defined in the plumed.dat up to this point
PRINT ARG=* STRIDE=100 FILE=COLVAR_ALL
\endverbatim
- The library has been written in C++ for a more flexible structure:
  - Extensive use of STL containers for things such as lists/vectors/maps/...
  - Polymorphism for collective variables/free energy methods
  However, for compatibility, its main interface is in plain C (with FORTRAN
  and C++ wrappers). All the C++ definitions are hidden in a PLMD namespace.
- Hierarchy of classes describing each possible Action performed by PLUMED.
  There is a class for each CV (e.g. PLMD::ColvarDistance, PLMD::ColvarEnergy,
  PLMD::ColvarVolume), a class for each bias (e.g. PLMD::BiasRestraint, PLMD::BiasMovingRestraint),
  and a class for each function (e.g. PLMD::FunctionCombine).
  There are also auxiliary classes to write the output (PLMD::Print),
  to set the units (PLMD::Units), to print dedug information (PLMD::Debug),
  to flush the open files (PLMD::Flush), etc.
  More or less, there should be a class for each possible directive of "plumed.dat".
  To see the full hierarchy, look at PLMD::Action.
- It should be possible to program Actions independently from each other. To this
  aim, there is a register (PLMD::ActionRegister, contained in the function
  PLMD::actionRegister()) where, during C++ initialization, each
  Action registers itself. Thus, if a new CV or bias is added, there is no need
  for recompilation. If dlopen() is available on a system, it should be possible
  to load Actions runtime (using LOAD directive).
  In the long run we can imagine libraries of CVs
  suitable for different problems and, possibly, released independently from
  the kernel. On a mainframe, one could add CVs without recompiling neither plumed
  nor the MD engine.
- There is an option to load the plumed kernel at runtime. If you patch with
  --runtime, the plumed kernel is looked for at the path in variable PLUMED_KERNEL.
  If the variable is not set, basic (un-plumed) version of MD is used.
  On a mainframe, one can have multiple installed plumed versions.
- Ideally, inside the kernel there is nothing related to specific CVs or FE-methods. Thus, CVs and 
  methods are optional plugins for PLUMED. The only exception
  are tools which are common to several CVs/methods, such as grid interpolators, etc.
- Ideally, inside the kernel there is nothing related to specific MD code. The interface is kept
  as standard as possibly. Anyway, all the details of the interaction PLUMED/MD are inside the
  src/Atoms.cpp file.  E.g., there are two (templated) versionsi of class PLMD::MDAtoms,
  one for double precision and the other
  for single precision MD. Code specific tools could be added here. In the future, we may try to
  design a plugin approach also for MD engines (similarly to CVs/methods).
- To simplify interface, there is a single routine plumed_cmd which takes a string and a pointer.
  It can be used to pass any information to plumed, such as:
\verbatim
plumed p=plumed_create();
plumed_cmd(p,"setNatoms",&natoms);
plumed_cmd(p,"setMDEngine","gromacs");
plumed_cmd(p,"init",NULL);
...
plumed_cmd(plumedmain,"setPositions",pos);
plumed_cmd(plumedmain,"setBox",box);
plumed_cmd(plumedmain,"setEnergy",&energy);
plumed_cmd(plumedmain,"setForces",forces);
plumed_cmd(plumedmain,"setVirial",virial);
plumed_cmd(plumedmain,"calc",NULL);
...
plumed_finalize(p);
\endverbatim
  Fortran/C++ interfaces are similar (see src/Plumed.c for details), and are based on the C interface
  (wrappers).
- Units: PLUMED reads and writes only in its internal units, which, by default, are
  nm and kj/mol. In plumed.dat it is possible to change it to other choices:
\verbatim
UNITS ...
  LENGTH=A
  TIME=fs
  ENERGY=kcal/mol
... UNITS
\endverbatim
  The MD code should specify to plumed its internal units, so as to allow proper conversion.
  E.g., a code using angstrom and kcal should do the following calls
\verbatim
double energyUnits=4.184;
double lengthUnits=0.1;
plumed_cmd(plumedmain,"setMDEnergyUnits",&energyUnits);
plumed_cmd(plumedmain,"setMDLengthUnits",&lengthUnits);
\endverbatim
- Other cool features:
  - Functions of colvars (or functions of functions) can be used. For example, defining:
\verbatim
COMBINE LABEL=sum2     ARG=dist.x,dist.y,dist.z POWERS=2,2,2
COMBINE LABEL=sqrtsum2 ARG=sum2                 POWERS=0.5
# The following two restraints are equivalent:
RESTRAINT ARG=dist     AT=1.2 KAPPA=1.0
RESTRAINT ARG=sqrtsum2 AT=1.2 KAPPA=1.0
\endverbatim
  - Multiple-time-step: biases can be applied with multiple-time-step using a stride. This should
    help for variables which are heavy to compute but smooth
\verbatim
RESTRAINT ARG=dist AT=1.2 KAPPA=1.0 STRIDE=2
\endverbatim
  - It is possible to include other files:
\verbatim
INCLUDE FILE=anotherplumed.dat
\endverbatim
  - It is possible to load shared libraries implementing new CVs and methods:
\verbatim
LOAD FILE=share-object.so
\endverbatim

\section Install Install

- Configure and compile your MD code
- Configure and compile PLUMED, possibly using the same compiler:
\verbatim
$ ./configure.sh
... choose your compiler interactively here ...
... it may be necessary to edit the Makefile.conf file ...
$ make -j 4
\endverbatim
- Source the ./sourceme.sh file
\verbatim
$ source sourceme.sh
\endverbatim
  \attention This should be done on every shell where you want to patch/run plumed
- Go to your MD code directory and do the patch
\verbatim
$ plumed patch --patch
\endverbatim
  (use -h to get information about other options).  Also experiment other linking modes (e.g. --runtime)
- Recompile your MD code (without necessarily cleaning it)

\section Content Content

src/
Plumed library source code (C++) plus a two wrapper files (Plumed.c and PlumedStatic.cpp; the latter is just
equivalent to the former but is compiled as cpp, for testing, and does not allow runtime binding).
Sources are compiled into a libplumed.so library and a libplumedKernel.so library
(replace .so with .dylib on Mac).
The src/Plumed.inc file contains shortcuts for the compilation. Just include it in your makefile and:
- link the src/Plumed.h file in an included directory
- add to the linker command the $(PLUMED_LDFLAG) options, to have the proper link flags
- add to the linker command the $(PLUMED_LIBS) variable, to link the proper external libraries
- add to the linker command one of the following variables:
  - (A) \$(PLUMED_OBJ) : plumed will be statically bound
  - (B) \$(PLUMED_SHARED_OBJ) : plumed will be dynamically bound
  - (C) \$(PLUMED_WRAPPER) : behavior depend on runtime value of the PLUMED_KERNEL environment variable.
    If set to the full path of the libplumedKernel.so library, plumed will be available.
    If unset, or if set to a wrong file, plumed will not be available.
- The difference between (A) and (B) is that in case (B) if you recompile plumed and rerun MD your code
  is automatically up to date.
  The difference between (B) and (C) is that in case (C) the MD code is able to run also if plumed is
  not available. This allows to have a single compiled MD code for both plumed users and others.
  Moreover, in case (C) it is trivial to change plumed version at execution time, by properly setting
  the PLUMED_KERNEL environment variable.
  Notice that in (B) case the full path of the plumed library is recorded, thus it should not
  be changed after patching, and it should be reachable from computing nodes.
  All these task can be done automatically with "plumed patch" using respectively the flags:
  - (A) --static
  - (B) --shared
  - (C) --runtime
   
extensions/ 
   Plumed extensions (e.g. contributed collective variables, ...)
   They are compiled into a libplumedExtensions.so file which can be loaded at runtime.
   To load them, use LOAD command inside plumed.dat

test/link/
   A few simple executables to test compilation/linking
   Executables are:
-  (A) XXX-static statically linked with src/*.o (except src/Plumed.o)
-  (B) XXX        dynamically linked with libplumed.so
-  (C) XXX-dummy  statically linked with src/Plumed.o

user-doc/
   User documentation

developer-doc/
   Developer documentation

\section Notes Notes

Information about C++
http://www.parashift.com/c++-faq-lite/

Compiler options to use shared libraries on many architectures:
http://www.fortran-2000.com/ArnaudRecipes/sharedlib.html

\page HowToAddACollectiveVariable How to add a collective variable

\page HowToAddAFunction How to add a function

\page HowToAddABias How to add a biasing potential


*/