Skip to content
Projects

soran-ghaderi/torchebm has 119 GitHub stars and 24 forks. GitHot measured 0 stars in 24 hours and +2 in 7 days. Last checked 2026-11-15 15:49 UTC. Last push 2026-11-15.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
+2
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

🍓 Simulation-free, GPU-first generative modeling in PyTorch ⚡ Composable primitives for scalable, stable training of modern EBMs, diffusion, flow matching, and Schrödinger bridges.

Machine Learning

README.md

Original

TorchEBM Logo

PyPI License GitHub Stars Ask DeepWiki Build Status Docs Downloads Python Versions

⚡ TorchEBM: simulation-free, GPU-first generative modeling in PyTorch

Composable primitives for scalable, stable training of EBMs, diffusion, flow matching, and equilibrium and energy matching.

An energy landscape being learned from data
An energy landscape learning to place its low-energy basins on the data.

What is ∇ TorchEBM 🍓?

A PyTorch library of composable, GPU-first primitives for energy-based models, diffusion, flow matching, and equilibrium and energy matching. Every method is a composition of the same parts:

Component Role Package
Model the energy or vector field torchebm.core, torchebm.models
Interpolant the path from noise to data torchebm.interpolants
Coupling which noise pairs with which datum torchebm.couplings
Objective how the model fits the data torchebm.losses
Sampler the dynamics that generate torchebm.samplers
Integrator how the dynamics are discretized torchebm.integrators

📚 Documentation · 🧭 Design and scope · ⚡ Benchmarks

Equilibrium matching transporting noise onto eight gaussians
Equilibrium matching on eight gaussians.

What's inside

Training objectives (torchebm.losses)

Objective Idea Inner sampling
ContrastiveDivergenceLoss push energy down on data, up on short-run MCMC negatives drawn by any sampler; a ReplayBuffer gives persistent CD yes
ScoreMatchingLoss match the model score to the data score no
DenoisingScoreMatchingLoss match the score of noise-perturbed data no
SlicedScoreMatchingLoss estimate the Hessian trace by random projections no
FlowMatchingLoss regress a time-conditioned velocity onto the conditional velocity of a path no
EquilibriumMatchingLoss regress a time-invariant field (implicit) or the gradient of a potential (EqM-E) onto the scaled path velocity; generate by ODE integration or fixed-point iteration no
EnergyMatchingLoss one time-independent potential: optimal-transport flow warm-up, then contrastive sharpening of its Boltzmann density phase two only

Samplers (torchebm.samplers)

Sampler Dynamics
LangevinDynamics overdamped Langevin: steps along the score with Gaussian noise; samples the Boltzmann density of an energy
HamiltonianMonteCarlo Hamiltonian trajectories with a symplectic integrator and a Metropolis test
RiemannianManifoldHMC HMC on a position-dependent metric, for ill-conditioned geometry
GradientDescentSampler noise-free steps along the model's field: descent on an energy, fixed-point iteration on a general field
NesterovSampler the same steps with Nesterov momentum
FlowSampler continuous-time generation: mode="ode" (probability flow) or mode="sde" (diffusion), from velocity, score, or noise predictions

Numerical integrators (torchebm.integrators)

Family Integrators
Explicit Runge-Kutta MidpointIntegrator, HeunIntegrator, Bosh3Integrator, RK4Integrator, RK438Integrator
Adaptive step size AdaptiveHeunIntegrator, Dopri5Integrator, Dopri8Integrator
Stochastic (SDE) EulerMaruyamaIntegrator, BackwardEulerMaruyamaIntegrator (implicit)
Symplectic (Hamiltonian) LeapfrogIntegrator, GeneralisedLeapfrogIntegrator (non-separable)

Paths and pairings (torchebm.interpolants, torchebm.couplings)

Interpolants Couplings
LinearInterpolant (flow matching) IndependentCoupling (the classical pairing)
CosineInterpolant GreedyCoupling (nearest unmatched)
VariancePreservingInterpolant, VarianceExplodingInterpolant (diffusion) SinkhornCoupling (entropic OT), ExactOTCoupling
UnbalancedSinkhornCoupling (per-pair weights)

And the rest

Analytic energies (GaussianModel, DoubleWellModel, ...), DiT presets, TimeConditionedMLP, ClassifierFreeGuidance, InteractionModel, ReplayBuffer, BaseTrainer, schedulers, 2D datasets, CUDA kernels and mixed precision.

Install

