markov-chain-monte-carlo

Single-chain illustration: open-boundary 1-D Ising with 50 spins, β = 0.5, J = 1, seed 42, 5,000 burn-in steps, and 20,000 recorded steps. The current example extends this to four chains. just notebook-check regenerates target/ising_1d_trace.csv, the executed notebook, and the PNG under target/notebooks/; just notebook-ising-figure promotes that exact PNG to the tracked image above.

Research-oriented Metropolis-Hastings tools in Rust for ordinary numeric states, large combinatorial state spaces, and proposal implementations that need rollback-safe mutation or delayed commits.

• Introduction
• Use this crate when
• Quick start
• API at a glance
• Features
• Cargo features
• Scientific basis
• Validation model
• Documentation map
• Examples
• Benchmarking
• Ecosystem
• Limitations and roadmap
• Contributing
• Citation
• References
• AI Agents
• License

This library implements composable Metropolis-Hastings sampling in Rust for application-specific state spaces, proposals, and observables. Domain code owns the model and proposal kernel; the sampler owns transition bookkeeping, acceptance decisions, and measurement workflows.

Targets return unnormalized natural log weights. Proposals describe the same concrete transition they generate, with proposal asymmetry in the Hastings correction. Numeric examples, spin systems, and triangulation moves use this same contract.

🚧 Pre-release (0.x) — This is research software under active development. APIs may change before 1.0. API links point to the latest published documentation. Run just doc for the API reference matching this checkout.

• Application-specific states and proposals need reusable Metropolis-Hastings transition mechanics.
• Composable log weights represent model, bias, energy/action, or externally supplied regularizer terms.
• Large states benefit from in-place rollback or delayed commits.
• Long runs need streaming statistics, numeric traces, thinning, or validated checkpoints.
• Proposal development needs explicit Hastings ratios and empirical transition checks.

Proposal correctness, irreducibility, aperiodicity, equilibration, and scientific interpretation remain application responsibilities.

Add the library and rand 0.10 to your crate:

cargo add markov-chain-monte-carlo
cargo add rand@0.10

The example imports StdRng and its traits from rand, so your application needs to declare rand directly. You create and seed the generator, then pass it to the sampler to control its randomness.

Enable checkpoint serialization when needed:

cargo add markov-chain-monte-carlo --features serde

Rust 1.99.0 or newer is required.

Minimal by-value Metropolis-Hastings sampler. This example demonstrates the transition mechanics; convergence assessment remains a separate analysis step.

use markov_chain_monte_carlo::prelude::by_value::*;
use rand::{Rng, RngExt, SeedableRng, rngs::StdRng};

#[derive(Clone)]
struct Scalar(f64);

struct Normal;
impl Target<Scalar> for Normal {
    fn log_prob(&self, state: &Scalar) -> f64 {
        -0.5 * state.0 * state.0
    }
}

struct RandomWalk {
    width: f64,
}
impl Proposal<Scalar> for RandomWalk {
    fn propose<R: Rng + ?Sized>(&self, current: &Scalar, rng: &mut R) -> Scalar {
        let delta = rng.random_range(-self.width..self.width);
        Scalar(current.0 + delta)
    }
}

fn main() -> Result<(), McmcError> {
    let mut rng = StdRng::seed_from_u64(42);
    let mut chain = Chain::new(Scalar(0.0), &Normal)?;
    let proposal = RandomWalk { width: 1.0 };

    for _ in 0..1000 {
        let _ = chain.step(&Normal, &proposal, &mut rng)?;
    }

    assert!(chain.acceptance_rate() > 0.0);
    Ok(())
}

To run the repository's examples, follow the environment setup guidance, then run these commands from the checkout:

just example ising_1d  # Run the one-dimensional Ising example
just examples         # Run all examples
just                  # List all public recipes, arguments, and descriptions

Use explicit step calls when every transition needs metadata. Bulk in-place runs skip observational telemetry hooks; delayed chunk observation can retain per-step telemetry and post-step state. See the proposal testing workflow and the generated API contracts for each method. The checkout's crate-level API migration section records signature, telemetry, thinning, and checkpoint changes since earlier APIs.

• Additive target composition keeps model/bias weights separate from proposal corrections.
• By-value, in-place rollback, and delayed-commit proposals share log-space acceptance with typed invalid-value errors.
• Checkpoints recompute cached log weights against the resumed target; optional serde support uses a canonical portable shape.
• Detailed-balance diagnostics compare representative discrete transition flows, continuous density ratios, and sampled proposal bins.
• Fixed two-dimensional reference distributions with analytical moments are available behind benchmarks.
• Repeated and resumable runs support iterator sampling, observation, counter resets after burn-in, and positive validated thinning intervals.
• Scalar adaptive warmup tunes a bounded proposal scale; production keeps the final scale fixed.
• Scalar autocorrelation, single-chain and multi-chain ESS, measured ESS/second, mean/quantile MCSE, and R-hat have typed unavailable results. Multi-chain ESS accounts for between-chain disagreement; MCSE reports uncertainty in estimated summaries in original observable units.
• Streaming statistics and binning summaries avoid retaining every sample.
• Pooled rank data preserve original chain and draw order for downstream plots without a rendering dependency.
• Trace recording retains chain IDs, acceptance metadata, and target log weights for CSV export.

No Cargo features are enabled by default. Scalar diagnostics need no optional feature.

