How sbi-dev/sbi works
1. What this repo is
- sbi is a Python 3.10+ simulation-based inference toolkit built on PyTorch.
- The core architectural idea is: user supplies a prior and a simulator, sbi generates simulations, trains an inference model, and turns that model into a posterior object for sampling and diagnostics.
2. Top-level package boundaries
- The package is split into four major runtime areas:
- sbi/inference: training and posterior construction
- sbi/neural_nets: neural estimators and network builders
- sbi/samplers: post-training sampling and refinement
- sbi/analysis + sbi/diagnostics: evaluation, plotting, and calibration checks
- sbi/utils contains shared glue used across these layers.
3. Inference entry points
- The user-facing API lives under sbi.inference and exposes algorithm families like NPE, NLE, NRE, MNLE, and vector-field methods.
- The main workflow is append simulations, train, then build a posterior.
- There is a clear split between trainers and posterior objects: trainers learn a model; posterior classes wrap that learned model into an inference-time interface.
4. Algorithm families
- sbi/inference/trainers/npe, nle, nre, vfpe, and marginal implement the major training strategies.
- sbi/inference/abc provides classic ABC variants (mcabc, smcabc) as a separate branch of approximate inference.
- Sequential and amortized variants are represented as different trainer/potential/posterior combinations rather than a single monolith.
5. Model/potential/posterior separation
- sbi/inference/potentials defines the scoring functions used by samplers and posterior construction.
- sbi/inference/posteriors defines runtime posterior objects such as direct, rejection, MCMC, importance, VI, ensemble, and vector-field posteriors.
- This separation matters architecturally: training produces estimators, potentials transform estimators into sampling objectives, and posterior classes expose the final inference interface.
6. Neural network subsystem
- sbi/neural_nets contains the learned components used by the trainers: embedding networks, density estimators, ratio estimators, score estimators, and vector-field networks.
- net_builders and factory.py centralize construction/configuration, so trainer code can request models by type rather than instantiate architectures directly.
- Embedding networks cover different input structures such as sets, sequences, images, and time-series-like data.
7. Sampling and refinement layer
- sbi/samplers is the execution layer for turning posteriors/potentials into samples.
- It includes:
- rejection sampling
- importance sampling / SIR
- MCMC wrappers and initialization strategies
- VI utilities
- score-based samplers and ODE solvers for vector-field methods
- Optional external MCMC backends are supported through Pyro and PyMC, which are material dependencies because they extend the sampling boundary beyond native PyTorch code.
8. Simulation and example models
- sbi/simulators provides lightweight built-in simulators such as linear Gaussian and Gaussian mixture models.
- sbi/examples/minimal.py is the smallest end-to-end integration example and effectively demonstrates the package’s intended control flow.
- Tests also include miniature sbibm-style tasks under tests/mini_sbibm, indicating that the repo validates against standardized benchmark-like simulation tasks.
9. Analysis and diagnostics
- sbi/analysis provides plotting, conditional density estimation, sensitivity analysis, and TensorBoard output helpers.
- sbi/diagnostics contains formal evaluation tools such as SBC, TARP, LC2ST, and model misspecification checks.
- These modules are downstream consumers of posterior samples and simulated observations; they do not train models, but assess calibration and quality.
10. Shared utilities and cross-cutting concerns
- sbi/utils holds common functionality for input validation, I/O, metrics, plotting helpers, posterior ensembles, Pyro integration utilities, and tensor/torch helpers.
- This layer is the main boundary for reusable infrastructure that many subsystems depend on, especially checks around user inputs, device handling, and simulation bookkeeping.
11. Documentation and tutorial system
- The repo is documentation-heavy: docs/ contains Sphinx docs and notebook tutorials, while mkdocs/ contains a separate documentation site configuration.
- The docs are organized by workflow stage: prior/simulator setup, training, sampling, diagnostics, and visualization.
- The architecture of the docs mirrors the library architecture, which is useful for understanding the intended user journey.
12. Quality, packaging, and delivery
- pyproject.toml, MANIFEST.in, and the package layout indicate a standard Python distribution.
- CI/CD is fully automated via GitHub Actions for linting, testing, code coverage, release publishing, and documentation-related checks.
- The test suite is broad and maps directly onto subsystems: inference algorithms, samplers, diagnostics, neural nets, plotting, I/O, and device behavior.
13. Overall data flow
- The canonical flow is: prior + simulator → simulated training pairs → trainer → learned estimator → potential/posterior → sampler → posterior samples → diagnostics/analysis.
- The main architectural boundary is between simulation/training time and inference/evaluation time.
- Another important boundary is between algorithm-agnostic infrastructure (utils, samplers, analysis) and algorithm-specific trainers (npe, nle, nre, vfpe, abc).
Main entry points: trainers Trainers · utils Utils · neural_nets Neural nets · posteriors Posteriors
Components 20
Inference
Training, potentials, and posterior construction.
- Inference API · User-facing inference namespace exposing the main algorithm families and workflow.
sbi/inference/__init__.py - Trainers · Base training machinery and algorithm families for NPE, NLE, NRE, VFPE, marginal methods, and ABC.
sbi/inference/trainers - ABC · Classic Monte Carlo and sequential ABC implementations as a separate branch of approximate inference.
sbi/inference/abc - Potentials · Likelihood-, ratio-, posterior-, and vector-field-based objectives used for posterior construction and sampling.
sbi/inference/potentials - Posteriors · Direct, rejection, importance, MCMC, VI, ensemble, NPE-A, and vector-field posterior interfaces.
sbi/inference/posteriors - NPE/NPEA · Neural posterior estimation trainers and sequential variants.
sbi/inference/trainers/npe - NLE/MNLE · Neural likelihood estimation trainers and multivariate extensions.
sbi/inference/trainers/nle - NRE · Neural ratio estimation trainers and their sequential variants.
sbi/inference/trainers/nre - VFPE · Vector-field and flow-matching style trainers for score/vector-field inference.
sbi/inference/trainers/vfpe
Neural nets
Learned estimators and network builders.
- Neural nets · Embedding networks, density estimators, ratio estimators, score estimators, and vector-field networks.
sbi/neural_nets - Builders · Central construction/configuration helpers for estimators and embeddings.
sbi/neural_nets/net_builders - Embeddings · Set, sequence, image, and time-series embedding networks.
sbi/neural_nets/embedding_nets - Estimators · Density, mixture, categorical, score, and flow-matching estimator implementations.
sbi/neural_nets/estimators
Sampling
Posterior sampling and refinement backends.
- Samplers · Sampling backends for rejection, importance, MCMC, variational inference, and score-based/ODE methods.
sbi/samplers
Evaluation
Analysis and diagnostics downstream of inference.
- Analysis · Plotting, conditional density estimation, sensitivity analysis, and TensorBoard outputs.
sbi/analysis - Diagnostics · SBC, TARP, LC2ST, and misspecification checks for posterior quality assessment.
sbi/diagnostics
Shared
Cross-cutting utilities and built-in simulators.
- Prior + simulator · The starting point for simulation-based inference: prior distributions and simulators that generate training pairs.
sbi/simulators - Toy sims · Built-in linear Gaussian and Gaussian mixture simulators used for examples and tests.
sbi/simulators/linear_gaussian.py - Utils · Validation, I/O, metrics, plotting helpers, posterior ensembles, Pyro integration, and torch utilities.
sbi/utils
Docs
Tutorials and reference material mirroring the library flow.
- Docs · Sphinx and MkDocs documentation, tutorials, and workflow guides that mirror the library architecture.
docs
Connections 25
- Prior + simulator → Toy sims: runs · Built-in simulators are example sources of synthetic observations.
- Prior + simulator → Inference API: feeds · User priors and simulations enter the main inference workflow.
- Inference API → Trainers: selects · The API routes users into the appropriate algorithm family.
- Trainers → NPE/NPEA: implements · NPE trainers produce posterior estimators.
- Trainers → NLE/MNLE: implements · NLE trainers produce likelihood estimators.
- Trainers → NRE: implements · NRE trainers produce ratio estimators.
- Trainers → VFPE: implements · VFPE trainers produce vector-field or flow-matching models.
- Trainers → ABC: branches · ABC is maintained as a separate approximate inference path.
- Trainers → Neural nets: builds on · Training code depends on the neural estimator subsystem.
- Neural nets → Builders: configured by · Builders centralize model construction and hyperparameter wiring.
- Neural nets → Embeddings: includes · Embedding networks encode structured simulator outputs.
- Neural nets → Estimators: includes · Core learned estimators live here.
- Trainers → Potentials: produces · Trained estimators are converted into potentials for inference-time use.
- Potentials → Samplers: drives · Potentials define objectives consumed by samplers and refinement methods.
- Potentials → Posteriors: wraps into · Potentials and estimators are turned into posterior objects.
- Samplers → Posteriors: samples · Sampling backends produce posterior samples from posterior objects or potentials.
- Posteriors → Analysis: analyzed by · Posterior samples are consumed by analysis tools.
- Posteriors → Diagnostics: evaluated by · Diagnostics assess calibration and misspecification of posterior behavior.
- Utils → Trainers: supports · Shared checks and helpers are used throughout training.
- Utils → Samplers: supports · Shared infrastructure supports sampling and backend integration.
- Utils → Analysis: supports · Plotting and analysis helpers are centralized here.
- Utils → Diagnostics: supports · Diagnostics utilities and common checks live here.
- Docs → Inference API: documents · Documentation follows the main user workflow and API surface.
- Docs → Samplers: documents · Tutorials cover posterior sampling and refinement.
- Docs → Analysis: documents · Docs include visualization and analysis workflows.