Skip to content

Integrators vs. the Exact Solution

advanced · salvage · Race Euler, Heun, RK4 and the generalised leapfrog against ground truth on an ODE and a curved manifold.

Run it:

python examples/90-showcase/02-integrator-ode/main.py

Two time-series scenes that race TorchEBM's numerical integrators against a ground-truth solution, on the dark brand theme.

What it teaches

  • Order of accuracy (oscillator scene): on the undamped oscillator \(\ddot q = -q\), forward EulerMaruyamaIntegrator does not conserve energy and visibly drifts, while HeunIntegrator (2nd) and RK4Integrator (4th) stay on the exact \(\cos t\) curve.
  • Geometry-aware integration (riemannian scene): on a non-separable Hamiltonian with metric \(M(x)=1+x^2\), the standard LeapfrogIntegrator ignores the metric and integrates the wrong dynamics, while the new GeneralisedLeapfrogIntegrator solves the implicit, geometry-aware updates and tracks the reference. This is the rm-HMC setting that motivated the generalised integrator in v0.6.0.

Requires

Runs on TorchEBM alone. For the polished outputs, MP4 export uses imageio-ffmpeg and the brand logo uses cairosvg (pip install imageio-ffmpeg cairosvg); both degrade gracefully (GIF fallback, text title) when absent.

Expected output

integrator_ode.{mp4,gif} (oscillator) and integrator_rmhmc.{mp4,gif} (riemannian), written to the assets/ folder next to the script; add --still for a final-frame PNG.

r"""Integrators vs. the exact solution: TorchEBM v0.6.0 announcement animations.

Two NeurIPS-style time-series scenes that race TorchEBM's numerical integrators
against a ground-truth solution, rendered on the dark brand theme.

scene "oscillator"  (default ground-truth = analytic cos t)
    The undamped harmonic oscillator  q'' = -q  (q(0)=1, p(0)=0, exact q=cos t).
    Forward Euler (1st), Heun (2nd) and RK4 (4th) are driven step-by-step; Euler
    does not conserve energy and visibly drifts while the higher-order methods
    stay on the exact curve, the classic order-of-accuracy picture.

scene "riemannian"  (ground-truth = an independent fine-step RK4 reference)
    A *non-separable* Hamiltonian with a position-dependent metric M(x)=1+x^2
    (the Riemann-manifold-HMC setting, Girolami & Calderhead 2011). The standard
    LeapfrogIntegrator assumes a separable Hamiltonian, so it ignores the metric
    and integrates the wrong dynamics; the new GeneralisedLeapfrogIntegrator
    solves the implicit, geometry-aware updates and tracks the reference. This is
    why TorchEBM 0.6.0 adds the generalised integrator.

Every plotted curve is the per-step output of the integrator (the
``integrate`` methods return only the final state, so we drive ``step`` directly).

Run both scenes (MP4 and GIF), one scene with a still frame, or one scene
without the GIF:
    python examples/90-showcase/02-integrator-ode/main.py
    python examples/90-showcase/02-integrator-ode/main.py --scene riemannian --still
    python examples/90-showcase/02-integrator-ode/main.py --scene oscillator --no-gif
"""

from __future__ import annotations

import argparse
import math
from pathlib import Path

import numpy as np
import torch
import matplotlib

matplotlib.use("Agg")
import matplotlib.pyplot as plt
import matplotlib.patheffects as pe
from matplotlib.animation import FuncAnimation, PillowWriter

from torchebm.integrators import (
    EulerMaruyamaIntegrator,
    HeunIntegrator,
    RK4Integrator,
    LeapfrogIntegrator,
    GeneralisedLeapfrogIntegrator,
)

ROOT = Path(__file__).resolve().parents[3]
OUT = Path(__file__).resolve().parent / "assets"
OUT.mkdir(parents=True, exist_ok=True)

LOGO_SVG = ROOT / "docs" / "assets" / "images" / "logo_with_text.svg"
LOGO_PNG = OUT / "_targets" / "logo_with_text.png"

BG = "#0b0b0f"
FG = "#f5f5f7"
MUTED = "#9aa0aa"
LIME = "#C7FF00"
TRUTH = "#e8e8ee"
ORANGE = "#E69F00"
BLUE = "#56B4E9"
GREEN = "#00D49A"


def osc_drift(x: torch.Tensor, t: torch.Tensor) -> torch.Tensor:
    """Autonomous drift f(z) = (p, -q) for the unit harmonic oscillator."""
    q, p = x[..., 0], x[..., 1]
    return torch.stack([p, -q], dim=-1)