For tracing, install an application-owned subscriber before sampling. The checkout's crate-level Tracing contract includes setup, event fields, timing costs, and counter semantics. Build it with just doc; the library never installs a subscriber.

The Metropolis-Hastings acceptance probability is

alpha(x, y) = min(1, exp(log pi(y) - log pi(x) + log q(x | y) - log q(y | x)))

Target<S> supplies the unnormalized log weight; the proposal supplies the reverse/forward log ratio for that same move. Additive target terms change the sampled distribution, while proposal corrections account for how moves are generated. See scientific basis and scope for assumptions, arithmetic conventions, method definitions, and diagnostic limitations, and the method-to-source index for attribution.

The crate checks local transition mechanics: invalid floating-point values, acceptance, counters, cached weights, checkpoint restoration, and proposal rollback/commit contracts. Deterministic and property tests exercise these contracts; representative empirical checks help proposal authors detect errors.

Independent fixtures cross-check rank-normalized R-hat, multi-chain ESS, and MCSE against pinned ArviZ results, and pooled ranks against SciPy. The analysis guide documents versions, numerical conventions, and commands to verify exported Rust results. The plotting notebook renders those results; ArviZ and SciPy are isolated validation dependencies, not Rust library dependencies.

These checks do not establish irreducibility, aperiodicity, equilibration, or convergence. Correlated uncertainty and observable-specific diagnostics need scientific assessment. The reviewer guide maps claims to evidence and reproducible checks.

Repository guides and source examples follow main; API links use docs.rs latest. Run just doc for the API reference matching this checkout.

Example workflows live in examples/:

Run just examples for all validated examples or just example NAME for one. The reference-distribution example requires --features benchmarks when run directly with Cargo.

Run just diagnostic-plots for original-chain rank overlays, bulk/tail ESS and relative-ESS curves, traces, ACF, and saved numeric reports. The Ising example compares two temperatures using four chains per temperature, with 5,000 warmup steps and 20,000 production draws per chain. just notebook-check executes both this workflow and the Ising trace-analysis notebook under target/notebooks/. See analyzing chains for input selection, timing scope, exports, and error handling; these demonstrations do not certify convergence. This crate is a library: the examples and notebook are contributor workflows, with no installed CLI.

Benchmarking owns workload contracts, reproduction commands, and the shared research-repo-tools publication workflow. Use just bench-save-baseline NAME to save this checkout's local stepping measurements, then compare later runs with just bench-compare NAME.

Statistic: median. Unit: ns.

Coverage: 13 selected of 22 comparable; 0 current-only; 0 baseline-only benchmarks.

Ratios are point estimates, not significance tests or scientific acceptance.

These fixed-seed stepping workloads measure transition and observation overhead. They do not establish convergence, mixing, effective sample size, or scientific efficiency. Ratios are baseline time divided by current time; values above one mean lower current time. Marginal timing bounds do not establish a paired ratio interval or statistical significance.

Review common names against the lifecycle contracts in docs/BENCHMARKING.md, especially when harness fingerprints differ. Added and removed names are coverage changes. Local measurements require matching known host identities. Release-asset comparisons need separate hardware and workload review; GitHub runners can change between releases. Source and harness fingerprints come from the shared measurement workflow.

• Full timing report
• Comparison evidence
• Provenance
• CSV export

This crate is part of a broader Rust ecosystem for computational geometry and simulation:

• causal-triangulations — CDT physics and simulation
• delaunay — geometric primitives and triangulations
• la-stack — fixed-size linear algebra

The long-term architecture separates:

• Geometry: triangulations and geometric predicates
• Sampling: this crate
• Physics: CDT actions, observables, and domain-specific dynamics

The crate supplies sampling mechanics and empirical diagnostics. Domain code owns model choice, valid proposals, reproducible random streams, equilibration, and precision thresholds. Classical split R-hat is not rank-normalized or folded; ESS and MCSE are observable-specific. Mean MCSE requires finite population moments; finite heavy-tail output does not establish their existence. Tied quantiles can leave MCSE unavailable.

Sequential multi-chain workflows and cross-chain diagnostics are available today. Built-in parallel-chain orchestration, tempering, and dedicated learned-proposal integrations remain roadmap work. Externally supplied learned log weights can already be composed as target terms; training energy models or proposal policies remains outside this crate's scope. See the roadmap and reviewer guide.

See CONTRIBUTING.md for the full contributor guide (project layout, development workflow, code style, testing, documentation layout, performance/benchmarking, and the release process). Community expectations live in CODE_OF_CONDUCT.md. AI assistants should follow AGENTS.md.

If you use this software in academic work or downstream research software, cite the Zenodo DOI and include the software metadata from CITATION.cff.

• DOI: https://doi.org/10.5281/zenodo.20033111
• Citation metadata: CITATION.cff

@software{getchell_markov_chain_monte_carlo,
  author = {Adam Getchell},
  title = {markov-chain-monte-carlo: A composable MCMC framework for Rust},
  doi = {10.5281/zenodo.20033111},
  url = {https://github.com/acgetchell/markov-chain-monte-carlo}
}

For release-specific fields such as version, release date, and ORCID, prefer CITATION.cff.

For canonical background references for Metropolis-Hastings, MCMC, and the example models, see bibliographic records and method-to-source index.

AI coding assistants should read AGENTS.md before proposing or applying changes. See CONTRIBUTING.md for the repository's AI-assisted development note.

This project is licensed under the BSD 3-Clause License.