oWALNUTS

owalnuts is a Rust implementation of WALNUTS, the Within-orbit Adaptive Leapfrog No-U-Turn Sampler (Bou-Rabee, Carpenter, Kleppe, Liu; JMLR 27, 2026). It is NUTS with a second time scale: every macro leapfrog step is subdivided into micro-steps, and the number of micro-steps is chosen per step so that the local energy error stays under a threshold delta. Fine steps are spent only where the curvature demands them, which is what lets it sample multi-scale targets such as Neal's funnel without the bias fixed-step NUTS shows there. The kernel is derived from, and tested leaf-for-leaf against, the Flatiron reference implementation walnutpie (MIT); the public API is a small builder, owalnuts::sampler, over a complete facade, owalnuts::walnutpie. Version 0.3.0; kernel revision walnutpie-warmup-telemetry-tau0.6-m1-r2-e1-d3-v10.

Defaults changed since 0.2.0 (released in 0.3.0, the trapped-chain guard on main after it; see CHANGELOG.md). The kernel, ALGORITHM_REVISION and the kernel fingerprints are unchanged; each old behaviour is one builder call away.

• Best-of-16 starts. Init::default() and run_from_random_starts keep the highest-log-density of 16 evaluable uniform(-2, 2) starts per chain, so draws for a given seed differ from 0.2.0; decided by the preregistered confirmation STUDIES/init_rule_confirmation_v1 (WP52: 1.254x ESS per gradient, 42 vs 42 gates) [E20].
• NonfinitePositionPolicy::RejectLeaf. An integrator overflow becomes a rejected zero-density leaf instead of ending the whole run, and any run without the event is bit-identical; decided by STUDIES/nonfinite_policy_requalification_v1 (WP54: bit-identical on 73/73 cells, 75 vs 73 runs completed) [E21].
• Fixed Metric::dense() warmup. Dense warmup now uses per-transition seeding, Stan's dense regularisation and a symmetrised precision; an engineering decision after STUDIES/dense_metric_confirmation_v1 (WP51: 3.21x the diagonal per gradient against 0.055x for the old dense defaults), whose own frozen rule failed (40 vs 43 gates) [E19].
• Trapped-chain guard (DEFAULT_TRAPPED_CHAIN_RESTART, after 0.3.0). With three or more chains on the identity or diagonal metric, a chain whose step at the close of the first slow warmup window is below 0.01x the chain median restarts from an independent best-of-16 start; draws are unchanged unless a chain fires. Decided by the preregistered confirmation STUDIES/trap_guard_confirmation_v1 (WP90: SV trapped chains 8/480 to 0/480, 282/282 unfired cell pairs bit-identical, 92 = 92 gates) [E54]. WarmupConfig::without_trapped_chain_restart() opts out.

Quick start

[dependencies]
owalnuts = "0.3.0"

Implement Target (log density and gradient in one call, unconstrained f64 coordinates) and run the sampler at its defaults. This is examples/readme_quick_start.rs, which CI runs:

use owalnuts::diagnostics::Summary;
use owalnuts::sampler::{Sampler, Target, TargetError};

struct Gaussian;
impl Target for Gaussian {
    fn dimension(&self) -> usize { 5 }
    fn log_density_gradient(&self, q: &[f64], grad: &mut [f64]) -> Result<f64, TargetError> {
        for (g, x) in grad.iter_mut().zip(q) { *g = -x; }
        Ok(-0.5 * q.iter().map(|x| x * x).sum::<f64>())
    }
}

let posterior = Sampler::new()
    .warmup(1_000)
    .draws(1_000)
    .chains(4)
    .seed(0x5eed)
    .run_from_random_starts(&Gaussian)?;   // best of 16 uniform(-2, 2) starts per chain

let summary = Summary::from_output(posterior.inner(), None)?;
println!("{summary}");                     // mean, sd, MCSE, quantiles, ESS, R-hat, health

The defaults are tuned for funnel-shaped posteriors as well as ordinary ones: eight refinement levels, which is what keeps the quick-start configuration unbiased on Neal's funnel (see "Where it shines"). Summary prints a Stan-style table (rank-normalised split R-hat, bulk and tail ESS, MCSE, 5/50/95 % quantiles; each estimator matches ArviZ to 1e-6) followed by the sampler health per chain and pooled: divergences, invalid evaluations, depth-cap stops, refinement exhaustions, mean tree depth, target calls, step size. posterior.draws() iterates retained positions as &[f64]; posterior.chains() gives per-chain draws, diagnostics, telemetry and metadata; .run(&target, &starts) takes explicit starts, one per chain.

One line each for the other front doors:

