Expand description
§Fugue
A type-safe, monadic probabilistic programming library for Rust — pre-1.0 and actively developed
Compose models in direct style; listen backwards with pluggable interpreters and state-of-the-art inference. Learn it interactively at fugue.run.
Supported Rust: 1.87+ • Platforms: Linux / macOS / Windows • Crate: fugue-ppl on crates.io
§✨ Features
- Monadic PPL: Compose probabilistic programs using pure functional abstractions
- Type-Safe Distributions: 17 built-in probability distributions with natural return types, plus Dirichlet/Multinomial conjugate helpers
- Multiple Inference Methods: MCMC, HMC, SMC, Variational Inference, ABC
- Comprehensive Diagnostics: R-hat convergence, effective sample size, validation
- Numerically Stable: Log-space computations throughout for robust probability arithmetic
- Ergonomic Macros: Do-notation (
prob!), vectorization (plate!), addressing (addr!) - Programs as Data (optional
programfeature): aprob!-subset language with text and JSON front ends, interpreted into realModels at load time, extensible with a host’s own distributions and functions
§🤔 Why Fugue?
- 🔒 Type-safe distributions: natural return types (Bernoulli →
bool, Poisson/Binomial →u64, Categorical →usize) - 🧩 Direct-style, monadic design: compose
Model<T>values withbind/mapfor explicit, readable control flow - 🔌 Pluggable interpreters: prior sampling, replay, scoring, and safe variants
- 📊 Diagnostics: R-hat, ESS, validation utilities, and a structured error taxonomy (see
error) - ⚡ Performance-minded: O(1), allocation-free address clones (
Arc<str>with a cached hash) and numerically stable log-space computations
§📦 Distributions
Bernoulli, Beta, Binomial, Categorical, Cauchy, ChiSquared, DiscreteUniform, Exponential, Gamma, InverseGamma, Laplace, LogNormal, Normal, Poisson, StudentT, Uniform, Weibull — 17 in total, each with natural return types and validated parameters.
Sites are scalar, so the vector-valued Dirichlet and Multinomial are standalone distributions (sampling and scoring outside a model). The core::conjugate module adds log-space conjugate helpers (Dirichlet–multinomial and Beta–binomial marginal likelihoods, posterior updates, predictives) and sample_dirichlet, which draws a Dirichlet vector inside a model from scalar Gamma sites.
§🧪 Where Fugue stands today
Fugue is 0.2.x: pre-1.0, actively developed, with no SemVer stability guarantee yet and a single primary maintainer (see Roadmap, below). It’s extensively tested — hundreds of unit, integration, and property-based tests, including statistical regression tests against closed-form posteriors — but that’s not the same claim as “production-ready.” Treat it as a serious, honestly-scoped research-grade PPL: pin an exact version, read the CHANGELOG before upgrading, and expect breaking API changes between 0.x releases as the design settles.
§📦 Installation
[dependencies]
fugue-ppl = "0.2.0"§Quickstart
cargo add fugue-ppl§💡 Example
use fugue::*;
use rand::rngs::StdRng;
use rand::SeedableRng;
// Run inference with model defined in closure
let mut rng = StdRng::seed_from_u64(42);
let samples = adaptive_mcmc_chain(&mut rng, || {
prob! {
let mu <- sample(addr!("mu"), Normal::new(0.0, 1.0).unwrap());
observe(addr!("y"), Normal::new(mu, 0.5).unwrap(), 1.2);
pure(mu)
}
}, 1000, 500);
let mu_values: Vec<f64> = samples.iter()
.filter_map(|(_, trace)| trace.get_f64(&addr!("mu")))
.collect();§📚 Documentation
- User Guide - Comprehensive tutorials and examples
- Explorables - Interactive, touchable essays: drag a prior and watch the posterior re-form, roll HMC across a landscape
- Playground - Write
prob!models in the browser and run real inference, compiled to WASM - API Reference - Complete API documentation
- Examples - See the
examples/directory, including one runnable example per inference method:adaptive_mcmc_chain- most foundation/statistical-modeling examples (e.g.bayesian_coin_flip.rs)hmc_chain(HMC) - see thehmcmodule rustdoc for a runnable doctestadaptive_smc(SMC) -examples/smc_inference.rsabc_smc_weighted(ABC) -examples/abc_inference.rsoptimize_meanfield_vi_with_config(VI) -examples/vi_inference.rs
- References - Zotero library for Fugue
§🌱 Ecosystem
- Fugue Evo — evolution as Bayesian inference: CMA-ES, NSGA-II, island models, and estimation-of-distribution algorithms on the same foundations, with its own interactive docs and live playground at evo.fugue.run
§🤝 Community
- Issues & Bugs: Use GitHub Issues
- Feature Requests: Open an issue with the
enhancementlabel - Discord: Join our Discord server
§🗺️ Roadmap
This project is an ongoing exploration of probabilistic programming in Rust. While many pieces are production-leaning, parts may not be 100% complete or correct yet. I’m steadily working toward a more robust implementation and broader feature set.
Planned focus areas:
- Strengthening core correctness and numerical stability
- Expanding distribution and inference coverage
- API refinements and stability guarantees
- Improved documentation, diagnostics, and examples
API stability / SemVer policy: Fugue follows Cargo’s pre-1.0 SemVer convention: any 0.x.y -> 0.(x+1).0 bump may contain breaking changes, and 0.x.y -> 0.x.(y+1) is additive/non-breaking. There is no 1.0 stability commitment yet; always pin an exact version and read the CHANGELOG before upgrading the minor version.
§🤝 Contributing
Contributions welcome! See our contributing guidelines.
git clone https://github.com/alexnodeland/fugue.git
cd fugue && cargo test§📄 License
Licensed under the MIT License.
§🔗 Citation
If you use Fugue in your research, please cite:
@software{fugue2026,
title = {Fugue: Monadic Probabilistic Programming for Rust},
author = {Alexander Nodeland},
url = {https://github.com/alexnodeland/fugue},
version = {0.2.0},
year = {2026}
}Or refer to the “Internal” collection in Zotero to generate a bibliography.
Re-exports§
pub use core::address::Address;pub use core::conjugate::beta_bernoulli_log_marginal;pub use core::conjugate::beta_binomial_log_marginal;pub use core::conjugate::beta_posterior;pub use core::conjugate::dirichlet_categorical_log_marginal;pub use core::conjugate::dirichlet_log_pdf;pub use core::conjugate::dirichlet_log_predictive;pub use core::conjugate::dirichlet_multinomial_log_marginal;pub use core::conjugate::dirichlet_posterior;pub use core::conjugate::dirichlet_predictive;pub use core::conjugate::ln_multinomial_coefficient;pub use core::conjugate::ln_multivariate_beta;pub use core::conjugate::multinomial_log_pmf;pub use core::conjugate::sample_dirichlet;pub use core::conjugate::Dirichlet;pub use core::conjugate::Multinomial;pub use core::distribution::Bernoulli;pub use core::distribution::Beta;pub use core::distribution::Binomial;pub use core::distribution::Categorical;pub use core::distribution::Cauchy;pub use core::distribution::ChiSquared;pub use core::distribution::DiscreteUniform;pub use core::distribution::Distribution;pub use core::distribution::Exponential;pub use core::distribution::Gamma;pub use core::distribution::InverseGamma;pub use core::distribution::Laplace;pub use core::distribution::LogNormal;pub use core::distribution::Normal;pub use core::distribution::Poisson;pub use core::distribution::StudentT;pub use core::distribution::Support;pub use core::distribution::Uniform;pub use core::distribution::Weibull;pub use core::distribution::WithMeta;pub use core::model::factor;pub use core::model::guard;pub use core::model::observe;pub use core::model::pure;pub use core::model::sample;pub use core::model::sample_bool;pub use core::model::sample_f64;pub use core::model::sample_i64;pub use core::model::sample_u64;pub use core::model::sample_usize;pub use core::model::sequence_vec;pub use core::model::traverse_vec;pub use core::model::zip;pub use core::model::Model;pub use core::model::ModelExt;pub use core::model::SampleType;pub use runtime::async_handler::run_async;pub use runtime::async_handler::AsyncHandler;pub use runtime::async_handler::FromSync;pub use runtime::delegate::Delegate;pub use runtime::delegate::Overrides;pub use runtime::handler::Handler;pub use runtime::interpreters::score_given_trace_reconciled;pub use runtime::interpreters::PriorHandler;pub use runtime::interpreters::ReconcileReport;pub use runtime::interpreters::ReplayHandler;pub use runtime::interpreters::SafeReplayHandler;pub use runtime::interpreters::SafeScoreGivenTrace;pub use runtime::interpreters::ScoreGivenTrace;pub use runtime::trace::Choice;pub use runtime::trace::ChoiceValue;pub use runtime::trace::Trace;pub use core::numerical::log1p_exp;pub use core::numerical::log_sum_exp;pub use core::numerical::normalize_log_probs;pub use core::numerical::safe_ln;pub use error::ErrorCategory;pub use error::ErrorCode;pub use error::ErrorContext;pub use error::FugueError;pub use error::FugueResult;pub use error::Validate;pub use inference::abc::abc_rejection;pub use inference::abc::abc_scalar_summary;pub use inference::abc::abc_smc;pub use inference::abc::DistanceFunction;pub use inference::abc::EuclideanDistance;pub use inference::diagnostics::classic_r_hat_f64;pub use inference::diagnostics::extract_bool_values;pub use inference::diagnostics::extract_f64_values;pub use inference::diagnostics::extract_i64_values;pub use inference::diagnostics::extract_u64_values;pub use inference::diagnostics::extract_usize_values;pub use inference::diagnostics::print_diagnostics;pub use inference::diagnostics::r_hat_f64;pub use inference::diagnostics::summarize_f64_parameter;pub use inference::diagnostics::Diagnostics;pub use inference::diagnostics::ParameterSummary;pub use inference::hmc::hmc_chain;pub use inference::hmc::HMCConfig;pub use inference::hmc::HmcSession;pub use inference::hmc::HmcStepInfo;pub use inference::hmc::LeapfrogPoint;pub use inference::mcmc_utils::effective_sample_size_mcmc;pub use inference::mcmc_utils::effective_sample_size_multichain;pub use inference::mcmc_utils::geweke_diagnostic;pub use inference::mcmc_utils::DiminishingAdaptation;pub use inference::mh::adaptive_mcmc_chain;pub use inference::mh::adaptive_mcmc_chain_thinned;pub use inference::mh::adaptive_mcmc_chain_with_overrides;pub use inference::mh::adaptive_mcmc_chain_with_overrides_thinned;pub use inference::mh::adaptive_single_site_mh;pub use inference::mh::adaptive_single_site_mh_cached;pub use inference::mh::adaptive_single_site_mh_with_overrides;pub use inference::mh::block_regeneration_mh;pub use inference::mh::proposal_kind_for_support;pub use inference::mh::SiteProposal;pub use inference::smc::adaptive_smc;pub use inference::smc::adaptive_smc_with_kernel;pub use inference::smc::decode_particle;pub use inference::smc::decode_particles;pub use inference::smc::effective_sample_size;pub use inference::smc::multinomial_resample;pub use inference::smc::normalize_particles;pub use inference::smc::rejuvenate_particles;pub use inference::smc::resample_particles;pub use inference::smc::smc_prior_particles;pub use inference::smc::stratified_resample;pub use inference::smc::systematic_resample;pub use inference::smc::try_decode_particle;pub use inference::smc::CrossoverKernel;pub use inference::smc::NoKernel;pub use inference::smc::Particle;pub use inference::smc::PopulationKernel;pub use inference::smc::ResamplingMethod;pub use inference::smc::SMCConfig;pub use inference::smc::SMCResult;pub use inference::validation::ks_test_distribution;pub use inference::validation::test_conjugate_beta_bernoulli_model;pub use inference::validation::test_conjugate_normal_model;pub use inference::validation::ConjugateBetaBernoulliConfig;pub use inference::validation::ConjugateNormalConfig;pub use inference::validation::ValidationResult;pub use inference::vi::elbo_with_guide;pub use inference::vi::optimize_meanfield_vi;pub use inference::vi::MeanFieldGuide;pub use inference::vi::VariationalParam;
Modules§
- core
coremodule- error
- Error handling for probabilistic programming operations.
- inference
inferencemodule- macros
macrosmodule- program
programmodule- runtime
- Runtime System: Probabilistic Model Execution Engine
Macros§
- addr
- Create an address for naming random variables and observation sites.
This macro provides a convenient way to create
Addressinstances with human-readable names and optional indices. The macro supports two forms: - invalid_
params - Create an InvalidParameters error with optional context.
- plate
- Plate notation for replicating models over ranges.
- prob
- Probabilistic programming macro, used to define probabilistic programs with do-notation.
- scoped_
addr - Enhanced address macro with scoping support.
- trace_
error - Create a TraceError with optional context.