Command-Line Usage#

BATTER ships with a batter command-line tool powered by click. This page summarises the key commands and options. Run batter --help or append --help to any subcommand for the full syntax.

Run Workflows#

batter run examples/mabfe.yaml

Options:

--on-failure {prune,raise,retry}

Control how ligand failures are handled (default: raise). retry clears FAILED sentinels and reruns that phase once.

--output-folder PATH

Override the system output directory.

--run-id TEXT

Override the execution run id (use auto to reuse the latest).

--dry-run / --no-dry-run

Toggle run.dry_run from the YAML.

--only-equil / --full

Run only equilibration preparation steps. FE preparation is still performed (up to prepare_fe_windows), but the FE equilibration/production/analyse phases are skipped.

--slurm-submit

Emit an sbatch script and submit the job instead of running locally.

Resume an existing execution (no YAML needed once seeded):

batter run-exec work/adrb2/executions/rep1

Notes:

  • The first batter run stores a copy of the YAML plus any external restraint files (e.g., extra_conformation_restraints) under artifacts/config/. run-exec reuses that copy.

Inspect Free-Energy Results#

List results stored in a portable work directory:

batter fe list work/adrb2

Use --format to output JSON/CSV/TSV instead of a table.

Display a specific FE record:

batter fe show work/adrb2 run-20240101 --ligand LIG1

If the run contains multiple ligands, pass --ligand to disambiguate.

Re-run FE analysis for a saved execution:

batter fe analyze work/adrb2 run-20240101 --ligand LIG1 --workers 4

Use --workers to control parallelism and --sim-range (start,end) to restrict which windows are parsed. Pass --no-raise-on-error to continue even if a ligand’s analysis fails.

Clone Executions#

Duplicate the directory structure of an execution (useful for what-if experiments):

batter clone-exec work/adrb2 run-20240101 run-20240101-test --mode symlink --only-equil

Only metadata, inputs/params, equilibration artifacts, and a minimal fe/ scaffold are copied, so the clone can start new simulations without recreating large FE dumps.

SLURM Utilities#

  • batter report-jobs – Summarise SLURM jobs launched by BATTER. Use --detailed to show per-job information and --partition to filter by queue.

  • batter cancel-jobs --contains TEXT – Cancel SLURM jobs whose name contains the supplied substring (matches the fep_... job names produced by BATTER).

FE Toolkit Schedules#

BATTER wraps the fetkutils-tischedule.py script from AMBERTOOLS via batter fek-schedule so you can optimise or analyse lambda schedules without leaving the main CLI.

batter fek-schedule \
    --opt 96 \
    --ar --ssc --sym \
    --start 4 --stop 8 \
    -T 310 \
    --out sched.ar.z.dat \
    --plot sched.ar.z.png \
    ADRB2_I/rep1/fe/pose0/sdr/z

Key options:

--opt N / --read FILE

Optimise a fresh schedule with N lambda values or analyse an existing schedule.

--pso | --ar | --kl

Choose the optimisation metric (phase-space overlap, replica-exchange ratio, or exp(-KL)).

--ssc / --sym / --alpha0 / --alpha1

Restrict optimisation to SSC(alpha) families, optionally symmetric around 0.5.

--plot PATH / --out PATH

Save the interpolated heatmap and the digitised schedule to disk.

All options mirror the original script, so existing workflows can switch to the new command without rewriting job scripts. Use --verbose to surface the diagnostic output emitted by the underlying fetkutils routines.

Environment Notes#

  • The CLI uses batter.api and is safe to call from activated conda/virtualenv installations.

  • batter run validates the YAML before invoking the orchestration layer.

  • When submitting to SLURM, the generated script is named <hash>_job_manager.sbatch using a hash of the YAML contents and overrides.