🎼 Fugue

A production-ready, monadic probabilistic programming library for Rust

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.70+ • Platforms: Linux / macOS / Windows • Crate: fugue-ppl on crates.io

✨ Features

• Monadic PPL: Compose probabilistic programs using pure functional abstractions
• Type-Safe Distributions: 10+ built-in probability distributions with natural return types
• Multiple Inference Methods: MCMC, SMC, Variational Inference, ABC
• Comprehensive Diagnostics: R-hat convergence, effective sample size, validation
• Production Ready: Numerically stable algorithms with memory optimization
• Ergonomic Macros: Do-notation (prob!), vectorization (plate!), addressing (addr!)

🤔 Why Fugue?

• 🔒 Type-safe distributions: natural return types (Bernoulli → bool, Poisson/Binomial → u64, Categorical → usize)
• 🧩 Direct-style, monadic design: compose Model<T> values with bind/map for explicit, readable control flow
• 🔌 Pluggable interpreters: prior sampling, replay, scoring, and safe variants for production robustness
• 📊 Production diagnostics: R-hat, ESS, validation utilities, and robust error handling
• ⚡ Performance-minded: memory pooling, copy-on-write traces, and numerically stable computations

📦 Installation

[dependencies]
fugue-ppl = "0.1.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
• API Reference - Complete API documentation
• Examples - See examples/ directory
• References - Zotero library for Fugue

🤝 Community

• Issues & Bugs: Use GitHub Issues
• Feature Requests: Open an issue with the enhancement label
• 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

🤝 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{fugue2025,
  title = {Fugue: Monadic Probabilistic Programming for Rust},
  author = {Alexander Nodeland},
  url = {https://github.com/alexnodeland/fugue},
  version = {0.1.0},
  year = {2025}
}

Or refer to the "Internal" collection in Zotero to generate a bibliography.