1# Interactive WALNUTS sampling
3Runs in the browser via [numbl](https://numbl.org) β no install.
5## π [Just the figure β](https://concept-collection.github.io/walnuts-interactive/#figure/sampler)
7The figure-only view runs the sampler and drops you straight into the
8interactive figure (it shows the run's output first, then the figure). The full
9developer view β file tree, editable code, console β is below.
11## βΆ [Open `walnuts_demo.m`](walnuts_demo.m) and click **Run**
13Samples are drawn from a 2D target by **WALNUTS** (the within-orbit adaptive
14leapfrog No-U-Turn Sampler). The figure shows the target density as a heatmap
15with the samples scattered on top. Switch between several targets (banana,
16Gaussian, correlated Gaussian, donut) to see the sampler handle different
17geometries.
19WALNUTS is a NUTS variant that grows a Hamiltonian orbit by NUTS-style doubling
20until a U-turn, but *within* each step it refines the leapfrog step size β
21halving the step (and doubling the count) until the energy variation over the
22step is within a tolerance Ξ΄ β then picks a draw from the orbit.
24Controls:
26- **Target** β switch the distribution (banana / Gaussian / correlated / donut).
27- **Samples** / **Step h** / **Energy tol Ξ΄** β change a setting to re-run the
28 sampler with it (a larger base step `h` or smaller `Ξ΄` triggers more
29 within-orbit refinement).
30- **Resample** β a fresh chain with the current settings.
31- **βΆ Movie** β animate WALNUTS building orbits step by step: each transition
32 traces its leapfrog path (amber), then circles the selected draw, which joins
33 the chain and starts the next transition.
35## How it works
37- [`walnuts_demo.m`](walnuts_demo.m) β driver: `addpath('helpers')`, seed, call the sampler.
38- [`walnuts_sampler.m`](walnuts_sampler.m) β loops the sampler (one transition per draw, passing the target as function handles), evaluates the target on a grid, opens the figure.
39- `helpers/` β Nawaf Bou-Rabee's reference WALNUTS ([`walnuts.m`](helpers/walnuts.m) + `extend_orbit_*`, `micro`, `leapfrog`, `u_turn`/`sub_u_turn`, `p_micro`/`pmf_p_micro`), and the targets [`log_density.m`](helpers/log_density.m) / [`grad_log_density.m`](helpers/grad_log_density.m).
40- `app/` β a single-file React app that draws the density heatmap + samples on a canvas.
42The script sends the density grid + samples via `uihtml(..., 'Data', ...)`. The
43controls call back: `resample` re-runs the chain, `setTarget` switches the
44target (and rebuilds the density), and `movie` records a few transitions'
45orbits; the script replies with `sendEventToHTMLSource`.
47## Credits
49- **Algorithm & reference MATLAB implementation:** N. Bou-Rabee, B. Carpenter,
50 T. S. Kleppe, and S. Liu, *The within-orbit adaptive leapfrog no-U-turn
51 sampler*, [JMLR 27(113):1β64](https://jmlr.org/papers/v27/25-1452.html)
52 (2026); preprint [arXiv:2506.18746](https://arxiv.org/abs/2506.18746). The
53 `helpers/` sampler (`walnuts.m` + its building blocks) is Nawaf Bou-Rabee's
54 reference MATLAB code, used here as provided. Reference C++ at
55 [flatironinstitute/walnuts](https://github.com/flatironinstitute/walnuts).
56- **Target distributions** (banana, donut, β¦) from Chi Feng's
57 [mcmc-demo](https://github.com/chi-feng/mcmc-demo).
59## Deploy
61Pushing to `main` builds the app and publishes the project to GitHub Pages via
62the [deploy workflow](.github/workflows/deploy.yml).