org.replikativ.foerster.nuts — org.replikativ/foerster 0.1.131

The No-U-Turn sampler on block sites (foerster.block), within Gibbs, as Stan implements it: multinomial sampling over the trajectory, the generalized no-U-turn criterion with the checks across merged subtrees (Hoffman & Gelman 2014; Betancourt 2017), divergences when the energy error exceeds 1000, a diagonal metric, and during warm-up dual-averaging step size adaptation and windowed variance estimation of the metric (Stan's 75/25/50 windows, scaled to short warm-ups). Stan's step size heuristic (init_stepsize: double or halve until one leapfrog step's acceptance crosses 0.8) runs as warm-up begins and after every metric window, and dual averaging restarts from it, at μ = log 10ε. As warm-up begins this deliberately deviates from Stan, whose first μ is log 10ε of its configured step size (default 1): here it comes from the heuristic's ε, as at every later restart, so the first window does not start from a scale-blind guess.

NUTS samples the block's own density, so the block's target must be the complete conditional of its latents (:block/target :complete-conditional): every factor they touch inside the block, and no other site depending on them. A replay that changes the log probability of anything outside the block is refused (::incomplete-target, its :changed the sites whose score moved). Put a hierarchy into one block, or move such a block with HMC (foerster.hmc) or delayed acceptance (foerster.block-mh), which accept on the full trace (doc/algorithms.md, section NUTS within Gibbs needs complete conditionals).

Each chain starts at its block sites' :init plus U(−2, 2) per coordinate of θ (jitter), unless :jitter false — also with :burn 0, where every draw is kept: to resume a frozen chain from a posterior draw, pass that draw as :init with :jitter false. :step-size and :inverse-metric set where warm-up starts, or with :burn 0 the frozen values NUTS runs at; the sampler statistics report them.

The kernel is (k/nuts-kernel iterations {:burn … :target-accept 0.8 :max-depth 10}): the first :burn iterations adapt and are dropped.

jitter clj/s

(jitter trace)

A chain's start for NUTS: every block site of trace (the chain's initial state) moved by a uniform jitter in (−2, 2) per coordinate of θ, the unconstrained coordinates — Stan's random initialization radius, around the site's :init as PyMC jitters around its initial point — so that chains start apart and R̂ can see them disagree. The draws come from the chain's world stream, so a seeded run is reproducible. A site keeps its value when none of 100 jitters has a finite log density and gradient, and the whole state keeps it when the jittered state has zero density. Returns a CPS operation resolving the new trace.

transition clj/s

(transition dist q0 eps inv-metric max-depth)

(transition dist q0 eps inv-metric max-depth start)

One NUTS transition of dist (a block distribution) from position q0 with step size eps and diagonal inverse metric inv-metric, drawing from the current generator. start, when given, is [log density, gradient] at q0 (the previous transition's), which is then not evaluated again. Returns {:q :lp (log density at q) :g (its gradient) :accept-stat :depth :n-leapfrog :divergent?}.

within-gibbs clj/s

(within-gibbs {:keys [burn target-accept max-depth metric step-size
                      inverse-metric]
               :or {burn 0 target-accept 0.8 max-depth 10 metric :variance}})

A step for foerster.trace/mh-chain (:step): a NUTS move of every block site, then one single-site MH move of a latent that is not a block site, if there is one. A fresh adaptation state per call (per chain). opts: :burn, :target-accept (0.8), :max-depth (10), :metric (:variance, Stan's estimate from the positions, or :fisher, from positions and gradients), :step-size (0.1) and :inverse-metric (ones), where each block's adaptation starts, or, with :burn 0, the fixed values it runs with — each one value for every block site or a map {address value}. The sampler statistics' :step-size and :inverse-metric are such maps, the values each block's transition ran with. Returns per-step :sampler-stats for direct NUTS inference. The flag :reached-max-depth? reports depth attainment, including transitions that stop naturally or diverge at that depth; it does not identify cap exhaustion. Composed kernels and final-state-only output do not retain these statistics.