def osc_run(integrator, x0: torch.Tensor, h: float, n_steps: int) -> np.ndarray:
    """Advance one RK integrator step-by-step; return the q-trajectory."""
    state = {"x": x0.clone()}
    qs = [float(x0[..., 0].item())]
    for i in range(n_steps):
        state = integrator.step(state, h, drift=osc_drift, t=torch.full((1,), i * h))
        qs.append(float(state["x"][..., 0].item()))
    return np.asarray(qs, dtype=np.float64)


def build_oscillator(h: float, periods: float) -> dict:
    torch.manual_seed(0)
    x0 = torch.tensor([[1.0, 0.0]])
    n = int(round(periods * 2 * math.pi / h))
    t = np.arange(n + 1, dtype=np.float64) * h
    exact = np.cos(t)

    methods = [
        ("Euler · 1st order", ORANGE, EulerMaruyamaIntegrator, 3.2, 4, True),
        ("Heun · 2nd order", BLUE, HeunIntegrator, 3.4, 6, True),
        ("RK4 · 4th order", GREEN, RK4Integrator, 1.9, 7, False),
    ]
    series = []
    rows = []
    for label, color, builder, lw, z, glow in methods:
        q = osc_run(builder(), x0, h, n)
        series.append({"label": label, "color": color, "traj": q,
                       "lw": lw, "z": z, "glow": glow})
        rows.append((label, abs(q[-1]), float(np.max(np.abs(q - exact)))))
    _print_table("harmonic oscillator  q''=-q", h, n, t[-1], t[-1] / (2 * math.pi), rows)

    return {
        "t": t, "ref": exact, "ref_label": "exact  cos(t)", "series": series,
        "ylim": 2.9, "ylabel": "position  q(t)",
        "subtitle": r"Numerical integrators vs. the exact solution  ·  $\ddot{q}=-q$",
        "out": "integrator_ode",
    }


RM_PERIOD = 8.0


def rm_force(x, p, t):
    invM = 1.0 / (1.0 + x ** 2)
    return -(x + 0.5 * p ** 2 * (-2.0 * x * invM ** 2) + 0.5 * (2.0 * x * invM))


def rm_velocity(x, p, t):
    return p / (1.0 + x ** 2)


def rm_full_drift(z, t):
    """First-order field (velocity, force) for the independent RK4 reference."""
    x, p = z[..., 0:1], z[..., 1:2]
    return torch.cat([rm_velocity(x, p, t), rm_force(x, p, t)], dim=-1)


def _rm_x0(x0, p0):
    return torch.tensor([[x0]]), torch.tensor([[p0]])


def rm_generalised(x0, p0, h, n) -> np.ndarray:
    integ = GeneralisedLeapfrogIntegrator()
    x, p = _rm_x0(x0, p0)
    state = {"x": x, "p": p}
    xs = [float(x0)]
    for _ in range(n):
        state = integ.step(state, h, force=rm_force, velocity=rm_velocity)
        xs.append(float(state["x"].item()))
    return np.asarray(xs, dtype=np.float64)


def rm_leapfrog(x0, p0, h, n) -> np.ndarray:
    integ = LeapfrogIntegrator()
    x, p = _rm_x0(x0, p0)
    state = {"x": x, "p": p}
    xs = [float(x0)]
    for _ in range(n):
        state = integ.step(state, h, drift=lambda x, t: -x)
        xs.append(float(state["x"].item()))
    return np.asarray(xs, dtype=np.float64)


def rm_reference(x0, p0, h, n) -> np.ndarray:
    integ = RK4Integrator()
    state = {"x": torch.tensor([[x0, p0]])}
    xs = [float(x0)]
    for _ in range(n):
        state = integ.step(state, h, drift=rm_full_drift)
        xs.append(float(state["x"][..., 0].item()))
    return np.asarray(xs, dtype=np.float64)


def build_riemannian(h: float, periods: float) -> dict:
    """Non-separable Hamiltonian with metric M(x) = 1 + x^2 and U(x) = x^2 / 2.

    Standard Leapfrog sees only drift = -dU/dx and unit mass, so it integrates
    the wrong dynamics; GeneralisedLeapfrog takes (force, velocity) and is
    exact for the metric. RM_PERIOD is the measured period of the reference
    orbit from (x0, p0) = (1.6, 0); the reference is an independent fine-step
    RK4 run.
    """
    x0, p0 = 1.6, 0.0
    n = int(round(periods * RM_PERIOD / h))
    t = np.arange(n + 1, dtype=np.float64) * h

    sub = 20
    ref = rm_reference(x0, p0, h / sub, n * sub)[::sub]
    glf = rm_generalised(x0, p0, h, n)
    lf = rm_leapfrog(x0, p0, h, n)

    rows = [("GeneralisedLeapfrog", abs(glf[-1]), float(np.max(np.abs(glf - ref)))),
            ("Leapfrog", abs(lf[-1]), float(np.max(np.abs(lf - ref))))]
    _print_table("non-separable H  ·  M(x)=1+x^2", h, n, t[-1], t[-1] / RM_PERIOD, rows,
                 errlabel="max err vs ref")

    series = [
        {"label": "GeneralisedLeapfrog · respects M(x)", "color": GREEN, "traj": glf,
         "lw": 2.6, "z": 7, "glow": True},
        {"label": "Leapfrog · ignores the metric", "color": ORANGE, "traj": lf,
         "lw": 2.8, "z": 5, "glow": True},
    ]
    return {
        "t": t, "ref": ref, "ref_label": "reference  ·  fine RK4", "series": series,
        "ylim": 1.95, "ylabel": "position  x(t)",
        "subtitle": r"Geometry-aware integration  ·  non-separable $H$,  $M(x)=1+x^2$",
        "out": "integrator_rmhmc",
    }


