Skip to content

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.

julia
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.

julia
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.

julia
@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)

FieldMeaningInterpretation
divergentA leapfrog step crossed the energy-error thresholdInvestigate the target gradient, geometry and step size
accept_probMean Metropolis probability over the transition's leapfrog stepsAn integration diagnostic, not the fraction of draws that changed position
n_leapfrogNumber of leapfrog steps in this transitionWork 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.