Model & belief¶
The generative model the agent assumes, and the Gaussian belief it carries over the hidden state.
LinearGaussianModel
dataclass
¶
LinearGaussianModel(
dynamics_matrix: ArrayLike,
*,
observation_matrix: ArrayLike | None = None,
dynamics_noise: ArrayLike | None = None,
observation_noise: ArrayLike | None = None,
prior: Belief,
control_matrix: ArrayLike | None = None,
observation_model: ObservationModel | None = None,
dynamics_noise_model: DynamicsNoiseModel | None = None,
structure: ModelStructure | None = None,
)
A linear-Gaussian state-space model — the agent's generative model.
The agent's assumed story for how a hidden state evolves and produces observations, under linear maps and Gaussian noise::
next_state = dynamics_matrix @ state + control_matrix @ action + dynamics noise
observation = observation_matrix @ state + observation noise
The noise terms are zero-mean Gaussians with covariances dynamics_noise
and observation_noise; the initial state is drawn from prior.
Parameters are role-named rather than using the traditional control-theory letters, to avoid the letter collision with discrete active inference (pymdp), where the same letters mean different things. The "also known as" column lists the terms other backgrounds use, so readers can still find the right field. Each field has that one name.
| role name | letter | meaning | shape | also known as |
|---|---|---|---|---|
dynamics_matrix |
A | state -> next state | (n,n) | state-transition |
control_matrix |
B | action -> state (optional) | (n,p) | input/control |
observation_matrix |
C | state -> reading | (m,n) | measurement/emission |
dynamics_noise |
Q | dynamics-noise covariance | (n,n) | process noise |
observation_noise |
R | reading-noise covariance | (m,m) | measurement noise |
prior |
-- | initial belief over state | n-D | Belief / D (pymdp) |
Dimensions: n = state, m = observation, p = action. A model with
no control_matrix is a pure filtering (tracking) model.
Everything after dynamics_matrix is keyword-only. Two of the four matrices
are maps and two are covariances, all of the same rank, and only the covariances are
content-checked. A transposed pair therefore constructs in silence whenever the maps
are square and symmetric. Naming them at the call site rules that out.
Three optional fields (all default None → the plain fixed-matrix model)
extend it: observation_model (an ObservationModel
for state-dependent sensing R(x)), dynamics_noise_model (a
DynamicsNoiseModel for state-dependent dynamics
noise Q(x)), and structure (a ModelStructure
declaring the factor / Markov-blanket partition).
observation_matrix and observation_noise are optional when an
observation_model is given. Omitted, they are the sensor's C and its R
at prior.mean, read once at construction. Passed, they must be those values
exactly, so a sensor's channel is never described twice and each field means one
thing (DECISIONS.md ADR-064, ADR-071). dynamics_noise follows the same rule
beside a dynamics_noise_model, and is its Q at prior.mean (ADR-065).
A consumer that understands a state-dependent object reads R(x) or Q(x)
from it. One that needs a constant refuses the model. To move the prior with
dataclasses.replace, pass the noises an object supplies as None so they
are read again at the new mean.
Source code in src/cpomdp/types.py
observation_noise_at ¶
The observation noise R at state, whatever sensor the model carries.
A model with no observation_model, or a fixed one, returns
observation_noise itself and reads no state. A state-dependent sensor is
linearized at state. A consumer that needs R where a belief sits reads it
here and does not branch on the sensor.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
state
|
ArrayLike
|
the state to read R at, shape |
required |
Returns:
| Type | Description |
|---|---|
Float64[Array, 'm m']
|
R at |
Source code in src/cpomdp/types.py
tree_flatten ¶
Leaves for JAX: every matrix plus the prior belief; structure is aux.
control_matrix, observation_model and dynamics_noise_model are
included as (possibly None) children; an uncontrolled / fixed-sensor /
fixed-Q model contributes no leaf there and the None is restored on
rebuild. A non-None observation_model/dynamics_noise_model is itself
a pytree and recurses into its own leaves. structure (declarative metadata,
no array leaves) rides in the static aux_data, so two models differing only in
structure are different pytrees and a jit keyed on the model re-specialises
when it changes.
Source code in src/cpomdp/types.py
tree_unflatten
classmethod
¶
tree_unflatten(
aux_data: ModelStructure | None,
children: tuple[_ModelLeaf, ...],
) -> LinearGaussianModel
Rebuild from leaves without validating — the leaves may be tracers.
aux_data is the static structure (or None), restored as-is.
Source code in src/cpomdp/types.py
Belief
dataclass
¶
A Gaussian belief over a continuous state.
In active inference an agent never knows the hidden state directly — it holds a probability distribution over what the state might be. For the linear-Gaussian case that distribution is always a Gaussian, fully described by two things:
mean-- the centre, the best single estimate. A 1-D vector of length n.cov-- the covariance, the uncertainty. An n x n matrix; its diagonal is the variance per state dimension, its off-diagonals the correlations between them.
Beliefs are immutable values: updating a belief produces a new Belief
rather than mutating an existing one. Inputs are accepted as anything
array-like (lists, tuples, arrays) and stored as float jax.Array.
A Belief is a registered JAX pytree (its leaves are mean and cov),
so it passes through jit/vmap/grad as data. Direct construction
checks the shapes, that the mean is finite, and that the covariance is symmetric
and positive semi-definite. JAX rebuilds a Belief from its leaves without
those checks, and under a trace the value checks are skipped because the values
are abstract.
Source code in src/cpomdp/types.py
tree_flatten ¶
tree_unflatten
classmethod
¶
tree_unflatten(
aux_data: None,
children: tuple[
Float64[Array, n], Float64[Array, "n n"]
],
) -> Belief
Rebuild from leaves without validating — the leaves may be tracers.