alchemlyb: the simple alchemistry library

2.5.0 verified Wed Apr 15 auth: no python

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.

pip install alchemlyb

Common errors

error ModuleNotFoundError: No module named 'alchemlyb' ↓

cause The 'alchemlyb' library is not installed in the Python environment.

fix

Install the library using pip: 'pip install alchemlyb'.

error ImportError: cannot import name 'extract_dHdl' from 'alchemlyb.parsing.gmx' ↓

cause The function 'extract_dHdl' is not available in the 'alchemlyb.parsing.gmx' module.

fix

Ensure you are using the correct function name and that your 'alchemlyb' version supports it.

error ValueError: The input should be u_nk ↓

cause The function expects input data in the 'u_nk' format, but received a different format.

fix

Convert your input data to the 'u_nk' format before passing it to the function.

error DeprecationWarning: Method 'dhdl' has been deprecated, using 'dE' instead. 'dhdl' will be removed in alchemlyb 3.0.0. ↓

cause The 'dhdl' method is deprecated and will be removed in future versions.

fix

Update your code to use the 'dE' method instead of 'dhdl'.

error DeprecationWarning: Method 'dhdl_all' has been deprecated, using 'all' instead. 'dhdl_all' will be removed in alchemlyb 3.0.0. ↓

cause The 'dhdl_all' method is deprecated and will be removed in future versions.

fix

Update your code to use the 'all' method instead of 'dhdl_all'.

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.

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
wrong
```
import pandas; pandas.concat()
```
correct
```
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)