Skip to content

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

model: LinearGaussianModel

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

infer_states(
    observation: ArrayLike,
    prior: Belief,
    action: ArrayLike | None = None,
) -> Belief

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
def infer_states(
    self,
    observation: ArrayLike,
    prior: Belief,
    action: ArrayLike | None = None,
) -> Belief:
    """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.
    """
    ...

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 model is a coupled graph backend's model, which leaves out the couplings.

ValueError

If steady_state=True and the model carries R(x) or Q(x), which have no constant fixed point.

RuntimeError

If the steady-state recursion does not converge within max_iter, because the model is not stabilisable or detectable.

Source code in src/cpomdp/backends/kalman.py
def __init__(
    self,
    model: LinearGaussianModel,
    *,
    steady_state: bool = False,
    tol: float = 1e-12,
    max_iter: int = 1000,
) -> None:
    _refuse_graph_interface(model, "KalmanBackend")
    self._model = model
    self._steady_state = steady_state
    if steady_state:
        require_fixed_noise(
            model,
            "steady_state=True needs a constant fixed point, and R(x) or Q(x) has "
            "none. Use steady_state=False.",
        )
        self._steady_gain, self._steady_cov = self._converge_to_steady_state(
            tol, max_iter
        )

model property

model: LinearGaussianModel

The model this backend filters under, fixed at construction.

steady_state property

steady_state: bool

Whether the gain was frozen at construction, fixed with it.

infer_states

infer_states(
    observation: ArrayLike,
    prior: Belief,
    action: ArrayLike | None = None,
) -> Belief

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 (m,).

required
prior Belief

The current belief, treated as this step's previous posterior. Never mutated.

required
action ArrayLike | None

The action just taken, shape (p,). Required iff the model has a control matrix; ignored (pass None) for pure filtering.

None

Returns:

Type Description
Belief

The posterior belief — a new Belief; the prior is left untouched.

Raises:

Type Description
ValueError

If observation is not shape (m,), prior is not a belief over the model's n-D state, the model has a control matrix but action is None, or action is not shape (p,).

Source code in src/cpomdp/backends/kalman.py
def infer_states(
    self,
    observation: ArrayLike,
    prior: Belief,
    action: ArrayLike | None = None,
) -> Belief:
    """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.

    Args:
        observation: The latest sensor reading, shape ``(m,)``.
        prior: The current belief, treated as this step's previous posterior.
            Never mutated.
        action: The action just taken, shape ``(p,)``. Required iff the model
            has a control matrix; ignored (pass ``None``) for pure filtering.

    Returns:
        The posterior belief — a new ``Belief``; the prior is left untouched.

    Raises:
        ValueError: If ``observation`` is not shape ``(m,)``, ``prior`` is not
            a belief over the model's ``n``-D state, the model has a control
            matrix but ``action`` is ``None``, or ``action`` is not shape
            ``(p,)``.
    """
    model = self.model
    observation, action = _validate_step_inputs(model, observation, prior, action)
    control_matrix = model.control_matrix
    if control_matrix is None:
        control_term = jnp.zeros(model.n_states)
    else:
        # _validate_step_inputs guarantees a non-None action when control exists
        assert action is not None
        control_term = control_matrix @ action

    sensor = state_dependent(model.observation_model)
    process = state_dependent(model.dynamics_noise_model)

    # μ⁻ is needed only to linearize a state-dependent sensor and/or process
    # noise; the fully-fixed hot path computes no extra matvec.
    mean_pred = (
        model.dynamics_matrix @ prior.mean + control_term
        if sensor is not None or process is not None
        else prior.mean  # placeholder, unused on the fixed path
    )

    if sensor is None:
        # fixed sensor: direct reads, byte-identical hot path (no linearize).
        observation_matrix, observation_noise = (
            model.observation_matrix,
            model.observation_noise,
        )
    else:
        # state-dependent R(x), linearized at μ⁻ (the EFE kernel's point).
        observation_matrix, observation_noise = sensor.linearize(mean_pred)

    if process is None:
        dynamics_noise = model.dynamics_noise
    else:
        # state-dependent Q(x), evaluated at μ⁻ — the dual of the R(x) gate.
        dynamics_noise = process.noise_at(mean_pred)

    if self.steady_state:
        gain, cov_post = self._steady_gain, self._steady_cov  # frozen
    else:
        gain, cov_post = _gain_and_posterior_cov(
            model.dynamics_matrix,
            observation_matrix,
            dynamics_noise,
            observation_noise,
            prior.cov,
        )

    mean_post = _posterior_mean(
        model.dynamics_matrix,
        observation_matrix,
        prior.mean,
        control_term,
        gain,
        observation,
    )

    return Belief(mean=mean_post, cov=cov_post)

