batter is a modern, object-oriented toolkit for free-energy workflows. It provides absolute binding free energy (ABFE) calculations for ligands––including charged species–––bound to membrane proteins, as well as absolute solvation free energy (ASFE). It extends the original BAT.py package with the support of membrane proteins, single-leg ABFE protocols, enhanced sampling via Hamiltonian replica exchange MD (H-REMD), OpenFF, and a revamped codebase for maintainability and extensibility.

ABFE runs in batter follow a single-component design that applies lambda-dependent Boresch restraints, uses the simultaneous decoupling/recoupling (SDR) protocol with both the interacting and dummy ligands present, and employs soft-core electrostatics and van der Waals potentials to ensure smooth coupling/decoupling. It also supports usage of H-REMD for enhanced sampling along the alchemical pathway.

batter supports resuming interrupted runs and flexible system definitions via modular YAML configuration files. Job submission is highly parallelized, with each lambda-window executed as an independent job. For example, 10 ligands × 24 lambda-windows yields 240 jobs submitted concurrently to your scheduler.

Clone the repository, initialize submodules, and create the environment:

git clone [email protected]:yuxuanzhuang/batter.git
# If SSH clone fails (or SSH is unavailable), use HTTPS instead:
# git clone https://github.com/yuxuanzhuang/batter.git
# For SSH setup tips:
# https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account

cd batter
git submodule update --init --recursive

conda create -n batter -y python=3.12
conda env update -f environment.yml -n batter
conda activate batter

# Editable installs for bundled deps
pip install -e ./extern/alchemlyb
pip install -e ./extern/rocklinc

# Install batter (editable)
pip install -e .

• Building the environment can be storage hungry and slow. try micromamba and/or run the install on a compute node.
• VMD often needs X11 forwarding and its own shared libraries on clusters. Set LD_LIBRARY_PATH to include $CONDA_PREFIX/lib/vmd (or your env path) and load any required x11/system modules before launching VMD. Override the executable with BATTER_VMD if needed.

This installs in editable mode so your code changes are immediately reflected.

To use this package without the core components—useful for running CLI commands (e.g., batter report-jobs), building docs, or running simple tests—install only the package itself:

pip install .

Run an example configuration:

cd examples

batter seed-headers   # create ~/.batter with SLURM headers

# modify ~/.batter/***.header to suit your cluster if needed

batter run mabfe.yaml

Use --help to see all commands:

batter -h
batter run -h

YAML files in examples/ illustrate common setups:

Absolute Binding Free Energy (ABFE)

1. mabfe.yaml — membrane protein (e.g., B2AR) in a lipid bilayer
2. mabfe_nonmembrane.yaml — soluble protein (e.g., BRD4) in water
3. extra_restraints/mabfe.yaml — add positional restraints to selected atoms
4. conformational_restraints/mabfe.yaml — add conformational restraints (distance between atoms)

Absolute Solvation Free Energy (ASFE)

1. masfe.yaml — small molecule (e.g., epinephrine) in water

Plain Molecular Dynamics (MD)

1. md.yaml — standard MD production run for a protein-ligand complex

Example YAMLs are intended as starting points; adjust to your system.

BATTER renders SLURM scripts by combining a header (user-editable) and a packaged body. On first use (run batter), the headers are copied into ~/.batter (or run.slurm_header_dir if set). Customize queue/partition or executable overrides by editing:

• ~/.batter/SLURMM-Am.header (equil/FE runs)
• ~/.batter/SLURMM-BATCH-remd.header (REMD runs)
• ~/.batter/job_manager.header (manager script for batter --slurm-submit)

If the files are missing, run any batter command once to seed them, then edit the headers; bodies remain managed by the package.

You can also seed headers explicitly with:

batter seed-headers           # seeds into ~/.batter
batter seed-headers --dest /path/to/dir
batter seed-headers --force   # overwrite existing headers

After seeding, edit the header files to match your cluster defaults; they will be used whenever BATTER renders SLURM scripts.

Runs store FE outputs under <run.output_folder>/executions/<run_id>/results. Use the CLI helpers to inspect and export them:

• batter fe list <system_root> – tabulates every stored run (ΔG, SE, components).
• batter fe show <system_root> <run_id> – prints per-window data and metadata for a specific execution.

A CSV file for all the FE results is stored under <system_root>/results. See detailed convergence in <system_root>/executions/<run_id>/<ligand_name>/Results.

Copyright (c) 2024, Yuxuan Zhuang

Built with the Computational Molecular Science Python Cookiecutter (v1.10).