CLAUDE.md #

Tips for future agents. Patterned after the sibling hitandrun-interactive project (same numbl + uihtml two-way bridge, 2D canvas figure).

Architecture#

app/ — React single-file widget (npm run build → app/dist/index.html).
*.m at root — walnuts_demo.m (driver) and walnuts_sampler.m (figure plumbing).
helpers/ — walnuts.m (the sampler) and the target log_density.m / grad_log_density.m, put on the path by the driver via addpath('helpers').
numbl-project.json — project metadata; entry is the landing page.

addpath('helpers') must be the first statement in the driver (numbl resolves the search path before running, and addpath can't live inside a function file). Run walnuts_demo.m, not the sampler directly.

Data flow (uihtml bridge)#

MATLAB → figure: uihtml(..., 'Data', struct) / sendEventToHTMLSource(src, name, data).
Figure → MATLAB: sendToMATLAB(name, value) (see app/src/bridge.ts), received via HTMLEventReceivedFcn.

The script sends the density grid + samples once, then handles two requests (walnuts_sampler.m on_event):

resample {n, dt, maxError} → fresh chain → samples event. (Target is fixed, so the density is not re-sent.)
movie {dt, maxError} → walnuts(..., record=true) for a few transitions → movie event carrying their orbit trajectories.

The figure's controls (samples / Δt / max error sliders, Resample) drive resample; the ▶ Movie button drives movie and animates the returned orbits (App.tsx + DensityView.tsx).

Trajectory recording#

walnuts.m records the orbit path only when called with record=true, via globals (WREC_*): macro_step appends each committed macro-step's leapfrog path (recomputed by leapfrog_capture), tagged with a segment id so the figure breaks the polyline at orbit direction flips. Plain sampling (record=false) takes the fast path with no recording overhead.

The algorithm#

helpers/walnuts.m is a direct port of Brian Ward's algorithms/WALNUTS.js from chi-feng/mcmc-demo (based on Bob Carpenter's C++, flatironinstitute/walnuts; paper arXiv:2506.18746). Spans carry both orbit endpoints; macro_step does the within-orbit step halving; build_span recurses (NUTS doubling); selection is Barker within sub-orbits, Metropolis at the top. See README for full credits.

Performance#

Unlike the hitandrun kernel, WALNUTS uses recursion + structs, so it runs in the numbl interpreter (it does not JS-JIT like a flat numeric loop). It's still fine — banana orbits are shallow, ~1–2 ms/transition — so keep N modest (the demo uses 1000 + 200 burn-in). Don't add a %!numbl:assert_jit guard here; it would (correctly) fail.

Key files#

File	Purpose
`app/src/App.tsx`	Reads data, hosts the info panel
`app/src/render/DensityView.tsx`	Canvas: density heatmap + sample scatter
`app/src/bridge.ts`	`onData` / `onHostEvent` / `sendToMATLAB` (generic)
`helpers/walnuts.m`	The WALNUTS sampler
`helpers/log_density.m` / `grad_log_density.m`	Banana target
`walnuts_sampler.m`	Runs the chain, builds the density grid, opens the figure
`walnuts_demo.m`	Driver: addpath + seed + call the sampler

Local iteration#

cd app && npm install && npm run build      # → app/dist/index.html
cd ..
npx tsx $NUMBL/src/cli.ts run walnuts_demo.m --plot    # quick loop
# or preview the GitHub Pages bundle:
( cd $NUMBL && npm run build:site-viewer )             # one-time
npx tsx $NUMBL/src/cli.ts build-site . --out _site --base /
( cd _site && python3 -m http.server 8080 )

$NUMBL is a local clone of flatironinstitute/numbl. The real target is GitHub Pages, where the deploy builds numbl from main.

CLAUDE.md#