pip install torchebm

Usage

Each block implements one published method. Runnable versions are in the examples.

Equilibrium matching

Equilibrium Matching: Generative Modeling with Implicit Energy-Based Models, Wang & Du 2025. One time-invariant field that vanishes on the data, sampled by descending it.

Flow matching's field changes with t; equilibrium matching learns a single time-invariant field
Fig. 1 of Wang & Du (2025).

EqM-XL/2 on ImageNet 256 latents x1 with labels y at times t:

model = dit_xl_2(input_size=32, in_channels=4, num_classes=1000, time_invariant=True)
path, loss_fn = LinearInterpolant(), EquilibriumMatchingLoss()
sampler = NesterovSampler(step_size=0.0017, momentum=0.3, lookahead_only=True,
                          prediction_type="velocity")

x_t, u_t = path(torch.randn_like(x1), x1, t)
loss = loss_fn(model(x_t, y=y), u_t, t)
samples = sampler(model, torch.randn_like(x1), n_steps=249, model_kwargs={"y": y})
Full recipe as in the paper: VAE moments encoded once, EMA, guidance and decoding
import torch
from diffusers.models import AutoencoderKL
from torch.optim.swa_utils import AveragedModel, get_ema_multi_avg_fn
from torch.utils.data import DataLoader, TensorDataset
from torchvision import datasets, transforms
from torchebm.interpolants import LinearInterpolant
from torchebm.losses import EquilibriumMatchingLoss
from torchebm.models import ClassifierFreeGuidance, dit_xl_2
from torchebm.samplers import NesterovSampler

transform = transforms.Compose([
    transforms.Resize(256),
    transforms.CenterCrop(256),
    transforms.ToTensor(),
    transforms.Normalize([0.5, 0.5, 0.5], [0.5, 0.5, 0.5]),
])
dataset = datasets.ImageFolder("imagenet/train", transform)
vae = AutoencoderKL.from_pretrained("stabilityai/sd-vae-ft-ema").cuda()

moments = torch.empty(len(dataset), 2, 8, 32, 32, dtype=torch.float16)
with torch.no_grad():
    for i, (images, _) in enumerate(DataLoader(dataset, batch_size=256, num_workers=8)):
        for mirror, view in enumerate([images, images.flip(-1)]):
            latent = vae.encode(view.cuda()).latent_dist
            moments[256 * i : 256 * i + len(view), mirror] = torch.cat([latent.mean, latent.std], 1)
labels = torch.tensor(dataset.targets)
loader = DataLoader(TensorDataset(moments, labels), batch_size=256, shuffle=True, drop_last=True)

model = dit_xl_2(
    input_size=32, in_channels=4, num_classes=1000, class_dropout_prob=0.1,
    time_invariant=True,
).cuda()
optimizer = torch.optim.AdamW(model.parameters(), lr=1e-4, weight_decay=0)
ema = AveragedModel(model, multi_avg_fn=get_ema_multi_avg_fn(0.9999))
path, loss_fn = LinearInterpolant(), EquilibriumMatchingLoss()

for epoch in range(1400):
    for batch, y in loader:
        mirror = torch.randint(2, (len(y),))
        mean, std = batch[torch.arange(len(y)), mirror].cuda().float().chunk(2, dim=1)
        x1, y = (mean + std * torch.randn_like(std)) * 0.18215, y.cuda()
        x0, t = torch.randn_like(x1), torch.rand(len(x1), device="cuda")
        x_t, u_t = path(x0, x1, t)
        loss = loss_fn(model(x_t, y=y), u_t, t)
        optimizer.zero_grad()
        loss.backward()
        optimizer.step()
        ema.update_parameters(model)

guided = ClassifierFreeGuidance(
    ema.module.eval(), guidance_scale=1.5, null_condition=1000, guide_channels=3
)
sampler = NesterovSampler(
    step_size=0.0017, momentum=0.3, lookahead_only=True, prediction_type="velocity"
)
y = torch.randint(1000, (64,), device="cuda")
noise = torch.randn(64, 4, 32, 32, device="cuda")
latents = sampler(guided, noise, n_steps=249, model_kwargs={"y": y})
with torch.no_grad():
    samples = vae.decode(latents / 0.18215).sample

Energy matching

Energy Matching: Unifying Flow Matching and Energy-Based Models, Balcerak et al. 2025. One time-independent potential: an OT flow warm-up, then contrastive sharpening near the data.

