apallath/wham

Python package to construct free energy profiles from biased molecular simulation data using both log-likelihood maximization and self-consistent iteration approaches.

WHAM

Python package to construct free energy profiles from umbrella sampling simulation data.

Link to documentation.

Status

Code

Details

Binless formulation/MBAR (WHAM.binless) [more accurate]

• Implemented using log-likelihood maximization for superlinear convergence and self-consistent iteration (as a baseline/for debugging)
• Support for both 1D and multidimensional umbrella sampling.
• Support for reweighting 1D profiles to 2D (in a second related order parameter).

Binned formulation (WHAM.binned) [faster]

• Implemented using log-likelihood maximization for superlinear convergence and self-consistent iteration (as a baseline/for debugging)
• Support for both 1D and multidimensional^ umbrella sampling.

^-> in progress

Both log-likelihood maximization approaches can use multiple nonlinear optimization algorithms. Read the documentation to see which algorithms are available.

Installation

1. Install requirements

pip install -r requirements.txt

2. Build C extensions

python setup.py build_ext --inplace

3. Install package

pip install .

Usage

See the Jupyter notebooks in the examples/ directory.

Tests

Integration tests are in the directory tests/tests_integration and unit tests are in the directory tests/tests_unit. Navigate to a test directory and run:

pytest

References:

• Shirts, M. R., & Chodera, J. D. (2008). Statistically optimal analysis of samples from multiple equilibrium states. Journal of Chemical Physics, 129(12). DOI
• Zhu, F., & Hummer, G. (2012). Convergence and error estimation in free energy calculations using the weighted histogram analysis method. Journal of Computational Chemistry, 33(4), 453–465. DOI
• Tan, Z., Gallicchio, E., Lapelosa, M., & Levy, R. M. (2012). Theory of binless multi-state free energy estimation with applications to protein-ligand binding. Journal of Chemical Physics, 136(14). DOI

wham's Issues

Tests for bootstrapping

Initial guess for log-likelihood maximization approach

WHAM error implementation

Rewrite tests to match API changes.

Tests for serialization

Add tests for serialization of binless calc.

Optimization issues with log-likelihood maximization approach

When using an initial guess = correct solution + gaussian perturbation:

Nelder-mead does converges to a flat solution
BFGS with 2-point gradient estimation converges to a flat solution
BFGS with jac information does not move away from initial guess

Unexpected behavior, as the landscape is supposed to be convex.

Minor fixes

Remove explicit matrix repeat from binned.pyx

2D binless WHAM

• Write 2-D version of binless WHAM

Migrate NLL and grad NLL workers to C/C++ extensions.

Provide options to use/not use autograd.
Benchmark autograd v/s non-autograd (add tests as well).

Add 'fast' option for 2D binning in binless.Calc1D

method='fast' bins using scipy (without logsumexp, requires uniform bins).
method='slow' bins using current method (with logsumexp, does not require uniform bins).

Fix function import styles for umbrella potentials for consistency with Google style

Minor feature enhancements

Write C version of logsumexp -> clogsumexp
Move alogsumexp and clogsumexp to lib

Restart self-consistent WHAM from saved g_i?

Add functionality to pass initial guess g_i as an argument, which allows:

• restarting self consistent WHAM from last iteration, to iterate further, until convergence
• passing special initial guesses to log-likelihood WHAM.

Minor fixe

Write C version of logsumexp -> clogsumexp
Move alogsumexp and clogsumexp to lib

Minor fixes

Write C version of logsumexp -> clogsumexp
Move alogsumexp and clogsumexp to lib

WHAM for parallel tempering MC simulations at different temperatures?

Hey guys!

I'm struggling to create a probability distribution from some parallel tempering/replica exchange MC trajectories - it would be interesting to know if you've used this package to reweight and produce a density of states/probability distribution from replica-exchange trajectories each at different temperatures

Thanks,
Shanil

Add GitHub actions integration tests

Profiling and optimization

Make WHAM go faster!

Examples

Add Jupyter Notebook examples on US simulations of particle in a model potential (in OpenMM), for:

• 1D US
• 1D to phi-ensemble reweighting
• 1D to 2D reweighting
• 2D US
• Sparse sampling

Log-likelihood WHAM won't optimize on protein dewetting dataset.

Initial condition?

Output individual window biased free energies

Useful for future debugging purposes