Crate fugue 

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

Community

• Issues & Bugs: Use GitHub Issues
• Feature Requests: Open an issue with the enhancement label

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/alexandernodeland/fugue.git
cd fugue && cargo test

License

Licensed under the MIT License.

---

Built with Rust • Monadic PPL • Type-safe distributions

Re-exports

pub use core::address::Address;

pub use core::distribution::Bernoulli;

pub use core::distribution::Beta;

pub use core::distribution::Binomial;

pub use core::distribution::Categorical;

pub use core::distribution::Distribution;

pub use core::distribution::Exponential;

pub use core::distribution::Gamma;

pub use core::distribution::LogNormal;

pub use core::distribution::Normal;

pub use core::distribution::Poisson;

pub use core::distribution::Uniform;

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_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::handler::Handler;

pub use runtime::interpreters::PriorHandler;

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::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::mcmc_utils::effective_sample_size_mcmc;

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_single_site_mh;

pub use inference::smc::adaptive_smc;

pub use inference::smc::effective_sample_size;

pub use inference::smc::Particle;

pub use inference::smc::ResamplingMethod;

pub use inference::smc::SMCConfig;

pub use inference::validation::ks_test_distribution;

pub use inference::validation::test_conjugate_normal_model;

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;

pub use runtime::memory::CowTrace;

pub use runtime::memory::PooledPriorHandler;

pub use runtime::memory::TraceBuilder;

pub use runtime::memory::TracePool;

Modules

core

core module

error

Error handling for probabilistic programming operations.

inference

inference module

macros

macros module

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 Address instances with human-readable names and optional indices. The macro supports two forms:

invalid_params

Create an InvalidParameters error with optional context.

numerical_error

Create a NumericalError 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.