Action matching, OT flow matching, EBM and energy matching transporting eight gaussians onto two moons
Fig. 1 of Balcerak et al. (2025).

from torchebm.core import TemperatureScheduler
from torchebm.couplings import SinkhornCoupling
from torchebm.interpolants import LinearInterpolant
from torchebm.losses import EnergyMatchingLoss
from torchebm.samplers import LangevinDynamics

model = EnergyMLP(prediction_type=("energy", "score"))
coupling, path = SinkhornCoupling(reg=0.01), LinearInterpolant()
loss_fn = EnergyMatchingLoss(lambda_cd=2.0)
optimizer = torch.optim.Adam(model.parameters(), lr=1e-4)
langevin_sweep = LangevinDynamics(
    step_size=0.01, noise_scale=TemperatureScheduler(epsilon_max=0.15, tau_star=0.8, n_steps=200)
)
langevin_hold = LangevinDynamics(step_size=0.01, noise_scale=0.15 ** 0.5)

for step in range(22_000):
    x1 = data[torch.randint(len(data), (128,))]
    x0, x1 = coupling(torch.randn_like(x1), x1)
    t = torch.rand(len(x1))
    x_t, u_t = path(x0, x1, t)
    _, score = model(x_t)
    if step < 20_000:
        loss = loss_fn(score, u_t, t)
    else:
        negatives = torch.cat([langevin_sweep(model, x0[:64], n_steps=200),
                               langevin_hold(model, x1[64:], n_steps=200)])
        loss = loss_fn(score, u_t, t, model(x1)[0], model(negatives)[0])
    optimizer.zero_grad(); loss.backward(); optimizer.step()

temperature = TemperatureScheduler(epsilon_max=0.15, tau_star=0.8, n_steps=200, t_end=1.0)
sampler = LangevinDynamics(step_size=0.01, noise_scale=temperature)
samples = sampler(model, torch.randn(4000, 2), n_steps=200)

Flow matching

Flow Matching for Generative Modeling, Lipman et al. 2023. Regress a time-conditioned velocity field onto the conditional velocity of a probability path.

Diffusion path conditional score field versus optimal-transport path conditional vector field
Fig. 2 of Lipman et al. (2023).

from torchebm.interpolants import LinearInterpolant
from torchebm.losses import FlowMatchingLoss
from torchebm.models import TimeConditionedMLP
from torchebm.samplers import FlowSampler

model = TimeConditionedMLP(in_dim=2)
path, loss_fn = LinearInterpolant(), FlowMatchingLoss()

x1 = data[torch.randint(len(data), (256,))]
x0 = torch.randn_like(x1)
t = torch.rand(len(x1))
x_t, u_t = path(x0, x1, t)
loss = loss_fn(model(x_t, t), u_t)

sampler = FlowSampler(interpolant="linear", integrator="heun")
samples = sampler(model, torch.randn(1000, 2), n_steps=50)

With interpolant="vp" and mode="sde", the same sampler runs score-based diffusion (Song et al. 2021):

Forward SDE to a prior, reverse SDE and probability flow ODE back to data
Fig. 2 of Song et al. (2021).

sampler = FlowSampler(mode="sde", interpolant="vp", prediction_type="epsilon")
samples = sampler(model, torch.randn(1000, 2), n_steps=250)

Optimal-transport couplings

Improving and generalizing flow-based generative models with minibatch optimal transport, Tong et al. 2024. Minibatch OT pairing straightens the flow.

Flow matching, conditional flow matching and OT conditional flow matching probability paths
Fig. 1 of Tong et al. (2024).

from torchebm.couplings import SinkhornCoupling, ExactOTCoupling

coupling = SinkhornCoupling(reg=0.05)
x0, x1 = coupling(x0, x1)

Rectified flow

Flow Straight and Fast, Liu et al. 2023. Retrain on the flow's own (noise, sample) pairs for straight, few-step paths.

Linear interpolation crosses; the rectified flow induced by its own pairs is straight
Fig. 2 of Liu et al. (2023).

x0 = torch.randn(256, 2)
x1 = FlowSampler(integrator="heun")(model, x0, n_steps=50)

Contrastive divergence

Training products of experts by minimizing contrastive divergence, Hinton 2002, with the deep-EBM recipe of Du & Mordatch 2019. Push the energy down on data and up on short-run MCMC negatives.

Replay buffer, Langevin negatives, and the CD objective
Fig. 1 of Du & Mordatch (2019).

