Index: src/documentation/constructs/constructs.dox
===================================================================
--- src/documentation/constructs/constructs.dox	(revision 2448f8f6d400d7eefa93cae4b6e5f44796ba4baa)
+++ src/documentation/constructs/constructs.dox	(revision 661d2d3ce0a5613629e4086605fe6934191a29c3)
@@ -31,6 +31,6 @@
  *  \li \ref observers
  *  \li \ref parameters
- *  \li \ref parsers
- *  \li \ref potentials
+ *  \li \ref parsers "Parsers"
+ *  \li \ref potentials "Potentials"
  *  \li \ref qt-gui
  *  \li \ref queries
@@ -47,5 +47,5 @@
  *
  *
- * \date 2013-02-07
+ * \date 2013-04-09
  *
  */
Index: src/documentation/constructs/potentials.dox
===================================================================
--- src/documentation/constructs/potentials.dox	(revision 2448f8f6d400d7eefa93cae4b6e5f44796ba4baa)
+++ src/documentation/constructs/potentials.dox	(revision 661d2d3ce0a5613629e4086605fe6934191a29c3)
@@ -71,8 +71,9 @@
  *    perform the fit.
  *
- * \section potentials-howto Howto use the potentials
+ * \section potentials-howto-use Howto use the potentials
  *
  *  We just give a brief run-down in terms of code on how to use the potentials.
- *  Here, we just describe what to do in order to perform the fitting.
+ *  Here, we just describe what to do in order to perform the fitting. This is
+ *  basically what is implemented in FragmentationFitPotentialAction.
  *
  *  \code
@@ -102,5 +103,5 @@
  *  // give initial parameter
  *  FunctionModel::parameters_t params(PairPotential_Angle::MAXPARAMS, 0.);
- *  ... set some initial parameters
+ *  // ... set some potential-specific initial parameters in params struct
  *  angle.setParameters(params);
  *
@@ -123,8 +124,31 @@
  *  // evaluate
  *  FunctionModel::arguments_t args;
- *  .. initialise args to the desired distances
+ *  // .. initialise args to the desired distances
  *  const double value = angle(args)[0]; // output is a vector!
  *  \endcode
  *
- * \date 2012-11-28
+ * \section potentials-stability-of-fit note in stability of fit
+ *
+ *  As we always start from random initial parameters (within a certain sensible
+ *  range at least), the non-linear fit does not always converge. For this case
+ *  the FragmentationFitPotentialAction has the option "take-best-of" to allow
+ *  for multiple fits where the best (in terms of l2 error) is taken eventually.
+ *
+ * \section potentials-howto-add Howto add new potentials
+ *
+ *  Adding a new potential requires the following:
+ *  -# Add the new modules to Potentials/Specifics
+ *  -# Add a unit test on the potential in Potentials/Specifics/unittests
+ *  -# Give the potential a type name and add it to PotentialTypes.def. Note
+ *     that the name must not contain white space.
+ *  -# Add the potential name as case to PotentialFactory such that it knows
+ *     how to instantiate your new potential when requested.
+ *
+ * PotentialTypes.def contains a boost::preprocessor sequence of all
+ * potential names. PotentialFactory uses this sequence to build its enum to
+ * type map and inverse which the user sees when specifying the potential to
+ * fit via PotentialTypeValidator.
+ *
+ *
+ * \date 2013-04-09
  */
Index: src/documentation/install.dox
===================================================================
--- src/documentation/install.dox	(revision 2448f8f6d400d7eefa93cae4b6e5f44796ba4baa)
+++ src/documentation/install.dox	(revision 661d2d3ce0a5613629e4086605fe6934191a29c3)
@@ -55,4 +55,6 @@
  *    -# MPQC: see below for instructions
  *    -# ScaFaCoS: see below for instructions
+ *    -# VTK: see below for instructions
+ *    -# levmar: see below for instructions
  *
  *  If you are programming with or for MoleCuilder, the following packages are
@@ -109,8 +111,8 @@
  *  \subsubsection install-prerequisites-other-scafacos ScaFaCoS
  *
