{"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":"python","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-05-23T18:03:50.405Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Install the library using pip: 'pip install alchemlyb'.","cause":"The 'alchemlyb' library is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'alchemlyb'"},{"fix":"Ensure you are using the correct function name and that your 'alchemlyb' version supports it.","cause":"The function 'extract_dHdl' is not available in the 'alchemlyb.parsing.gmx' module.","error":"ImportError: cannot import name 'extract_dHdl' from 'alchemlyb.parsing.gmx'"},{"fix":"Convert your input data to the 'u_nk' format before passing it to the function.","cause":"The function expects input data in the 'u_nk' format, but received a different format.","error":"ValueError: The input should be u_nk"},{"fix":"Update your code to use the 'dE' method instead of 'dhdl'.","cause":"The 'dhdl' method is deprecated and will be removed in future versions.","error":"DeprecationWarning: Method 'dhdl' has been deprecated, using 'dE' instead. 'dhdl' will be removed in alchemlyb 3.0.0."},{"fix":"Update your code to use the 'all' method instead of 'dhdl_all'.","cause":"The 'dhdl_all' method is deprecated and will be removed in future versions.","error":"DeprecationWarning: Method 'dhdl_all' has been deprecated, using 'all' instead. 'dhdl_all' will be removed in alchemlyb 3.0.0."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.5.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/alchemistry/alchemlyb","docs":"https://alchemlyb.readthedocs.io/","changelog":"https://github.com/alchemistry/alchemlyb/blob/master/CHANGES","pypi":"https://pypi.org/project/alchemlyb/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","ai-ml"],"base_url":null,"auth_type":null,"install_checks":{"last_tested":"2026-05-23","tag":null,"tag_description":null,"installed_version":"2.3.1","pypi_latest":"2.5.0","is_stale":true,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"alchemlyb","exit_code":1,"wheel_type":null,"failure_reason":"build_error","import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"alchemlyb","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":19.4,"import_time_s":1.13,"mem_mb":36.9,"disk_size":"579M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"alchemlyb","exit_code":1,"wheel_type":null,"failure_reason":"build_error","import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"alchemlyb","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":18.4,"import_time_s":1.8,"mem_mb":42.5,"disk_size":"611M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"alchemlyb","exit_code":1,"wheel_type":null,"failure_reason":"build_error","import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"alchemlyb","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":18.9,"import_time_s":1.84,"mem_mb":41.4,"disk_size":"590M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"alchemlyb","exit_code":1,"wheel_type":null,"failure_reason":"build_error","import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"alchemlyb","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":19,"import_time_s":1.73,"mem_mb":41.9,"disk_size":"588M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"alchemlyb","exit_code":1,"wheel_type":null,"failure_reason":"build_error","import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"alchemlyb","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":22.4,"import_time_s":1.04,"mem_mb":32.8,"disk_size":"578M"}]},"_links":{"self":"https://checklist.day/api/registry/alchemlyb","v1":"https://checklist.day/v1/registry/alchemlyb","v1_install":"https://checklist.day/v1/registry/alchemlyb/install","v1_imports":"https://checklist.day/v1/registry/alchemlyb/imports","v1_compatibility":"https://checklist.day/v1/registry/alchemlyb/compatibility","v1_quickstart":"https://checklist.day/v1/registry/alchemlyb/quickstart","docs":"https://checklist.day/docs"}}