alchemrs is a CLI-first tool for alchemical free energy analysis. The package ships an alchemrs command-line binary for the main workflow and a Rust library crate for embedding, custom pipelines, and future bindings. The scientific core covers parsing AMBER and GROMACS outputs, preprocessing time series, running TI/BAR/MBAR/IEXP/DEXP estimators, and computing diagnostics such as overlap analysis and schedule advice. Fixtures and tests compare results against established reference implementations (alchemlyb) to keep the numerical behavior grounded.
Native SVG plotting is available as an optional plotting feature.
The alchemrs binary is the primary entry point.
Commands:
advise-scheduletibarmbariexpdexp
Pre-built binaries for versioned releases can be found at https://github.com/helmutcarter/alchemrs/releases crates.io support will come later in development.
If you want the latest update, or to compile it for your machine:
First, clone this repo
git clone git@github.com:helmutcarter/alchemrs.git
cd alchemrsthen you can either automatically compile and run the binary through cargo:
cargo run --release -- [command] [arguments]or compile using cargo and then call the binary:
cargo build --release
./target/release/alchemrs [command] [arguments]--remove-burnin <N>: skip the firstNsamples in each window before analysis.--auto-equilibrate: usepymbar-style equilibration detection as described here.--decorrelate: subsample to reduce correlation before estimating.tiuses the parseddH/dlambdaseries.bar,iexp,dexp, andmbaruse the observable selected by--u-nk-observable <de|all|epot>.
--u-nk-observable <de|all|epot>: choose the scalar observable used foru_nkauto-equilibration and decorrelation onbar,iexp,dexp, andmbarruns. The default isde.--output-units <kt|kcal|kj>: output energy units (defaultkt).--output-format <text|json|csv>: output format for estimator results (defaulttext).--output <PATH>: write the formatted result to a file instead of stdout.--overlap-summary: include overlap scalar and overlap eigenvalues for BAR/IEXP/DEXP/MBAR runs.
The CLI also includes a lambda-schedule advisor. For u_nk workflows it analyzes adjacent edges and reports whether the current schedule looks healthy, should be monitored, needs more sampling, or likely needs an inserted window. For TI workflows, pass --input-kind dhdl to switch the same command over to dH/dlambda-based spacing diagnostics.
alchemrs advise-schedule \
--decorrelate \
--u-nk-observable de \
--report schedule-report.html \
--output-format json \
/path/to/*/prod.outFull CLI usage is documented in docs/src/cli.md.
The top-level alchemrs crate re-exports the common parse, prep, estimator, and analysis entry points used by the CLI and available for direct Rust integration:
use alchemrs::{
decorrelate_u_nk_with_observable, extract_u_nk_with_potential, DecorrelationOptions,
MbarEstimator, MbarOptions,
};
let (u_nk, epot) = extract_u_nk_with_potential("prod.out", 300.0)?;
let u_nk = decorrelate_u_nk_with_observable(&u_nk, &epot, &DecorrelationOptions::default())?;
let fit = MbarEstimator::new(MbarOptions::default()).fit(&[u_nk])?;
let result = fit.result_with_uncertainty()?;
if let Some(labels) = fit.lambda_labels() {
println!("lambda components = {:?}", labels);
}Use the Rust API when you need embedding, custom orchestration, or tighter control than the CLI exposes. The repo also includes runnable top-level examples:
cargo run --example amber_ti -- 300 path/to/lambda0.out path/to/lambda1.outcargo run --example amber_mbar -- 300 path/to/lambda0.out path/to/lambda1.out path/to/lambda2.out
Optional plotting helpers can be enabled with:
cargo build --features plotting --releaseExample JSON output:
{
"delta_f": -113.58,
"uncertainty": 1.17,
"from_lambda": 0.0,
"to_lambda": 1.0,
"units": "kT",
"overlap": {
"scalar": 0.0183,
"eigenvalues": [1.0, 0.9817]
},
"provenance": {
"estimator": "mbar",
"temperature_k": 300.0,
"decorrelate": true,
"remove_burnin": 0,
"auto_equilibrate": false,
"fast": false,
"conservative": true,
"nskip": 1,
"u_nk_observable": "de",
"lambda_components": null,
"windows": 15,
"samples_in": 300,
"samples_after_burnin": 300,
"samples_kept": 126
}
}For multidimensional GROMACS schedules, the parsed UNkMatrix, estimator DeltaFMatrix, and OverlapMatrix all preserve parser-derived lambda component names when available through .lambda_labels().
The CLI also includes a lambda-schedule advisor. For u_nk workflows it analyzes adjacent edges and reports whether the current schedule looks healthy, should be monitored, needs more sampling, or likely needs an inserted window. For TI workflows, pass --input-kind dhdl to switch the same command over to dH/dlambda-based spacing diagnostics.
alchemrs advise-schedule \
--decorrelate \
--u-nk-observable de \
--report schedule-report.html \
--output-format json \
/path/to/*/prod.outUseful advisor-specific flags:
--estimator <mbar|bar>--input-kind <auto|u-nk|dhdl>--overlap-min <VALUE>--block-cv-min <VALUE>--n-blocks <N>--no-midpoints--report <PATH>
For TI spacing diagnostics:
alchemrs advise-schedule \
--input-kind dhdl \
--decorrelate \
--report ti-schedule-report.html \
--output-format json \
/path/to/*/prod.outThe JSON output includes sample_counts, provenance, and suggestions, plus either edges for u_nk mode or windows and intervals for TI mode. u_nk edge diagnostics include neighbor-relative metrics, dominant changing components, and a priority score. TI interval diagnostics include mean_dhdl, slope, curvature, interval_uncertainty, and block-stability summaries. When --report is provided, the CLI also writes a standalone HTML report; the u_nk report includes the full SVG lambda-axis and multidimensional component breakdown, while the TI report also includes an integration-method shape gallery showing the applicable TI interpolants on the current lambda grid.
CSV output is useful for quick ingestion into spreadsheets or tabular tools:
alchemrs bar \
--output-format csv \
/path/to/*/prod.outCSV columns include estimator parameters after the result fields:
delta_f,uncertainty,from_lambda,to_lambda,units,overlap_scalar,overlap_eigenvalues,estimator,temperature_k,decorrelate,remove_burnin,auto_equilibrate,fast,conservative,nskip,u_nk_observable,ti_method,ti_method_reason,lambda_components,windows,samples_in,samples_after_burnin,samples_kept
alchemrs ti \
--method trapezoidal \
--remove-burnin 125 \
/path/to/*/prod.outti supports --method <trapezoidal|simpson|cubic-spline|pchip|akima|gaussian-quadrature>.
For more on picking an integration method, see the docs.
To let the CLI choose a method automatically and record why it was selected:
alchemrs ti \
--method auto \
--output-format json \
/path/to/*/prod.outTI outputs now include ti_method and, for --method auto, ti_method_reason in provenance.
alchemrs bar \
--decorrelate \
/path/to/*/prod.outNote: BAR uncertainties are only computed for adjacent windows; non-adjacent state pairs (for example, 0->1) are reported as NaN, matching alchemlyb.
alchemrs mbar \
--decorrelate \
/path/to/*/prod.outalchemrs iexp \
/path/to/*/prod.out
alchemrs dexp \
/path/to/*/prod.outIEXP reports FEP results in the forward direction, DEXP reports FEP results in the reverse direction.
Documentation is online at https://helmutcarter.github.io/alchemrs/. The source files are in docs/ and can be viewed locally:
cargo install mdbook
mdbook serve docsInitial internal benchmarks on the bundled fixtures show substantial speedups over
alchemlyb for several workflows. Ongoing profiling notes and experiment results live in
optimizations.md.
This project is licensed under either of
- MIT license (LICENSE-MIT)
- Apache License, Version 2.0 (LICENSE-APACHE)
Copyright (c) 2026 Helmut Carter