• CmdStan CSV: export::CmdStanCsv::new().with_log_density(&target).write_dir(posterior.inner(), "out", "chain")? writes out/chain-1.csv ... that arviz.from_cmdstan loads directly.
• Python: pip install maturin then maturin develop --release in integrations/python; owalnuts.sample(logp_and_grad, dim=10, warmup=1000, draws=1000, seed=1).summary(), with from_jax, from_torch and from_pymc adapters. For PyMC models use from_pymc(model, gil_free=True) with threads=4; for hand-written densities a numba from_cfunc (within 1.15x of a native Rust target); plain callables, the default from_pymc and from_jax at threads=1 (from_jax adds 20–40 µs per gradient). nutpie is 1.4–1.9x faster per second on smooth and larger hierarchical PyMC models and fails noncentred Eight Schools [E44].
• Stan models: owalnuts-bridgestan wraps a BridgeStan-compiled model as a Target (ReplicatedStanTarget::load(so, preload, data, seed, threads) for multi-chain runs). On Windows the Rust integration by default records the requested replica count but uses one effective owned worker per target and serializes all native BridgeStan calls process-wide (see "Threads and chains" for the opt-in static-runtime dispatch); Python from_stan and direct Python BridgeStan operations are disabled there for 0.2.
• Rust autodiff: owalnuts-autodiff turns fn log_density<S: Scalar>(&self, q: &[S]) -> S into a Target with a reverse-mode tape, a few times the cost of a hand-written gradient.

Diagnostics

Summary (and posterior.chain_warnings()) also prints observe-only warning: chain k ... lines; computing them never changes a draw.

• A restarted chain (WP90): a chain whose step at the close of the first slow warmup window was below 0.01x the chain median reran from an independent best-of-16 start; RunTelemetry::trapped_chain_checks (Python trapped_chain_checks) records every chain's check and the restart. Nothing is copied from another chain, so the chains remain independent starts and independent-chain R-hat stays valid [E54].
• A chain that disagrees with the others (WP44, WP74): a collapsed end-of-warmup step, a median log density far below the other chains' at the end of warmup or over the draws, or a chain whose removal alone brings R-hat under 1.01 [E22]. When R-hat fails and no single chain explains it, a pairwise check groups chains whose pair R-hat is at most 1.01 and flags every chain outside the largest group (if that group has two or more chains). That reports mode splits with two chains per mode or a chain caught crossing between modes: 5/5 split cells in WP74, against 1/5 without it, and no finding on 43 healthy posteriordb cells [E40]. It needs at least three chains, misses a split in which no two chains agree, and does not replace the R-hat / ESS gates. The older step and warmup-density checks fired on 3 of those 43 healthy cells (transient warmup dips).
• Rejected nonfinite positions: warning: chain k rejected n nonfinite positions during warmup. The default RejectLeaf rescue records no divergence, so this line (or WorkTotals::nonfinite_position_rejections) is where an integrator overflow shows [E21].
• Zero divergences does not rule out a funnel. On centred hierarchical models a run can be wrong with no divergence at all. In WP55, 11 of 12 wrong cells on the funnel, centred Eight Schools, seeds_centered and centred radon had zero retained divergences, and the R-hat / bulk ESS / tail ESS gates caught every one of them [E23]. This is not specific to WALNUTS refinement: in posteriordb v7, CmdStan and nutpie also recorded zero retained divergences on every seeds_centered cell, and failed it on the same sigma [E26]. Check the R-hat / ESS gates, not the divergence count.

Threads and chains

Chains run in parallel on up to threads worker threads (WP45, [E24]):

• threads above chains does nothing; the driver clamps it to the chain count. Draws are bit-identical at every thread count.
• Wall time is bounded by the slowest chain. Chain lengths differ by target (max/mean gradients at 16 chains were 1.51 on a 100-D Gaussian and 3.05 on a local-level model), so one straggler sets the wall.
• Windows BridgeStan: the default owned worker serialises every native call. For multi-chain throughput build the model and tbb.dll with the static mingw runtime (integrations/bridgestan/tools/build_static_runtime.py) and load with ReplicatedOptions::concurrent_if_static_runtime(): 3.2x (sblrc) / 4.0x (arK) contended sampling wall with bit-identical draws (WP50C). It is opt-in, not the default, because the WP50D confirmatory gate was not supported (1/1000 static children failed, with a sampler nonfinite-position error rather than a crash) [E25].
• Linux BridgeStan (x86_64, glibc): the default concurrent-replica dispatch is qualified (WP65, [E30]): 0/500 child faults, draws bit-identical to the serialised path, 4.0–5.4x gradient throughput at four callers, and wall per gradient 0.96x CmdStan's on the fixed-16 models (pinned, co-tenanted, one seed). Serialising the calls costs 3.6x. Build without STAN_THREADS on Linux too: a threaded library costs up to 1.57x per call (arK) and is not unloaded on drop. macOS, aarch64 and Windows multi-worker dispatch remain unqualified.

Warm continuation

