A pure Python implementation of UWHAM.

Copyright 2012 Patrick Varilly.

Introduction
------------

UWHAM is an algorithm for stitching together data from umbrella sampling
simulations, and is closely related to MBAR and WHAM.  The key difference
is that the governing equations are solved by minimization of a convex
function instead of through self-consistent iteration, and so convergence
is *much* faster.

UWHAM:
  Zhiqiang Tan, Emilio Gallicchio, Mauro Lapelosa, and Ronald M. Levy,
  "Theory of binless multi-state free energy estimation with applications
  to protein-ligand binding", J. Chem. Phys. 136, 144102 (2012)
  http://dx.doi.org/10.1063/1.3701175 (14 pages)

MBAR:
   Michael R. Shirts and John D. Chodera,
   "Statistically optimal analysis of samples from multiple equilibrium states",
   J. Chem. Phys. 129, 124105 (2008)
   http://dx.doi.org/10.1063/1.2978177 (10 pages)

WHAM: Any modern molecular simulations textbook.  Original reference:
   Alan M. Ferrenberg and Robert H. Swendsen,
   "Optimized Monte Carlo data analysis",
   Phys. Rev. Lett. 63, 1195--1198 (1989)
   http://dx.doi.org/10.1103/PhysRevLett.63.1195 (4 pages)

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

  The uwham package relies on NumPy and SciPy to do its work.  Make sure
  these are installed (for Mac OS X users, see note below).  Then run the
  following command inside the uwham directory:

    python setup.py install --user

Basic usage
-----------

  import uwham
  import numpy as np

  # K umbrellas, N_k independent samples in each, labeled x_kn
  # kth umbrella has biasing potential u_k(x) in units of kT
  
  N_k = [...]     # Number of samples in each umbrella
  u_kln = [...]   # u_k(x_ln), in units of kT
                  #  The value of u_kln[k, l, n] is ignored if n >= N_k[l]

  results = uwham(u_kln, N_k)

  # weight_ln[l, n] = weight of x_ln in the absence of biasing potential
  # Its value is np.NaN if n >= N_k[l]
  assert np.abs(np.nansum(results.weight_ln) - 1.0) < 1e-5

  # f_k[k] = Free energy of umbrella k with respect to unbiased ensemble,
  # in units of kT
  print results.f_k

Detailed Example
---------------

  See test_uwham.py for a self-contained example of sampling a Gaussian
  distribution with lots of parabolic umbrellas.



Installation in OS X
--------------------

In Mac OS X, the usual automatic downloading of dependencies during a
python setup.py install isn't able to successfully install NumPy and SciPy
(in my machine, it's the lack of a Fortran compiler, but the SciPy docs
point to other potential problems).  So you have to download and install
NumPy and SciPy manually.

The good news: binaries are easily available
The bad news: they only work with the version of Python from
  http://www.python.org, not the version that ships with OS X!

So you have to download and install three things:

1. Python 2.7.2 from http://www.python.org/download
2. Latest version of NumPy from http://numpy.org
3. Latest version of SciPy from http://scipy.org

This is far less painful than it sounds.  In my own case, the disk images
that I ended up downloading were:

1. python-2.7.2-macosx10.6.dmg
2. numpy-1.6.1-py2.7-python.org-macosx10.6.dmg
3. scipy-0.10.0-py2.7-python.org-macosx10.6.dmg

CAREFUL: for some of these packages, the "link to the latest version" that
SourceForge suggests may be incorrect!  Do look at the full list of downloads
available and pick the one that is most appropriate to your own setup

Once you've installed python2.7, numpy and scipy, you can run the command

    python setup.py install --user