def _print_table(title, h, n, T, periods, rows, errlabel="max abs err"):
    print(f"\n  {title}   h={h}  n_steps={n}  T={T:.2f}  ({periods:.2f} periods)")
    print(f"  {'method':<24}{'end |x|':>10}{errlabel:>16}")
    print("  " + "-" * 50)
    for name, end, err in rows:
        print(f"  {name:<24}{end:>10.3f}{err:>16.3e}")
    print()


def _glow(lw: float, color: str, alpha: float = 0.35):
    """Soft outer glow so semi-thick lines pop on the dark background."""
    return [pe.Stroke(linewidth=lw + 3.5, foreground=color, alpha=alpha), pe.Normal()]


def load_logo(width_px: int = 1400):
    """Return the brand wordmark as a trimmed RGBA array (or None).

    Rasterizes the canonical ``logo_with_text.svg`` with cairosvg (cached under
    ``_targets/``) so the logo is always the real one. Falls back to the cached
    PNG, then to ``None`` (caller draws a text title instead).
    """
    try:
        import cairosvg
        LOGO_PNG.parent.mkdir(parents=True, exist_ok=True)
        cairosvg.svg2png(url=str(LOGO_SVG), write_to=str(LOGO_PNG), output_width=width_px)
    except Exception as exc:  # noqa: BLE001
        print(f"  (cairosvg unavailable: {exc}; using cached logo if present)")
    if not LOGO_PNG.exists():
        return None
    from PIL import Image
    im = Image.open(LOGO_PNG).convert("RGBA")
    bbox = im.getbbox()
    return np.asarray(im.crop(bbox) if bbox else im)


def _draw_header(fig, subtitle: str):
    """The SVG wordmark with the version snug to its right, plus a subtitle."""
    lx, lcy, logo_h = 0.088, 0.945, 0.056
    logo = load_logo()
    if logo is not None:
        aspect = logo.shape[1] / logo.shape[0]
        logo_w = logo_h * aspect
        logo_ax = fig.add_axes([lx, lcy - logo_h / 2, logo_w, logo_h], zorder=6)
        logo_ax.imshow(logo, aspect="auto", interpolation="antialiased")
        logo_ax.axis("off")
        logo_ax.patch.set_visible(False)
        ver_x = lx + logo_w + 0.018
    else:
        fig.text(lx, lcy, "∇ TorchEBM", color=LIME, fontsize=23,
                 fontweight="bold", ha="left", va="center")
        ver_x = 0.50
    fig.text(ver_x, lcy, "0.6.0", color=FG, fontsize=22, fontweight="bold",
             ha="left", va="center", alpha=0.9)
    fig.text(lx, lcy - 0.052, subtitle, color=MUTED, fontsize=12.5,
             ha="left", va="center")


