Examples¶
A runnable curriculum. Every example is one folder teaching one idea; its main.py runs on a bare pip install torchebm, and CI runs every example outside the showcase tier on each commit.
Each page in this section is generated from the main.py and index.md of the folder it documents.
The four tiers¶
Work through them in order, or jump to the one that matches your goal. Each tier has a companion chapter in Concepts explaining the theory the examples exercise.
| Tier | You learn to | Theory |
|---|---|---|
| Foundations | build the static objects: energies, datasets, schedulers, interpolants | The Energy-Based View |
| Sampling | draw samples from a fixed target: MCMC, parallel chains, integrators, flows | Sampling and Integration |
| Training | learn a target from data: CD, score matching, equilibrium and energy matching, couplings | Learning Objectives and Interpolants and Couplings |
| Showcase | see the components pushed end to end | Design and Scope |
Where to start¶
| If you want to | Start with |
|---|---|
| understand what an energy is | Foundations: Energy Landscapes |
| sample a distribution you already have | Sampling: Langevin Dynamics 101 |
| train an energy-based model on your data | Training: CD-k on Two Moons |
| build a fast generative model | Training: Equilibrium Matching in 2D |
| see why the pairing of noise and data matters | Training: Coupling Comparison |
| choose a numerical integrator | Sampling: Integrator Comparison |
Anatomy of an example¶
main.py is the lesson. It imports only torchebm and the standard library, so it runs on a bare install. It is a linear script: a few constants at the top, then a body that ends by printing the key result (a shape, a metric, a recovered statistic), with no argparse, main() function or device flags.
Smoke mode. Every main.py honours TORCHEBM_SMOKE=1 by shrinking its iteration counts so CI can execute it in seconds:
Visualization is separate. Pages show prose and code only. Where a figure helps, the folder carries a plot.py that writes into a local, gitignored assets/ folder.
meta.yaml¶
The single source of an example's metadata, and the discovery signal: a folder with a meta.yaml is an example.
order places the example in the global learning path: 0-399 Foundations, 400-799 Sampling, 800-1199 Training, 1200+ Showcase. difficulty is intro, intermediate or advanced. The ci block is optional: timeout is in seconds (default 120), and skip: true excludes a heavy showcase from the smoke run.
Adding an example¶
- Create a folder under the right tier, with a numeric prefix.
- Write
main.py: pure torchebm, prints its result, honoursTORCHEBM_SMOKE. - Add
meta.yaml, choosing anorderinside the tier's band. - Optionally add
index.md(prose) andplot.py(figures). - Verify:
The nav entry, the tier table, and the page itself are all generated from the folder.
Tags¶
- capability:
langevin,hmc,score-matching,cd,eqm,energy-matching,flow,coupling - surface:
2d-energy,image,interpolant,integrator,scheduler,dataset - trait:
gpu,animation,comparison,showcase