An open tool implementing some recommended practices for analyzing alchemical free energy calculations
Latest commit 429256f Oct 14, 2016 @davidlmobley davidlmobley committed on GitHub Merge pull request #93 from mrshirts/master
Fix for when expanded ensemble files don't have samples in all states

Alchemical Analysis: An open tool implementing some recommended practices for analyzing alchemical free energy calculations

Analyze alchemical free energy calculations conducted in GROMACS, AMBER or SIRE using recommended best practices from Klimovich et al., JCAMD 29:397-411 (2015).

This tool handles analysis via a slate of free energy methods, including BAR, MBAR, TI, and the Zwanzig relationship (exponential averaging) among others, and provides a good deal of analysis of computed free energies and convergence in order to help you assess the quality of your results.

If you have problems with this tool, please use the github issue tracker.

Citation DOI for Citing Alchemical Analysis

Alchemical Analysis is research software. If you make use of it in work which you publish, please cite it. The BibTex reference is

author = {Klimovich, Pavel V and Shirts, Michael R and Mobley, David L},
title = {Guidelines for the analysis of free energy calculations},
journal = {J Comput Aided Mol Des},
year = {2015},
volume = {29},
number = {5},
pages = {397--411},
doi = {10.1007/s10822-015-9840-9}


Alchemical Analysis requires the pymbar module (we recommend installation via conda, but other options are also available). Version 3.0.0.dev0 or above is required. The latest version of pymbar can be found here.

Python 2 is required.


git clone
cd alchemical-analysis
sudo python install


Script: alchemical_analysis

This implements recommended practices for analyzing alchemical free energy calculations, as described in Klimovich et al., JCAMD 29:397-411 (2015). This was motivated in part by earlier work illustrating how to apply MBAR to alchemical free energy calculations (and a comparison with other methods) in Paliwal and Shirts, J. Chem. Theory Comp, v. 7, 4115-4134 (2011).

See description in samples/gromacs/, samples/sire/, and samples/amber/

Help for (obtained with alchemical_analysis -h) is:

  -h, --help            show this help message and exit
  -a SOFTWARE, --software=SOFTWARE
                        Package's name the data files come from: Gromacs,
                        Sire, or AMBER. Default: Gromacs.
  -c, --cfm             The Curve-Fitting-Method-based consistency inspector.
                        Default: False.
                        Directory in which data files are stored. Default:
                        Current directory.
  -f BFORWREV, --forwrev=BFORWREV
                        Plotting the free energy change as a function of time
                        in both directions. The number of time points (an
                        integer) is to be followed the flag. Default: 0
  -g, --breakdown       Plotting the free energy differences evaluated for
                        each pair of adjacent states for all methods. Default:
                        Perform the analysis with rather all the data if the
                        number of uncorrelated samples is found to be less
                        than this number. If 0 is given, the time series
                        analysis will not be performed at all. Default: 50.
                        Give a string of lambda indices separated by '-' and
                        they will be removed from the analysis. (Another
                        approach is to have only the files of interest present
                        in the directory). Default: None.
  -m METHODS, --methods=METHODS
                        A list of the methods to esitimate the free energy
                        with. Default: [TI, TI-CUBIC, DEXP, IEXP, BAR, MBAR].
                        To add/remove methods to the above list provide a
                        string formed of the method strings preceded with +/-.
                        For example, '-ti_cubic+gdel' will turn methods into
                        [TI, DEXP, IEXP, BAR, MBAR, GDEL]. 'ti_cubic+gdel', on
                        the other hand, will call [TI-CUBIC, GDEL]. 'all'
                        calls the full list of supported methods [TI, TI-
                        CUBIC, DEXP, IEXP, GINS, GDEL, BAR, UBAR, RBAR, MBAR].
                        Directory in which the output files produced by this
                        script will be stored. Default: Same as
  -p PREFIX, --prefix=PREFIX
                        Prefix for datafile sets, i.e.'dhdl' (default).
  -q SUFFIX, --suffix=SUFFIX
                        Suffix for datafile sets, i.e. 'xvg' (default).
  -r DECIMAL, --decimal=DECIMAL
                        The number of decimal places the free energies are to
                        be reported with. No worries, this is for the text
                        output only; the full-precision data will be stored in
                        'results.pickle'. Default: 3.
  -s EQUILTIME, --skiptime=EQUILTIME
                        Discard data prior to this specified time as
                        'equilibration' data. Units picoseconds. Default: 0
                        Temperature in K. Default: 298 K.
  -u UNITS, --units=UNITS
                        Units to report energies: 'kJ', 'kcal', and 'kBT'.
                        Default: 'kJ'
  -v, --verbose         Verbose option. Default: False.
  -w, --overlap         Print out and plot the overlap matrix. Default: False.
  -x, --ignoreWL        Do not check whether the WL weights are equilibrated.
                        No log file needed as an accompanying input.
                        Convergence criterion for the energy estimates with
                        BAR and MBAR. Default: 1e-10.
  -z INIT_WITH, --initialize=INIT_WITH
                        The initial MBAR free energy guess; either 'BAR' or
                        'zeroes'. Default: 'BAR'.


GNU LGPL version 2.1. See the supplied license file for additional details.