Model binding and fitting¶
The model interface binds external values using the types and roles checked from QVR, then applies a reusable inference method.
Declare explicit inputs in the runtime telescope of a program header, as in
program regression(x : Tensor[Real]([Row]), y : Tensor[Real]([Row])) : Row -> Out.
Static objects, morphisms, and extents use a preceding bracketed telescope.
Annotations constrain values; observe determines which inputs are responses.
The parameter reference explains
the convention across language constructs.
MCMCMethod, VariationalMethod, and PathfinderMethod return ModelFit.
SMCMethod instead returns the existing SMCResult with its particles,
normalizing-constant estimate, and tempering diagnostics. All four consume the
same checked BoundModel, and their result contracts remain specific to the
inference method. Pathfinder retains independent
approximate draws. MCMCMethod(cores=2) runs the chains in two worker
processes that recompile the model from its source and binding, with the
result of the serial run (parallel chains).
An existing ModelFit exposes fit.evidence(sampler). This applies the same
SMC driver to the retained checked program and data, including a fit initialized
with a variational guide. The guide and retained posterior draws do not enter
the evidence calculation. Observation weights define a powered target whose
normalizing constant need not be an ordinary data probability.
ModelFit.posterior_epred collects native conditional response expectations
with retained chain/draw axes. ModelFit.conditional_effects applies this
collector once to a bounded predictor grid, using the checked nominal row axis
to distinguish row inputs from unrelated fitted tensors. Both reuse the fitted
latent layout and deterministic parameters; neither fits a new posterior.
See source conditional effects
for conditioning, Scan addressing, and finite-moment approximation semantics.
import torch
from quivers.inference import SMC
from quivers.inference.mcmc import MetropolisKernel, RandomWalkProposal
from quivers.modeling import Model, SMCMethod
source = """object One:FinSet 1
object Out:Real 1
program model(y:Real):One->Out
sample mu <- Normal(loc=0.0,scale=1.0)
observe y <- Normal(loc=mu,scale=1.0)
return mu
export model
"""
result = Model(source).fit(
{"y": torch.tensor(0.7)},
method=SMCMethod(sampler=SMC(
MetropolisKernel(RandomWalkProposal(0.5)),
num_particles=16, num_mcmc_steps=1, num_pilot_steps=0, seed=7,
)),
)
assert result.num_particles == 16
assert result.temperatures[0] == 0 and result.temperatures[-1] == 1
model
¶
Compile, bind, and inspect QVR models through checked input metadata.
ModelSchema
didactic-model
¶
ModelSchema(*, entry: ProgramEntry = field(opaque=True, extras=OPAQUE_BY_VALUE))
Bases: ValueModel
The checked input contract of one QVR program.
| PARAMETER | DESCRIPTION |
|---|---|
entry
|
Typed parameters, site roles, plates, and static binders. The entry is immutable and compared by value, without rendering away its types.
TYPE:
|
inputs
property
¶
inputs: tuple[ProgramParameter, ...]
External data and observations, in checked parameter order.
| RETURNS | DESCRIPTION |
|---|---|
tuple[ProgramParameter, ...]
|
Typed external parameters in declaration order. |
observations
property
¶
The names of the values scored by observation steps.
| RETURNS | DESCRIPTION |
|---|---|
tuple[str, ...]
|
Observation names, excluding covariates and index maps. |
types
property
¶
types: dict[str, TypeExpr]
External symbols mapped to their original checked types.
| RETURNS | DESCRIPTION |
|---|---|
dict[str, TypeExpr]
|
The typed external input contract. |
describe
¶
Render the external input contract for display.
| RETURNS | DESCRIPTION |
|---|---|
dict[str, dict[str, str]]
|
Each input's role, readable type, and optional value restriction. |
Source code in src/quivers/modeling/model.py
InferenceMethod
¶
Bases: Protocol
An inference implementation whose result type is chosen by the method.
Implementations may return draws, messages, a MAP certificate, or another result. They must check their own execution and differentiation requirements.
run
¶
run(model: BoundModel) -> Result
Run inference on a bound model.
| PARAMETER | DESCRIPTION |
|---|---|
model
|
Checked program, data, input, and schema.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Result
|
The method's own result type. |
Source code in src/quivers/modeling/model.py
Model
¶
Model(source: str, *, entry: str | None = None, families: FamilyCatalog | None = None)
A reusable QVR source whose finite dimensions specialize at data binding.
| PARAMETER | DESCRIPTION |
|---|---|
source
|
QVR source, optionally declaring objects as
TYPE:
|
entry
|
Program to select. Defaults to the first exported program, or the only program when none is exported.
TYPE:
|
families
|
Immutable native family definitions for this model's compilation.
TYPE:
|
Source code in src/quivers/modeling/model.py
from_file
classmethod
¶
from_file(path: str | Path, *, entry: str | None = None, families: FamilyCatalog | None = None) -> Model
Read a QVR model from a file.
| PARAMETER | DESCRIPTION |
|---|---|
path
|
UTF-8 source file.
TYPE:
|
entry
|
Program to select.
TYPE:
|
families
|
Immutable native family definitions for this compilation.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Model
|
Parsed reusable model. |
Source code in src/quivers/modeling/model.py
fit
¶
fit(data: Mapping[str, object], *, method: InferenceMethod[Result], parameters: Mapping[str, object] | None = None, input: Tensor | None = None, seed: int = 0, sample_prior: PriorMode = 'no', num_prior_samples: int = 100, prior_seed: int = 1, snapshot_policy: SnapshotPolicy = 'clone') -> Result
Bind external data and apply an inference method in one call.
| PARAMETER | DESCRIPTION |
|---|---|
data
|
External values, with roles inferred from QVR.
TYPE:
|
method
|
Inference configuration, including its own random seed and budgets.
TYPE:
|
parameters
|
Static specialization arguments passed to binding.
TYPE:
|
input
|
One-run domain input, if the program reads one.
TYPE:
|
seed
|
Compilation seed, independent of the method's inference seed.
TYPE:
|
sample_prior
|
Ordinary fitting, ordinary fitting plus independent prior draws, or inference with observation likelihoods disabled. Explicit score potentials remain active in prior-only inference.
TYPE:
|
num_prior_samples
|
Positive independent draw budget for mode "yes".
TYPE:
|
prior_seed
|
Isolated prior stream, independent of the inference method.
TYPE:
|
snapshot_policy
|
Refit-data ownership. Clone retains one independent training-data copy; reference explicitly shares later caller mutations.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Result
|
The method's result with its own type and semantics. |
Source code in src/quivers/modeling/model.py
bind
¶
bind(data: Mapping[str, object], *, parameters: Mapping[str, object] | None = None, input: Tensor | None = None, seed: int = 0) -> BoundModel
Infer dimensions, compile, and validate one data binding.
| PARAMETER | DESCRIPTION |
|---|---|
data
|
External data and observations. Roles and types come from QVR.
TYPE:
|
parameters
|
Explicit static arguments. Runtime scalars belong in
TYPE:
|
input
|
Explicit one-run domain input. Required for a real-valued domain.
TYPE:
|
seed
|
Compilation seed; the caller's CPU random state is restored.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
BoundModel
|
Compiled entry and its checked binding. |
| RAISES | DESCRIPTION |
|---|---|
CompileError
|
If sizes cannot be inferred or the source cannot be checked. |
ValueError
|
If input names, shapes, or required values disagree with the schema. |
TypeError
|
If supplied element types disagree with their checked types. |
Source code in src/quivers/modeling/model.py
BoundModel
didactic-model
¶
BoundModel(*, specification: Model = field(opaque=True, extras=OPAQUE_BY_IDENTITY), template_arguments: Mapping[str, object] = field(opaque=True, extras=OPAQUE_BY_IDENTITY), compilation_seed: int, module: Program = field(opaque=True, extras=OPAQUE_BY_IDENTITY), program: MonadicProgram | CheckedProgram = field(opaque=True, extras=OPAQUE_BY_IDENTITY), schema: ModelSchema = field(opaque=True, extras=OPAQUE_BY_VALUE), data: Mapping[str, object] = field(opaque=True, extras=OPAQUE_BY_IDENTITY), input: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY))
Bases: ValueModel
A compiled model with validated external values and one execution input.
| PARAMETER | DESCRIPTION |
|---|---|
specification
|
Original source and entry selection, retained by identity for rebinding.
TYPE:
|
template_arguments
|
Static arguments retained by identity for recompilation.
TYPE:
|
compilation_seed
|
Seed used to initialize deterministic parameters when binding.
TYPE:
|
module
|
Compiled module container, held by identity.
TYPE:
|
program
|
Selected entry, held by identity.
TYPE:
|
schema
|
Checked parameter and site metadata, compared by value.
TYPE:
|
data
|
External values, held by identity to preserve gradients and structured values.
TYPE:
|
input
|
One run's domain input, held by identity.
TYPE:
|
rebind
¶
rebind(data: Mapping[str, object], *, input: Tensor | None = None) -> BoundModel
Bind new data while retaining the fitted parameter interpretation.
| PARAMETER | DESCRIPTION |
|---|---|
data
|
Replacement covariates and optional responses. Inferred dimensions specialize again; explicit cardinalities remain fixed.
TYPE:
|
input
|
One execution input; the original input when omitted.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
BoundModel
|
Independent binding with copied deterministic parameter state. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If the new data change latent site names or shapes. |
Source code in src/quivers/modeling/model.py
459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 | |
infer
¶
infer(method: InferenceMethod[Result], *, sample_prior: PriorMode = 'no', num_prior_samples: int = 100, prior_seed: int = 1, snapshot_policy: SnapshotPolicy = 'clone') -> Result
Apply a method without imposing a posterior-draw result contract.
| PARAMETER | DESCRIPTION |
|---|---|
method
|
Solver responsible for its capability checks and result metadata.
TYPE:
|
sample_prior
|
Fit the posterior, additionally retain independent priors, or disable declared observation and marginalized likelihood scores.
TYPE:
|
num_prior_samples
|
Positive independent prior draw budget for mode "yes".
TYPE:
|
prior_seed
|
Isolated CPU stream for independent prior draws.
TYPE:
|
snapshot_policy
|
Retained refit-data ownership for methods returning ModelFit.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Result
|
The solver's result without conversion. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If the policy is invalid or global score potentials prevent independent prior sampling. |
TypeError
|
If mode "yes" is requested from a solver not returning ModelFit. |
Source code in src/quivers/modeling/model.py
539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 | |
prior_draws
¶
prior_draws(*, num_samples: int = 100, seed: int = 0, method: Literal['ancestral'] | MCMC = 'ancestral') -> PriorDraws | MCMCResult
Draw retained conditional priors, or use explicit factor-conditioned MCMC.
| PARAMETER | DESCRIPTION |
|---|---|
num_samples
|
Positive independent ancestral draw count.
TYPE:
|
seed
|
Isolated CPU random stream.
TYPE:
|
method
|
Independent sampling, or a configured driver for global potentials.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
PriorDraws or MCMCResult
|
Independent constrained draws or genuine factor-conditioned chains. |
Source code in src/quivers/modeling/model.py
sample
¶
Fit using a configured MCMC driver, including its budgets and hooks.
| PARAMETER | DESCRIPTION |
|---|---|
sampler
|
Driver with kernel, chains, seed, adaptation, and optional checkpoint.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ModelFit
|
Bound model and posterior draws. |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If the selected entry cannot use the tensor inference runtime. |
Source code in src/quivers/modeling/model.py
tensor_data
¶
tensor_data() -> dict[str, Tensor]
Adapt external values to the native tensor executor's one-run layout.
Scanned observations acquire a leading run axis through tensor views. The stored binding retains its checked shapes and original objects.
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Tensor]
|
Values for a custom tensor inference method or guide constructor. |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If the entry requires reference execution or an input has no tensor form. |
Source code in src/quivers/modeling/model.py
require_tensor_program
¶
require_tensor_program() -> MonadicProgram
Select the tensor runtime or explain its current capability limit.
| RETURNS | DESCRIPTION |
|---|---|
MonadicProgram
|
Tensor-executable program. |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If only reference execution is available (enhancement #232). |
Source code in src/quivers/modeling/model.py
trace
¶
Trace one run with optional latent-site conditioning.
| PARAMETER | DESCRIPTION |
|---|---|
sites
|
Latent values to condition on; external data come from the binding.
A scanned position can be addressed as
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Trace
|
The execution trace, including differentiable scores. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If conditioning names an external input or an unknown sample site. |
Source code in src/quivers/modeling/model.py
ModelFit
didactic-model
¶
ModelFit(*, model: BoundModel = field(opaque=True, extras=OPAQUE_BY_IDENTITY), posterior: MCMCResult | PriorDraws | Guide = field(opaque=True, extras=OPAQUE_BY_IDENTITY), sample_prior: PriorMode = 'no', prior: PriorDraws | MCMCResult | None = field(default=None, opaque=True, extras=OPAQUE_BY_IDENTITY), losses: tuple[float, ...] = (), refit_recipe: RefitRecipe[Mapping[str, object], InferenceMethod[ModelFit], ModelFit] | None = field(default=None, opaque=True, extras=OPAQUE_BY_IDENTITY))
Bases: ValueModel
A bound model and fitted posterior, held by identity.
| PARAMETER | DESCRIPTION |
|---|---|
model
|
Data, checked schema, and compiled model used by this fit.
TYPE:
|
posterior
|
Genuine MCMC chains, independent prior draws, or a variational guide. Live posterior objects are held by identity.
TYPE:
|
sample_prior
|
Observation-scoring and retained-prior policy used for this fit.
TYPE:
|
prior
|
Retained independent priors or explicitly factor-conditioned chains.
TYPE:
|
losses
|
Optimization losses for a variational fit; empty for MCMC.
TYPE:
|
refit_recipe
|
Live fitting adapter and explicit training-data snapshot. Attached by BoundModel.infer; manually constructed results may omit it.
TYPE:
|
samples
property
¶
samples: dict[str, Tensor]
Constrained draws with separate chain and draw axes.
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Tensor]
|
Recorded MCMC chains by latent site. |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If the posterior is variational and has no recorded chains. |
update
¶
update(data: Mapping[str, object] | None = None, *, method: InferenceMethod[ModelFit] | None = None, seed: int | None = None) -> ModelFit
Refit retained or replacement data without changing this posterior.
| PARAMETER | DESCRIPTION |
|---|---|
data
|
Replacement training data, or the recipe's retained snapshot.
TYPE:
|
method
|
Explicit inference override, otherwise the retained method and seed.
TYPE:
|
seed
|
Compilation seed override. Inference seeds belong to the method.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ModelFit
|
Fresh fitting result with the same source, entry, static arguments, domain input, and prior-scoring policy. New latent dimensions are permitted in a refit; prediction rebind remains stricter. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If this manually constructed result has no retained recipe. |
Source code in src/quivers/modeling/model.py
refit_callback
¶
refit_callback(*, method_factory: Callable[[InferenceMethod[ModelFit], int], InferenceMethod[ModelFit]], row_axis: str | None = None, partition: Callable[[Mapping[str, object], tuple[int, ...]], Mapping[str, object]] | None = None, num_samples: int | None = None) -> Callable[[FoldSplit], FoldPrediction]
Build an adapter for the shared explicit cross-validation runner.
| PARAMETER | DESCRIPTION |
|---|---|
method_factory
|
Explicit fold-specific inference configuration. The seed comes from FoldSplit; return the method unchanged to retain its seed.
TYPE:
|
row_axis
|
Checked leading nominal axis to partition. Unrelated equal-size inputs remain constants. Supply this or an explicit partitioner.
TYPE:
|
partition
|
Custom row selection when a single leading axis is insufficient.
TYPE:
|
num_samples
|
Per-chain draw budget passed to existing raw held-out scoring.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Callable[[FoldSplit], FoldPrediction]
|
Fresh fitting and raw held-out scoring, preserving actual results. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If the recipe or a unique partition policy is missing. |
Source code in src/quivers/modeling/model.py
posterior_epred
¶
posterior_epred(data: Mapping[str, object] | None = None, *, input: Tensor | None = None, sites: Sequence[str] | None = None, num_samples: int | None = None, mc_samples: int | None = None, seed: int = 0) -> dict[str, Tensor]
Read native conditional response expectations at retained joint draws.
| PARAMETER | DESCRIPTION |
|---|---|
data
|
New checked predictors and optional conditioning responses; None retains the original fitted binding.
TYPE:
|
input
|
One-run execution input; the fitted input by default.
TYPE:
|
sites
|
Response names, or None for all declared observations. Exact Scan occurrence labels are supported by the generic collector.
TYPE:
|
num_samples
|
Leading draws per recorded chain, or fresh variational draw count.
TYPE:
|
mc_samples
|
Explicit approximation budget for certified finite response means without an analytic expression.
TYPE:
|
seed
|
Isolated posterior and response seed; caller RNG is restored.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Tensor]
|
Conditional means preserving chain/draw/checked observation axes. Categorical and ordinal responses append a probability axis. Upstream observed and lexical values retain their conditioning; this is not an analytic joint integration over other responses. |
| RAISES | DESCRIPTION |
|---|---|
(ValueError, TypeError)
|
If binding, latent geometry, selected sites, or response moments violate the existing checked prediction contract. |
Source code in src/quivers/modeling/model.py
conditional_effects
¶
conditional_effects(grid: PredictionGrid, *, site: str | None = None, num_samples: int | None = None, mc_samples: int | None = None, seed: int = 0) -> ConditionalEffects
Evaluate expected source responses on one checked predictor grid.
| PARAMETER | DESCRIPTION |
|---|---|
grid
|
Explicit row-axis effect and conditioning coordinates.
TYPE:
|
site
|
Declared observation; may be omitted when exactly one exists.
TYPE:
|
num_samples
|
Leading draws per recorded chain or fresh variational draw count.
TYPE:
|
mc_samples
|
Explicit finite-moment approximation budget when required.
TYPE:
|
seed
|
Isolated posterior and response random stream.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ConditionalEffects
|
Joint expected responses with explicit conditional or empirical reduction. Source grouping inputs remain checked numeric maps; the fitted latent-layout guard prevents accidental new identities. |
| RAISES | DESCRIPTION |
|---|---|
(ValueError, TypeError)
|
If observation selection, row-axis identity, conditioning data, latent layout, or response moments are invalid. |
Source code in src/quivers/modeling/model.py
evidence
¶
Estimate the fitted target's normalizing constant with existing SMC.
| PARAMETER | DESCRIPTION |
|---|---|
sampler
|
Configured likelihood-tempered driver, including its particle budget, rejuvenation kernel, and random stream.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SMCResult
|
Independent particles and the estimated log normalizing constant. This is ordinary data evidence only for a normalized prior and likelihood. Observation weights instead define a powered target. |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If the retained program has no tensor executor. |
ValueError
|
If SMC cannot partition the target, normalize its prior, or use an exact likelihood without observation subsampling. |
RuntimeError
|
If no temperature step meets the driver's ESS requirement. |
Notes
The retained program, input, and data are reused. The fitted posterior is neither sampled nor modified; the driver's own guards and random stream govern this separate computation.
Source code in src/quivers/modeling/model.py
draws
¶
draws(*, num_samples: int | None = None, seed: int | None = None) -> dict[str, Tensor]
Draw a variational posterior, or return recorded MCMC chains.
| PARAMETER | DESCRIPTION |
|---|---|
num_samples
|
Maximum draws per recorded chain, or fresh guide draws. Omission retains all MCMC draws or samples 100 guide draws.
TYPE:
|
seed
|
Optional CPU seed for guide sampling, restored on exit.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Tensor]
|
Draws with leading chain and draw axes. Variational samples have one pseudo-chain; it cannot diagnose MCMC convergence. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If num_samples is not positive. |
Source code in src/quivers/modeling/model.py
prior_view
¶
prior_view(*, num_samples: int | None = None, seed: int = 0, method: Literal['ancestral'] | MCMC = 'ancestral') -> ModelFit
Reuse prediction and analysis with retained or newly sampled prior draws.
| PARAMETER | DESCRIPTION |
|---|---|
num_samples
|
Fresh independent count, or None to reuse retained priors. Without retained draws, None generates 100 independent draws.
TYPE:
|
seed
|
Isolated CPU stream for fresh ancestral samples.
TYPE:
|
method
|
Conditional sampling or explicit factor-conditioned inference.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ModelFit
|
A view sharing the bound model and its original priors. |
Source code in src/quivers/modeling/model.py
predict
¶
predict(data: Mapping[str, object] | None = None, *, input: Tensor | None = None, num_samples: int | None = None, seed: int | None = None) -> dict[str, Tensor]
Sample responses at the fitted data or a compatible new binding.
| PARAMETER | DESCRIPTION |
|---|---|
data
|
New covariates and optional responses; fitted data when omitted. Observation values are released before predictive sampling.
TYPE:
|
input
|
Execution input for new data; the fitted input when omitted.
TYPE:
|
num_samples
|
Maximum posterior draws; all available MCMC draws when omitted.
TYPE:
|
seed
|
Optional CPU random seed, restored on exit.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Tensor]
|
Predictive samples by site at the requested data layout. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If new data change the latent parameter layout. |
Source code in src/quivers/modeling/model.py
1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 | |
log_likelihood
¶
log_likelihood(data: Mapping[str, object] | None = None, *, num_samples: int | None = None, seed: int | None = None) -> dict[str, Tensor]
Evaluate observation densities separately at posterior draws.
| PARAMETER | DESCRIPTION |
|---|---|
data
|
Replacement covariates and observed responses; fitted data by default.
TYPE:
|
num_samples
|
Maximum draws per MCMC chain; 100 draws for a guide when omitted.
TYPE:
|
seed
|
Optional seed for variational draws and participating native streams, restored on exit.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Tensor]
|
Raw observation log densities with leading chain and draw axes. Event dimensions are reduced; observation plate axes are retained. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If responses are missing or the draw count is not positive. |
TypeError
|
If an observation is hidden by marginalization and requires a marginal-likelihood observer rather than a conditional site score. |
Source code in src/quivers/modeling/model.py
analysis
¶
analysis(*, num_samples: int | None = None, seed: int = 0) -> PosteriorAnalysis
Prepare reusable tensor posterior analysis on the fitted data.
| PARAMETER | DESCRIPTION |
|---|---|
num_samples
|
Maximum recorded draws per chain, or fresh variational draws.
TYPE:
|
seed
|
Guide sampling seed; participating caller RNG streams are preserved.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
PosteriorAnalysis
|
Posterior draws, raw observation scores, observed responses, and recorded sampler statistics on their original axes. |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If a hidden observation needs a marginal-likelihood observer. |
ValueError
|
If fitted response data are missing or the draw count is invalid. |
Source code in src/quivers/modeling/model.py
summary
¶
summary() -> dict[str, ConvergenceSummary]
Summarize MCMC chains with the package's convergence estimators.
| RETURNS | DESCRIPTION |
|---|---|
dict[str, ConvergenceSummary]
|
Means, quantiles, R-hat, ESS, and Monte Carlo errors by site. |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If this is a variational fit, which has no MCMC chains. |
Source code in src/quivers/modeling/model.py
methods
¶
Reusable inference components for bound QVR models.
SourceChainWorker
didactic-model
¶
SourceChainWorker(*, source: str, entry: str, families: FamilyCatalog | None = field(default=None, opaque=True, extras=OPAQUE_BY_IDENTITY), data: Mapping[str, object] = field(opaque=True, extras=OPAQUE_BY_IDENTITY), parameters: Mapping[str, object] = field(opaque=True, extras=OPAQUE_BY_IDENTITY), input: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), seed: int, sampler: MCMC = field(opaque=True, extras=OPAQUE_BY_IDENTITY))
Bases: ValueModel
Rebuild a bound QVR model in a worker process and run some chains.
The worker recompiles the source with the binding's data, static arguments, input, and compilation seed, so it builds the program the parent sampled, then runs its assigned chains with a copy of the parent's driver.
| PARAMETER | DESCRIPTION |
|---|---|
source
|
QVR source text.
TYPE:
|
entry
|
Selected program.
TYPE:
|
families
|
Native family definitions of the compilation.
TYPE:
|
data
|
External values of the binding.
TYPE:
|
parameters
|
Static arguments of the binding.
TYPE:
|
input
|
One-run input.
TYPE:
|
seed
|
Compilation seed.
TYPE:
|
sampler
|
The parent's driver.
TYPE:
|
__call__
¶
__call__(chains: tuple[int, ...]) -> ChainStates
Recompile the binding and run the assigned chains.
| PARAMETER | DESCRIPTION |
|---|---|
chains
|
Chain indices.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ChainStates
|
Their records. |
Source code in src/quivers/modeling/methods.py
MCMCMethod
didactic-model
¶
MCMCMethod(*, sampler: MCMC = field(default_factory=lambda: MCMC(NUTSKernel(), num_warmup=500, num_samples=1000, seed=0), opaque=True, extras=OPAQUE_BY_IDENTITY), cores: int = 1)
Bases: ValueModel
Fit with a reusable MCMC driver, defaulting to seeded NUTS.
| PARAMETER | DESCRIPTION |
|---|---|
sampler
|
Driver carrying kernel, chains, warmup, seed, budgets, and callbacks. Held by identity. The default runs four NUTS chains, with 500 warmup transitions and 1000 retained draws per chain, seeded with zero.
TYPE:
|
cores
|
Worker processes for the chains (brms
TYPE:
|
run
¶
run(model: BoundModel) -> ModelFit
Sample the bound model using this driver's configuration.
| PARAMETER | DESCRIPTION |
|---|---|
model
|
Validated data binding.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ModelFit
|
Posterior draws and the original data binding. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If |
Source code in src/quivers/modeling/methods.py
SMCMethod
didactic-model
¶
SMCMethod(*, sampler: SMC = field(default_factory=lambda: SMC(NUTSKernel(), seed=0), opaque=True, extras=OPAQUE_BY_IDENTITY))
Bases: ValueModel
Apply likelihood-tempered SMC to a checked data binding.
| PARAMETER | DESCRIPTION |
|---|---|
sampler
|
Existing driver with explicit particle, rejuvenation, adaptation, and random-stream settings, held by identity. The default uses NUTS rejuvenation, 1024 particles, and seed zero.
TYPE:
|
Notes
The result retains the driver's particles, temperature ladder, weight ESS, acceptance, evaluation count, and estimated log normalizing constant. Particles are not recorded MCMC chains. A data-evidence interpretation requires the declared prior and likelihood to define that comparison.
run
¶
run(model: BoundModel) -> SMCResult
Run the existing sampler without converting its result.
| PARAMETER | DESCRIPTION |
|---|---|
model
|
Checked program, validated data, and one-run input.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SMCResult
|
Equally weighted particles and the driver's evidence diagnostics. |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If the entry has no tensor executor. |
ValueError
|
If the driver cannot partition the target, normalize its prior, or use an exact likelihood without observation subsampling. |
Source code in src/quivers/modeling/methods.py
PathfinderMethod
didactic-model
¶
PathfinderMethod(*, pathfinder: Pathfinder = field(default_factory=Pathfinder, opaque=True, extras=OPAQUE_BY_IDENTITY))
Bases: ValueModel
Fit with single- or multi-path Pathfinder variational inference.
| PARAMETER | DESCRIPTION |
|---|---|
pathfinder
|
Driver carrying the path count, draw counts, L-BFGS settings, initialization, and seed. The default runs CmdStan's defaults: four paths of 1000 draws resampled to 1000 draws, history size 5, and 25 draws per ELBO estimate, seeded with zero. Held by identity.
TYPE:
|
run
¶
run(model: BoundModel) -> ModelFit
Run Pathfinder on the bound model's unconstrained log joint.
| PARAMETER | DESCRIPTION |
|---|---|
model
|
Validated data binding.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ModelFit
|
Bound model and |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If the entry has no tensor executor. |
ValueError
|
If every path fails or an initial point is invalid. |
Source code in src/quivers/modeling/methods.py
VariationalMethod
didactic-model
¶
VariationalMethod(*, num_steps: int = 1000, learning_rate: float = 0.01, seed: int = 0, guide_factory: Callable[[BoundModel], Guide] | None = field(default=None, opaque=True, extras=OPAQUE_BY_IDENTITY), objective: Objective = field(default_factory=ELBO, opaque=True, extras=OPAQUE_BY_IDENTITY), optimizer_factory: Callable[[Iterable[Tensor]], Optimizer] | None = field(default=None, opaque=True, extras=OPAQUE_BY_IDENTITY), callback: Callable[[int, float], None] | None = field(default=None, opaque=True, extras=OPAQUE_BY_IDENTITY))
Bases: ValueModel
Optimize a guide and model using a chosen objective and optimizer.
| PARAMETER | DESCRIPTION |
|---|---|
num_steps
|
Nonnegative optimization step budget; zero retains the initialized guide.
TYPE:
|
learning_rate
|
Positive Adam learning rate, used when no optimizer factory is given.
TYPE:
|
seed
|
CPU random seed for guide construction and training; restored on exit.
TYPE:
|
guide_factory
|
Build a fresh guide for each fit. The default is a traced AutoNormalGuide, which includes every position of a scan. Held by identity.
TYPE:
|
objective
|
Variational objective, held by identity; ELBO by default.
TYPE:
|
optimizer_factory
|
Optional optimizer constructor, held by identity. Receives unique guide and model parameters so shared modules are optimized once.
TYPE:
|
callback
|
Called after each step with its zero-based index and loss. Held by identity.
TYPE:
|
run
¶
run(model: BoundModel) -> ModelFit
Fit one variational posterior and retain its loss history.
| PARAMETER | DESCRIPTION |
|---|---|
model
|
Validated model and data.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ModelFit
|
Bound model, guide, and losses. A guide's draws are approximate; optimization does not establish posterior convergence. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If a budget or rate is invalid, or an objective returns a nonfinite loss. |
Source code in src/quivers/modeling/methods.py
Retained fitting recipes¶
ModelFit.update runs a fresh fit through its retained RefitRecipe, with
explicit data ownership and inference overrides. Its fold adapter delegates to
the shared cross-validation runner. See updating and refitting
for nominal row axes, data snapshots, and method seeds.
refit
¶
Retained fitting recipes and adapters for explicit held-out partitions.
SnapshotPolicy
¶
Retain an independent data snapshot or explicitly share the caller's data.
RefitRecipe
dataclass
¶
RefitRecipe(data: Data, method: Method, operation: Callable[[Data, Method, int | None], Result], *, snapshot_policy: SnapshotPolicy = 'clone', snapshot: Callable[[Data], Data] | None = None, provenance: Mapping[str, str | int] | None = None)
An identity-held fitting operation with explicit data ownership.
This is live process state, not a portable model format. A recipe runs the supplied fitter anew; it never resumes or mutates a fitted posterior.
| PARAMETER | DESCRIPTION |
|---|---|
data
|
Original training data. Clone mode retains one independent copy, separate from posterior draws, and returns fresh copies to callers.
TYPE:
|
method
|
Retained inference configuration, held by identity. Its own random seed remains unchanged unless the caller supplies another method.
TYPE:
|
operation
|
Existing fitting adapter. The optional seed overrides preparation; its interpretation is part of the adapter's declared contract.
TYPE:
|
snapshot_policy
|
Clone by default. Reference mode explicitly observes later mutations of the supplied data, and is useful when another owner freezes them.
TYPE:
|
snapshot
|
Optional backend-specific data copier. The default copies containers and arrays, detaching and cloning tensor data without autograd graphs.
TYPE:
|
provenance
|
Read-only descriptive reconstruction metadata, such as source/entry and compilation seed. Callables and modules remain live objects.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If the snapshot policy is unknown. |
Source code in src/quivers/modeling/refit.py
data
property
¶
Return isolated training data, or the explicitly shared reference.
| RETURNS | DESCRIPTION |
|---|---|
Data
|
A fresh snapshot in clone mode, the original object otherwise. |
run
¶
Fit retained or replacement data through the original fitting adapter.
| PARAMETER | DESCRIPTION |
|---|---|
data
|
Replacement training data, or the retained data snapshot.
TYPE:
|
method
|
Explicit inference override; otherwise retain the original method.
TYPE:
|
seed
|
Optional preparation override; None preserves the recipe's policy.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Result
|
A fresh result with the fitter's original result semantics. |
Source code in src/quivers/modeling/refit.py
__reduce_ex__
¶
Refuse to serialize live fitting operations and inference objects.
| PARAMETER | DESCRIPTION |
|---|---|
protocol
|
Requested pickle protocol.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
Recipes require a separate durable reconstruction format. |
Source code in src/quivers/modeling/refit.py
refit_callback
¶
refit_callback(recipe: RefitRecipe[Data, Method, Result], partition: Callable[[Data, tuple[int, ...]], Data], score: Callable[[Result, Data, int], Mapping[str, Tensor]], *, method_factory: Callable[[Method, int], Method]) -> Callable[[FoldSplit], FoldPrediction]
Adapt one recipe to the existing cross-validation runner.
| PARAMETER | DESCRIPTION |
|---|---|
recipe
|
Retained fitting adapter and original training data.
TYPE:
|
partition
|
Nonmutating row selection producing fresh partitions, preserving non-row constants and identities. The adapter snapshots original data once, rather than copying the full training data for every fold.
TYPE:
|
score
|
Existing raw held-out likelihood accessor. Its tensors retain joint chain/draw/test-row axes; weights are not predictive replications.
TYPE:
|
method_factory
|
Required explicit inference seed/configuration policy for each fold. Returning the original method intentionally retains its own seed.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Callable[[FoldSplit], FoldPrediction]
|
A callback for cross_validate, with actual fitted results retained. Preprocessing and inference stay in the original fitting operation. |
Source code in src/quivers/modeling/refit.py
Durable fitted artifacts¶
save_fit records a source ModelFit or formula BayesianFit as a versioned
JSON specification and safe tensor checkpoint. load_fit rebuilds the checked
program through the original preparation path, restores its
module and posterior state, and rebuilds the retained fitting recipe. It does
not optimize a model or draw replacement posterior values. For a scanned guide,
strict conditioned replay recovers every reached latent address from saved
values; a missing value is an error.
from pathlib import Path
from tempfile import TemporaryDirectory
import torch
from quivers.modeling import Model, VariationalMethod, load_fit, save_fit
artifact_source = """object Row:FinSet _
program regression(y:Tensor[Real]([Row])):Row->Row
sample mu <- Normal(loc=0.0,scale=1.0)
observe y:Row <- Normal(loc=mu,scale=1.0)
return mu
export regression
"""
artifact_fit = Model(artifact_source).fit(
{"y": torch.tensor([-0.5, 0.25, 1.0])},
method=VariationalMethod(num_steps=0, seed=7),
)
with TemporaryDirectory() as artifact_directory:
artifact_path = Path(artifact_directory) / "regression.qvrfit"
save_fit(artifact_fit, artifact_path)
restored_fit = load_fit(artifact_path)
for name, value in artifact_fit.posterior.state_dict().items():
assert torch.equal(value, restored_fit.posterior.state_dict()[name])
The checkpoint retains static arguments, typed data, compilation and method
seeds, parameter and buffer dtypes, tied parameters, module modes, prior policy,
and recorded chain statistics. Loaded recipes reuse update and the existing
fold adapter. Saving captures values at write time. A loaded reference-owned
source recipe shares the loaded binding's values. A cloned recipe retains an
independent training snapshot. Neither shares memory with the original process.
Formula artifacts rebuild transforms, contrasts, category labels, nonlinear
designs, group layouts, threshold constraints, and retained spline knots from
one frozen preparation snapshot. They restore trained neural state separately
from the original predictor state retained for future refits. Loading neither
executes the predictor nor calls fit. The artifact stores numeric, Boolean, string, or categorical dataframe
columns with their dtypes, levels, order, and row index; live
formulae evaluators are rebuilt rather than serialized.
import pandas as pd
from pathlib import Path
from tempfile import TemporaryDirectory
import torch
from quivers.formulas import fit
from quivers.modeling import load_fit, save_fit
formula_fit = fit(
"y ~ center(x)",
data=pd.DataFrame({"y": [.2, .4, -.1], "x": [-1., 0., 2.]}),
method="svi", num_steps=0, seed=7,
)
new_rows = pd.DataFrame({"x": [.5, 3.]})
with TemporaryDirectory() as formula_directory:
formula_path = Path(formula_directory) / "regression.qvrfit"
save_fit(formula_fit, formula_path)
restored_formula = load_fit(formula_path)
assert torch.equal(
formula_fit.posterior_linpred(new_data=new_rows, num_samples=4, seed=11),
restored_formula.posterior_linpred(new_data=new_rows, num_samples=4, seed=11),
)
Clone-owned formula recipes share their existing training snapshot internally
with the reconstruction plan. Reference-owned recipes retain one separate
frozen training snapshot, since later caller mutations may change a future
update without changing the fitted prediction law. This costs one retained
data snapshot per fit, independent of posterior draw count.
The default Normal guide, recorded MCMC results, and retained prior draws have
built-in contracts. Custom guides and external Python modules require an
explicit named ArtifactFactory at both write and read time. Its decoder
receives an ArtifactContext when reconstructing a guide. Factories are trusted
caller code and must reconstruct without fitting or sampling. An artifact never
chooses an import path or falls back to arbitrary object serialization.
Custom family catalogs use the same explicit factory registration. Their
checked semantic definitions are saved through the QIEC wire codec and must
match the reconstructed catalog exactly. The factory key should identify a
stable, versioned implementation; equality of semantic metadata does not prove
that an external implementation computes the declared law.
Analysis exports retain posterior tensors and diagnostics. A fitted artifact additionally retains the checked model needed for prediction and refitting. Unsupported artifact versions, missing factories, changed latent geometry, and failed integrity checks are refused before a fit is returned.
artifact
¶
Durable fitted models reconstructed from checked specifications and tensor state.
Artifacts contain no live program, dataframe evaluator, or executable pickle. Loading rebuilds checked source or formula preparation and restores its state; it never fits a model or draws a replacement posterior. Registered factories are explicit caller-provided reconstruction code, not imports selected by the file.
ArtifactContext
dataclass
¶
ArtifactContext(program: MonadicProgram, input: Tensor, observations: Mapping[str, Tensor])
Checked execution context supplied to an explicit reconstruction factory.
| PARAMETER | DESCRIPTION |
|---|---|
program
|
Recompiled model with restored deterministic parameter state.
TYPE:
|
input
|
Original one-run input.
TYPE:
|
observations
|
Original checked host data and response bindings.
TYPE:
|
ArtifactFactory
dataclass
¶
ArtifactFactory(value_type: type, encode: Callable[[object], object], decode: Callable[[object, ArtifactContext | None], object])
Explicit portable configuration for an external Python class.
| PARAMETER | DESCRIPTION |
|---|---|
value_type
|
Exact class accepted by this factory; subclasses require registration.
TYPE:
|
encode
|
Extract declarative configuration using supported artifact values.
TYPE:
|
decode
|
Reconstruct the class from configuration. Guide factories receive the checked model context; ordinary option factories receive None. Factories must not fit, optimize, or sample. Module tensor state is stored separately.
TYPE:
|
save_fit
¶
save_fit(fitted: ModelFit | BayesianFit | MultivariateFit, path: str | Path, *, factories: Mapping[str, ArtifactFactory] | None = None) -> None
Atomically save a fitted model using JSON and safe tensor payloads.
| PARAMETER | DESCRIPTION |
|---|---|
fitted
|
Original checked model, posterior, deterministic module state, and recipe.
TYPE:
|
path
|
Destination checkpoint. An existing file is replaced only after success.
TYPE:
|
factories
|
Explicit contracts for external modules, custom guides, or method objects. No arbitrary Python object or import path is serialized.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
(TypeError, ValueError)
|
If the fit or one of its configurations has no portable contract. |
Source code in src/quivers/modeling/artifact.py
load_fit
¶
load_fit(path: str | Path, *, factories: Mapping[str, ArtifactFactory] | None = None, map_location: str | device = 'cpu') -> ModelFit | BayesianFit | MultivariateFit
Reconstruct a fit without optimization or replacement posterior draws.
| PARAMETER | DESCRIPTION |
|---|---|
path
|
Fitted artifact produced by save_fit.
TYPE:
|
factories
|
Explicit trusted reconstructors required by the artifact.
TYPE:
|
map_location
|
Tensor destination, passed to torch.load with weights_only=True.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ModelFit or BayesianFit or MultivariateFit
|
Independent checked binding, posterior, and reconstructed live recipe. Loading a reference-owned recipe shares its newly loaded data, not the original process's memory. Saving always captures values at write time. |
| RAISES | DESCRIPTION |
|---|---|
(ValueError, TypeError, RuntimeError)
|
If the format, tensor integrity, checked source, or factory contract fails. |
Source code in src/quivers/modeling/artifact.py
ArtifactContext
dataclass
¶
ArtifactContext(program: MonadicProgram, input: Tensor, observations: Mapping[str, Tensor])
Checked execution context supplied to an explicit reconstruction factory.
| PARAMETER | DESCRIPTION |
|---|---|
program
|
Recompiled model with restored deterministic parameter state.
TYPE:
|
input
|
Original one-run input.
TYPE:
|
observations
|
Original checked host data and response bindings.
TYPE:
|
ArtifactFactory
dataclass
¶
ArtifactFactory(value_type: type, encode: Callable[[object], object], decode: Callable[[object, ArtifactContext | None], object])
Explicit portable configuration for an external Python class.
| PARAMETER | DESCRIPTION |
|---|---|
value_type
|
Exact class accepted by this factory; subclasses require registration.
TYPE:
|
encode
|
Extract declarative configuration using supported artifact values.
TYPE:
|
decode
|
Reconstruct the class from configuration. Guide factories receive the checked model context; ordinary option factories receive None. Factories must not fit, optimize, or sample. Module tensor state is stored separately.
TYPE:
|