def render(scene: dict, *, fps: int, hold: int,
           make_mp4: bool, make_gif: bool, still: bool):
    plt.rcParams.update({
        "font.family": "DejaVu Sans",
        "figure.facecolor": BG, "savefig.facecolor": BG,
        "text.color": FG, "axes.edgecolor": MUTED,
    })

    t, ref, ylim = scene["t"], scene["ref"], scene["ylim"]
    fig, ax = plt.subplots(figsize=(7.2, 7.2), dpi=150)
    fig.subplots_adjust(left=0.105, right=0.965, top=0.85, bottom=0.115)
    ax.set_facecolor(BG)
    ax.set_xlim(t[0], t[-1])
    ax.set_ylim(-ylim, ylim)
    ax.set_xlabel("time  t", color=MUTED, fontsize=12)
    ax.set_ylabel(scene["ylabel"], color=MUTED, fontsize=12)
    ax.tick_params(colors=MUTED, labelsize=10)
    for s in ("top", "right"):
        ax.spines[s].set_visible(False)
    for s in ("left", "bottom"):
        ax.spines[s].set_color(MUTED)
        ax.spines[s].set_alpha(0.4)
    ax.grid(True, color=MUTED, alpha=0.12, linewidth=0.8)
    ax.axhline(0.0, color=MUTED, alpha=0.18, linewidth=0.8)

    ax.plot(t, ref, color=TRUTH, lw=7.0, alpha=0.10, solid_capstyle="round", zorder=1)
    (ref_line,) = ax.plot([], [], color=TRUTH, lw=2.0, ls=(0, (5, 4)), alpha=0.9,
                          label=scene["ref_label"], zorder=8)

    lines, dots = [], []
    for spec in scene["series"]:
        (ln,) = ax.plot([], [], color=spec["color"], lw=spec["lw"],
                        solid_capstyle="round", label=spec["label"], zorder=spec["z"])
        if spec["glow"]:
            ln.set_path_effects(_glow(spec["lw"], spec["color"]))
        (dot,) = ax.plot([], [], "o", color=spec["color"], ms=6.0,
                         zorder=spec["z"] + 10, markeredgecolor=BG, markeredgewidth=1.0)
        lines.append((ln, spec["traj"]))
        dots.append(dot)

    ax.legend(loc="upper left", frameon=True, facecolor=BG, edgecolor="none",
              framealpha=0.6, fontsize=11, labelcolor=FG, handlelength=1.8,
              borderaxespad=0.6)
    _draw_header(fig, scene["subtitle"])
    fig.text(0.965, 0.04, "pip install torchebm", color=MUTED, fontsize=10,
             ha="right", va="center", alpha=0.8)

    n = len(t)

    def update(i):
        k = min(i, n - 1) + 1
        ref_line.set_data(t[:k], ref[:k])
        arts = [ref_line]
        for (ln, traj), dot in zip(lines, dots):
            ln.set_data(t[:k], traj[:k])
            dot.set_data([t[k - 1]], [traj[k - 1]])
            arts += [ln, dot]
        return arts

    total = n + hold
    anim = FuncAnimation(fig, update, frames=total, interval=1000 / fps, blit=False)
    base = OUT / scene["out"]

    if make_mp4:
        try:
            import imageio_ffmpeg
            plt.rcParams["animation.ffmpeg_path"] = imageio_ffmpeg.get_ffmpeg_exe()
            from matplotlib.animation import FFMpegWriter
            writer = FFMpegWriter(fps=fps, codec="libx264", bitrate=-1,
                                  extra_args=["-pix_fmt", "yuv420p", "-crf", "18",
                                              "-preset", "slow"])
            anim.save(base.with_suffix(".mp4"), writer=writer, dpi=150)
            print(f"wrote {base.with_suffix('.mp4')}  ({total} frames @ {fps}fps)")
        except Exception as exc:  # noqa: BLE001
            print(f"!! MP4 export failed ({exc}); install imageio-ffmpeg. Falling back to GIF.")
            make_gif = True

    if make_gif:
        anim.save(base.with_suffix(".gif"), writer=PillowWriter(fps=min(fps, 25)), dpi=84)
        print(f"wrote {base.with_suffix('.gif')}  ({total} frames)")

    if still:
        update(n - 1)
        fig.savefig(base.with_suffix(".png"), dpi=150)
        print(f"wrote {base.with_suffix('.png')}")

    plt.close(fig)


SCENES = {"oscillator": build_oscillator, "riemannian": build_riemannian}
DEFAULT_H = {"oscillator": 0.13, "riemannian": 0.09}
DEFAULT_PERIODS = {"oscillator": 2.5, "riemannian": 3.0}


def main():
    p = argparse.ArgumentParser(description=__doc__)
    p.add_argument("--scene", choices=["oscillator", "riemannian", "both"], default="both")
    p.add_argument("--h", type=float, default=None, help="integrator step size (per-scene default)")
    p.add_argument("--periods", type=float, default=None, help="periods to show (per-scene default)")
    p.add_argument("--fps", type=int, default=30)
    p.add_argument("--hold", type=int, default=20, help="freeze frames at the end")
    p.add_argument("--no-mp4", action="store_true")
    p.add_argument("--no-gif", action="store_true")
    p.add_argument("--still", action="store_true", help="also save a final-frame PNG")
    args = p.parse_args()

    names = ["oscillator", "riemannian"] if args.scene == "both" else [args.scene]
    for name in names:
        h = args.h if args.h is not None else DEFAULT_H[name]
        periods = args.periods if args.periods is not None else DEFAULT_PERIODS[name]
        scene = SCENES[name](h, periods)
        render(scene, fps=args.fps, hold=args.hold,
               make_mp4=not args.no_mp4, make_gif=not args.no_gif, still=args.still)


if __name__ == "__main__":
    main()