A Rust library implementing various MCMC diagnostics and utilities, such as Gelman Rubin potential scale reduction factor (R hat), effective sample size (ESS), chain splitting, and others.
This crate is language agnostic and intended to work with the outputs of any MCMC sampler (e.g. Stan, PyMC, Turing.jl, etc).
Requires Rust 1.85 or later and uses the Rust 2024 edition. CI tests both the minimum supported Rust version and current stable Rust.
cargo test --all-targets
cargo test --doc
cargo test --all-targets --all-features
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo doc --no-deps
python3 scripts/validation/generate.py --checkThe public API accepts vectors, borrowed slices, and native arrays of f32 or
f64 draws, grouped by chain. Calculations and results use f64. The Array1
and Array2 aliases remain Vec<f64> and Vec<Vec<f64>> for existing callers.
Diagnostics trim each chain to the length of the shortest chain. Splitting drops
the middle draw when that common length is odd.
let draws = [[1.0_f32, 3.0, 2.0, 4.0], [2.0, 4.0, 1.0, 3.0]];
let ess = mcmc::ess::compute_effective_sample_size(&draws).unwrap();
let halves = mcmc::utils::split_chain_views(&draws).unwrap();f64 input buffers are borrowed; f32 inputs are widened once per retained
chain. split_chain_views returns borrowed halves without copying draws.
The existing consuming split_chains function still returns owned vectors.
Existing direct vector calls continue to work. With generic inputs, an untyped
empty input or an ambiguous .collect() needs a type annotation such as Array2.
Explicit diagnostic function pointers now take &[Vec<f64>] instead of &Array2.
Enable the optional ndarray feature for mcmc::ndarray adapters. These accept
ndarray::ArrayView2 with chains on axis 0 and draws on axis 1:
let draws = ndarray::array![[1.0_f64, 3.0, 2.0, 4.0], [2.0, 4.0, 1.0, 3.0]];
let rhat = mcmc::ndarray::potential_scale_reduction_factor(draws.view()).unwrap();
let halves = mcmc::ndarray::split_chain_views(draws.view()).unwrap();Contiguous f64 rows are borrowed. Column-major, transposed, reversed, and
strided views work too; noncontiguous rows are copied in their logical order.
f32 rows are converted to contiguous f64 buffers.
The ndarray split_chain_views adapter borrows the original samples and
preserves strides and element type, including for noncontiguous inputs.
Implementations for some of these diagnostics vary slightly, so reference implementations are based on Stan 2.24.0, and unit tests adapted from that version check matching behavior. Rhat and split Rhat currently use the classical variance-based estimator; rank normalization and folding are still planned. ESS is the classical estimator, and MCSE estimates the error of the sample mean.
Invalid inputs return errors: ESS and MCSE need at least four retained draws per chain; split ESS needs at least eight before splitting. Rhat needs two chains with two draws each; split Rhat can split one chain with at least four draws. Diagnostics reject non-finite retained draws and identical constant samples. Rhat also requires positive within-chain variance. See the Stan reference manual for the definitions and newer diagnostics.
Diagnostics center and scale retained draws internally to protect against large offsets, overflow, and underflow. Rhat preserves each chain's local variation before combining spreads. ESS and Rhat are independent of the original units; MCSE is converted back to those units after computing the standard error. Constant detection uses exact equality of retained draws rather than a fixed absolute tolerance. Variation already rounded away in the input cannot be recovered. If an estimate or its required variance cannot be represented, the function returns an error instead of a non-finite, negative, or spuriously zero result. Negative estimates of the classical truncated autocorrelation time also return errors, even when all input draws are finite and nonconstant.
In addition to the original two-chain Stan blocker fixture, tests use five
saved draw sets from posterior and ArviZ: eight schools (two independent fits),
a multivariate normal model, hierarchical radon regression, and rugby.
Three selected parameters per draw set give 15 cross-implementation cases,
each with four chains and either 100 or 500 stored posterior draws per chain.
Checked-in references were generated with R 4.5.2, posterior 1.7.1, and an
independent R implementation of the Stan 2.24 ESS formula. Tests compare
classical Rhat, split Rhat, ESS, split ESS, and unsplit MCSE across scalar/SIMD,
borrowed slices, f32, and contiguous/strided ndarray inputs. Cargo tests use
the saved files without R or network access.
Current and legacy ESS agree on the selected external cases, but differ on
some boundary inputs. posterior::mcse_mean also uses split ESS by default,
whereas this crate's MCSE uses unsplit ESS. Both forms and focused boundary
probes are recorded. See fixture provenance and reproduction
for source hashes, versions, licenses, estimator differences, and regeneration.
Enable simd to use the stable-Rust wide crate for four-lane f64
autocovariance dot products. It uses the compilation target's SIMD support with
portable fallbacks; the default build uses the scalar kernel. Both paths retain
f64 arithmetic and are checked against the Stan fixtures and arima reference
covariances, including unaligned inputs and incomplete vector lanes. Floating
point summation order differs, so results need not be bit-for-bit identical.
cargo bench --bench diagnostics
cargo bench --bench diagnostics --features simdThe benchmark uses four synthetic chains at 256, 1,024, and 4,096 draws each, reporting median time per call over seven 100 ms batches. Autocovariance still does quadratic work; an FFT implementation is a separate future improvement for long chains. SIMD accelerates the dot products, not array conversion or the sequential variance estimator.
Next: diagnostic coverage and reliability
- Add rank-normalized and folded split Rhat with reference tests from Stan or
the
posteriorpackage, while preserving the classical API. - Add bulk and tail ESS, then quantile-specific MCSE, with reference fixtures.
- Replace or deprecate the public test-oriented CSV helper with a fallible reader that reports I/O and parse errors and validates column counts.
- Add a worked example showing sampler output, warmup removal, and diagnostics.
Later: API and performance
- Benchmark FFT autocovariance against the direct scalar/SIMD kernels, and choose a crossover threshold using realistic chain lengths.
- Benchmark splitting and adapter conversion costs before further allocation changes.
- Evaluate named multi-parameter chains against concrete caller needs before committing to a container type.
- Consider thinning as an optional storage utility, with a validated nonzero stride and documentation of the statistical tradeoff.
[1]: Stephen P. Brooks and Andrew Gelman. General Methods for Monitoring Convergence of Iterative Simulations. Journal of Computational and Graphical Statistics, 7(4), 1998.
[2]: Andrew Gelman and Donald B. Rubin. Inference from Iterative Simulation Using Multiple Sequences. Statistical Science, 7(4):457-472, 1992.
[3]: Aki Vehtari, Andrew Gelman, Daniel Simpson, Bob Carpenter, Paul-Christian Burkner. Rank-normalization, folding, and localization: An improved R-hat for assessing convergence of MCMC, 2019. Retrieved from https://arxiv.org/abs/1903.08008.
[4]: Geyer, Charles J. Introduction to Markov Chain Monte Carlo. Handbook of Markov Chain Monte Carlo, edited by Steve Brooks, Andrew Gelman, Galin L. Jones, and Xiao-Li Meng. Chapman; Hall/CRC. 2011.
Thanks to Ivan Ukhov for generously providing
the mcmc namespace on Cargo.