Sampler::start_session serves one fixed target of fixed dimension: one adapt(), then draw(n) chunks. For a posterior that must be refreshed when the target changes (new data, a new latent coordinate), the warm path of WP84 ([E52]) is a library call since WP87: Posterior::warm_state() (or SessionChunk::warm_state()) carries each chain's last position, its adapted step size and its adapted diagonal mass; WarmState::extend_to(n, 0.0, 1.0) appends coordinates for a larger target; and Sampler::new().draws(k).seed(s).run_warm(&new_target, &state) runs k transitions per chain with no warmup, no adaptation, each chain on its own frozen step and metric (chain c is bit-identical to the single-chain run with seed s + c, Metric::fixed_diagonal, Adaptation::None and Tuning::step_size; tests/warm_continuation.rs). The result is an ordinary Posterior whose warm_state() is the next tick's state. It does not re-adapt, it carries identity/diagonal metrics only (dense and structured runs error), the fill of new coordinates is the caller's decision, and the library does not validate that k draws refresh the posterior to any accuracy: on the 250-return SV model of WP84, 50–200 draws per chain kept about 90% of draws inside reference 90% intervals over 100 ticks (20–80 ms per tick) but did not reach the R-hat 1.01 / reference-MCSE bar; scored against the quote itself (post hoc), 200 draws per chain kept the next-period sigma P50 within 2 % and the P95 within 5 % of the reference on 97 % / 98 % of ticks, 50 draws on 74 % / 78 %. Python: result.warm_state(), state.extend_to(dim), owalnuts.sample_warm(target, state, draws=k, seed=s).

For a loop of such refreshes, Sampler::new().seed(s).threads(t) .start_warm_session(target, state) (WP91) keeps the worker thread, a pool of t workers and every per-chain input resident: refresh(k) runs k transitions per chain and hands back the kernel's own draw buffers, state() is the current state, retarget(new_target, new_state) swaps both (a new dimension is allowed) and close() joins. Call n of a session is bit-identical to run_warm with seed s + n * chains on the state before the call (tests/warm_session.rs). WarmState::remap(dim, map, fill) rebuilds the state for a new coordinate layout (new coordinate j carries old coordinate map(j) or the fill), and WarmState::shift_window(drop_front, append, fill) is the fixed-lag move (drop the oldest latents, append new ones at the prior fill), so a constant-dimension window and the growing WP88 state are both one call. One laptop run of examples/warm_session_bench.rs (contended machine, indicative; median wall per call, 4 chains x 4 threads, release): on the WP84 shape (253 coordinates) run_warm 2.1 ms versus the session 1.6 ms at 5 transitions per chain, 3.6 versus 3.0 ms at 10, 19.5 versus 19.8 ms at 50; on a 50-latent fixed-lag window (53 coordinates) 0.70 versus 0.37 ms at 5, 1.07 versus 0.67 ms at 10, 4.3 versus 3.5 ms at 50; single- threaded the two are within noise. The removable per-call overhead is about 0.3-0.5 ms with a 4-thread pool; the rest is the kernel's own work (300-3,000 gradients per call at 1.7-12 us each), so a sub-millisecond refresh comes from few transitions on a small window (the 53-coordinate window at K = 5), not from the session alone. Python: owalnuts.WarmSession(target, state, seed=s, threads=t), session.refresh(k), session.retarget(target, state), state.shift_window(1, 1).

When the tick needs a few quote quantities rather than the draws, session.refresh_functionals(k, &functionals) (WP95) evaluates registered Functionals (FunctionalFn::new(outputs, |q, out| ...), or a C callback through RawFunctional) on every retained draw inside the chain loop and returns a FunctionalChunk: per chain the k x outputs values, streamed moments per output, the diagnostics and warm_state(), but no draws unless asked (Functionals::retain_draws), with pooled mean / variance / quantile(output, q); Sampler::run_warm_functionals is the one-shot form. The values are the functionals of refresh's draws bit for bit and the draws do not depend on the functionals (tests/warm_functionals.rs). The retained result shrinks from k x dim x chains x 8 to k x outputs x chains x 8 bytes (K = 50 on the WP84 shape: 395 KiB of draws against 9.4 KiB for six outputs) and the peak live memory of a call with it (597 KiB against 279 KiB at K = 50 and 4 threads; the rest is the kernel's own per-transition workspace, which no result layout changes); wall per call is within noise of refresh because the functionals cost far less than the kernel's gradients. Python: session.refresh_functionals(k, [owalnuts.from_cfunc_functional(f, 1)]) and chunk.quantile(0.95, 0); a Python callable functional works too but attaches the interpreter once per draw per chain (0.16-0.55 ms each on the SV targets).

Where it shines

Every number below is from a preregistered, checksummed study in STUDIES/; the Evidence list at the end links each one.

