Choose, run, and review an inference workflow

Model layer

One intermediate representation, two frontends

Constraints cover real, positive, bounded, ordered, simplex, unit/sum-to-zero, and covariance/correlation parameters. Compiled factors evaluate on reusable reverse tapes in unconstrained space and add the correct log-Jacobian. Host applications read CSV, JSON, databases, or other sources and bind primitive arrays; follow the file-backed example. Run Gradients.check before HMC/NUTS.

Sampler selection

Start with geometry and variable type

NUTS never silently uses finite differences. Opt in with allowFiniteDifferences(true) only when its cost and fragility are acceptable.

Trans-dimensional inference · expanded in 0.9.1

Use a complete joint and prove every reverse move

ReversibleJumpState stores a model identifier and variable-length parameters. A ReversibleJumpMove declares its reverse, forward/reverse proposal densities, and Jacobian; the sampler supplies boundary-aware move-selection probabilities. Warmup may adapt schedule weights, per-model continuous scales, and birth proposals, but retained sampling uses a frozen checkpointable process.

For up to 62 covariates or loci, start with SubsetSelectionTarget and SubsetSelectionRj. The general add/drop/swap path produces model and inclusion probabilities with ESS/MCSE/R-hat, transition and round-trip diagnostics, conditional coefficient summaries, and tidy ragged output. Read the small complete worked analysis.

For thousands of candidates with a small active cap, use SparseSubsetTarget, SparseSubsetState, and SparseSubsetRjSampler. Sorted integer states, state-dependent candidate proposals, online summaries, and exact interruption-safe checkpoints avoid dense model identities and unbounded retained storage. The 17,000-gene GSE93272 tutorial adds a mixed model, reproducible data preparation, and CUDA/OpenCL-assisted residual scores.

Adaptation

Warmup calibrates the algorithm; it is not posterior output

Dual averaging targets the requested acceptance probability. Windowed covariance learns a diagonal metric by default or a dense metric when enabled. Examine WarmupResult for final step size, inverse mass matrix, and mean warmup acceptance.

Diagnostics

No single number clears a model

JDistlib reports rank-normalized split/folded R-hat, bulk/tail ESS, MCSE, posterior summaries, acceptance, divergences, depth, failures, and the minimum per-chain E-BFMI.

Graphing

Use each graph to answer a distinct question

Every ChartSpec exports JSON, CSV, and standalone SVG. InferenceHtmlReport embeds plots into one offline HTML artifact.

Performance

Optimize evaluations before chasing sampler tricks

• Use analytic gradientsFinite differences multiply density evaluations by dimension.
• Parallelize chainsChains.parallel keeps deterministic independent streams.
• Keep local evaluatorsBundled samplers automatically reuse model buffers per chain.

0.8.0 also reuses random-walk proposal buffers and covariance scratch storage, avoids temporary metric velocities, reads immutable observation vectors without cloning, and uses scalar accessors during diagnostics/export. Prefer thinning only for storage or downstream cost. Use the included smoke benchmark for regression checks and JMH for serious comparisons.

Failure handling

Failures are data, not exceptions to ignore

ChainResult.Status distinguishes success, cancellation, invalid initial state, and numerical failure. Retained warnings and transition statistics preserve the evidence needed for review. Versioned NUTS checkpoints clone the exact RNG stream and restore the adapted metric, dual-averaging state, covariance accumulator, and warmup position; unsupported checkpoint formats fail explicitly.