727e2e4Interactive WALNUTS sampling of a 2D banana targetJeremy Magland 1# Interactive WALNUTS sampling
3Runs in the browser via [numbl](https://numbl.org) — no install.
5## ▶ [Open `walnuts_demo.m`](walnuts_demo.m) and click **Run**
cd4150fAdd target distribution selector (banana / Gaussian / correlated / donut)Jeremy Magland 7Samples are drawn from a 2D target by **WALNUTS** (the within-orbit adaptive
8leapfrog No-U-Turn Sampler). The figure shows the target density as a heatmap
9with the samples scattered on top. Switch between several targets (banana,
10Gaussian, correlated Gaussian, donut) to see the sampler handle different
11geometries.
727e2e4Interactive WALNUTS sampling of a 2D banana targetJeremy Magland 12
13WALNUTS is a NUTS variant that adapts the leapfrog step size *within* each
14orbit: each macro-step halves the step (and doubles the count) until the energy
15error is within tolerance, then grows the orbit by NUTS-style doubling until a
16U-turn.
18Controls:
cd4150fAdd target distribution selector (banana / Gaussian / correlated / donut)Jeremy Magland 20- **Target** — switch the distribution (banana / Gaussian / correlated / donut).
727e2e4Interactive WALNUTS sampling of a 2D banana targetJeremy Magland 21- **Samples** / **Leapfrog Δt** / **Max error** — change a setting to re-run the
22 sampler with it (lower Δt or max error → more, smaller leapfrog steps).
23- **Resample** — a fresh chain with the current settings.
24- **▶ Movie** — animate WALNUTS building orbits step by step: each transition
25 traces its leapfrog path (amber), then circles the selected draw, which joins
26 the chain and starts the next transition.
28## How it works
30- [`walnuts_demo.m`](walnuts_demo.m) — driver: `addpath('helpers')`, seed, call the sampler.
31- [`walnuts_sampler.m`](walnuts_sampler.m) — runs the chain, evaluates the target on a grid, opens the figure.
32- `helpers/` — [`walnuts.m`](helpers/walnuts.m) (the algorithm) and the target [`log_density.m`](helpers/log_density.m) / [`grad_log_density.m`](helpers/grad_log_density.m).
33- `app/` — a single-file React app that draws the density heatmap + samples on a canvas.
35The script sends the density grid + samples via `uihtml(..., 'Data', ...)`. The
cd4150fAdd target distribution selector (banana / Gaussian / correlated / donut)Jeremy Magland 36controls call back: `resample` re-runs the chain, `setTarget` switches the
37target (and rebuilds the density), and `movie` records a few transitions' orbit
38trajectories (`walnuts(..., record=true)`); the script replies with
41## Credits
43- **Algorithm:** N. Bou-Rabee, B. Carpenter, T. S. Kleppe, and S. Liu, *The
44 within-orbit adaptive leapfrog no-U-turn sampler*,
45 [arXiv:2506.18746](https://arxiv.org/abs/2506.18746) (2025). Reference C++ at
46 [flatironinstitute/walnuts](https://github.com/flatironinstitute/walnuts)
47 (Bob Carpenter).
48- **This MATLAB port** follows Brian Ward's JavaScript implementation in
49 [WardBrian/mcmc-demo](https://github.com/WardBrian/mcmc-demo) (`algorithms/WALNUTS.js`).
50- **Demo framework & banana target** from Chi Feng's
51 [mcmc-demo](https://github.com/chi-feng/mcmc-demo).
53## Deploy
55Pushing to `main` builds the app and publishes the project to GitHub Pages via
56the [deploy workflow](.github/workflows/deploy.yml).