Sampler state
Reuse a transition's returned state, retain draws without aliasing its buffers, and supply a scale for coordinates with different units.
Transitions
nuts!! takes a state and returns its replacement. Assign that return value on every call: the first call adds work buffers and later calls update diagnostics. The function mutates arrays reachable from the state, including the initial position vector. Construct separate arrays and an RNG for each independent chain.
using NUTS, Random, LinearAlgebra
struct StandardNormal end
function NUTS.log_density_gradient!(::StandardNormal, q, gradient)
gradient .= -q
return -sum(abs2, q) / 2
end
state = (rng=Xoshiro(42), posterior=StandardNormal(),
position=zeros(2), stepsize=0.5, scale=I, squared_scale=I)
state = nuts!!(state)
snapshot = copy(state.position)
alias = state.position
state = nuts!!(state)
(; alias_is_live=alias === state.position,
snapshot_is_separate=snapshot !== state.position)(alias_is_live = true, snapshot_is_separate = true)
Store a draw with copy(state.position) or copy it into a preallocated column. Saving only references to state.position does not preserve the chain history. Treat the returned state's work buffers as sampler-owned.
Scale
For a target with covariance C, supply a factor S and its product S * S' as scale and squared_scale. Momentum is generated by solving with S', and velocity is computed by multiplying momentum by C. A covariance factor, not a precision factor, belongs in scale under this convention.
The following setup preserves the requested diagonal scaling in the returned state. The target here is standard normal, so this deliberately illustrates the interface rather than recommending these scales for this target.
scales = [0.5, 2.0]
S = Diagonal(scales)
C = Diagonal(scales.^2)
scaled_state = (rng=Xoshiro(7), posterior=StandardNormal(),
position=zeros(2), stepsize=0.2,
scale=S, squared_scale=C)
scaled_state = nuts!!(scaled_state)
@assert scaled_state.scale === S
@assert scaled_state.squared_scale === C
(; supplied_factor=diag(scaled_state.scale),
supplied_covariance=diag(scaled_state.squared_scale))(supplied_factor = [0.5, 2.0], supplied_covariance = [0.25, 4.0])
Supply the pair explicitly for a user-provided metric. The factor must support an in-place solve with its adjoint; the covariance must support matrix-vector multiplication into a destination. Keep both objects fixed while reusing the state. Use a fresh initial state when changing the metric, dimension, target or tree-storage configuration.
Diagnostics
The returned state describes the last transition. The following output reads those fields from a completed transition rather than constructing a mock result.
@assert isfinite(state.accept_prob)
@assert 0 <= state.accept_prob <= 1
(; state.divergent, state.accept_prob, state.n_leapfrog)(divergent = false, accept_prob = 0.972190777681267, n_leapfrog = 5)
| Field | Meaning | Interpretation |
|---|---|---|
divergent | A leapfrog step crossed the energy-error threshold | Investigate the target gradient, geometry and step size |
accept_prob | Mean Metropolis probability over the transition's leapfrog steps | An integration diagnostic, not the fraction of draws that changed position |
n_leapfrog | Number of leapfrog steps in this transition | Work performed; a large count alone does not establish a failure |
NUTS chooses trajectory length using its U-turn criterion and a maximum tree depth. This package does not tune stepsize or learn a metric during warmup. Choose them before collecting draws, or use a package providing adaptation. Discarding initial draws is not step-size adaptation. The state does not expose a dedicated maximum-depth saturation flag; do not reinterpret may_continue as one.
The Gaussian example records these diagnostics while collecting copies of positions with a scale matched to the target.