Core concepts

The objects a reader meets in a printed plan, a Result or a stored artifact, each defined by what the source does today. Follow the links for the full contracts.

The model

Graph

The single description of the model. trace runs an ordinary Python function once and records every sample, det, observe and const call as a node. Nodes are Const, Deterministic and Probabilistic; edges are the parent references passed to them; declaration order is the topological order. Each node is an Equinox module, so the whole Graph is a differentiable pytree. A Graph holds no sampler settings, run state or diagnostic conclusions. See Graph and hierarchy.

Affine block

A group of latents is an exact candidate when, with every other latent held fixed, the prediction is affine in the group, the group's prior is Gaussian and the noise does not depend on it. bayesmith establishes this in two independent ways. A structural analysis of the traced computation certifies affinity over the whole valid domain. A numerical probe then compares the model with its own linearization at three scales (10⁻³, 1 and 10³ prior widths) and three points. A group enters an exact route only if both succeed. Probes that pass without a structural certificate are reported as "numerically validated (global affinity unproved)" and do not admit the group.

det(..., linear_in=(...)) is optional metadata kept for compatibility. Its presence does not admit a group and its absence does not exclude one. When a declared group fails the probe, the plan prints the measured departures and routes the group to NUTS. Calling check_linearity directly raises AffinityRefused instead.

The plan

Block and route

A plan partitions the latents into blocks and gives each one a method. The method attribute takes five values:

Method	Printed as	Meaning
`gcr`	GCR exact	Exact conditional Gaussian draw; the noise does not move with the block.
`gcr+snis`	GCR + SNIS	The whole graph is exact but the noise moves with it: draws at the generalized-least-squares fixed point, corrected by self-normalized importance sampling. Independent draws, no chain.
`gcr+mh`	GCR + iterative GLS + MH	An exact block beside a sampled remainder, with moving noise: the exact draw becomes a Metropolis–Hastings independence proposal.
`log-gcr`	`log-gcr`	The exact draw on a log-transformed block whose prediction is exponential in an affine function. Emitted by `factor_partition`.
`nuts`	NUTS	NumPyro's No-U-Turn sampler.

A mixed plan runs NUTS on the sampled block and draws the exact block given the current sampled values once per sweep. The Overview shows one such plan.

InferencePlan

compile returns the plan: its blocks, each block's evidence and the execution shape, printed before anything runs. plan.sample and plan.estimate read the method, tolerance and noise handling off the plan rather than analyzing the graph again. When discovery finds several exact groups, compile returns a factor plan that alternates between them; it samples, and it has no point estimate. See Structure and inference routes.

The question and its answer

Task and Result

A Task names a statistical question. There are five: PosteriorTask, EvidenceTask, PredictiveTask, PointEstimateTask and SimulationTask, each answered by the Result of the same name. A Task holds a model reference, fingerprints, a budget and a bounded table of options. It never holds a Graph, a callable, a compiled executable or a backend handle, so it can be stored and compared. compile_task turns a Graph and a Task into a planned task or a Refusal; execute_task turns a planned task into a Result or a Refusal. See Five questions, one model.

Posterior representations

A posterior Result carries one of four representations: DrawsPosterior, WeightedDrawsPosterior, AnalyticPosterior and FittedConditionalPosterior. They are separate classes rather than draws with optional weights, because weighted draws whose weights were dropped are a wrong sample. Task execution currently produces the first two.

Refusal

A Refusal is the answer when no available route can answer the question. It is data: a stable failed_premise code, non-empty grounds recording what was observed and expected, the scope it applies to (model, node, parameter, block, data, task or backend), non-empty remedies and an optional fallback. Faults in the model itself, failed convergence and caller errors are raised as exceptions instead.

Run record

Every Result references a RunRecord: the plan, fingerprints, seed, dtype, devices, JAX configuration, backend and version, budget, termination reason, timing, warnings and an approximation record. The approximation record states whether the answer is exact, certified deterministic, Monte Carlo or heuristic, and whether it targets the exact or an approximate posterior.

Identity and reuse

Fingerprint and artifact id

A fingerprint is a SHA-256 digest of a canonical encoding of what an artifact depends on. The same model, data and task give the same fingerprint on any machine, and reuse and invalidation are decided by it. An artifact id is a random UUID assigned once: it says which artifact, not what it was made from. Invalidating an artifact keeps its id and increments its revision. See Results, provenance and reuse.

ModelRef

A ModelRef is how a stored task refers to a model: an identifier plus either a source digest or a package name and version, and any build arguments. model_ref_from_callable computes the digest from the function's source text. When no source text is available, as for a function built with exec, it raises rather than fall back to repr, which contains a memory address.

Assessment

Reports and gates

A check reports two things separately: whether it applied (APPLICABLE, INAPPLICABLE or UNVERIFIABLE) and what it concluded (PASS, FAIL or ABSTAIN). Only an applicable check can pass or fail. A gate combines reports into an operational status (BLOCKED, INVALIDATED, ERROR or EVALUATED), and only an evaluated gate carries a verdict. A missing required diagnostic gives ABSTAIN, not a pass, which is the fourth of the ten invariants. See Diagnostics and model checks.

Square-root information term

SqrtInfo stores one dataset's marginal likelihood, with that dataset's nuisances integrated out, as a fixed-size term:

\log L(x) = -\tfrac12 \lVert R x - z \rVert^2 + \text{offset}

Terms from many datasets combine by one QR factorization, and working with R keeps the condition number at the square root of the information matrix's. A term is a likelihood component, not the model evidence. The graph-level evidence for whole-graph exact linear-Gaussian models is an EvidenceTask; see Evidence and model comparison.