soran-ghaderi/torchebm
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.
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 LearningREADME.md
Original
⚡ 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 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 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.
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.
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.
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):
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.
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.
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.
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.