Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

A fast solver for large scale MBAR/UWHAM equations

Project description

Build Status Anaconda-Server Badge

A Fast Solver for Large Scale MBAR/UWHAM Equations

The multistate Bennett acceptance ratio (MBAR) and unbinned weighted histogram analysis method (UWHAM) are widely imployed approaches to calculate free energies of multiple thermodynamcis states. They are routinely used in alchemical free energy calculations, umbrella sampling, and temperature/Hamiltonian replica exchange simulations to calculate free engies and potentials of mean force (PMF).

FastMBAR is a solver written in Python to solve large scale multistate Bennett acceptance ratio (MBAR)/unbinned weighted histogram analysis method (UWHAM) equations. Compared with the widely used python package pymbar, FastMBAR is 3 times faster on CPUs and more than two orders of magnitude faster on GPUs.

Installation

FastMBAR can be installed via conda or pip using the following commands:

  • using conda:

    • If you want to install FastMBAR and dependent packages in the main conda environment, run the command:
      conda install -c shawn_ding -c pytorch fastmbar.
    • If you want to install them in a specific conda environment, run the following commands:
      conda create -n myenv_name
      conda install -n myenv_name -c shawn_ding -c pytorch fastmbar,
      where you can replace myenv_name with whatever name you want.
  • using pip:
    pip install FastMBAR

Usage

The input to the MBAR/UWHAM equations are an energy (unitless) matrix and an integer array consisting of numbers of configurations sampled from states of interest. Let's say that we are interested in calculating relative free energies of a system in M thermodynamics states. The j th state has an energy function of Uj(x). From each of the first m states, system configurations x are sampled based on Boltzmann distributions. Let's assume that the number of configurations sampled from the j th state is nj, j = 1,2,...,m. To use these configurations to calculate the relative free energies of the M states using MBAR, we need to prepare the following energy matrix U in the blue bracket: Figure Elements of the above matrix are energies of all the sampled configurations evaluated in all M states. In addition to the energy matrix U, we also need an integer array v consisting of the numbers of configurations sampled from M states, i.e., v = (n1, n2, ..., nm, 0, 0, ..., 0). The last M-m elements of the array v is zeros because no configurations are sample from those states.

With the energy matrix U and the number of configuration array v, we can use the following Python command to calculate the relative free energies of the M states:

# import the FastMBAR package
import FastMBAR

# construct a FastMBAR object with the energy matrix and the number of configuration array
mbar = FastMBAR.FastMBAR(energy = U, num_conf = v, cuda=False) # set cuda = True if you want to run the calcuation on GPUs

# calcualte free energies by solving the MBAR equations
F = mbar.calculate_free_energies(bootstrap=False)

# if you want to estimate the uncertainty, change the above command into
# F, F_std = mbar.calculate_free_energies(bootstrap=True)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for FastMBAR, version 0.0.5
Filename, size File type Python version Upload date Hashes
Filename, size FastMBAR-0.0.5-py3-none-any.whl (8.6 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size FastMBAR-0.0.5.tar.gz (8.1 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page