# sbi-dev/sbi architecture

> Architecture diagram of the GitHub repository sbi-dev/sbi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sbi-dev/sbi
- Repository: https://github.com/sbi-dev/sbi

## Overview

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: [`sbi/inference/trainers`](https://github.com/sbi-dev/sbi/tree/main/sbi/inference/trainers) (Trainers), [`sbi/utils`](https://github.com/sbi-dev/sbi/tree/main/sbi/utils) (Utils), [`sbi/neural_nets`](https://github.com/sbi-dev/sbi/tree/main/sbi/neural_nets) (Neural nets), [`sbi/inference/posteriors`](https://github.com/sbi-dev/sbi/tree/main/sbi/inference/posteriors) (Posteriors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_inference["Inference"]
  node_inference_api["Inference API<br/>entrypoints<br/>[__init__.py]"]
  node_trainers["Trainers<br/>training layer"]
  node_abc["ABC<br/>approximate bayes"]
  node_potentials["Potentials<br/>scoring"]
  node_posteriors["Posteriors"]
  node_npe_family["NPE/NPEA<br/>trainer family"]
  node_nle_family["NLE/MNLE<br/>trainer family"]
  node_nre_family["NRE<br/>trainer family"]
  node_vfpe_family["VFPE<br/>trainer family"]
end

subgraph group_group_nn["Neural nets"]
  node_neural_nets["Neural nets<br/>estimators"]
  node_net_builders["Builders<br/>factory layer"]
  node_embeddings["Embeddings<br/>feature encoders"]
  node_estimators["Estimators<br/>learned models"]
end

subgraph group_group_sampling["Sampling"]
  node_samplers["Samplers<br/>execution layer"]
end

subgraph group_group_eval["Evaluation"]
  node_analysis["Analysis<br/>plots + stats"]
  node_diagnostics["Diagnostics<br/>calibration"]
end

subgraph group_group_shared["Shared"]
  node_prior_simulator["Prior + simulator<br/>user inputs"]
  node_simulators["Toy sims<br/>simulators<br/>[linear_gaussian.py]"]
  node_utils["Utils<br/>shared glue"]
end

subgraph group_group_docs["Docs"]
  node_docs["Docs<br/>documentation"]
end

node_prior_simulator -->|"runs"| node_simulators
node_prior_simulator -->|"feeds"| node_inference_api
node_inference_api -->|"selects"| node_trainers
node_trainers -->|"implements"| node_npe_family
node_trainers -->|"implements"| node_nle_family
node_trainers -->|"implements"| node_nre_family
node_trainers -->|"implements"| node_vfpe_family
node_trainers -->|"branches"| node_abc
node_trainers -->|"builds on"| node_neural_nets
node_neural_nets -->|"configured by"| node_net_builders
node_neural_nets -->|"includes"| node_embeddings
node_neural_nets -->|"includes"| node_estimators
node_trainers -->|"produces"| node_potentials
node_potentials -->|"drives"| node_samplers
node_potentials -->|"wraps into"| node_posteriors
node_samplers -->|"samples"| node_posteriors
node_posteriors -->|"analyzed by"| node_analysis
node_posteriors -->|"evaluated by"| node_diagnostics
node_utils -->|"supports"| node_trainers
node_utils -->|"supports"| node_samplers
node_utils -->|"supports"| node_analysis
node_utils -->|"supports"| node_diagnostics
node_docs -.->|"documents"| node_inference_api
node_docs -.->|"documents"| node_samplers
node_docs -.->|"documents"| node_analysis

click node_prior_simulator "https://github.com/sbi-dev/sbi/tree/main/sbi/simulators"
click node_simulators "https://github.com/sbi-dev/sbi/blob/main/sbi/simulators/linear_gaussian.py"
click node_inference_api "https://github.com/sbi-dev/sbi/blob/main/sbi/inference/__init__.py"
click node_trainers "https://github.com/sbi-dev/sbi/tree/main/sbi/inference/trainers"
click node_abc "https://github.com/sbi-dev/sbi/tree/main/sbi/inference/abc"
click node_potentials "https://github.com/sbi-dev/sbi/tree/main/sbi/inference/potentials"
click node_posteriors "https://github.com/sbi-dev/sbi/tree/main/sbi/inference/posteriors"
click node_npe_family "https://github.com/sbi-dev/sbi/tree/main/sbi/inference/trainers/npe"
click node_nle_family "https://github.com/sbi-dev/sbi/tree/main/sbi/inference/trainers/nle"
click node_nre_family "https://github.com/sbi-dev/sbi/tree/main/sbi/inference/trainers/nre"
click node_vfpe_family "https://github.com/sbi-dev/sbi/tree/main/sbi/inference/trainers/vfpe"
click node_neural_nets "https://github.com/sbi-dev/sbi/tree/main/sbi/neural_nets"
click node_net_builders "https://github.com/sbi-dev/sbi/tree/main/sbi/neural_nets/net_builders"
click node_embeddings "https://github.com/sbi-dev/sbi/tree/main/sbi/neural_nets/embedding_nets"
click node_estimators "https://github.com/sbi-dev/sbi/tree/main/sbi/neural_nets/estimators"
click node_samplers "https://github.com/sbi-dev/sbi/tree/main/sbi/samplers"
click node_analysis "https://github.com/sbi-dev/sbi/tree/main/sbi/analysis"
click node_diagnostics "https://github.com/sbi-dev/sbi/tree/main/sbi/diagnostics"
click node_utils "https://github.com/sbi-dev/sbi/tree/main/sbi/utils"
click node_docs "https://github.com/sbi-dev/sbi/tree/main/docs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_inference_api,node_trainers,node_abc,node_potentials,node_posteriors,node_npe_family,node_nle_family,node_nre_family,node_vfpe_family toneBlue
class node_neural_nets,node_net_builders,node_embeddings,node_estimators toneAmber
class node_samplers toneMint
class node_analysis,node_diagnostics toneRose
class node_prior_simulator,node_simulators,node_utils toneIndigo
class node_docs toneTeal
```

## Components

### Inference

Training, potentials, and posterior construction.

- [Inference API](https://github.com/sbi-dev/sbi/blob/main/sbi/inference/__init__.py): entrypoints · User-facing inference namespace exposing the main algorithm families and workflow. · `sbi/inference/__init__.py`
- [Trainers](https://github.com/sbi-dev/sbi/tree/main/sbi/inference/trainers): training layer · Base training machinery and algorithm families for NPE, NLE, NRE, VFPE, marginal methods, and ABC. · `sbi/inference/trainers`
- [ABC](https://github.com/sbi-dev/sbi/tree/main/sbi/inference/abc): approximate bayes · Classic Monte Carlo and sequential ABC implementations as a separate branch of approximate inference. · `sbi/inference/abc`
- [Potentials](https://github.com/sbi-dev/sbi/tree/main/sbi/inference/potentials): scoring · Likelihood-, ratio-, posterior-, and vector-field-based objectives used for posterior construction and sampling. · `sbi/inference/potentials`
- [Posteriors](https://github.com/sbi-dev/sbi/tree/main/sbi/inference/posteriors): runtime posteriors · Direct, rejection, importance, MCMC, VI, ensemble, NPE-A, and vector-field posterior interfaces. · `sbi/inference/posteriors`
- [NPE/NPEA](https://github.com/sbi-dev/sbi/tree/main/sbi/inference/trainers/npe): trainer family · Neural posterior estimation trainers and sequential variants. · `sbi/inference/trainers/npe`
- [NLE/MNLE](https://github.com/sbi-dev/sbi/tree/main/sbi/inference/trainers/nle): trainer family · Neural likelihood estimation trainers and multivariate extensions. · `sbi/inference/trainers/nle`
- [NRE](https://github.com/sbi-dev/sbi/tree/main/sbi/inference/trainers/nre): trainer family · Neural ratio estimation trainers and their sequential variants. · `sbi/inference/trainers/nre`
- [VFPE](https://github.com/sbi-dev/sbi/tree/main/sbi/inference/trainers/vfpe): trainer family · 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](https://github.com/sbi-dev/sbi/tree/main/sbi/neural_nets): estimators · Embedding networks, density estimators, ratio estimators, score estimators, and vector-field networks. · `sbi/neural_nets`
- [Builders](https://github.com/sbi-dev/sbi/tree/main/sbi/neural_nets/net_builders): factory layer · Central construction/configuration helpers for estimators and embeddings. · `sbi/neural_nets/net_builders`
- [Embeddings](https://github.com/sbi-dev/sbi/tree/main/sbi/neural_nets/embedding_nets): feature encoders · Set, sequence, image, and time-series embedding networks. · `sbi/neural_nets/embedding_nets`
- [Estimators](https://github.com/sbi-dev/sbi/tree/main/sbi/neural_nets/estimators): learned models · Density, mixture, categorical, score, and flow-matching estimator implementations. · `sbi/neural_nets/estimators`

### Sampling

Posterior sampling and refinement backends.

- [Samplers](https://github.com/sbi-dev/sbi/tree/main/sbi/samplers): execution layer · Sampling backends for rejection, importance, MCMC, variational inference, and score-based/ODE methods. · `sbi/samplers`

### Evaluation

Analysis and diagnostics downstream of inference.

- [Analysis](https://github.com/sbi-dev/sbi/tree/main/sbi/analysis): plots + stats · Plotting, conditional density estimation, sensitivity analysis, and TensorBoard outputs. · `sbi/analysis`
- [Diagnostics](https://github.com/sbi-dev/sbi/tree/main/sbi/diagnostics): calibration · SBC, TARP, LC2ST, and misspecification checks for posterior quality assessment. · `sbi/diagnostics`

### Shared

Cross-cutting utilities and built-in simulators.

- [Prior + simulator](https://github.com/sbi-dev/sbi/tree/main/sbi/simulators): user inputs · The starting point for simulation-based inference: prior distributions and simulators that generate training pairs. · `sbi/simulators`
- [Toy sims](https://github.com/sbi-dev/sbi/blob/main/sbi/simulators/linear_gaussian.py): simulators · Built-in linear Gaussian and Gaussian mixture simulators used for examples and tests. · `sbi/simulators/linear_gaussian.py`
- [Utils](https://github.com/sbi-dev/sbi/tree/main/sbi/utils): shared glue · 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](https://github.com/sbi-dev/sbi/tree/main/docs): documentation · Sphinx and MkDocs documentation, tutorials, and workflow guides that mirror the library architecture. · `docs`

## Connections

- 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.
