\page installation Installation

This section covers how to install %ForceBalance.  Currently only Linux
is supported, though installation on other Unix-based systems
(e.g. Mac OS) should also be straightforward.

Importantly, note that <em>%ForceBalance does not contain a simulation
engine</em>.  Instead it interfaces with simulation software like
GROMACS, TINKER, AMBER or OpenMM; reference data is obtained from
experimental measurements (consult the literature) or from quantum
chemistry software (for example, NWChem or Q-Chem).

Several interfaces to existing software packages are provided.
However, if you use %ForceBalance for a research project, you should be
prepared to write some simple Python code to interface with a software
package of your choice.  If you choose to do so, please contact me as
I would be happy to include your contribution in the main
distribution.

@section installing_forcebalance Installing ForceBalance

%ForceBalance is packaged as a Python module.  Here are the installation instructions.  

A quick preface: Installing software can be a real pain.  I tried to make %ForceBalance easy to install by providing clear instructions and minimizing the number of dependencies; however, complications and challenges during installation happen all the time.  If you are running into installation problems or having trouble resolving a dependency, please contact me.

@subsection installing_forcebalance_prereq Prerequisites

%ForceBalance requires the following software packages:

@li <a href=http://www.python.org/>Python</a> version 2.7
@li <a href=http://numpy.scipy.org/>NumPy</a> version 1.5
@li <a href=http://www.scipy.org/>SciPy</a> version 0.9

The following packages are required for certain functionality:

@li <a href=http://lxml.de/>lxml</a> version 2.3.4 - Python interface to libxml2 for parsing OpenMM force field files
@li <a href=http://nd.edu/~ccl/software/>cctools</a> version 3.4.1 - Cooperative Computing Tools from Notre Dame for distributed computing
@li <a href=https://matplotlib.org>matplotlib</a> version 2.0.2 - Python plotting library which produces publication quality figures

The following packages are used for documentation:

@li <a href=http://www.stack.nl/~dimitri/doxygen/>Doxygen</a> version 1.7.6.1
@li <a href=http://code.foosel.org/doxypy>Doxypy</a> plugin for Doxygen
@li LaTeX software such as <a href=http://www.tug.org/texlive/>TeXLive</a>
@li The dot program from <a href=http://www.graphviz.org/> graphviz</a> software package

@subsection installing_forcebalance_install Installing

To install the package, first extract the tarball that you downloaded from the
webpage using the command:

@verbatim tar xvzf ForceBalance-[version].tar.gz @endverbatim

Alternatively, download the newest Subversion revision from the SimTK website:

@verbatim svn checkout https://simtk.org/svn/forcebalance @endverbatim

Upon extracting the distribution you will see this directory structure:

@verbatim
<root>
  +- bin
  |   |- <Executable scripts>
  +- src
  |   |- <ForceBalance source files>
  +- ext
  |   |- <Extensions; self-contained software packages that are used by ForceBalance>
  +- studies
  |   +- <ForceBalance example jobs>
  +- doc
  |   +- callgraph
  |   |   |- <Stuff for making a call graph>
  |   +- Images
  |   |   |- <Images for the website and PDF manual>
  |   |- make-all-documentation.sh (Create the documentation)
  |   |- <Below are documentation chapters in Doxygen format>
  |   |- introduction.txt
  |   |- installation.txt
  |   |- usage.txt
  |   |- tutorial.txt
  |   |- glossary.txt
  |   |- <The above files are concatenated into mainpage.py>
  |   |- make-all-documentation.sh (Command for making all documentation)
  |   |- make-option-index.py (Create the option index documentation chapter)
  |   |- header.tex (Customize the LaTex documentation)
  |   |- add-tabs.py (Adds more navigation tabs to the webpage)
  |   |- DoxygenLayout.xml (Removes a navigation tab from the webpage)
  |   |- doxygen.cfg (Main configuration file for Doxygen)
  |   |- ForceBalance-Manual.pdf (PDF manual, but the one on the SimTK website is probably newer)
  |- PKG-INFO (Auto-generated package information)
  |- README.txt (Points to the SimTK website)
  |- setup.py (Python script for installation) @endverbatim

To install the code into your default Python location, run this (you might need to be root):