import torch
from torch import nn
from torchebm.core import BaseModel
from torchebm.datasets import TwoMoonsDataset
from torchebm.losses import ContrastiveDivergenceLoss
from torchebm.samplers import LangevinDynamics

class EnergyMLP(BaseModel):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.net = nn.Sequential(nn.Linear(2, 128), nn.SiLU(), nn.Linear(128, 1))
    def forward(self, x):
        return self.net(x).squeeze(-1)

data = TwoMoonsDataset(n_samples=3000, noise=0.05).get_data()
model = EnergyMLP()
sampler = LangevinDynamics(step_size=0.1, noise_scale=1.0)
loss_fn = ContrastiveDivergenceLoss()
optimizer = torch.optim.Adam(model.parameters(), lr=1e-3)

for _ in range(1000):
    batch = data[torch.randint(len(data), (256,))]
    negatives = sampler(model, batch, n_steps=10)
    loss = loss_fn(model(batch), model(negatives))
    optimizer.zero_grad(); loss.backward(); optimizer.step()

Persistent CD (Tieleman 2008) keeps the chains in a replay buffer:

from torchebm.utils import ReplayBuffer

buffer = ReplayBuffer(capacity=8192, sample_shape=(2,))
negatives = sampler(model, buffer.sample(256), n_steps=10)
buffer.add(negatives)

Score matching

Estimation of non-normalized statistical models by score matching, Hyvärinen 2005, with denoising (Vincent 2011) and sliced (Song et al. 2019) variants.

from torchebm.losses import DenoisingScoreMatchingLoss

model = EnergyMLP(prediction_type="score")
x = data[torch.randint(len(data), (256,))]
noise = torch.randn_like(x)
loss = DenoisingScoreMatchingLoss()(model(x + 0.1 * noise), -noise / 0.1)

Sampling an energy

Chains are a batch dimension, and the model is an argument of the call.

import torch
from torchebm.core import GaussianModel
from torchebm.samplers import LangevinDynamics

model = GaussianModel(mean=torch.zeros(2), cov=torch.tensor([[1., .8], [.8, 1.]]))
sampler = LangevinDynamics(step_size=0.02, noise_scale=1.0)

samples = sampler(model, torch.randn(10_000, 2), n_steps=500)

Hamiltonian Monte Carlo

MCMC using Hamiltonian dynamics, Neal 2011.

from torchebm.samplers import HamiltonianMonteCarlo

sampler = HamiltonianMonteCarlo(step_size=0.1, n_leapfrog_steps=10)
samples = sampler(model, torch.randn(1000, 2), n_steps=500)

Riemannian manifold HMC

Riemann manifold Langevin and Hamiltonian Monte Carlo, Girolami & Calderhead 2011. metric_fn maps (b, d) points to (b, d, d) SPD matrices.

from torchebm.samplers import RiemannianManifoldHMC

def metric_fn(x):
    scale = 1.0 + x.pow(2).sum(-1)[:, None, None]
    return torch.eye(2).expand(x.shape[0], 2, 2) * scale

sampler = RiemannianManifoldHMC(metric_fn=metric_fn, step_size=0.05, n_leapfrog_steps=5)
samples = sampler(model, torch.randn(1000, 2), n_steps=200)

Examples

Runnable and tested in CI: examples/, also on the website.

Tier You learn to
00-foundations/ work with energies, datasets, schedulers, and interpolants
10-sampling/ sample a fixed target with MCMC, parallel chains, integrators, and flows
20-training/ learn a target: CD, persistent CD, score matching, equilibrium and energy matching, couplings
90-showcase/ study end-to-end demos that push the components
python examples/10-sampling/01-mcmc/01-langevin-101/main.py

Contributing

See CONTRIBUTING.md and the Developer Guide.

Built with TorchEBM

Year Paper
2026 Mixed-Field Matching Preprint soon

Citation

If TorchEBM helps your research, please ⭐️ the repository and cite it:

@misc{ghaderi2024torchebm,
  author       = {Ghaderi, Soran},
  title        = {{TorchEBM}: A Composable {PyTorch} Library for Energy-Based and Transport-Based Generative Modeling},
  year         = {2024},
  howpublished = {\url{https://github.com/soran-ghaderi/torchebm}},
}

Changelog

See CHANGELOG for version history.

License

MIT License. See LICENSE for details.

Research collaboration

Interested in research on energy-based, flow or diffusion models? Reach out.