Backends¶
The inference engine is swappable behind the InferenceBackend protocol. KalmanBackend is the default. The Agent runs it per step, and the gain and covariance are recomputed from each belief. KalmanBackend(model, steady_state=True) freezes them at construction instead, for a fixed-noise, time-invariant model read every step, and reaches an agent through Agent.from_backend. On a fixed-noise model the per-step filter is the exact Kalman filter. Under a state-dependent R(x) or Q(x) it reads the noise at the predicted mean, a first-order plug-in. RxInferBackend is imported from cpomdp.backends.rxinfer and needs the optional rxinfer extra. It re-derives the fixed-noise answers through Julia as an independent correctness oracle 1, and it refuses a model with R(x) or Q(x).
InferenceBackend ¶
Bases: Protocol
A swappable inference engine for a LinearGaussianModel.
A backend is built from a model. Expensive work that does not depend on the
data happens at construction (ADR-002), which keeps the per-step
infer_states cheap. Each call advances the belief one
recursive filter step: the current belief goes in as the prior and the
updated belief comes back as the posterior.
A backend must honour the model's observation_model and
dynamics_noise_model or refuse the model. Reading only the plain
observation_noise and dynamics_noise would filter a state-dependent model
against constants. KalmanBackend honours both, and
RxInferBackend refuses a model whose noise depends on the state.
The Protocol is structural: any class with a matching infer_states (and the
model it was built from) is a backend, with no shared base class. This is the
abstraction wall. The Kalman filter and the RxInfer oracle are interchangeable
behind it, and neither's implementation (JAX, juliacall, …) leaks into this
signature.
The protocol does not require infer_states to trace. Of the shipped backends,
KalmanBackend and
CouplingGraphBackend trace under jit,
vmap, grad and lax.scan. RxInferBackend calls Julia and does not.
The backends page lists every public name with how it behaves under a transform.
model
property
¶
The model whose sizes, prior, sensor and control this backend reads.
The Agent takes its own model from here. A flat backend
filters this model exactly. A graph backend's model leaves out its couplings,
so KalmanBackend(backend.model) need not reproduce infer_states, and the
flat consumers refuse a coupled one. A plain attribute satisfies this as well
as a read-only property.
infer_states ¶
Advance the belief by one filter step: prior in, posterior out.
Given the current belief (prior) and a new observation (plus the
action just taken, if the model has a control matrix), return the
updated belief.
Source code in src/cpomdp/backends/base.py
KalmanBackend ¶
KalmanBackend(
model: LinearGaussianModel,
*,
steady_state: bool = False,
tol: float = 1e-12,
max_iter: int = 1000,
)
Kalman-filter inference for a LinearGaussianModel, exact under fixed noise.
Implements the InferenceBackend protocol: constructed from a model,
then advances a belief one step at a time (prior in, posterior out) via
the standard predict/update recursion.
Under fixed noise this is the exact Kalman filter. Under a state-dependent
R(x) or Q(x) it reads the noise at the predicted mean and filters with
that value. That is a first-order plug-in, and its posterior is approximate.
Two modes:
- Per-step (default): recomputes the Kalman gain and covariance every step from the incoming belief, transient included. On a fixed-noise model this is the analytic oracle the rest of the toolbox is validated against.
- Steady-state (
steady_state=True): solves the covariance recursion once at construction to a fixed point, then reuses the frozen gain and covariance every step. No covariance maths runs per step. It needs fixed noise, a time-invariant model and a reading every step. It reports the converged covariance from the first step on, whatever the prior's.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
LinearGaussianModel
|
The linear-Gaussian generative model to filter under. |
required |
steady_state
|
bool
|
If True, precompute and freeze the steady-state gain. |
False
|
tol
|
float
|
Convergence tolerance for the steady-state fixed point (absolute, on successive covariances). |
1e-12
|
max_iter
|
int
|
Cap on steady-state iterations before giving up. |
1000
|
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
ValueError
|
If |
RuntimeError
|
If the steady-state recursion does not converge within
|
Source code in src/cpomdp/backends/kalman.py
model
property
¶
The model this backend filters under, fixed at construction.
steady_state
property
¶
Whether the gain was frozen at construction, fixed with it.
infer_states ¶
Advance the belief by one filter step.
Runs one predict/update cycle: step the prior through the dynamics
(applying action if the model has a control matrix), then correct the
prediction toward observation using the Kalman gain. In steady-state
mode the gain and covariance are the frozen fixed-point values; otherwise
they are recomputed from prior.cov on this step.
The numeric work runs in two jit-compiled kernels. The method itself is
pure, so it traces under jit, vmap, grad and lax.scan. Its
input checks read only shapes, which a trace knows.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
observation
|
ArrayLike
|
The latest sensor reading, shape |
required |
prior
|
Belief
|
The current belief, treated as this step's previous posterior. Never mutated. |
required |
action
|
ArrayLike | None
|
The action just taken, shape |
None
|
Returns:
| Type | Description |
|---|---|
Belief
|
The posterior belief — a new |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Source code in src/cpomdp/backends/kalman.py
155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 | |
RxInferBackend ¶
Linear-Gaussian filtering via RxInfer.jl, the oracle backend.
Satisfies the InferenceBackend protocol: built from a model, advances a
belief one step at a time. On a fixed-noise model it gives
KalmanBackend's answers through separate machinery.
It exists for correctness, so it has no steady-state mode. The first instance
built in a process loads the Julia runtime, and later ones reuse it. The first
ever built in an environment also has juliapkg install Julia and RxInfer there,
which needs network access and can take minutes. The README's install section
says where that environment lives and how to provision it ahead of time.
Fixed noise only. The Julia model takes one Q and one R, so a model
carrying a state-dependent R(x) or Q(x) raises ValueError here, before
Julia starts. Filtering it on the plain fields would hold constant what the model
varies.
Source code in src/cpomdp/backends/rxinfer.py
model
property
¶
The model this backend filters under, fixed at construction.
infer_states ¶
Advance the belief one filter step: prior in, posterior out.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
observation
|
ArrayLike
|
Latest sensor reading, shape |
required |
prior
|
Belief
|
Current belief; never mutated. |
required |
action
|
ArrayLike | None
|
Action just taken, shape |
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Source code in src/cpomdp/backends/rxinfer.py
CouplingGraphBackend filters a CouplingGraph whose nodes each carry their own dynamics. It reads like a flat backend. Its model holds the stacked sensor as observation_matrix and the joint width as n_states. stack_observations turns readings keyed by node into the vector infer_states takes, and marginal reads one node back out of the joint belief. A state-dependent R(x) on a coupled node cannot be flattened to a fixed linear-Gaussian model, and asking it to raises IncompatibleLinearizationError.
In plain terms
Some systems are a web of parts that run at their own pace and push on one another.
A cell's signalling chain is one. CouplingGraphBackend keeps a single belief over
every part at once, and each step updates all of it from whichever parts were
measured. A part nobody measures still grows more certain when a part it pushes on
is measured.
One convention to know. The backend takes each step's readings as one vector, the
measured parts in ascending node order. Hand stack_observations a dictionary from
node to reading and it builds that vector, so the order never has to be typed by
hand.
partition trades accuracy for speed. Grouping the parts tells the filter which
links between groups it may forget from one step to the next. The default keeps one
group and forgets nothing. severed_mass reports how much a grouping forgets.
CouplingGraphBackend ¶
CouplingGraphBackend(
graph: CouplingGraph,
transitions: Sequence[GaussianTransition],
*,
prior: Belief,
control_matrix: ArrayLike | None = None,
partition: Sequence[Sequence[int]] | None = None,
)
FFG message-passing inference on a branching linear-Gaussian tree.
Implements the InferenceBackend protocol for a
CouplingGraph whose nodes each carry their own temporal
dynamics. Constructed once from the graph and the per-node transitions, then
advances a joint belief over every node one step at a time (prior in, posterior
out). Read a single node back with marginal.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
graph
|
CouplingGraph
|
the rooted tree — the structural couplings (the within-slice drive
|
required |
transitions
|
Sequence[GaussianTransition]
|
one |
required |
prior
|
Belief
|
the belief over the joint state before any reading, a mean of length
|
required |
control_matrix
|
ArrayLike | None
|
B, shape |
None
|
partition
|
Sequence[Sequence[int]] | None
|
clusters of node indices that together hold every node once. The
filter carries the correlation within a cluster to the next step and
drops the correlation between clusters (ADR-016). |
None
|
An observation passed to infer_states is the readings of the observed nodes
stacked in ascending node-index order, each node contributing its sensor's rows.
stack_observations builds it from readings keyed by node.
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
ValueError
|
If there is not one transition per node sized to it, if
|
Validate the wiring and front-load the data-independent work (ADR-002).
Everything here depends only on the graph and the transitions, never on a
per-step observation / prior / action, so it is built once and reused across
every infer_states call.
Source code in src/cpomdp/backends/coupling.py
transitions
property
¶
Each node's transition, indexed by node, fixed at construction.
partition
property
¶
The carry partition's clusters of nodes, fixed at construction.
One cluster over every node when none was given, the exact joint carry.
model
property
¶
The model of the graph's interface, which leaves out its couplings.
Block-diagonal dynamics (F, Q), the real sensors and the control: the joint
state as one linear-Gaussian model, with the sizes an Agent
reads. The Agent takes its own model from this, so passing the backend
is enough (issue #26). Read the stacked sensor C as
model.observation_matrix and R at a mean as
model.observation_noise_at(mean). A fixed graph's model returns the R it
front-loaded. A state-dependent graph's model reads each node's R at that
node's block of the mean, the point the filter uses.
It omits the structural couplings, so it is not the graph's plant. On a
coupled graph every flat consumer refuses it: both flat backends, the flat
selectors and searches, LQRController, the schedules and the flat EFE
functions. The mark survives a pytree rebuild and dataclasses.replace. A
model rebuilt field by field through the constructor is not marked.
to_flat_model() adds the couplings as pseudo-observations, for the oracle
cross-check.
stack_observations ¶
One step's readings, keyed by node, as the vector infer_states takes.
The vector holds each observed node's reading in ascending node order. A dict iterates in insertion order, so readings of one width stacked by hand in the wrong order pass every shape check and filter each node against another's.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
readings
|
Mapping[int, ArrayLike]
|
one reading per observed node, keyed by node, the form
|
required |
Returns:
| Type | Description |
|---|---|
Float64[Array, m]
|
The stacked observation, shape |
Raises:
| Type | Description |
|---|---|
ValueError
|
If an observed node has no reading, a reading names a node with no sensor, or a reading's width is not its sensor's row count. |
Source code in src/cpomdp/backends/coupling.py
infer_states ¶
Advance the joint belief by one filter step over the tree.
Validate the inputs, form the control shift b = control_matrix @ action,
then run the driven-relaxation pipeline: cut the prior by the partition, lift
it into canonical form, _predict through the block-diagonal per-node
dynamics (the temporal edges), add the structural coupling precision and the
per-node observation messages (the within-slice update), and to_moment the
joint posterior back.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
observation
|
ArrayLike
|
the observed nodes' readings, stacked in ascending node-index
order, shape |
required |
prior
|
Belief
|
the current joint belief over all nodes. Never mutated. |
required |
action
|
ArrayLike | None
|
the action just taken, shape |
None
|
Returns:
| Type | Description |
|---|---|
Belief
|
The posterior joint belief over all nodes; slice one node out with |
Belief
|
|
Source code in src/cpomdp/backends/coupling.py
severed_mass ¶
severed_mass(
observation: ArrayLike,
prior: Belief,
action: ArrayLike | None = None,
) -> Float64[jax.Array, ""]
The covariance one step's carry drops under this partition (ADR-016).
The norm of the between-cluster covariance blocks the carry zeros: how much
cross-cluster correlation the partition drops at the time boundary, the
approximation cost of the cut. A covariance magnitude, not bits and not a rate.
0.0 for the full-joint [[all]] partition (exact), growing as the cut
severs more correlation. The per-node marginals this slice are unaffected. The
carry only drops what is carried forward (ADR-017).
A 0-d array, so it composes under jit, vmap and lax.scan. A per-run
profile is a scan over infer_states and this, and float(...) reads one
value on the host. It takes the dense joint solve, separately from
infer_states, so its cost is its own.
Source code in src/cpomdp/backends/coupling.py
marginal ¶
The marginal belief at a single node — a pure slice of the joint belief.
The joint carried by infer_states makes every node exact, so a chosen node's
belief is a slice, no re-inference (issue #25: the target latent need not be the
root).
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Source code in src/cpomdp/backends/coupling.py
block ¶
The state indices node node occupies in the joint (a public _block).
Lets a caller (e.g. the EFE selector) turn a node index into the joint-state
block the epistemic term targets — info_node node → block (issue #26).
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Source code in src/cpomdp/backends/coupling.py
severed_efe_edges ¶
The EFE-relevant edges this carry partition cuts (ADR-018 diagnostic).
Each efe_relevant coupling whose parent and child fall in different clusters
— so the carry drops the cross-temporal covariance it holds, breaking the
integration of that information about the targeted latent. Non-empty means
every EFE entry point must refuse this partition; empty for the exact
[[all]] carry and for any cut that only severs unflagged edges. It is a
structural read and forms no covariance.
Source code in src/cpomdp/backends/coupling.py
predicted_belief ¶
The joint belief after dynamics + structural couplings, before observing.
The predict side of one step (Σ⁺, μ⁺): cut the joint prior as the partition
carries it, push it through the per-node dynamics under action and fold in
the structural couplings, but add no observation. This is the covariance the
EFE reads — a candidate action's epistemic value is the info gain from this Σ⁺
to the post-observation covariance (issue #26). Pure (no host-side
validation), so it rides jit / vmap over a grid of candidate actions.
Source code in src/cpomdp/backends/coupling.py
to_flat_model ¶
The tree flattened into one dense LinearGaussianModel (the oracle route).
The temporal edges become the block-diagonal transition (F, Q); the real
observations and the structural couplings stack into one sensor, each coupling
an always-zero pseudo-observation child − W·parent ~ N(0, Q_struct). Running
KalmanBackend or RxInferBackend on this
reproduces this backend's filter exactly. It is the independent cross-check.
Pad a step's readings with flat_observation first. The returned model
carries the backend's prior.
With couplings present a state-dependent R(x) is a category error for this
route (IncompatibleLinearizationError — the flat Kalman linearizes at μ⁻,
the FFG at μ⁺). Coupling-free, μ⁻ = μ⁺, so the emitted model carries the graph's
own state-dependent sensor and stays faithful; it is a state-dependent flat
model, not a fixed one, and no fixed one exists.
The refusal reads the sensor's declared state-dependence. Whether R really
varies over the means a policy can reach is a property of the noise function and
the reachable set, which this cannot decide — cpomdp.diagnostics.probe_model
samples it.
Source code in src/cpomdp/backends/coupling.py
flat_observation ¶
Pad a step's readings with the structural pseudo-observations' zeros.
to_flat_model stacks the real observations then the structural couplings, so
a flat backend consumes [readings, zeros(n_structural)].
Source code in src/cpomdp/backends/coupling.py
IncompatibleLinearizationError ¶
Bases: ValueError
The flattened-Kalman route can't reproduce this backend's linearization.
to_flat_model encodes couplings as pseudo-observations, so the flat Kalman
linearizes R at the pre-coupling predicted mean μ⁻, while the FFG linearizes at
the coupling-resolved μ⁺ (issue #27, ADR-019). With a state-dependent R(x) and a
mean-shifting coupling, μ⁻ ≠ μ⁺ and no fixed flat model reproduces the filter. The
test suite checks this backend against a NumPy filter that reads R at μ⁺, and
against CallableSensor on a single node.
A carry partition that severs an edge the model flags as EFE-load-bearing filters fine. The EFE selectors, rollouts and searches refuse it with InadmissiblePartitionError.
InadmissiblePartitionError ¶
Bases: ValueError
A carry partition severs an edge the model declares EFE-load-bearing (ADR-018).
The carry drops the cross-cluster covariance that edge holds across the time
boundary (the ADR-016 severed mass). That cross-temporal correlation is how
information about a slow latent integrates from weak per-step observations of the
fast nodes it couples to; severing an edge on the covariance path from the sensed
nodes to the targeted latent breaks that integration. The one-step epistemic and the
behavioural drift can still look right while the accumulated information about the
latent — what the instrumental epistemic rides on — degrades, up to collapse for an
integration-limited latent. Whether the degradation is mild or total is
model-specific (measure it with CouplingGraphBackend.severed_mass), so the
guard refuses conservatively rather than sever and hope. Keep the flagged edge's
endpoints in one cluster, or, if a check shows the cut is safe, drop its
efe_relevant flag.
Which names trace¶
The JAX backends, the EFE functions and the selectors' select are pure over pytrees.
They compose under jax.jit, vmap, grad and lax.scan. The Agent is an eager
convenience over them, and its page shows the same loop written under lax.scan.
Construction is host-side work done once. Build outside the transform and close over the
result. Belief, LinearGaussianModel and Preference are pytrees, so they pass as
arguments, and under a trace their construction checks are skipped because the values
are abstract. Goals, selectors and backends are not pytrees. They enter a transform as
closures.
| Name | Under jit, vmap, grad and lax.scan |
|---|---|
KalmanBackend.infer_states |
Traces, per-step or steady-state, under fixed noise, R(x) or Q(x) |
CouplingGraphBackend.infer_states |
Traces |
expected_free_energy, cpomdp.efe.policy_efe |
Traces |
LQRSelector.select |
Traces, with a gradient through the gain |
EFESelector.select, FFGEFESelector.select, cpomdp.enumeration.RecedingHorizonSelector.select |
Traces. The action is an argmin over fixed candidates, so its gradient is zero |
Agent.infer_states, cpomdp.enumeration.OpenLoopSelector.select |
Does not. Each keeps state between calls. A traced call restarts from the state it was traced with and leaves a tracer behind |
Agent.sample_action |
Does not. It reads the action on the host to refuse a NaN, so a traced call raises before it keeps anything |
KalmanBackend(model, steady_state=True), LQRController(...), Agent(model, goal) |
Does not. Each solves once on the host at construction |
RxInferBackend.infer_states |
Does not. It calls Julia |
probe_model |
Does not. It runs in NumPy on the host |
tests/test_transform_table.py runs every row except RxInferBackend's, which needs Julia. A row that traces runs under jit, vmap and grad, and a row that does not is shown failing under jit. The lax.scan loop is on the Agent page.
-
Dmitry Bagaev, Albert Podusenko, and Bert de Vries. RxInfer: a Julia package for reactive real-time Bayesian inference. Journal of Open Source Software, 8(84):5161, 2023. URL: https://doi.org/10.21105/joss.05161, doi:10.21105/joss.05161. ↩