Skip to content

Checked model fitting

The model interface uses the program's checked data contract to bind a dataset and select an inference method. This tutorial (i) lets data determine the row count; (ii) inspects the external types and observation roles; and (iii) fits and predicts without constructing a guide or an optimizer.

Declare, bind, and fit

The example below is executable as one Python block. The short fitting budget checks the workflow; it does not establish posterior convergence.

import torch
from quivers.modeling import Model, VariationalMethod

source = """
object Row : FinSet _
object Out : Real 1
program regression(x : Tensor[Real]([Row]), y : Tensor[Real]([Row])) : Row -> Out
    sample b <- Normal(loc=0.0, scale=1.0)
    let mu = b * x
    observe y : Row <- Normal(loc=mu, scale=1.0)
    return b
export regression
"""

model = Model(source)
assert model.schema.observations == ("y",)
print(model.schema.describe())
data = {
    "x": torch.tensor([1.0, 2.0, 3.0]),
    "y": torch.tensor([0.5, 1.0, 1.5]),
}
bound = model.bind(data)
print(bound.schema.describe())
fit = bound.infer(VariationalMethod(num_steps=30, seed=7))
draws = fit.draws(num_samples=10)
replicated = fit.predict(num_samples=10)
assert draws["b"].shape[:2] == (1, 10)
assert replicated["y"].shape[0] == 10
assert torch.isfinite(torch.tensor(fit.losses)).all()

Row becomes three at binding. The parameter y : Tensor[Real]([Row]) declares the response type; observe y gives it the observation role. Prediction thus releases y and retains x. A new binding can change the number of rows when the fitted latent layout remains the same:

new_inputs = {"x": torch.tensor([0.5, 1.5])}
new_predictions = fit.predict(new_inputs, num_samples=10, seed=11)
assert new_predictions["y"].shape == (10, 2)
pointwise = fit.log_likelihood(num_samples=10)
assert pointwise["y"].shape == (1, 10, 3)

The pointwise array retains one likelihood term per response and posterior draw; the first axis is the variational result's single pseudo-chain. Scoring new responses additionally requires their y values. The fitting guide specifies event reductions and the current restriction on marginalized responses.

Report invalid inputs before inference

from quivers.dsl import CompileError

try:
    model.bind({"x": torch.ones(2), "y": torch.ones(3)})
except CompileError:
    pass
else:
    raise AssertionError("conflicting row counts must be refused")

try:
    model.bind({"x": torch.ones(3, dtype=torch.long), "y": data["y"]})
except TypeError:
    pass
else:
    raise AssertionError("integer values do not inhabit Tensor[Real]")

Declarations are optional when uses determine the type. A declaration is needed when uses leave an ambiguous input. Dimensions also need evidence: a shared scalar does not determine the number of participants, and an empty index array does not determine the number of groups. The binding guide specifies exact-shape and index-bound inference, templates, scans, and custom methods.

Choose another method

Replace VariationalMethod(...) with MCMCMethod(sampler=MCMC(...)) to reuse a configured sampler and obtain MCMC summaries. The fitting guide gives the complete call. A custom InferenceMethod[Result] can instead return its own messages, bounds, or certificates. Its result type does not imply that its algorithm is exact or that its certificate has been verified.

The interactive tools guide shows the same symbolic model in the editor, REPL, and Jupyter kernel. The capability audit records the remaining brms and structured-executor requirements. Chapter 1 then opens the fitting components to explain what inference computes.