alchemlyb: the simple alchemistry library

2.5.0 · active · verified Wed Apr 15

alchemlyb is a Python library for the analysis of alchemical free energy calculations, a crucial method in computational chemistry and biology. It provides flexible building blocks for parsing data from molecular dynamics engines, subsampling time series data, and estimating free energies using best-practice approaches like Multistate Bennett Acceptance Ratio (MBAR), Bennett Acceptance Ratio (BAR), and Thermodynamic Integration (TI). The library also offers high-level, end-to-end workflows for streamlined analysis. It is currently at version 2.5.0 and under active development, adhering to semantic versioning to ensure API stability within major releases.

Warnings

breaking alchemlyb 2.x releases (including 2.5.0) require `pymbar >= 4.0`. They are incompatible with `pymbar 3.x`. Ensure your `pymbar` installation is updated when upgrading to alchemlyb 2.x.
Fix: pip install --upgrade pymbar>=4.0
breaking alchemlyb 2.2.0 and later versions require `pandas >= 2.1`. Using older versions of pandas may lead to unexpected behavior or errors, particularly with metadata loading from parquet files.
Fix: pip install --upgrade pandas>=2.1
gotcha When concatenating alchemlyb DataFrames, standard `pandas.concat()` may not correctly propagate `alchemlyb`'s metadata. Always use `alchemlyb.concat()` to ensure metadata (such as temperature and energy units) is safely maintained.
Fix: Replace `pandas.concat()` with `alchemlyb.concat()`.
deprecated Support for Python 3.8 was removed in alchemlyb 2.2.0. The current 2.5.0 release supports Python 3.11 - 3.14.
Fix: Upgrade your Python environment to 3.11 or newer.
gotcha Since alchemlyb 2.1.0, the library switched from the standard `logging` module to `loguru` for logging. If you have custom logging configurations, you may need to adapt them for `loguru`.
Fix: Review `loguru` documentation for custom logging setups.
gotcha A fix in version 2.0.1 changed the behavior of the `dE` method in `u_nk2series` to correctly use the difference between two lambda columns. Users relying on the previous (potentially incorrect) calculation might see different results.
Fix: Verify that the updated `dE` calculation aligns with expected results in your analyses.

Install

pip install alchemlyb Install stable release

Imports

extract_u_nk

from alchemlyb.parsing.gmx import extract_u_nk

extract_dHdl

from alchemlyb.parsing.gmx import extract_dHdl

decorrelate_u_nk

from alchemlyb.preprocessing.subsampling import decorrelate_u_nk

MBAR
```
from alchemlyb.estimators import MBAR
```
ABFE
```
from alchemlyb.workflows import ABFE
```
concat
```
from alchemlyb import concat
```
Use alchemlyb.concat() to ensure metadata propagation for alchemlyb DataFrames.

Quickstart

This quickstart demonstrates how to use the high-level `ABFE` workflow to automatically analyze absolute binding free energy calculations, requiring only a few lines of code. It uses example GROMACS data provided by the `alchemtest` library to parse files, perform data preprocessing, estimate free energies using MBAR, BAR, and TI estimators, and generate diagnostic plots.

import os
from alchemtest.gmx import load_ABFE
from alchemlyb.workflows import ABFE

# This example uses test data from the alchemtest library. 
# Ensure alchemtest is installed: `pip install alchemtest`

# Obtain the path of the data
dir_path = os.path.dirname(load_ABFE()['data']['complex'][0])

# Initialize and run the Absolute Binding Free Energy (ABFE) workflow
workflow = ABFE(
    units='kcal/mol', 
    software='GROMACS', 
    dir=dir_path, 
    prefix='dhdl', 
    suffix='xvg', 
    T=298, 
    outdirectory='./alchemlyb_output'
)

# Execute the complete workflow with specified parameters
result = workflow.run(
    skiptime=10, 
    uncorr='dhdl', 
    threshold=50, 
    estimators=('MBAR', 'BAR', 'TI'), 
    overlap='O_MBAR.pdf', 
    breakdown=True, 
    forwrev=10
)

print("Free energy estimates:")
print(result)

view raw JSON →