{"id":6307,"library":"alchemlyb","title":"alchemlyb: the simple alchemistry library","description":"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.","status":"active","version":"2.5.0","language":"en","source_language":"en","source_url":"https://github.com/alchemistry/alchemlyb","tags":["free energy","molecular dynamics","computational chemistry","alchemistry","data analysis","pandas","biophysics","cheminformatics"],"install":[{"cmd":"pip install alchemlyb","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Core data structure (DataFrame) and data manipulation; requires >= 2.1 for alchemlyb >= 2.2.0.","package":"pandas","optional":false},{"reason":"Backend for MBAR and BAR estimators; alchemlyb 2.x requires >= 4.0.","package":"pymbar","optional":false},{"reason":"Fundamental numerical computing library, part of the PyData stack.","package":"numpy","optional":false},{"reason":"Used for logging since alchemlyb 2.1.0.","package":"loguru","optional":false},{"reason":"Provides test data used in tutorials and examples.","package":"alchemtest","optional":true}],"imports":[{"symbol":"extract_u_nk","correct":"from alchemlyb.parsing.gmx import extract_u_nk"},{"symbol":"extract_dHdl","correct":"from alchemlyb.parsing.gmx import extract_dHdl"},{"symbol":"decorrelate_u_nk","correct":"from alchemlyb.preprocessing.subsampling import decorrelate_u_nk"},{"symbol":"MBAR","correct":"from alchemlyb.estimators import MBAR"},{"symbol":"ABFE","correct":"from alchemlyb.workflows import ABFE"},{"note":"Use alchemlyb.concat() to ensure metadata propagation for alchemlyb DataFrames.","wrong":"import pandas; pandas.concat()","symbol":"concat","correct":"from alchemlyb import concat"}],"quickstart":{"code":"import os\nfrom alchemtest.gmx import load_ABFE\nfrom alchemlyb.workflows import ABFE\n\n# This example uses test data from the alchemtest library. \n# Ensure alchemtest is installed: `pip install alchemtest`\n\n# Obtain the path of the data\ndir_path = os.path.dirname(load_ABFE()['data']['complex'][0])\n\n# Initialize and run the Absolute Binding Free Energy (ABFE) workflow\nworkflow = ABFE(\n    units='kcal/mol', \n    software='GROMACS', \n    dir=dir_path, \n    prefix='dhdl', \n    suffix='xvg', \n    T=298, \n    outdirectory='./alchemlyb_output'\n)\n\n# Execute the complete workflow with specified parameters\nresult = workflow.run(\n    skiptime=10, \n    uncorr='dhdl', \n    threshold=50, \n    estimators=('MBAR', 'BAR', 'TI'), \n    overlap='O_MBAR.pdf', \n    breakdown=True, \n    forwrev=10\n)\n\nprint(\"Free energy estimates:\")\nprint(result)","lang":"python","description":"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."},"warnings":[{"fix":"pip install --upgrade pymbar>=4.0","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"pip install --upgrade pandas>=2.1","message":"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.","severity":"breaking","affected_versions":">=2.2.0"},{"fix":"Replace `pandas.concat()` with `alchemlyb.concat()`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade your Python environment to 3.11 or newer.","message":"Support for Python 3.8 was removed in alchemlyb 2.2.0. The current 2.5.0 release supports Python 3.11 - 3.14.","severity":"deprecated","affected_versions":">=2.2.0"},{"fix":"Review `loguru` documentation for custom logging setups.","message":"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`.","severity":"gotcha","affected_versions":">=2.1.0"},{"fix":"Verify that the updated `dE` calculation aligns with expected results in your analyses.","message":"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.","severity":"gotcha","affected_versions":">=2.0.1"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}