 |
ForceBalance
1.7.4
Automated optimization of force fields and empirical potentials
|
|
ForceBalance
1.7.4
Automated optimization of force fields and empirical potentials
|
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 ForceBalance does not contain a simulation engine. 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.
As of version 1.7.4, ForceBalance is available as a package on the conda-forge channel. To install the package, make sure you are using an Anaconda/Miniconda Python distribution for Python versions 2.7, 3.5, 3.6, or 3.7, then run:
python setup.py install
This will install ForceBalance and all of the required dependencies. It will not install optional dependencies such as OpenMM, Gromacs, AMBER, Tinker, CCTools/Work Queue, or the Open Force Field toolkit.
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.
ForceBalance requires the following software packages:
The following packages are required for certain functionality:
The following packages are used for documentation:
To install the package, first extract the tarball that you downloaded from the webpage using the command:
tar xvzf ForceBalance-[version].tar.gz
Alternatively, download the newest Subversion revision from the SimTK website:
svn checkout https://simtk.org/svn/forcebalance
Upon extracting the distribution you will see this directory structure:
<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)
To install the code into your default Python location, run this (you might need to be root):
python setup.py install
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:
python setup.py install --prefix=/home/leeping/local
Assuming your Python version is 2.7, the executable scripts will be placed into /home/leeping/local/bin and the module will be placed into /home/leeping/local/lib/python2.7/site-packages/forcebalance.
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:
ln -s /home/leeping/local /home/leeping/.local
export PYTHONUSERBASE=/home/leeping/local
export PYTHONPATH=$PYTHONPATH:/home/leeping/local/lib/python2.7
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 Enthought website. Configure your environment by running both of the commands below (assuming Enthought was installed to /home/leeping/opt/epd-7.3.2 , with the python executable in the bin subdirectory):
export PATH=/home/leeping/opt/epd-7.3.2/bin:$PATH export PYTHONUSERBASE=/home/leeping/opt/epd-7.3.2
An alternative option is to use Anaconda2, that can be downloaded the Continuum website. It is also free for academic users.
export PATH=/home/leeping/opt/anaconda2/bin:$PATH
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.
pip package - simply run a command like pip install numpy. sudo apt-get install libblas-dev). 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 Intel's website. To use ATLAS, install the package from the ATLAS website and set the ATLAS environment variable (for example, export ATLAS=$HOME/local/lib/libatlas.so) before installing Scipy. lxml is a Python interface to the libxml2 XML parser. After much ado, I decided to use lxml instead of the xml module in Python's standard library for several reasons (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 lxml website but summarized here. The packages libxml2 and libxslt need to be installed first, and in that order. On Ubuntu, run sudo apt-get install libxml2-dev libxslt1-dev. To compile from source, run ./configure –prefix=$HOME/local –with-python=$HOME/local. Then run make followed by make install. Python itself needs to be compiled with –enable-shared for this to work. Finally, download and unzip lxml, then run python setup.py install –prefix=$HOME/local .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 doc directory in the distribution and run doxygen doxygen.cfg to generate the HTML documentation and LaTeX source files. Run the add-tabs.py script to generate the extra navigation tabs for the HTML documentation. Then go to the latex directory and type in make to build the PDF manual (You will need a LaTeX distribution for this.) All of this is automated by running make-all-documentation.sh.
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.
I have provided a specialized version of GROMACS (dubbed version 4.0.7-X2) on the SimTK website 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 and its analytic derivatives 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): qtpie.c, fortune.c, fortune_utils.c, fortune_vsite.c, fortune_nb_utils.c, zmatrix.c and their corresponding header files, and 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 mdrun with the command line argument '-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 abinitio_gmxx2.py ; the objective function and derivatives are computed and printed to output files. The interface is defined in fortune.c on the GROMACS side. ForceBalance needs to know where the GROMACS-X2 executables are located, and this is specified using the gmxpath option in the input file.
GROMACS-X2 needs the base GROMACS requirements and several other libraries.
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 sudo apt-get install libglib2.0-dev libfftw3-dev; if you're using CentOS or some other distro with the yum package manager, run sudo yum install glib2-devel.x86_64 fftw3-devel.x86_64 (or replace x86_64 with 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:
tar xvjf gromacs-[version]-x2.tar.bz2
The directory structure is identical to GROMACS 4.0.7, but I added some shell scripts. 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!
1.8.13