<commit_before>[![Build Status](https://travis-ci.org/choderalab/pymbar.png)](https://travis-ci.org/choderalab/pymbar)
[![PyPI Version](https://badge.fury.io/py/pymbar.png)](https://pypi.python.org/pypi/pymbar)
[![Downloads](https://pypip.in/d/pymbar/badge.png)](https://pypi.python.org/pypi/pymbar)

pymbar
======

Python implementation of the multistate Bennett acceptance ratio (MBAR) method for estimating expectations and free energy differences.  See our [Docs](http://pymbar.readthedocs.org/en/latest/).

Authors
-------
* <NAME> <<EMAIL>>
* <NAME> <<EMAIL>>
* <NAME> <<EMAIL>>

Manifest
--------

This archive contains the following files:

* `README.md` - this file
* `LICENSE` - a copy of the GNU General Public License version 2 covering this code
* `pymbar/` - Python MBAR package
* `examples/` - examples of applications of MBAR to various types of calculations
  See the README.md in that folder for more information
* `tests/` - unit tests for the functionality
* `docs/` - sphinx documetation
* `devtools/` - travis CI and conda configuration files

Prerequisites
-------------

The pymbar module requires the following:

* Python 2.4 or later: http://www.python.org/
* The `Python.h` header file (either installed via the Python installer, but a separate `python-dev` package on distributions like Ubunti)
* the NumPy package: http://numpy.scipy.org/
* the SciPy package: http://www.scipy.org/
* Some optional graphing functionality in the tests requires the matplotlib library: http://matplotlib.sourceforge.net/

Many of these packages are now standard in scientific Python installations or bundles, such as [Enthought Canopy](https://www.enthought.com/products/canopy/) or [continuum.io Anaconda](http://continuum.io/).

Installation
------------

There are several ways to install pymbar.

You can grab the latest version from the [Python Package Index (PyPI)](https://pypi.python.org/pypi/pymbar) with `easy_install`:
```tcsh
easy_install pymbar
```
or using `pip install`:
```tcsh
pip install pymbar==2.1.0-beta
```

The bleeding-edge development version can be installed using [conda](http://conda.pydata.org) via
```tcsh
conda install -c https://conda.binstar.org/omnia pymbar-dev
```

If you see an error like
```
gcc -pthread -fno-strict-aliasing -DNDEBUG -g -fwrapv -O2 -Wall -Wstrict-prototypes -fPIC -I/usr/lib/python2.7/dist-packages/numpy/core/include -I/usr/lib/python2.7/dist-packages/numpy/core/include/numpy/ -I/usr/include/python2.7 -c pymbar/_pymbar.c -o build/temp.linux-x86_64-2.7/pymbar/_pymbar.o -std=c99 -O2 -shared -msse2 -msse3

pymbar/_pymbar.c:80:20: fatal error: Python.h: No such file or directory

#include "Python.h"
```
and you are using a Linux distro like Ubuntu, you may need to also install the `python-dev` package:
```
sudo apt-get install python-dev
```

If you download the [GitHub version](http://github.com/choderalab/pymbar), you can use the provided `setup.py` to install.

To install to your default Python site-packages location:
```tcsh
# python setup.py install
```
Or to install to a different location (e.g. a local Python package repository):
```tcsh
# python setup.py install --prefix=/path/to/my/site-packages/
```
The C++ helper code will automatically be built in both cases, if possible.

To build pymbar in situ, without installing to site-packages, run
```tcsh
# python setup.py build
```
and add the directory containing this file to your PYTHONPATH environment variable.
```tcsh
# For tcsh
setenv PYTHONPATH "/path/to/pymbar:$PYTHONPATH"
# For bash
export PYTHONPATH="/path/to/pymbar:$PYTHONPTH"
```

Usage
-----

In Python 2.4 or later, you can view the docstrings with `help()`:
```python
>>> 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:
```python
>>> mbar = MBAR(u_kln, N_k)
```
Next, we extract the dimensionless free energy differences and uncertainties:
```python
>>> (Deltaf_ij_estimated, dDeltaf_ij_estimated) = mbar.getFreeEnergyDifferences()
```
or compute expectations of given observables A(x) for all states:
```python
>>> (A_k_estimated, dA_k_estimated) = mbar.computeExpectations(A_kn)
```
See the help for these individual methods for more information on exact usage.

Examples
--------

Several examples of applications of `pymbar` to various types of simulation data can be found in [pymbar-examples](http://github.com/choderalab/pymbar-examples/).

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:
```python
method = 'Newton-Raphson'
```
to the MBAR initialization, as in 
```python
>>> 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.
```python
>>> mbar = pymbar.MBAR(u_kln, N_k, use_optimized = False)
```

References
----------

* Please cite the original MBAR paper:

  Shirts MR and Chodera JD. Statistically optimal analysis of samples from multiple equilibrium states. J. Chem. Phys. 129:124105 (2008).  [DOI](http://dx.doi.org/10.1063/1.2978177)
  
* Some timeseries algorithms can be found in the following reference:

  Chodera JD, Swope WC, Pitera JW, Seok C, and <NAME>. Use of the weighted histogram analysis method for the analysis of simulated and parallel tempering simulations. J. Chem. Theor. Comput. 3(1):26-41 (2007).  [DOI](http://dx.doi.org/10.1021/ct0502864)

  
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, (c) 2008-2013 University of Virginia, and (c) 2013 Memorial Sloan-Kettering Cancer Center.

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.

Thanks
------

We would especially like to thank a large number of people for helping us identify issues
and ways to improve `pymbar`, including <NAME>, <NAME>, <NAME>, 
<NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, 
<NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, 
<NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, 
<NAME>, <NAME>, <NAME>, <NAME>, <NAME>, and <NAME>.<commit_msg>Fixes to README<commit_after>[![Build Status](https://travis-ci.org/choderalab/pymbar.png)](https://travis-ci.org/choderalab/pymbar)
[![PyPI Version](https://badge.fury.io/py/pymbar.png)](https://pypi.python.org/pypi/pymbar)
[![Downloads](https://pypip.in/d/pymbar/badge.png)](https://pypi.python.org/pypi/pymbar)
[![Binstar Badge](https://binstar.org/omnia/pymbar/badges/installer/conda.svg)](https://conda.binstar.org/omnia)

pymbar
======

Python implementation of the multistate Bennett acceptance ratio (MBAR) method for estimating expectations and free energy differences.  See our [Docs](http://pymbar.readthedocs.org/en/latest/).

Authors
-------
* <NAME> <<EMAIL>>
* <NAME> <<EMAIL>>
* <NAME> <<EMAIL>>


Manifest
--------

This archive contains the following files:

* `README.md` - this file
* `LICENSE` - a copy of the GNU General Public License version 2 covering this code
* `pymbar/` - Python MBAR package
* `examples/` - examples of applications of MBAR to various types of calculations
  See the README.md in that folder for more information
* `tests/` - unit tests for the functionality
* `docs/` - sphinx documetation
* `devtools/` - travis CI and conda configuration files

Prerequisites
-------------

The pymbar module requires the following:

* Python 2.4 or later: http://www.python.org/
* The `Python.h` header file (either installed via the Python installer, but a separate `python-dev` package on distributions like Ubunti)
* the NumPy package: http://numpy.scipy.org/
* the SciPy package: http://www.scipy.org/
* Some optional graphing functionality in the tests requires the matplotlib library: http://matplotlib.sourceforge.net/

Quickstart
----------

The easiest way to install `pymbar` is via [conda](http://conda.pydata.org), a binary package installer that comes with the [Anaconda Scientific Python distribution](https://store.continuum.io/cshop/anaconda/):
```tcsh
conda install -c https://conda.binstar.org/omnia pymbar
```
If you don't have `conda` installed but do have `pip`, you can install it with:
```tcsh
pip install conda
```

Alternatives
------------

There are several other ways to install pymbar.

You can grab the latest version from the [Python Package Index (PyPI)](https://pypi.python.org/pypi/pymbar) with `easy_install`:
```tcsh
easy_install pymbar
```
or using `pip install`:
```tcsh
pip install pymbar
```

Or, if you download the [GitHub version](http://github.com/choderalab/pymbar), you can use the provided `setup.py` to install.

To install to your default Python site-packages location:
```tcsh
python setup.py install
```
Or to install to a different location (e.g. a local Python package repository):
```tcsh
python setup.py install --prefix=/path/to/my/site-packages/
```
The C++ helper code will automatically be built in both cases, if possible.

To build pymbar in situ, without installing to site-packages, run
```tcsh
python setup.py build
```
and add the directory containing this file to your PYTHONPATH environment variable.
```tcsh
# For tcsh
setenv PYTHONPATH "/path/to/pymbar:$PYTHONPATH"
# For bash
export PYTHONPATH="/path/to/pymbar:$PYTHONPATH"
```

Usage
-----

In Python 2.6 or later, you can view the docstrings with `help()`:
```python
>>> 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:
```python
>>> mbar = MBAR(u_kln, N_k)
```
Next, we extract the dimensionless free energy differences and uncertainties:
```python
>>> (Deltaf_ij_estimated, dDeltaf_ij_estimated) = mbar.getFreeEnergyDifferences()
```
or compute expectations of given observables A(x) for all states:
```python
>>> (A_k_estimated, dA_k_estimated) = mbar.computeExpectations(A_kn)
```
See the help for these individual methods for more information on exact usage.

Examples
--------

Several examples of applications of `pymbar` to various types of simulation data can be found in [pymbar-examples](http://github.com/choderalab/pymbar-examples/).


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:
```python
method = 'Newton-Raphson'
```
to the MBAR initialization, as in 
```python
>>> 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.
```python
>>> mbar = pymbar.MBAR(u_kln, N_k, use_optimized = False)
```

References
----------

* Please cite the original MBAR paper:

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

* Some timeseries algorithms can be found in the following reference:

  Chodera JD, Swope WC, Pitera JW, Seok C, and <NAME>. Use of the weighted histogram analysis method for the analysis of simulated and parallel tempering simulations. J. Chem. Theor. Comput. 3(1):26-41 (2007).  [DOI](http://dx.doi.org/10.1021/ct0502864)


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, (c) 2008-2014 University of Virginia, and (c) 2014 Memorial Sloan-Kettering Cancer Center.

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.

Thanks
------

We would especially like to thank a large number of people for helping us identify issues
and ways to improve `pymbar`, including <NAME>, <NAME>, <NAME>,
<NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>,
<NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>,
<NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>,
<NAME>, <NAME>, <NAME>, <NAME>, <NAME>, and <NAME>.
{'fraction_non_alphanumeric': 0.11497424576894776, 'fraction_numerical': 0.013551631101299975, 'mean_word_length': 4.310647997394986, 'pattern_counts': {'":': 0, '<': 79, '<?xml version=': 0, '>': 121, 'https://': 20, 'lorem ipsum': 0, 'www.': 5, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4564714', 'n_tokens_mistral': 5102, 'n_tokens_neox': 4705, 'n_words': 2001}