RxInferBackend

RxInferBackend(model: LinearGaussianModel)

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
def __init__(self, model: LinearGaussianModel) -> None:
    _refuse_graph_interface(model, "RxInferBackend")
    require_fixed_noise(
        model,
        "the RxInfer model filters on one fixed Q and R. Use KalmanBackend for "
        "R(x) or Q(x).",
    )
    self._model = model
    self._jl = _julia()

model property

model: LinearGaussianModel

The model this backend filters under, fixed at construction.

infer_states

infer_states(
    observation: ArrayLike,
    prior: Belief,
    action: ArrayLike | None = None,
) -> Belief

Advance the belief one filter step: prior in, posterior out.

Parameters:

Name Type Description Default
observation ArrayLike

Latest sensor reading, shape (m,).

required
prior Belief

Current belief; never mutated.

required
action ArrayLike | None

Action just taken, shape (p,). Required iff the model has a control matrix; pass None for pure filtering.

None

Raises:

Type Description
ValueError

If observation, prior or action does not match the model, on the same checks as KalmanBackend.infer_states.

Source code in src/cpomdp/backends/rxinfer.py
def infer_states(
    self,
    observation: ArrayLike,
    prior: Belief,
    action: ArrayLike | None = None,
) -> Belief:
    """Advance the belief one filter step: prior in, posterior out.

    Args:
        observation: Latest sensor reading, shape ``(m,)``.
        prior: Current belief; never mutated.
        action: Action just taken, shape ``(p,)``. Required iff the model has
            a control matrix; pass ``None`` for pure filtering.

    Raises:
        ValueError: If ``observation``, ``prior`` or ``action`` does not match the
            model, on the same checks as ``KalmanBackend.infer_states``.
    """
    model = self.model
    observation, action = _validate_step_inputs(model, observation, prior, action)
    control_matrix = model.control_matrix
    if control_matrix is None:
        control_term = jnp.zeros(model.n_states)
    else:
        # _validate_step_inputs guarantees a non-None action when control exists
        assert action is not None
        control_term = control_matrix @ action

    # juliacall speaks numpy, not jax.Array, so coerce every array as it
    # crosses into Julia and coerce the posteriors back on the way out.
    mean_post, cov_post = self._jl.cpomdp_run_step(
        np.asarray(observation),
        np.asarray(model.dynamics_matrix),
        np.asarray(model.observation_matrix),
        np.asarray(model.dynamics_noise),
        np.asarray(model.observation_noise),
        np.asarray(prior.mean),
        np.asarray(prior.cov),
        np.asarray(control_term),
    )

    return Belief(mean=np.asarray(mean_post), cov=np.asarray(cov_post))

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 child = W·parent + noise) and the per-node sensors.

required
transitions Sequence[GaussianTransition]

one GaussianTransition (A_i, Q_i) per node, indexed by node, so transitions[i] is node i's own dynamics. Each Q_i must be positive-definite, because the information form inverts it. A flat LinearGaussianModel accepts a semi-definite Q.

required
prior Belief

the belief over the joint state before any reading, a mean of length sum(graph.dims). It is model.prior, so an Agent built on this backend starts from it, and to_flat_model carries it.

required
control_matrix ArrayLike | None

B, shape (n, p) with n = sum(graph.dims), mapping an action into the joint state. None for a pure filtering model.

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 is one cluster of every node, the exact filter. All singletons take a cheaper node-by-node pass. A prior passed in is cut the same way before it is used. severed_mass measures what a cut drops.

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 prior is not a Belief.

ValueError