• Neal's funnel is sampled without bias. At the paper's tuning, 4 x 50,000 draws give tail mass P(omega < -5) = 0.0474 against the exact 0.0478 (the reference implementation at identical tuning: 0.0477), with zero divergences; fixed-step NUTS is biased on this target, and so was the pre-v9 kernel (0.0971). [E1] At the sampler defaults (adapted diagonal metric, dual averaging, h0 = 0.5) the tail mass is within |z| <= 2 of exact on three fresh seeds (0.0412, 0.0346, 0.0897) because the default is eight refinement levels; at four levels it was half the exact value, and a one-level NUTS-like control never draws below omega = -5 on two seeds. The pooled estimate is right but the funnel does not mix well at the defaults (one chain per seed adapts to h ~ 0.01, omega R-hat 1.01-1.04); Tuning::new().max_error(0.5) mixes better there at a 21 % cost on a 100-D Gaussian. [E11] Over 30 fresh seeds (WP53, 4 x 2,000/20,000) the default's tail estimate is biased low: mean z -0.42, 4/30 seeds beyond |z| 2 and all low, pooled P(omega < -5) 0.0458 +/- 0.0014 against the exact 0.0478, with no divergences or warnings to show for it. delta = 2 shares the deficit (pooled 0.0455) with no seed beyond |z| 2. A three-seed |z| <= 2 funnel gate fails the unchanged default about 35 % of the time, so read single-seed funnel z values as noise and pooled tail mass as the check [E29].
• Long state-space paths mix at depth 3–4. On an exact Gaussian state-space model at T = 1000, supplying the posterior-precision tridiagonal metric (Metric::Structured) gives ESS per target call ~1,000x a prior-based metric and 4.8x the identity, at Monte-Carlo accuracy against the closed-form posterior. [E2]
• Eight Schools throughput on a strict matched track. Noncentered Eight Schools, 4 chains, 1,000/1,000, one thread: the conservative minimum over seven seeds and six functionals is 12,830 bulk / 10,346 tail ESS/s against CmdStan 6,290 / 3,951, BlackJAX 5,645 / 4,195 and NumPyro 5,241 / 4,050 on the same track. [E3]
• Zero divergences where NUTS diverges. In the posteriordb benchmark, oWALNUTS passes every gate on noncentered eight schools (3/3 seeds; CmdStan 1/3, nutpie 0/3) and gp_pois_regr (up to 3/3; CmdStan 0/3 with 9–16 divergences, nutpie 0/3 with 120–822), with no divergence on either. [E4]

Where it does not (yet)

posteriordb v7 (WP56), the current defaults: mixed. At the defaults listed under "Defaults changed since 0.2.0", oWALNUTS passes 43/51 house cells against CmdStan 34 and nutpie 26. The run used the 17 posteriordb posteriors, every sampler at its defaults, 4 chains, 1,000/1,000 and three fresh seeds. The gates were rank R-hat <= 1.01, bulk and tail ESS >= 400 and zero retained divergences, with CmdStan 2.39.0 and nutpie 0.16.8 on the same seeds. No passing reference cell is above |z| 3.82. All 66 oWALNUTS cells completed with no error, timeout or frozen chain. The funnel is unbiased on every seed (z +1.69, -0.59, +0.84). [E26]

Five hard posteriors joined the benchmark in v7 (GLMM_Poisson, seeds_centered, kilpisjarvi, grsm and centred radon). There oWALNUTS passes 6/15, against CmdStan 7 and nutpie 3: 3/3 on kilpisjarvi and grsm, and 0/3 on GLMM_Poisson, seeds_centered and radon. Those three fail on a slow sigma or beta[1], the same parameters that defeat the competitors (CmdStan passes one radon cell; nutpie none). [E26]

ESS per gradient is 0.83x CmdStan's over 18 Linux seeds (median of paired per-seed ratios over the fixed-16 models, seed-bootstrap interval [0.79, 0.94]; WP72, [E38]). The earlier six-seed figures, 0.76 on Windows and 1.21 on Linux, were both seed noise: on six seeds the interval spans 0.7–1.6 on either platform. Gates over the same 288 cells are 239 for oWALNUTS, 198 for CmdStan and 163 for nutpie 0.16.8 (WP76, [E42]); per gradient oWALNUTS is 0.70x nutpie [0.65, 0.96], and per second on Linux it is 0.89x CmdStan [0.85, 1.00] and 0.93x nutpie [0.87, 1.28], both intervals reaching 1. The honest line over 18 seeds: the most reliable of the three by a wide margin, a little behind per gradient, about even per second. v7's own three seeds gave 0.708 over the 15 complete fixed-16 models, against v6's 0.848; a preregistered three-seed extension (WP62) gave 0.810 on the new seeds and 0.761 pooled over six, with a leave-one-seed-out interval of [0.740, 0.822] [E28]. Pooled over 96 cells oWALNUTS passes 80 against CmdStan's 62. The one loss that survives both seed sets is accel_gp (0.35x); one_comp (0.50x -> 1.63x) and hmm_drive_0 (0.66x -> 0.98x) swung with the seeds. Wall per gradient is 1.85x CmdStan's, because the Windows owned worker serialises BridgeStan and the machine was contended. ESS per second is 1.23x nutpie's.

The same protocol on Linux (WP64, 16 dedicated cores, pinned and co-tenanted) reproduces the pass counts within one cell per block: oWALNUTS 44/51, 7/15 and 41/48 (one seeds_centered cell now passes), CmdStan 33, 5 and 31, nutpie 27 and 5. No cell is bit-identical across platforms (the start search matches; runs diverge by warmup iteration 50, as libm differs). The per-gradient headline is platform- and seed-dependent: pooled over six Linux seeds it is 1.21x CmdStan, because CmdStan's chain sits in hmm_drive_0's second mode on 4 of 6 Linux seeds (2 of 6 on Windows), and 0.86x without that model (Windows 0.75x). Wall per gradient falls to 0.94x CmdStan's with the concurrent-replica dispatch, and ESS per second is 1.22x CmdStan's and 1.45x nutpie's on those six seeds (over 18 seeds, 0.89x and 0.93x; WP76). The robustness study (WP72, 12 further seeds) fixed the headline statistic above. [E34]

