Reference / binference.samplers.NUTS

binference.samplers.NUTS

class binference.samplers.NUTS(model, *, n_chains=4, n_warmup=1000, target_accept=None, max_depth=10, metric='auto', reparametrize=True, init=None, jitter=0.1, n_jobs=1, rng=None, progress=False)

No-U-Turn Sampler on the exact posterior, for every prior.

Samples the unconstrained coordinates of the model (isometric log-ratios for simplex priors, whitened fields and log-hyperparameters for smooth priors, log-rates for rates) with multinomial NUTS, dual-averaging step size adaptation and Stan-style windowed metric adaptation. Chains run in lock-step, so the engine supports progress reporting, a generator interface (sample()) and resuming (call run() again to draw more samples without re-running warm-up).

Parameters:

modelPopulationModel

n_chainsint

Number of independent chains (default 4; needed for R-hat).

n_warmupint

Warm-up (adaptation) iterations per chain.

target_acceptfloat, optional

Target mean acceptance statistic for step-size adaptation. Defaults to 0.8, or 0.9 for logistic (smoothness) priors, whose hyperparameters make the geometry harder.

max_depthint

Maximum tree depth (at least 1; at most 2**max_depth gradient evaluations per draw).

metric{“auto”, “diag”, “dense”}

Adapted Euclidean metric. "auto" uses a dense metric for logistic (smoothness) priors with at most 200 unconstrained dimensions, whose hyperparameters correlate with the field, and a diagonal one otherwise.

reparametrizebool

Partially centre the basis coefficients of logistic priors during warm-up. For logistic priors, switch each basis coefficient between the non-centred and centred forms according to how strongly the data constrain it (partial non-centring with weights 1 / -H_jj from the curvature at the chains’ positions early in warm-up). If the field pins the hyperparameters down poorly (few basis coefficients per hyperparameter, e.g. a handful of bins), the coefficients stay non-centred, which avoids funnels. This changes the sampling coordinates, not the posterior.

initarray_like (dim,) or (n_chains, dim), optional

Starting points in the model’s unconstrained coordinates; a single point gets jitter added for each chain. Every start must have a finite log density. By default chains start at the posterior mode (in unconstrained coordinates) plus jitter.

jitterfloat

Standard deviation of the Gaussian jitter around the starting point.

n_jobsint

Number of worker processes for the chains (-1: one per CPU this process may use). The default 1 runs the chains in this process. The workers share the cores’ BLAS threads instead of oversubscribing them, never exceeding a thread limit already set. Parallel and serial runs use the same random streams, so their draws agree up to rounding differences in multithreaded linear algebra. Parallel runs show no progress bar.

rngint, Generator or None

Random number generator (SPEC 7); each chain gets an independent child.

progressbool

Show a progress bar.

Notes

For logistic (smoothness) priors, after min(25, first window start) warm-up iterations (none when n_warmup < 20, which also skips metric adaptation) the engine reparametrises the prior (reparametrize) and, for at most 500 dimensions, initialises the metric from the finite-difference curvature of the log posterior at the chains’ positions. Each later adaptation window shrinks its estimate toward the previous window’s metric, starting from that curvature-based one. Simplex and rate priors use Stan’s windowed adaptation unchanged.

Results (x, log_density_unconstrained, model) are in the prior’s non-centred coordinates whatever the sampling coordinates; info["centring"] holds the partial-centring weights used, and info["inv_metric"] is in those sampling coordinates.

__init__(model, *, n_chains=4, n_warmup=1000, target_accept=None, max_depth=10, metric='auto', reparametrize=True, init=None, jitter=0.1, n_jobs=1, rng=None, progress=False)

Methods

__init__(model, *[, n_chains, n_warmup, ...])
run([n_samples])	Warm up (first call only), draw n_samples per chain, and return all draws so far.
sample(n_samples)	Generator over post-warm-up iterations, yielding (n_chains, dim) positions.
unsupported(model)	Why the engine cannot run on model, or None when it can.
warmup()	Run warm-up (adaptation) if it has not been run yet.

Attributes

approximate
joint	whether the engine infers a selection from injections or a tallied response jointly (DECISIONS #30, #80, #81)
markov	whether its draws are Markov chains, described by R-hat and ESS
name
result	A PopulationResult with every draw recorded so far.

joint = True

whether the engine infers a selection from injections or a tallied response jointly (DECISIONS #30, #80, #81)

markov = True

whether its draws are Markov chains, described by R-hat and ESS

property result

A PopulationResult with every draw recorded so far.

run(n_samples=1000)

Warm up (first call only), draw n_samples per chain, and return all draws so far.

Parameters:

n_samplesint, optional

Draws per chain after warm-up.

sample(n_samples)

Generator over post-warm-up iterations, yielding (n_chains, dim) positions.

Positions are in the model’s unconstrained coordinates (the prior’s non-centred form). Draws are also recorded and included in the next run() / result. With n_jobs > 1 the chains advance in worker processes and the positions are yielded once all have finished.

Parameters:

n_samplesint

Iterations per chain.

warmup()

Run warm-up (adaptation) if it has not been run yet.