Skip to content

API ​

Transitions ​

NUTS.nuts!! Function
julia
nuts!!(state)

Take one No-U-Turn Sampler transition with multinomial sampling and the strict generalized no-u-turn criterion. Return the updated state.

The input is a named tuple containing rng, posterior, stepsize and a mutable position vector. The target implements NUTS.log_density_gradient!.

Supply scale and squared_scale together, with squared_scale = scale * scale'. The sampler uses ldiv! with scale' to transform momentum and mul! with squared_scale to compute velocity. The identity pair scale=I, squared_scale=I is a complete configuration.

Optional controls are max_depth=10 and min_dhamiltonian=-1000.0, the threshold for the change in negative Hamiltonian that marks a divergence. The returned state initializes and reuses internal work arrays. Keep the target, position dimension and storage depth fixed while reusing that state.

The new draw is state.position; copy it when retaining draws. The returned current phase point contains log_density and log_density_gradient. Transition diagnostics are divergent, accept_prob (the mean integration acceptance probability) and n_leapfrog (the number of integration steps). This function does not adapt the step size or metric.

source

The state guide explains buffer reuse, metric conventions and the interpretation of transition diagnostics.

Target callbacks ​

NUTS.log_density_gradient! Function
julia
NUTS.log_density_gradient!(posterior, position, gradient)

Return the scalar log density at position and overwrite every entry of gradient with its derivative in the same coordinates. Define a method for your target type. A position-independent normalization constant may be omitted.

The current sampler allocates internal position and gradient buffers as Vector{Float64}. A target in transformed coordinates must include the appropriate log-Jacobian term and its derivative.

source

The log-density guide implements this extension point and checks its gradient. The Gaussian example uses it in a complete chain.