Skip to content

Rollforward API

The rollforward runs state-machine projections across every policy in parallel. The public surface is four pieces: a builder for declaring the period-by-period steps, a compile step, a collector for extracting per-state and per-increment expressions, and the compiled model itself with its inspection helpers.

For concept-level material, see Rollforward. For runnable patterns, see gaspatchio_core/tutorials/rollforward-patterns/ in the source tree.

RollforwardBuilder

gaspatchio_core.RollforwardBuilder

Mutable builder that produces an immutable IR on ._build().

compile_rollforward

gaspatchio_core.compile_rollforward(target)

Run the 5-pass chain over a Builder or an IR.

Each pass logs a one-line TRACE record for observability:

[validate]              ok — N transitions
[resolve_state_refs]    ok
[fold_constants]        ok
[assign_capture_slots]  ok — N slots
[lower_polars]          ok — N kwargs

CompiledRollforward

gaspatchio_core.CompiledRollforward dataclass

Frozen artefact carrying the compiled IR and inspection surface.

Returned by :func:compile_rollforward. Carries everything the kernel needs to execute (plugin_kwargs, plugin_args, capture_slots) plus three inspection helpers for governance and audit.

canonical_form()

Return a stable, deterministic dict describing the model structure.

Two compiled rollforwards with the same Op chain (in the same order), same states, same Schedule canonical-form, and same configuration produce equal canonical-form dicts. Column-name aliases inside Op expressions are reduced to str(expr), so renaming a column does not change the canonical form.

explain()

Return a multi-line human-readable summary of the model.

Lists states, points, schedule, transitions in order, and the cross-cutting configuration (lapse, contract boundary, increment tracking). Plain text — fits in audit reports and TRACE logs.

fingerprint()

Return a SHA-256 fingerprint of the canonical form.

Stable across runs and across machines for an unchanged model. Suitable for governance metadata and run logs.

RollforwardCollector

gaspatchio_core.RollforwardCollector

Per-rollforward facade that exposes per-state / per-increment Polars Exprs.

The collector caches a single register_plugin_function result so the Polars optimiser can deduplicate the kernel call across multiple .struct.field(...) accesses within a single with_columns call.

expr_for(state, *, point='eop')

Return a Polars Expr selecting the per-period values for (state, point).

increment_for(label)

Return a Polars Expr selecting the per-period delta for a labelled Op.