v7 did not pass the v6 release rule. Its per-gradient clause (>= 0.75 CmdStan) failed: the value was 0.708, and the clause was formally unevaluable because one CmdStan lotka_volterra cell errored. Its wall clause failed too. That per-gradient clause is now known to be seed-noisy. Paired reruns on the same seeds attribute the 0.848 -> 0.708 change neither to best-of-16 starts (1.061x uniform, WP60) nor to removing chain rescue (1.023x, WP61), but to seed-to-seed variation. The 3-seed geomean moves by about 0.1 between seed sets with no code change behind it [E27]. The pass counts are therefore the headline. Under its frozen rule, v7 does not replace v5 as the last release-qualified benchmark. v5 and v6 follow as history.

History: v5 and v6. The last breadth benchmark admitted by its preregistered release rule is STUDIES/posteriordb_bench_v5, on the same 17 posteriors and protocol, at the 0.2.0 defaults. [E15] (v3 on the pre-WP31 defaults, kept as history: 35/51, 0.34x CmdStan per gradient [E4].)

WP33 subsequently made warmup restart-from-best chain rescue the default. The then-current-default validation, posteriordb_bench_v6, passes 45/51 cells against CmdStan 34 and nutpie 29 with no frozen chain, but did not meet its frozen release rule: one passing one_comp cell has max |z| 4.023 and one sblrc sampler subprocess exited without a result, leaving its fixed-16 efficiency gates unevaluable (observed 0.848x CmdStan per gradient over the 15 complete models). WP36 then mechanically selected no_rescue: its preregistered completeness gate failed after seven process faults, and two_hit failed its conjunctive efficacy, nuisance-reduction, funnel, origin-safety and efficiency gates. That failure alone did not select no_rescue; it advanced the mechanical rule to the current fallback check. current had registered red lines in four origin-overwrite cells (five events) plus unknown run history for HMM/92104, so the fallback selected no_rescue. The final 0.2 default therefore returns to the plain multi-chain warmup used by v5. The v5 numbers below are the 0.2.0 release figures; v6 remains the historical record of the temporary WP33 default and must be read beside it. [E16, E17, E18]

Historical WP35 replay: do not run STUDIES/posteriordb_bench_v6 from the current tree and call it a WP35 reproduction. Check out the recorded WP35 study revision 8d3a7b5 (source under test aa4510f) first. At current HEAD, Adaptation::default() intentionally means no rescue, whereas WP35 measured the temporary restart-from-best default.

v5 (0.2.0 defaults):

• More cells pass than CmdStan or nutpie. oWALNUTS passes 42/51 cells; CmdStan 36, nutpie 28. Twelve models at 3/3 against ten and eight.
• ESS per gradient is still below CmdStan on ordinary posteriors. Geometric mean 0.82x CmdStan over the 16 models where CmdStan is healthy, 0.67–0.95x per model with no exception; 1.07x over all 17 only because CmdStan and nutpie each lose two arma11 seeds to a chain that never leaves its start (oWALNUTS 3/3 there). Against nutpie 0.84x per gradient. The residual is the kernel (reverse-coarser stops on refined leaves and orbit length, [E13]), not warmup.
• Wall time and ESS per second are ahead. Wall per gradient 0.80x CmdStan's; ESS per second 1.40x CmdStan's and 3.09x nutpie's (above CmdStan on 8 of 17 models, above nutpie on 14 of 16).
• What still fails. The centered eight schools fails every sampler on every seed; accel_gp (66-d GP) fails every sampler at 0.47x CmdStan per gradient; hmm_drive_0 can put one chain in a second mode from a uniform start (one seed each for oWALNUTS and CmdStan here); one_comp is 1/3 for oWALNUTS and CmdStan; diamonds still hits the depth-10 cap on 250–540 transitions per seed. Bad starts no longer stall a chain: no frozen chain, no step collapse (sblrc 0/3 -> 3/3), zero retained divergences on every oWALNUTS cell.
• Refinement rarely engages on these posteriors. A refinement level above zero is selected on 1–3 % of retained transitions, so on ordinary models the kernel runs as NUTS, and its endpoint U-turn rule then costs 0.75–0.9x per gradient against Stan's momentum-sum rule on Gaussian targets. On the posteriordb set, swapping in Stan's rule alone (UTurnRule::MomentumSum) is a per-model coin (1.06–1.12x geometric mean) because the default metric regularisation floors small posterior variances at 0.01 and hides it; with Stan's regularisation (DiagonalMetricRegularization::Stan) the two together are 1.51x the default per gradient over the 17 models and pass 41 cells against 35. The preregistered flip rule failed on the two cells no option passes (hmm_drive_0's second-mode draw, the centered eight schools); the pair was made the default afterwards as a post-hoc decision and validated on fresh seeds in STUDIES/posteriordb_bench_v5 [E15]. [E5, E6, E12, E13, E14]

