🎼 Fugue User Guide
A type-safe, monadic probabilistic programming library for Rust — pre-1.0 and actively developed
Write elegant probabilistic programs by composing Model values in direct style; execute them with pluggable interpreters and state-of-the-art inference algorithms.
Supported Rust: 1.87+ • Platforms: Linux / macOS / Windows • Crate: fugue-ppl on crates.io
Learn Fugue by playing, not just reading. The Explorables are interactive, touchable diagrams — drag a slider and watch a posterior re-form, step an interpreter one effect at a time, roll a Hamiltonian trajectory across a density. In the tradition of Bret Victor's explorable explanations and 3Blue1Brown.
- Anatomy of a Probabilistic Program — the coin-flip Bayes loop, fully touchable
- The Model Is a Score — a step-debugger for the
Modelmonad - Random Walks in Posterior Space — Metropolis–Hastings by hand
- Rolling, Not Guessing: HMC — Hamiltonian Monte Carlo, rolling a ball across the posterior landscape
- Particles That Tell Stories — sequential Monte Carlo, resampling made visible
- A Field Guide to Distributions — all 17 distributions, sampled live
Check out these resources to get started:
- Getting Started - Installation and first steps
- How-To Guides - Practical guides for common tasks
- Tutorials - In-depth learning materials
- API Reference - Complete API documentation
About Fugue
- 🧩 Monadic PPL: Compose probabilistic programs as pure
Modelvalues, then interpret them with pluggable handlers — effects are interpreted, never performed by the model itself - 🔒 Type-Safe Distributions: 17 built-in distributions with natural return types (
Bernoulli→bool,Poisson→u64,Categorical→usize) — the type system tracks what each draw is - 📊 Multiple Inference Methods: adaptive Metropolis–Hastings, Hamiltonian Monte Carlo, Sequential Monte Carlo (with an unbiased log-evidence estimate), Variational Inference (support-matched guide families), and importance-weighted ABC-SMC (see Advanced Inference)
- 🔍 Comprehensive Diagnostics: split-R̂ convergence, autocorrelation-based effective sample size, Geweke, and closed-form validation
- 🌀 Stack-Safe Interpreter: a trampolined runtime evaluates models in O(1) stack depth — 100 000-site programs run without overflowing
- ⚡ Numerically Stable: log-space computations throughout for robust probability arithmetic
- ✨ Ergonomic Macros: Do-notation (
prob!), vectorization (plate!), addressing (addr!)
Fugue is 0.2.x: pre-1.0, actively developed, with no SemVer stability guarantee yet and a single primary maintainer. It's extensively tested (unit, integration, and statistical regression tests against closed-form posteriors), but that's a different claim from "production-ready" — pin an exact version and expect breaking API changes between 0.x releases as the design settles.
Installation
[dependencies]
fugue-ppl = "0.2.0"