If there is not one transition per node sized to it, if prior or control_matrix is not over the joint state, or if partition misses a node, repeats one or names one outside the graph.

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
def __init__(
    self,
    graph: CouplingGraph,
    transitions: Sequence[GaussianTransition],
    *,
    prior: Belief,
    control_matrix: ArrayLike | None = None,
    partition: Sequence[Sequence[int]] | None = None,
) -> None:
    """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.
    """
    self._validate_transitions(graph, transitions)

    self._graph = graph
    self._transitions = tuple(transitions)
    self._offsets = tuple(int(o) for o in np.cumsum([0, *graph.dims]))
    self._n_states = self._offsets[-1]  # n, the joint state's width
    self._prior = self._validate_prior(prior)
    self._control = self._coerce_control(control_matrix)
    self._partition = self._resolve_partition(partition)
    # Fully-factored (every cluster a singleton) → the carry keeps the belief
    # block-diagonal, so the within-slice solve is a tree and cheap two-pass BP
    # (``_infer_all``) replaces the dense joint solve (ADR-016 energy lever).
    self._is_factored = all(len(cluster) == 1 for cluster in self._partition)
    self._is_exact = len(self._partition) == 1  # one cluster severs nothing

    # Front-loaded factor tier — built once, reused every step (ADR-002).
    self._transition = self._build_transition()
    self._structural_precision = self._assemble_structural_precision()
    self._obs_layout, self._n_observations = self._build_observation_layout()
    self._sensor_is_fixed = all(
        o.is_fixed for o in self._graph.observation_models.values()
    )
    self._model = self._build_model()
    self._partition_mask = self._build_partition_mask()
    # node -> its partition cluster index (ADR-018 admissibility diagnostic).
    self._cluster_of = {
        node: cid for cid, cluster in enumerate(self._partition) for node in cluster
    }

graph property

graph: CouplingGraph

The graph this backend filters over, fixed at construction.

transitions property

transitions: tuple[GaussianTransition, ...]

Each node's transition, indexed by node, fixed at construction.

partition property

partition: tuple[tuple[int, ...], ...]

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

model: LinearGaussianModel

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

stack_observations(
    readings: Mapping[int, ArrayLike],
) -> Float64[jax.Array, m]

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 CouplingGraph.infer takes. A scalar is a one-row reading.

required

Returns:

Type Description
Float64[Array, m]

The stacked observation, shape (model.n_observations,).

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
def stack_observations(
    self, readings: Mapping[int, ArrayLike]
) -> Float64[jax.Array, "m"]:
    """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.

    Args:
        readings: one reading per observed node, keyed by node, the form
            ``CouplingGraph.infer`` takes. A scalar is a one-row reading.

    Returns:
        The stacked observation, shape ``(model.n_observations,)``.

    Raises:
        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.
    """
    observed = [node for node, _lo, _hi in self._obs_layout]
    missing = sorted(set(observed) - set(readings))
    if missing:
        raise ValueError(f"no reading for observed node(s) {missing}")
    unobserved = sorted(set(readings) - set(observed))
    if unobserved:
        raise ValueError(
            f"node(s) {unobserved} carry no sensor, so they take no reading. "
            f"The observed nodes are {observed}."
        )
    parts = []
    for node, lo, hi in self._obs_layout:
        reading = jnp.atleast_1d(jnp.asarray(readings[node], dtype=float))
        if reading.shape != (hi - lo,):
            raise ValueError(
                f"the reading on node {node} has shape {reading.shape}, and its "
                f"sensor reads {hi - lo} value(s)"
            )
        parts.append(reading)
    return jnp.concatenate(parts) if parts else jnp.zeros(0)

infer_states

infer_states(
    observation: ArrayLike,
    prior: Belief,
    action: ArrayLike | None = None,
) -> Belief

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 (model.n_observations,). stack_observations builds it from readings keyed by node.

required
prior Belief

the current joint belief over all nodes. Never mutated.

required
action ArrayLike | None

the action just taken, shape (p,); required iff the model has a control matrix, None for pure filtering.

None

Returns:

Type Description
Belief

The posterior joint belief over all nodes; slice one node out with

Belief

marginal.

