A Python implementation of the multistate Bennett acceptance ratio (MBAR) method
described in reference [1] below.

===============================================================================
REFERENCES
===============================================================================

[1] Shirts MR and Chodera JD. Statistically optimal analysis of samples from
multiple equilibrium states.  J. Chem. Phys. 129:124105, 2008.
http://dx.doi.org/10.1063/1.2978177

AUTHORS

Written by John D. Chodera <jchodera@gmail.com> and Michael R. Shirts
<michael.shirts@virginia.edu>.

===============================================================================
COPYRIGHT NOTICE
===============================================================================

Copyright (c) 2006-2012 The Regents of the University of California.  All Rights
Reserved.  Portions of this software are Copyright (c) 2007-2008 Stanford
University and Columbia University, and (c) 2008-2013 University of Virginia.

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.
 
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.
 
You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
Street, Fifth Floor, Boston, MA 02110-1301, USA.

===============================================================================
MANIFEST
===============================================================================

This archive contains the following files:

README - this file
GPL - a copy of the GNU General Public License version 2
pymbar/ - Python MBAR package
examples/ - examples of applications of MBAR to various types of experiments

All but examples are downloaded as pymbar-2.0.tgz, and the examples
are downloaded as pymbar-examples.tgz, but will unpack into the same
directory.

===============================================================================
REQUIREMENTS
===============================================================================

The pymbar module requires Python 2.4 or later:

http://www.python.org/

and the NumPy package for array support:

http://numpy.scipy.org/

Some examples also require the SciPy package:

http://www.scipy.org/

Some optional graphing functionality in the tests requires the matplotlib library

http://matplotlib.sourceforge.net/

===============================================================================
INSTALLATION
===============================================================================

Change to the pymbar/ directory, and use the provided setup.py to install.

To build pymbar in site, without installing to site-packages, run

# python setup.py build

And add the directory containing this file to your PYTHONPATH environment
variable.

# For tcsh
setenv PYTHONPATH "/path/to/pymbar:$PYTHONPATH"
# For bash
export PYTHONPATH="/path/to/pymbar:$PYTHONPTH"

To install to your default Python site-packages location:

# python setup.py install

Or to install to a different location (e.g. a local Python package repository):

# python setup.py --prefix=/path/to/my/site-packages/

The C++ helper code will automatically be built in both cases, if possible.

===============================================================================
USAGE
===============================================================================

In Python 2.4 or later, you can view the docstrings with help():

>>> from pymbar import MBAR
>>> help(MBAR)

See the example code in the docstrings, or find more elaborate examples in the
examples/ directory.

Basic usage involves first constructing a MBAR object, initializing it with the
reduced potential from the simulation or experimental data:

>>> mbar = pymbar.MBAR(u_kln, N_k)

Next, we extract the dimensionless free energy differences and uncertainties:

>>> (Deltaf_ij_estimated, dDeltaf_ij_estimated) = mbar.getFreeEnergyDifferences()

or compute expectations of given observables A(x) for all states:

>>> (A_k_estimated, dA_k_estimated) = mbar.computeExpectations(A_kn)

See the help for these individual methods for more information on exact usage.

===============================================================================
OPTIMIZATIONS AND IMPROVEMENTS
===============================================================================

By default, the pymbar class uses an adaptive method which uses
self-consistent iteration initially and switches to Newton-Raphson
iteration (with N-R implemented as described in the Appendix of
Ref. [1]) when the norm of the gradient of a Newton-Raphson step is
lower than the norm of the gradient of a self-consistent step.
Self-consistent iteration or Newton-Raphson can be selected instead if
desired.  For example, to use the Newton-Raphson solver alone, add the
optional argument:

method = 'Newton-Raphson'

to the MBAR initialization, as in 

>>> mbar = MBAR.MBAR(u_kln, N_k, method = 'Newton-Raphson')

In very rare cases, the self-consistent iteration may still work when
the adaptive method switches to Newton-Raphson prematurely.

* C++ helper code

We have provided a C++ helper code ('_pymbar.c') to speed up the most
time-consuming operation in computing the dimensionless free energies (used by
all methods).  For many applications, use of the compiled helper code results in
a speedup of ~40x.  There should be no significant difference in the output (if
any) between the pure-Python/Numpy results and those employing the helper
routine.  

The routine should be installed correctly using the setup.py script,
but if it fails, instructions on compilation for several platforms can
be found in the header of _pymbar.c

pymbar.py will import and use the compiled dynamic library (_pymbar.so) provided it
can be found in your PYTHONPATH.  An optional 'use_optimized' flag passed to the
MBAR constructor can be used to force or disable this behavior.  Passing the
flag use_optimized = False to the MBAR initialization will disable use of the
module.

>>> mbar = pymbar.MBAR(u_kln, N_k, use_optimized = False)

===============================================================================
THANKS
===============================================================================

We would especially like to thank a large number of testers for pymbar
for helping us identify issues and ways to improve with the previous
pymbar release, including Tommy Knotts, David Mobley, Himanshu Paliwal,
Zhiqiang Tan, Patrick Varilly, Todd Gingrich, Aaron Keys, Anna Schneider,
Adrian Roitberg, Nick Schafer, Thomas Speck, Troy van Voorhis, Gupreet Singh,
Jason Wagoner, Gabriel Rocklin, Yannick Spill, Ilya Chorny, Greg Bowman, 
Vincent Voelz, Peter Kasson, Sam Moors, Carl Rogers, Josua Adelman, 
Javier Palacios, David Chandler, and Andrew Jewett.

