Skip to content

Architecture

TorchEBM is organised around a small set of base classes (BaseModel, BaseSampler, BaseLoss, BaseIntegrator, BaseInterpolant, BaseCoupling). Everything else is composition in the training loop: a coupling and an interpolant build the regression target, a loss compares model outputs, a sampler drives the model through an integrator. The user-facing statement of this design is Design and Scope; this page is the contributor view.

Package layout

The tree below is generated from the installed package at build time (comments come from docs/hooks/gen_diagrams.py; new subpackages appear automatically):

torchebm/
├── core/          # Base classes, analytic energies, schedulers, TorchEBMModule
├── samplers/      # MCMC, optimization, and flow/diffusion samplers
├── losses/        # Training objectives (CD, score matching, equilibrium/energy matching)
├── interpolants/  # Noise-to-data probability paths
├── couplings/     # Pairings between noise and data batches
├── integrators/   # Numerical integrators for SDE/ODE/Hamiltonian dynamics
├── models/        # Neural architectures used as energies or fields
├── datasets/      # Synthetic data generators
├── utils/         # Shared helpers
└── cuda/          # Custom CUDA kernels

Mirror this layout under tests/ when adding tests.

Core abstractions

One contract per axis. The table is generated at build time from the root base classes exported by torchebm.core and the first line of their docstrings, so it always matches the code:

Base class Contract
BaseCoupling Abstract base class for couplings.
BaseIntegrator Abstract integrator that advances a sampler state according to dynamics.
BaseInterpolant Abstract base class for stochastic interpolants.
BaseLoss Abstract base class for loss functions used in energy-based models.
BaseModel Abstract base class for energy-based models (EBMs).
BaseSampler Abstract base class for samplers.
BaseScheduler Abstract base class for parameter schedulers.
TorchEBMModule Base nn.Module with cached, parameter-derived device/dtype access.

The current composition map and export counts, generated from the installed package at build time (see docs/hooks/gen_diagrams.py; per-family class trees render the same way on the Concepts pages):

graph LR
    field["energy / field<br/>core: 10 analytic energies · models"]
    interp["interpolants (4)"]
    coup["couplings (7)"]
    integ["integrators (12)"]
    samp["samplers (7)"]
    loss["objectives (14)"]
    data[("datasets (8)")]
    out(("samples"))
    field --> samp
    field --> loss
    interp --> loss
    interp --> samp
    coup --> loss
    integ --> samp
    samp -- negatives --> loss
    data --> loss
    samp --> out

String registries (get_integrator, get_coupling, get_interpolant) make each axis addressable by name; resolve_* helpers validate instances against the family a consumer requires. Every component exported through torchebm.*.__init__ is auto-discovered by the benchmark suite (see Performance and Benchmarking).

How the pieces compose

Training is the standard PyTorch loop: the model is called on inputs, a loss function compares its outputs with targets, the optimizer steps. Losses never hold the model; samplers take it as an argument of the call, sampler(model, x, n_steps=...), the torchdiffeq form. Two patterns cover the library.

Sampler-free (score, flow, EqM, EM warm-up)

The loop builds the target from data with a coupling and an interpolant: couple the batch, draw \(t\), interpolate, call the model, regress.

1
2
3
x0, x1 = coupling(torch.randn_like(x1), x1)
x_t, u_t = path(x0, x1, t)
loss = loss_fn(model(x_t, t), u_t)

Samplers only appear at generation time.

Sampler-based (CD family, EM joint phase)

Contrastive divergence draws negatives from the current model every step, from a replay buffer for persistent chains, and the loss compares the energies of data and negatives:

graph LR
    buffer[replay buffer] --> sampler
    model --> sampler
    sampler -- negatives x_neg --> model
    data[data x] --> model
    model -- "E(x), E(x_neg)" --> loss_fn
    loss_fn -- grad --> optimizer
    optimizer --> model

BaseTrainer.compute_loss implements exactly this step given a sampler and a buffer; other objectives override it.

Generation (all objectives)

A sampler drives the trained model through an integrator. MCMC samplers consume a score: an energy model is differentiated on the fly, a prediction_type="score" model passes through, an ("energy", "score") pair is indexed. FlowSampler integrates a velocity, score or noise prediction as an ODE or SDE on a uniform or custom time grid. Each piece can be swapped (e.g. integrator="heun" for "rk4") without changing the others.

Time conditioning

Not all objectives condition the model on \( t \):

  • EquilibriumMatching: time-invariant; the model is called as model(x_t) in training and declares no prediction_type, so every sampler consumes the raw field: FlowSampler integrates it as the velocity and the gradient samplers apply \( x \leftarrow x + \eta f(x) \) to it.
  • FlowSampler with velocity/score models: time-conditional; the field is \( v(x, t) \) and the sampler feeds \( t \) every step.
  • EnergyMatching: the potential \(V(x)\) is time-independent; time lives in the temperature schedule of the generation sweep.

See examples/20-training for the reference loops.