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**
7Samples are drawn from a 2D "banana" target by **WALNUTS** (the within-orbit
8adaptive leapfrog No-U-Turn Sampler). The figure shows the target density as a
9heatmap with the samples scattered on top.
11WALNUTS is a NUTS variant that adapts the leapfrog step size *within* each
12orbit: each macro-step halves the step (and doubles the count) until the energy
13error is within tolerance, then grows the orbit by NUTS-style doubling until a
14U-turn.
16Controls:
18- **Samples** / **Leapfrog Δt** / **Max error** — change a setting to re-run the
19 sampler with it (lower Δt or max error → more, smaller leapfrog steps).
20- **Resample** — a fresh chain with the current settings.
21- **▶ Movie** — animate WALNUTS building orbits step by step: each transition
22 traces its leapfrog path (amber), then circles the selected draw, which joins
23 the chain and starts the next transition.
25## How it works
27- [`walnuts_demo.m`](walnuts_demo.m) — driver: `addpath('helpers')`, seed, call the sampler.
28- [`walnuts_sampler.m`](walnuts_sampler.m) — runs the chain, evaluates the target on a grid, opens the figure.
29- `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).
30- `app/` — a single-file React app that draws the density heatmap + samples on a canvas.
32The script sends the density grid + samples via `uihtml(..., 'Data', ...)`. The
33controls call back: `sendToMATLAB('resample', {n, dt, maxError})` re-runs the
34chain, and `sendToMATLAB('movie', {dt, maxError})` records a few transitions'
35orbit trajectories (`walnuts(..., record=true)`); the script replies with
36`sendEventToHTMLSource`.
38## Credits
40- **Algorithm:** N. Bou-Rabee, B. Carpenter, T. S. Kleppe, and S. Liu, *The
41 within-orbit adaptive leapfrog no-U-turn sampler*,
42 [arXiv:2506.18746](https://arxiv.org/abs/2506.18746) (2025). Reference C++ at
43 [flatironinstitute/walnuts](https://github.com/flatironinstitute/walnuts)
44 (Bob Carpenter).
45- **This MATLAB port** follows Brian Ward's JavaScript implementation in
46 [WardBrian/mcmc-demo](https://github.com/WardBrian/mcmc-demo) (`algorithms/WALNUTS.js`).
47- **Demo framework & banana target** from Chi Feng's
48 [mcmc-demo](https://github.com/chi-feng/mcmc-demo).
50## Deploy
52Pushing to `main` builds the app and publishes the project to GitHub Pages via
53the [deploy workflow](.github/workflows/deploy.yml).