Source code in src/cpomdp/backends/coupling.py
def infer_states(
    self,
    observation: ArrayLike,
    prior: Belief,
    action: ArrayLike | None = None,
) -> Belief:
    """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.

    Args:
        observation: the observed nodes' readings, stacked in ascending node-index
            order, shape ``(model.n_observations,)``. ``stack_observations``
            builds it from readings keyed by node.
        prior: the current *joint* belief over all nodes. Never mutated.
        action: the action just taken, shape ``(p,)``; required iff the model has a
            control matrix, ``None`` for pure filtering.

    Returns:
        The posterior *joint* belief over all nodes; slice one node out with
        ``marginal``.
    """
    observation, action = _validate_step_inputs(
        self._model, observation, prior, action
    )
    if self._is_factored:
        # Fully-factored carry: skip the dense joint solve, run tree BP instead.
        return self._infer_states_factored(observation, prior, action)
    precision, potential = self._assemble_unchecked(observation, prior, action)
    mean, cov = CanonicalGaussian._unchecked(
        precision, potential
    ).to_moment()  # exact joint: Σ = Λ⁻¹, μ = Λ⁻¹h
    factored_cov, _severed = self._carry(cov)
    return Belief(mean=mean, cov=factored_cov)

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
def severed_mass(
    self,
    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.
    """
    precision, potential = self._assemble_posterior(observation, prior, action)
    _mean, cov = CanonicalGaussian._unchecked(precision, potential).to_moment()
    _factored, severed = self._carry(cov)
    return severed

marginal

marginal(node: int, belief: Belief) -> Belief

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 node is not a node of the graph.

Source code in src/cpomdp/backends/coupling.py
def marginal(self, node: int, belief: Belief) -> Belief:
    """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:
        ValueError: If ``node`` is not a node of the graph.
    """
    block = self._block(self._checked_node(node))
    return Belief(mean=belief.mean[block], cov=belief.cov[block, block])

block

block(node: int) -> range

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 node is not a node of the graph.

Source code in src/cpomdp/backends/coupling.py
def block(self, node: int) -> range:
    """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:
        ValueError: If ``node`` is not a node of the graph.
    """
    node = self._checked_node(node)
    return range(self._offsets[node], self._offsets[node + 1])

severed_efe_edges

severed_efe_edges() -> tuple[Coupling, ...]

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
def severed_efe_edges(self) -> tuple[Coupling, ...]:
    """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.
    """
    return tuple(
        edge
        for edge in self._graph.couplings
        if edge.efe_relevant
        and self._cluster_of[edge.parent] != self._cluster_of[edge.child]
    )

predicted_belief

predicted_belief(
    prior: Belief, action: ArrayLike | None = None
) -> 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
def predicted_belief(
    self, prior: Belief, action: ArrayLike | None = None
) -> 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.
    """
    coerced = None if action is None else jnp.asarray(action, dtype=float)
    precision, potential = self._predicted_precision(prior, coerced)
    mean, cov = CanonicalGaussian._unchecked(precision, potential).to_moment()
    return Belief(mean=mean, cov=cov)

to_flat_model

to_flat_model() -> LinearGaussianModel

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
def to_flat_model(self) -> LinearGaussianModel:
    """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`][cpomdp.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.
    """
    if not self._sensor_is_fixed and self._graph.couplings:
        # A mean-shifting coupling makes μ⁺ ≠ μ⁻, so no fixed flat model
        # reproduces R(μ⁺) -- inherent, not a missing feature.
        raise IncompatibleLinearizationError(
            "Cannot flatten a state-dependent R(x) model with couplings: a "
            "mean-shifting coupling makes the prediction mean μ⁺ differ from "
            "the prior mean μ⁻, so no fixed linear-Gaussian model reproduces "
            "R(μ⁺). This reads the sensor's declared state-dependence; a "
            "declared R(x) that ignores the state is constant in fact and does "
            "flatten — see cpomdp.diagnostics.probe_model."
        )
    if not self._sensor_is_fixed:
        # Coupling-free R(x): μ⁻ = μ⁺, so handing the graph's own sensor to a flat
        # backend reproduces this filter, and this model is the backend's own.
        return self._model
    rows = self._embedded_sensor_rows()
    noise_blocks = self._fixed_noise_blocks()
    for edge in self._graph.couplings:  # child − W·parent ~ N(0, Q_struct)
        coupling = edge.coupling_matrix  # W
        child_dim = coupling.shape[0]
        row = jnp.zeros((child_dim, self._n_states))
        row = row.at[:, self._block(edge.child)].set(jnp.eye(child_dim))
        row = row.at[:, self._block(edge.parent)].set(-coupling)
        rows.append(row)
        noise_blocks.append(edge.coupling_noise)
    return LinearGaussianModel(
        dynamics_matrix=self._transition.dynamics_matrix,
        observation_matrix=jnp.vstack(rows),
        dynamics_noise=self._transition.dynamics_noise,
        observation_noise=jax.scipy.linalg.block_diag(*noise_blocks),
        prior=self._prior,
        control_matrix=self._control,
    )

flat_observation

flat_observation(observation: ArrayLike) -> jax.Array

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
def flat_observation(self, observation: ArrayLike) -> jax.Array:
    """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)]``.
    """
    observation = jnp.asarray(observation, dtype=float)
    n_structural = sum(
        edge.coupling_matrix.shape[0] for edge in self._graph.couplings
    )
    return jnp.concatenate([observation, jnp.zeros(n_structural)])

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.


  1. 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. ↩