The wins measured so far come from funnel-type targets, from structured metrics, from gates (fewer failed cells than either NUTS implementation on the posteriordb set) and from wall time; per gradient, an ordinary regression that CmdStan already samples cleanly still costs oWALNUTS 1.05–1.5x the gradients.

Defaults and opt-ins

Sampler::new() with no other calls runs:

Setting	Default	Why
warmup / draws / chains	1,000 / 1,000 / one per start	Stan's shape
Tuning::max_depth	10	ablation over nine posteriordb models: 1.45x ESS per gradient and 17/18 gates against depth 8 [E7]
Tuning::step_size (h)	0.5	initial macro step; dual averaging adapts it
Tuning::max_refinement_levels	8	micro-steps down to h / 128; four levels halve the funnel's tail mass at the adapted step, eight are exact and never engage on Eight Schools or a 100-D Gaussian [E11]
Tuning::max_error (delta)	1	energy-error threshold per macro step
Tuning::kernel_options U-turn rule	UTurnRule::MomentumSum (Stan's generalised criterion)	post-hoc default change after WP31, validated by WP32: with Stan's metric prior it is 1.51x the endpoint rule per gradient over 17 posteriordb models; the frozen v10 endpoint rule is KernelOptions::default() [E14, E15]
Adaptation	dual averaging to acceptance 0.8	75 / 25, 50, 100, ... / 50 windows (gamma 0.05, t_0 10, kappa 0.75); warmup exhaustion rule AcceptUnlessDivergent [E10]
Metric	adapted diagonal	Welford, regularised with Stan's prior (DiagonalMetricRegularization::Stan, post-hoc default change after WP31; the v10 TowardUnit prior floors small variances at 0.01 and collapsed the step on sblrc / arma11) [E14, E15]
warmup chain rescue	none (DEFAULT_CHAIN_RESCUE = None)	two_hit failed its conjunctive gates; current then hit registered red lines in four origin-overwrite cells (five events) plus unknown HMM/92104 run history, selecting the WP36 fallback; default telemetry has no rescue records [E18]
trapped-chain guard	DEFAULT_TRAPPED_CHAIN_RESTART (TrappedChainRestartConfig::guard(): step ratio 0.01 at the close of the first slow window, three or more chains, identity and diagonal metrics only; an independent best-of-16 restart, at most once per chain)

Opt-ins, each one builder call:

• Adaptation::Paper(PaperAdaptationConfig::default()): the JMLR Appendix C rules (delta from the K-quantile rule, h so a fraction of macro leaves needs no refinement). On Neal's funnel from delta = 1, h = 0.1 it is unbiased and 1.41x / 1.61x (bulk / tail ESS per call) the paper's own fixed funnel tuning [E8]; on posteriordb it is at parity with dual averaging (geomean 0.995) and robust on the cells that froze under its v3 defaults [E4, E9]. See examples/funnel_paper_adaptation.rs.
• Adaptation::Custom(WarmupConfig::new(0.8)?.with_warmup_exhaustion_rule( DEFAULT_WARMUP_EXHAUSTION).with_metric_regularization(DEFAULT_METRIC_REGULARIZATION)), or .without_trapped_chain_restart() on any custom warmup: the pre-WP90 default without the trapped-chain guard, bit for bit [E54].
• Adaptation::Custom(WarmupConfig::stan_style(0.8)): Stan's acceptance statistic, init_stepsize, metric prior and restart reference. 2.0x the default's ESS per gradient on correlated regressions but 12–16 % worse on three models and R-hat > 1.01 on two, so opt-in [E7].
• Adaptation::Custom(WarmupConfig::new(0.8)?.with_chain_rescue( ChainRescueConfig::restart_from_best())): the WP33 immediate restart-from-best rescue remains an explicit bad-start robustness opt-in (25/27 cells against the plain driver's 21, including lotka_volterra 0/3 -> 3/3). When it acts it copies another chain's state, invalidating the independent-start interpretation of ordinary R-hat; inspect RunTelemetry::chain_rescues. Observe-only, two-hit and pooling policies are explicit opt-ins through the same builder [E16, E18].
• The pre-WP31 kernel rules (the frozen v10 endpoint U-turn rule and the unit-variance metric prior), for reproducing runs made before the default change: Tuning::new().kernel_options(KernelOptions::default()) with Adaptation::Custom(WarmupConfig::new(0.8).with_warmup_exhaustion_rule(DEFAULT_WARMUP_EXHAUSTION).with_metric_regularization(DiagonalMetricRegularization::TowardUnit)). The current defaults (UTurnRule::MomentumSum + DiagonalMetricRegularization::Stan) are a post-hoc decision: STUDIES/joint_default_v1 preregistered a flip rule and failed it on two cells no option passes (hmm_drive_0's arm-dependent second-mode draw, the centered eight schools), while the pair was 1.51x the old default's minimum bulk ESS per gradient over the 17 posteriordb models (earnings 3.7x, sblrc 9.1x, arma11 2.3x, kidiq 2.0x, hmm_example 1.9x, nes2000 1.5x; nothing below 0.94x among the models the old default passes), 41 cells against 35, funnel tail mass exact at both tunings with zero divergences and 1.29x on the Eight Schools strict track [E14]. The flip was decided after that result and validated on fresh seeds against CmdStan and nutpie in [E15]. The two rules go together: the U-turn rule alone is a per-model coin (1.06–1.12x geomean) [E12], and the Stan prior under the endpoint rule is unstable on (0.08x, R-hat up to 1.6: the short endpoint-rule orbits leave the window variance at the prior's floor) [E14].

Structured metrics

StructuredBlockMass (BidiagonalCholesky, ScaledAr1; linear time), DenseMass, BlockDiagonalMass and LowRankArrowheadMass are fixed momentum covariances run from the Sampler through Metric::Structured and Metric::Dense. For a Gaussian state-space path, the tridiagonal posterior precision Q_rw + diag(1/r_t) as M whitens the whole path, so trajectories U-turn at depth 3–4 at any T where a prior-based metric caps the tree [E2]; examples/state_space_path_metric.rs shows it against the exact posterior mean. When the right block depends on parameters being sampled, Metric::StructuredRefresh rebuilds it from a caller-supplied StructuredMetricRefresh at every completed slow warmup window and freezes it before retention, with a typed StructuredRefreshUpdate per boundary.

Dense metric (Metric::dense())

Sampler::new().metric(Metric::dense()) adapts a full dense metric during warmup. It is never selected automatically, and the adapted diagonal remains the default.

When to use it: correlated or collinear near-Gaussian regression and autoregression posteriors. These are min-bulk-ESS-per-gradient ratios against the diagonal default, posteriordb, 3 fresh seeds, all gates passed in both arms [E19]:

model	dense / diagonal
diamonds	98.7x (step 0.0036 -> 0.28; depth caps 10 % -> 0)
nes2000	15.5x
mesquite	15.3x
arK	7.6x
kidiq	5.4x
earnings	4.5x

When not to: GP-hyperparameter posteriors. At 1,000 draws gp_pois_regr went 3/3 -> 0/3 gates: it is 1.73x per gradient, but it takes fewer gradients per draw and the length-scale's ESS falls below 400. accel_gp went 1/3 -> 0/3 at 0.38x. For GP models that must pass their gates, a target acceptance of 0.95 is the measured opt-in: on accel_gp it passes 3/3 with 2.7x the ESS at 2.5x the gradients (WP70, [E35]). Funnels and hierarchical scale problems also need care: on Neal's funnel the tail mass is exact, but there were 2 retained divergences against 0 for the diagonal. Over all 17 models dense passes 40/51 gate cells against the diagonal's 43/51 (geomean 3.21x per gradient). On fresh seeds in posteriordb v7's descriptive dense arm, Metric::dense() passed 18/18 cells on the six correlated regressions above, at 13.4x the diagonal default's ESS per gradient (diamonds 67.5x) with max |z| 3.05. This supports dense as an opt-in for correlated regressions, not as a default [E26].

Warmup uses per-transition seeding, Stan's dense regularisation and a symmetrised precision. These have been the defaults since WP51. Earlier builds used Legacy / MeanVarianceShrinkage / no symmetrisation, which was 0.055x the diagonal with 12/51 gates; that setting is still available through Adaptation::Custom for reproduction (STUDIES/dense_metric_posteriordb_v1, STUDIES/dense_metric_confirmation_v1).

Oracle parity

Private test-only modules compare the kernel with pinned outputs of the unmodified upstream headers (cargo test oracle_tests):

• oracle/walnutpie/f5bba365: 54 Gaussian macro-leaf, span, transition and transition-sequence units;
• oracle/walnutpie/f5bba365_funnel_leaves: 4,000 Neal's-funnel macro leaves across four tunings and omega in [-8, 4]: decision, level, endpoint, adaptation statistic and target calls agree to 1e-11 (kernel v8 disagreed on 1,555);
• oracle/walnutpie/f5bba365_invalid_leaves: 4,000 leaves against a throwing wall target, pinning the v10 rule that a recoverable failure refines like any over-tolerance micro-step.

Orbit-level parity on hard targets is covered statistically (STUDIES/funnel_bias_fix_v1, STUDIES/paper_funnel_reproduction_v1), and every Sampler::run path is bit-identical to the walnutpie entry point it wraps (tests/sampler_api.rs).

Known limitations

• The posteriordb gaps above: about 0.7x CmdStan per gradient (v7 [E26]; 0.34x on the v3 defaults), no throughput win on ordinary regressions, single chains stalled by bad starts on three models [E4, E10].
• Paper adaptation runs on the diagonal and fixed-operator facades only; the dense-adaptive, projected and pooled facades reject it.
• The sigma_x -> 0 state-space funnel (sspd-10) is not sampled by any Euclidean sampler tested, NumPyro NUTS included; it needs a reparameterisation, not a metric [E2].
• On an exactly whitened Gaussian a fixed macro step can alias the tree-doubling schedule; there is no step-jitter option.
• Seeds reproduce runs bit for bit only under the same kernel revision, crate build, lock file, target architecture, operating system (the C math library sets the last bits of the draws; trajectory decisions agree across Windows and Linux) and thread-independent deterministic target.
• Cancellation and deadlines are cooperative; a callback that never returns cannot be interrupted. ResourceLimits are preflight ceilings for accounted allocations, not process memory.
• The Python, BridgeStan and autodiff crates are built from the tree, not published; the BridgeStan sampling tests need a locally compiled model.
• The core Rust sampler is distinct from optional Stan support. The Windows GNU Rust StanTarget owned-worker mitigation completed 540 ordinary and 180 concurrent-target diagnostic children without a fault, but the historical root cause is not proven and sampling was 3.1–5.1x the four-replica comparator. Windows execution is therefore limited by default to one effective replica per target with a process-global native-call lock; static-runtime DLLs can opt into concurrent replicas (see "Threads and chains"). Windows MSVC and the Linux/macOS/package matrices remain release gates; Windows Python from_stan and direct Python BridgeStan calls remain disabled.

API stability

owalnuts::sampler, owalnuts::diagnostics, owalnuts::export and owalnuts::walnutpie are public and follow semver from 0.1.0. Research-only items (OuterOrbitSelection, ResearchTargetEvaluationLimit, ResearchRestartReferenceMultiplier, DualAveragingAcceptance::AcceptedTrajectory, the direct_original_q family, the projected and pooled arrowhead facades) are exported from walnutpie only with features = ["research"] and may change between minor versions. sampler::Tuning::default() is not walnutpie::KernelTuning::default(): the facade keeps the frozen replay defaults so pinned fingerprints hold.

Research record

• wiki/README.md: the wiki map. Start with the decisions register, the negative results and the topic pages under wiki/findings/.
• wiki/release-0.3.0.md: 0.3.0 changes, validation evidence, limitations and upgrade notes;
• wiki/release-0.2.0.md: 0.2.0 changes, validation tables and limitations; CHANGELOG.md for the upgrade notes.
• wiki/research-ledger-2026-08-31.md: one checksummed entry per study.
• wiki/research-program-2026-09-04.md: the 0.2 program — what shipped, why each default changed, what the posteriordb benchmark falsified, and the open lines; wiki/research-program-2026-08-31.md: the program that produced 0.1.0-beta.2.
• STUDIES/: every preregistration, runner, artifact and checksum.

Toolchain

Rust 1.88 or newer. CI runs GNU 1.88 on Linux and Windows plus Linux stable: tests (including all oracles), strict Clippy, fmt --check, -D warnings rustdoc, examples and cargo package.

Support and license

See SECURITY.md for scope. MIT; see LICENSE, NOTICE and THIRD_PARTY.md for the walnutpie provenance.

Evidence

Terminology clarification (2026-10-27): early online-SV entries use "calibrated" for the proportion of warm draws inside reference-posterior intervals. That statistic measures reference-interval occupancy. Predictive calibration requires comparison with realized outcomes, and full posterior agreement requires additional checks. The historical measurements below are unchanged; WP96 and the predictive-functional diagnostics separate these claims explicitly.

• [E1] Funnel tail mass 0.0474 vs 0.0478, reference 0.0477, v8 0.0971: STUDIES/funnel_bias_fix_v1 (ledger WP6-FUNNEL-BIAS-FIX-V9).
• [E2] State-space path metric, depth 3–4 at T = 1000, ~1,000x prior-based, 4.8x identity; sspd-10 unsampled: STUDIES/exact_state_space_ground_truth_v1 (WP4-ESSGT-V1), STUDIES/real_target_path_metric_v1 (WP4B-REAL-TARGET-PATH-METRIC-V1).
• [E3] Eight Schools strict track, 12,830 / 10,346 ESS/s vs CmdStan, BlackJAX, NumPyro (walls on a loaded machine): STUDIES/eight_schools_v9_rebench_v1 (WP8-EIGHT-SCHOOLS-V9-REBENCH-V1).
• [E4] posteriordb v3 (fresh seeds, WP24 default), 35/51 vs 37 and 31, 0.34x per gradient, 0.75x wall per gradient, 1.35x nutpie ESS/s, gate wins on noncentered eight schools and gp_pois_regr: STUDIES/posteriordb_bench_v3 (WP25-POSTERIORDB-BENCH-V3); v2 before the rule, with the frozen chains and the paper arm at 0.995x dual averaging: STUDIES/posteriordb_bench_v2 (WP23-POSTERIORDB-BENCH-V2).
• [E10] the freeze mechanism (two-sided energy check at the initial leaf from overflow starts) and the AcceptUnlessDivergent warmup rule that unfroze 12/12 arma11 chains: STUDIES/freeze_mode_v1 (WP24-FREEZE-MODE-V1).
• [E5] Refinement on 1–3 % of retained transitions; kernel-side 0.7–0.8x: .