alchemlyb

alchemlyb is a library designed to simplify alchemical free energy calculations. It provides flexible, composable building blocks for the entire analysis pipeline, including:

• Parsing: Extracting data from common Molecular Dynamics (MD) engine formats.
• Subsampling/Preprocessing: Preparing and cleaning data.
• Estimation: Fitting data with estimators to obtain free energies.
• Visualization: Plotting results.

The library is designed to be simple and modular, allowing users to chain functions together for customized workflows. It supports scaling from single workstations to large datasets using distributed computing libraries like dask.

alchemlyb is a library designed to simplify alchemical free energy calculations by integrating with the PyData stack. Its core functionality is divided into three main stages of the alchemical workflow:

1. Parsing: Extracting raw data from output files of common molecular dynamics engines (e.g., GROMACS, AMBER, NAMD).
2. Subsampling: Obtaining uncorrelated samples from timeseries data, including methods for extracting independent, equilibrated samples.
3. Estimation: Calculating free energies directly from the processed data using best-practice approaches like Multistate Bennett Acceptance Ratio (MBAR), Bennett Acceptance Ratio (BAR), and Thermodynamic Integration (TI).

The alchemlyb.convergence module provides building blocks for performing convergence analysis. These functions typically operate on lists of raw data and perform one of two tasks:

1. Run estimators on data sets to obtain free energies as a function of the amount of data.
2. Directly assess the convergence of the raw data.

For convenience, the most important functions are exposed directly at the alchemlyb.convergence level, even though they are defined in the alchemlyb.convergence.convergence submodule.

The alchemlyb.parsing.namd module provides parsers for NAMD .fepout output files. These files contain derivatives of the Hamiltonian and Free Energy Perturbation (FEP/BAR) data.

To perform BAR (Bennett Acceptance Ratio) analysis, you must provide the .fepout files from both the forward and reverse transformations.

In alchemlyb, estimators are used to calculate free energy differences from raw alchemical data. The library follows a design pattern similar to scikit-learn, making it intuitive for users familiar with that ecosystem.

Estimators in alchemlyb are categorized into two main varieties:

1. TI-based estimators: Based on Thermodynamic Integration.
2. FEP-based estimators: Based on Free Energy Perturbation.

To obtain free energies, you select an appropriate estimator implementation based on your data type and the specific alchemical method used.

If your simulations were performed specifically at Gaussian quadrature points, use alchemlyb.estimators.TI_GQ.

Key differences from TI:

• Cumulative Values: In TI_GQ, the values in the .delta_f_ and .d_delta_f_ tables represent the cumulative addition of the estimation from one $\lambda$ window to the next, rather than pairwise differences between all windows.
• Endpoint Handling: To maintain consistency with other estimators, TI_GQ sets diagonal values to zero and adds two end states at $\lambda=0$ and $\lambda=1$. Even if simulations were not performed at exactly 0 or 1, the value at $\lambda=0$ is set to zero, and the value at $\lambda=1$ is set to the value of the previous Gaussian quadrature point.

from alchemlyb.estimators import TI_GQ

# Usage is similar to TI
tigq = TI_GQ().fit(dHdl_data)
# Note: delta_f_ contains cumulative sums

The alchemlyb.estimators.TI_GQ estimator implements thermodynamic integration using Gaussian quadrature. It integrates the space between $\left<\frac{dH}{d\lambda}\right>$ values for each sampled $\lambda$.

Requirements for use: To use this estimator correctly, your simulations must be performed at specific $\lambda$ values corresponding to fixed Gaussian quadrature points. The estimator currently supports up to 16 Gaussian quadrature points.

To ensure unit conversion functions work correctly, you must preserve metadata (specifically energy_unit and temperature) in the .attrs attribute of your DataFrames.

When writing custom code or functions that manipulate DataFrames, follow these patterns:

1. Use alchemlyb.concat instead of pandas.concat to ensure metadata is handled correctly during concatenation.
2. Use the @alchemlyb.pass_attrs decorator on your functions to automatically copy metadata from input DataFrames to the output DataFrame.