@verbatim python setup.py install @endverbatim

You might not have root permissions, or you may want to install the package somewhere other than the default location.  You can install to a custom location (for example, to /home/leeping/local) by running:

@verbatim python setup.py install --prefix=/home/leeping/local @endverbatim

Assuming your Python version is 2.7, the executable scripts will be placed into <tt>/home/leeping/local/bin</tt> and the module will be placed into <tt>/home/leeping/local/lib/python2.7/site-packages/forcebalance</tt>.

Note that Python does not always recognize installed modules in custom locations.  Any one of the three below options will work for adding custom locations to the Python search path for installed modules:

@verbatim ln -s /home/leeping/local /home/leeping/.local @endverbatim
@verbatim export PYTHONUSERBASE=/home/leeping/local @endverbatim
@verbatim export PYTHONPATH=$PYTHONPATH:/home/leeping/local/lib/python2.7 @endverbatim

As with the installation of any software, there are potential issues with dependencies (for example, scipy and lxml.)  One way to resolve dependencies is to use the Enthought Python Distribution (EPD), which contains all of the required packages and is free for academic users.  Install EPD from the <a href=http://www.enthought.com/products/epd.php>Enthought website</a>.  Configure your environment by running both of the commands below (assuming Enthought was installed to <tt> /home/leeping/opt/epd-7.3.2 </tt>, with the python executable in the \c bin subdirectory):

@verbatim
export PATH=/home/leeping/opt/epd-7.3.2/bin:$PATH
export PYTHONUSERBASE=/home/leeping/opt/epd-7.3.2 @endverbatim

An alternative option is to use Anaconda2, that can be downloaded <a href=https://www.continuum.io/downloads>the Continuum website</a>. It is also free for academic users.

@verbatim
export PATH=/home/leeping/opt/anaconda2/bin:$PATH @endverbatim

Once you have done this, the Numpy, Scipy, Matplotlib and lxml dependency issues should be resolved and %ForceBalance will run without any problems.

Here are a list of installation notes (not required if you install %ForceBalance into the Enthought Python Distribution).  These notes assume that Python and other packages are installed into $HOME/local.

@li The installation of Numpy, Scipy and lxml may be facilitated by installing the \c pip package - simply run a command like <tt>pip install numpy</tt>.
@li Scipy requires a BLAS (Basic Linear Algebra Subroutines) library to be installed.  On certain Linux distributions such as Ubuntu, the BLAS libraries and headers can be found on the repository (run <tt>sudo apt-get install libblas-dev</tt>).  Also, BLAS is provided by libraries such as ATLAS (Automatically Tuned Linear Algebra Software) or the Intel MKL (Math Kernel Library) for Intel processors.  To compile Scipy with Intel's MKL, follow the guide on <a href=http://software.intel.com/en-us/articles/numpy-scipy-with-mkl>Intel's website</a>.  To use ATLAS, install the package from the <a href=http://math-atlas.sourceforge.net> ATLAS website </a> and set the ATLAS environment variable (for example, <tt>export ATLAS=$HOME/local/lib/libatlas.so</tt>) before installing Scipy.
@li \c lxml is a Python interface to the libxml2 XML parser.  After much ado, I decided to use \c lxml instead of the \c xml module in Python's standard library for several reasons (\c xml contains only limited support for XPath, scrambles the ordering of attributes in an element, etc.)  The downside is that it can be harder to install.  Installation instructions can be found on the <a href=http://lxml.de/installation.html> lxml website</a> but summarized here.  The packages \c libxml2 and \c libxslt need to be installed first, and in that order.  On Ubuntu, run <tt>sudo apt-get install libxml2-dev libxslt1-dev</tt>.  To compile from source, run <tt>./configure --prefix=$HOME/local --with-python=$HOME/local</tt>.  Then run \c make followed by <tt>make install</tt>.  Python itself needs to be compiled with \c --enable-shared for this to work.  Finally, download and unzip \c lxml, then run <tt> python setup.py install --prefix=$HOME/local </tt>.

@section create_doc Create documentation

This documentation is created by Doxygen with the Doxypy plugin.
To create new documentation or expand on what's here, follow the
examples in the source code or visit the Doxygen home page.

