# pyro-ppl/numpyro architecture

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

- Interactive diagram: https://gitdiagram.com/pyro-ppl/numpyro
- Repository: https://github.com/pyro-ppl/numpyro

## Overview

NumPyro is a JAX-powered probabilistic programming library. Users define models with primitives and distributions, then run inference—especially MCMC—or variational inference to obtain posterior samples or fitted approximations; diagnostics help assess results. Effect handlers and inference utilities provide an internal layer for interpreting model execution and preparing densities. The README documents the main workflow and capabilities; the source index supports several internal links, while unsampled areas are represented only where documented.

Main entry points: [`numpyro/__init__.py`](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/__init__.py) (Public API), [`numpyro/distributions/distribution.py`](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/distributions/distribution.py) (Distributions), [`numpyro/primitives.py`](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/primitives.py) (Model primitives), [`numpyro/infer/mcmc.py`](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/infer/mcmc.py) (MCMC runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_modeling["Modeling"]
  node_primitives["Model primitives<br/>[primitives.py]"]
  node_distributions["Distributions<br/>[distribution.py]"]
  node_continuous["Continuous families<br/>[continuous.py]"]
  node_discrete["Discrete families<br/>[discrete.py]"]
  node_constraints["Support constraints<br/>[constraints.py]"]
  node_transforms["Bijective transforms<br/>[transforms.py]"]
end

subgraph group_inference["Inference"]
  node_mcmc["MCMC runner<br/>[mcmc.py]"]
  node_hmc["HMC and NUTS<br/>[hmc.py]"]
  node_vi["Variational inference<br/>[svi.py]"]
  node_elbo["ELBO objectives<br/>[elbo.py]"]
  node_guides["Automatic guides<br/>[autoguide.py]"]
  node_inferutil["Inference utilities<br/>[util.py]"]
  node_inspect["Model inspection<br/>[inspect.py]"]
  node_diagnostics["Sampling diagnostics<br/>[diagnostics.py]"]
end

subgraph group_runtime["Runtime Core"]
  node_api["Public API<br/>[__init__.py]"]
  node_handlers["Effect handlers<br/>[handlers.py]"]
  node_types["Shared types<br/>[_typing.py]"]
end

subgraph group_extensions["Extensions"]
  node_funsor["Discrete enumeration<br/>[enum_messenger.py]"]
  node_tfp["TFP distributions<br/>[distributions.py]"]
  node_steinvi["Stein variational inference<br/>[steinvi.py]"]
  node_hsgp["HSGP approximation<br/>[approximation.py]"]
end

node_user(("Model author"))

node_user -->|"uses"| node_api
node_api -->|"exports"| node_primitives
node_api -->|"exports"| node_handlers
node_api -->|"exports"| node_distributions
node_api -->|"exports inference"| node_mcmc
node_primitives -->|"dispatches messages"| node_handlers
node_primitives -->|"samples from"| node_distributions
node_distributions -->|"uses supports"| node_constraints
node_distributions -->|"uses transforms"| node_transforms
node_user -->|"defines model"| node_primitives
node_user -->|"chooses distributions"| node_distributions
node_mcmc -->|"runs kernel"| node_hmc
node_user -->|"runs inference"| node_mcmc
node_mcmc -.->|"reports samples"| node_diagnostics
node_vi -->|"optimizes objective"| node_elbo
node_vi -->|"uses guides"| node_guides
node_elbo -->|"evaluates model"| node_inferutil
node_hmc -->|"computes potential"| node_inferutil
node_inferutil -->|"conditions model"| node_handlers
node_inferutil -->|"constrains values"| node_constraints
node_api -->|"exports inspection"| node_inspect
node_handlers -->|"supports enumeration"| node_funsor
node_user -->|"can use distributions"| node_tfp
node_user -.->|"may choose extension"| node_steinvi
node_user -.->|"may choose extension"| node_hsgp

click node_api "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/__init__.py"
click node_primitives "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/primitives.py"
click node_handlers "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/handlers.py"
click node_types "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/_typing.py"
click node_distributions "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/distributions/distribution.py"
click node_continuous "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/distributions/continuous.py"
click node_discrete "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/distributions/discrete.py"
click node_constraints "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/distributions/constraints.py"
click node_transforms "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/distributions/transforms.py"
click node_mcmc "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/infer/mcmc.py"
click node_hmc "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/infer/hmc.py"
click node_vi "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/infer/svi.py"
click node_elbo "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/infer/elbo.py"
click node_guides "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/infer/autoguide.py"
click node_inferutil "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/infer/util.py"
click node_inspect "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/infer/inspect.py"
click node_diagnostics "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/diagnostics.py"
click node_funsor "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/contrib/funsor/enum_messenger.py"
click node_tfp "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/contrib/tfp/distributions.py"
click node_steinvi "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/contrib/einstein/steinvi.py"
click node_hsgp "https://github.com/pyro-ppl/numpyro/blob/master/numpyro/contrib/hsgp/approximation.py"

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_primitives,node_distributions,node_continuous,node_discrete,node_constraints,node_transforms toneBlue
class node_mcmc,node_hmc,node_vi,node_elbo,node_guides,node_inferutil,node_inspect,node_diagnostics toneAmber
class node_api,node_handlers,node_types toneMint
class node_funsor,node_tfp,node_steinvi,node_hsgp toneRose
class node_user toneIndigo
```

## Components

### Modeling

- [Model primitives](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/primitives.py): `numpyro/primitives.py`
- [Distributions](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/distributions/distribution.py): `numpyro/distributions/distribution.py`
- [Continuous families](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/distributions/continuous.py): `numpyro/distributions/continuous.py`
- [Discrete families](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/distributions/discrete.py): `numpyro/distributions/discrete.py`
- [Support constraints](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/distributions/constraints.py): `numpyro/distributions/constraints.py`
- [Bijective transforms](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/distributions/transforms.py): `numpyro/distributions/transforms.py`

### Inference

- [MCMC runner](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/infer/mcmc.py): `numpyro/infer/mcmc.py`
- [HMC and NUTS](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/infer/hmc.py): `numpyro/infer/hmc.py`
- [Variational inference](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/infer/svi.py): `numpyro/infer/svi.py`
- [ELBO objectives](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/infer/elbo.py): `numpyro/infer/elbo.py`
- [Automatic guides](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/infer/autoguide.py): `numpyro/infer/autoguide.py`
- [Inference utilities](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/infer/util.py): `numpyro/infer/util.py`
- [Model inspection](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/infer/inspect.py): `numpyro/infer/inspect.py`
- [Sampling diagnostics](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/diagnostics.py): `numpyro/diagnostics.py`

### Runtime Core

- [Public API](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/__init__.py): `numpyro/__init__.py`
- [Effect handlers](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/handlers.py): `numpyro/handlers.py`
- [Shared types](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/_typing.py): `numpyro/_typing.py`

### Extensions

- [Discrete enumeration](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/contrib/funsor/enum_messenger.py): `numpyro/contrib/funsor/enum_messenger.py`
- [TFP distributions](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/contrib/tfp/distributions.py): `numpyro/contrib/tfp/distributions.py`
- [Stein variational inference](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/contrib/einstein/steinvi.py): `numpyro/contrib/einstein/steinvi.py`
- [HSGP approximation](https://github.com/pyro-ppl/numpyro/blob/master/numpyro/contrib/hsgp/approximation.py): `numpyro/contrib/hsgp/approximation.py`

### Other components

- **Model author**

## Connections

- Model author → Public API: uses
- Public API → Model primitives: exports (evidence: `numpyro/__init__.py`)
- Public API → Effect handlers: exports (evidence: `numpyro/__init__.py`)
- Public API → Distributions: exports (evidence: `numpyro/__init__.py`)
- Public API → MCMC runner: exports inference (evidence: `numpyro/__init__.py`)
- Model primitives → Effect handlers: dispatches messages (evidence: `numpyro/primitives.py`)
- Model primitives → Distributions: samples from (evidence: `numpyro/primitives.py`)
- Distributions → Support constraints: uses supports (evidence: `numpyro/distributions/distribution.py`)
- Distributions → Bijective transforms: uses transforms (evidence: `numpyro/distributions/distribution.py`)
- Model author → Model primitives: defines model
- Model author → Distributions: chooses distributions
- MCMC runner → HMC and NUTS: runs kernel (evidence: `numpyro/infer/hmc.py`)
- Model author → MCMC runner: runs inference
- MCMC runner → Sampling diagnostics: reports samples
- Variational inference → ELBO objectives: optimizes objective
- Variational inference → Automatic guides: uses guides (evidence: `numpyro/infer/autoguide.py`)
- ELBO objectives → Inference utilities: evaluates model (evidence: `numpyro/infer/elbo.py`)
- HMC and NUTS → Inference utilities: computes potential (evidence: `numpyro/infer/hmc.py`)
- Inference utilities → Effect handlers: conditions model (evidence: `numpyro/infer/util.py`)
- Inference utilities → Support constraints: constrains values (evidence: `numpyro/infer/util.py`)
- Public API → Model inspection: exports inspection (evidence: `numpyro/__init__.py`)
- Effect handlers → Discrete enumeration: supports enumeration (evidence: `numpyro/handlers.py`)
- Model author → TFP distributions: can use distributions
- Model author → Stein variational inference: may choose extension
- Model author → HSGP approximation: may choose extension