- *  ScaFaCoS is a library of fast Coulomb solvers, created by the same-named BMBF
- *  funded project. The library contains Versatile MultiGrid (vmg) as one of its
- *  solvers which is used in the BOSSANOVA scheme for the calculation of
- *  long-range forces.
+ *  ScaFaCoS (http://www.scafacos.org/) is a library of fast Coulomb solvers,
+ *  created by the same-named BMBF funded project. The library contains Versatile
+ *  MultiGrid (vmg) as one of its solvers which is used in the BOSSANOVA scheme
+ *  for the calculation of long-range forces.
  *
  *  ScaFaCoS requires the following packages to compile:
@@ -118,4 +120,29 @@
  *  -# F2C: libf2c2-dev
  *  -# Fortran compiler: gfortan
+ *  -# VTK >=5.10
+ *
+ *  Firstly, you should obtain a recent copy of the visualization tool kit (VTK)
+ *  (http://www.vtk.org/) and compile as
+ *  \code
+ *  export MPI_HOME=$( which mpirun | sed 's#/bin/mpirun##g')
+ *  export CXX_FLAGS=-fPIC
+ *  cmake -DCMAKE_INSTALL_PREFIX:PATH=<install-path> \
+ *        -DBUILD_SHARED_LIBS=TRUE \
+ *        -DCMAKE_BUILD_WITH_INSTALL_RPATH:BOOL=OFF \
+ *        -DCMAKE_INSTALL_RPATH:PATH=<install-path>/lib/vtk-<install-version> \
+ *        -DCMAKE_INSTALL_RPATH_USE_LINK_PATH:BOOL=ON \
+ *        -DCMAKE_SKIP_BUILD_RPATH:BOOL=OFF \
+ *        -DVTK_USE_PARALLEL:BOOL=ON \
+ *        -DVTK_USE_MPI:BOOL=ON \
+ *        -DMPI_LIBRARY:PATH=${MPI_HOME}/lib/libmpi.so \
+ *        -DMPI_EXTRA_LIBRARY:PATH=${MPI_HOME}/lib/libmpi_cxx.so \
+ *        -DMPI_INCLUDE_PATH:PATH=${MPI_HOME}/include/mpi \
+ *        ..
+ *  make -j4
+ *  make install
+ *  \endcode
+ *  where we force rpath-linking and shared libraries (MPI is actually not
+ *  required here).
+ *
  *  Compilation additionally required use of
  *  \code CPPFLAGS="-fPIC" \endcode
@@ -125,8 +152,38 @@
  *  for a debug compile you might want to use:
  *  \code
- *  ../configure -C --prefix=<path> --enable-shared BSPLINE_DEG=3 MPICC=mpicc.openmpi
- *  MPICXX=mpicxx.openmpi MPIEXEC=mpirun.openmpi CPPFLAGS="-Wall -g3 -O0 -ggdb -fPIC"
- *  --enable-mpi --with-boost-libdir=/usr/lib --with-boost=/usr --enable-fcs-solvers=vmg
+ *  ../configure \
+ *    -C \
+ *    --prefix=<path> \
+ *    --enable-shared \
+ *    BSPLINE_DEG=3 \
+ *    MPICC=mpicc.openmpi \
+ *    MPICXX=mpicxx.openmpi \
+ *    MPIEXEC=mpirun.openmpi \
+ *    CPPFLAGS="-Wall -g3 -O0 -ggdb -fPIC" \
+ *    --enable-mpi \
+ *    --with-boost-libdir=/usr/lib --with-boost=/usr \
+ *    --with-vtk=<path-to-vtk> --with-vtk-version=<vtk-version path string, i.e. -5.10> \
+ *    --enable-fcs-solvers=vmg
  *  \endcode
+ *  where we specify a recent boost and the installed VTK version from above.
+ *
+ *  \subsubsection install-prerequisites-other-levmar LevMar
+ *
+ *   We also require the levmar (http://www.ics.forth.gr/~lourakis/levmar/) which
+ *   implements a Levenberg-Marquardt for non-linear regression which is employed
+ *   for fitting empirical potentials to energies obtained from calculated
+ *   fragment energies.
+ *
+ *   Compile and install as follows
+ *   \code
+ *    cmake \
+ *      -DCMAKE_INSTALL_PREFIX:PATH=<install-path> \
+ *      -DCMAKE_C_FLAGS="-fPIC" \
+ *      ..
+ *    make
+ *    cp -f liblevmar.a <install-path>/lib
+ *    cp -f levmar.h <install-path>/include
+ *   \endcode
+ *   where we have to copy the stuff by hand as no \a install target exists.
  *
  *  \subsubsection install-prerequisites-other-mpqc MPQC
@@ -276,4 +333,4 @@
  *  from a distributed archive. This is checked for each release version.
  *
- * \date 2012-12-20
+ * \date 2013-04-09
  */
