Getting Started

The fastest way to use alchemrs is through the CLI. The Rust API is documented separately for embedding and custom workflows.

Prerequisites

Rust 1.85 or newer
AMBER output files or GROMACS dhdl.xvg files
Python 3.9 or newer plus maturin if you want the local Python package

The repository is a normal Cargo workspace and can be built and tested with standard Rust tooling.

Build the package

cargo build

Build the CLI binary

cargo build --release

Then run:

./target/release/alchemrs --help

Try a CLI workflow

./target/release/alchemrs ti \
  --temperature 300 \
  ./fixtures/amber/acetamide_tiny/*/acetamide.prod.out

Run tests

cargo test

Run the Rust examples

cargo run --example amber_ti -- 300 ./fixtures/amber/acetamide_tiny/*/acetamide.prod.out

cargo run --example amber_mbar -- 300 ./fixtures/amber/acetamide_tiny/*/acetamide.prod.out

cargo run --example openmm_u_kln_mbar

Run the Python package locally

Build and install the Python extension into the active environment:

maturin develop

Then run the Python tests and example scripts from the repository root:

python -m pytest python/tests -q
python python/examples/amber_fixture_analysis.py
python python/examples/atm_analysis.py

The OpenMM toy-system examples are also available when openmm is installed:

python python/examples/openmm_u_kln_mbar.py
python python/examples/openmm_nes.py
python python/examples/openmm_atm.py

See Python and OpenMM for the Python package layout, helper APIs, and the current local-usage workflow.

Build this book

This documentation uses mdBook.

Install it once:

cargo install mdbook

Preview the docs locally:

mdbook serve docs

Build static HTML:

mdbook build docs

Keyboard shortcuts

alchemrs