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 and Michael R. Shirts . =============================================================================== 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.