To create this documentation from the source files, go to the \c doc
directory in the distribution and run <tt> doxygen doxygen.cfg </tt>
to generate the HTML documentation and LaTeX source files.  Run the \c
add-tabs.py script to generate the extra navigation tabs for the HTML
documentation.  Then go to the \c latex directory and type in
<tt>make</tt> to build the PDF manual (You will need a LaTeX
distribution for this.)  All of this is automated by running \c make-all-documentation.sh.

@section install_gmxx2 Installing GROMACS-X2

<em> GROMACS-X2 is not required for %ForceBalance and is currently deprecated.  Installation is not recommended.  This section is retained for your information and in case I choose to revive the software. </em>

I have provided a specialized version of GROMACS (dubbed version
4.0.7-X2) on the <a href=https://simtk.org/home/forcebalance/>SimTK
website</a> which interfaces with %ForceBalance through the
abinitio_gmxx2 module.  Although interfacing with unmodified
simulation software is straightforward, GROMACS-X2 is optimized for
force field optimization and makes things much faster.  

GROMACS-X2 contains major modifications from GROMACS 4.0.7.
Most importantly, it enables computation of the objective function
<a>and its analytic derivatives</a> for rapid energy and force matching.  There
is also an implementation of the QTPIE fluctuating-charge polarizable
force field, and the beginnings of a GROMACS/Q-Chem interface
(carefully implemented but not extensively tested).  Most of the
changes were added in several new source files (less than ten): \c
qtpie.c, \c fortune.c, \c fortune_utils.c, \c fortune_vsite.c, \c
fortune_nb_utils.c, \c zmatrix.c and their corresponding header files,
and \c fortunerec.h for the force matching data structure.  The name 'fortune'
derives from back when this code was called ForTune.

The force matching functions are turned on by calling \c mdrun with
the command line argument \c '-fortune' ; without this option, there
should be no impact on the performance of normal MD simulations.

%ForceBalance interfaces with GROMACS-X2 through the functions in
\c abinitio_gmxx2.py ; the objective function and
derivatives are computed and printed to output files.  The interface
is defined in \c fortune.c on the GROMACS side.  %ForceBalance needs to know
where the GROMACS-X2 executables are located, and this is specified
using the \c gmxpath option in the input file.

@subsection install_gmxx2_prerequisites Prerequisites for GROMACS-X2

GROMACS-X2 needs the base GROMACS requirements and several other libraries.

@li FFTW version 3.3
@li GLib version 2.0
@li Intel MKL library

GLib is the utility library provided by the GNOME foundation (the
folks who make the GNOME desktop manager and GTK+ libraries).
GROMACS-X2 requires GLib for its hash table (dictionary).

GLib and FFTW can be compiled from source, but it is much easier if
you're using a Linux distribution with a package manager.  If you're
running Ubuntu or Debian, run <tt>sudo apt-get install libglib2.0-dev
libfftw3-dev</tt>; if you're using CentOS or some other distro with
the yum package manager, run <tt>sudo yum install glib2-devel.x86_64
fftw3-devel.x86_64</tt> (or replace \c x86_64 with \c i386 if you're
not on a 64-bit system.

GROMACS-X2 requires the Intel Math Kernel Library (MKL) for linear algebra.
In principle this requirement can be lifted if I rewrite the source
code, but it's a lot of trouble, plus MKL is faster than other
implementations of BLAS and LAPACK.

The Intel MKL can be obtained from the Intel website, free of charge
for noncommercial use.  Currently GROMACS-X2 is built with MKL version
10.2, which ships with compiler version 11.1/072 ; this is not the
newest version, but it can still be obtained from the Intel website
after you register for a free account.

After installing these packages, extract the tarball that you downloaded
from the website using the command:

@verbatim tar xvjf gromacs-[version]-x2.tar.bz2 @endverbatim

The directory structure is identical to GROMACS 4.0.7, but I added
some shell scripts. \c Build.sh will run the configure script using
some special options, compile the objects, create the executables and
install them; you will probably need to modify it slightly for your
environment.  The comments in the script will help further
with installation.

Don't forget to specify the install location of the GROMACS-X2 executables
in the %ForceBalance input file!
