Factor graph models¶
A CouplingGraph declares a rooted tree of Gaussian-coupled variables. It holds the shape a chain cannot: a node with three or more neighbours, inferred through the ones around it. Coupling edges carry the within-slice drive child = W·parent + noise, and each node's dynamics is a GaussianTransition. A node's observation is the sensor a flat model takes, a FixedSensor or a state-dependent CallableSensor. Moving a model onto a graph keeps its sensors. Run the graph through a CouplingGraphBackend.
CouplingGraph ¶
CouplingGraph(
dims: Sequence[int],
couplings: Sequence[Coupling],
observation_models: Mapping[int, ObservationModel],
)
A rooted tree of Gaussian-coupled variables.
The N nodes are indexed 0..N-1 with dimensions dims. couplings are
the tree edges, each directed from parent to child, and the root is the one node no
edge points to. observation_models maps a node index to the sensor on it. A node
takes the sensor a flat model takes: a
FixedSensor, a state-dependent
CallableSensor, or any other
ObservationModel. Construction validates the wiring
and raises if it is malformed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dims
|
Sequence[int]
|
|
required |
couplings
|
Sequence[Coupling]
|
the tree edges — one per non-root node, each that node's only parent. The node left without a parent is the root. |
required |
observation_models
|
Mapping[int, ObservationModel]
|
maps a node index to the |
required |
Raises:
| Type | Description |
|---|---|
TypeError
|
if a dimension is not an int, an edge is not a |
ValueError
|
if |
The four fields are read-only once built. Construction is where the wiring is checked, so a graph that needs other wiring is a new graph.
Source code in src/cpomdp/ffg/graph.py
observation_models
property
¶
Each observed node's sensor, keyed by node index. A read-only view.
infer_root ¶
Compute the marginal belief at the root from per-node readings and a prior.
Each reading becomes a message about its node; those messages are passed up the tree through the couplings and combined at the root with the prior, giving the root's posterior over every reading. Only the root is converted to and from moment form — once to lift the prior in, once to read the result out — while every message in between stays in canonical form.
The reading comes first and the belief second, the order
InferenceBackend.infer_states takes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
readings
|
Mapping[int, ArrayLike]
|
maps a node index to that node's observation. Each such node must
carry a fixed sensor, since static inference has no predicted mean to
evaluate a state-dependent |
required |
prior
|
Belief
|
the belief on the root node, taken as its prior. |
required |
Returns:
| Type | Description |
|---|---|
Belief
|
The marginal belief at the root. |
Raises:
| Type | Description |
|---|---|
TypeError
|
if |
ValueError
|
if |
Source code in src/cpomdp/ffg/graph.py
Coupling
dataclass
¶
Coupling(
parent: int,
child: int,
coupling_matrix: ArrayLike,
*,
coupling_noise: ArrayLike,
efe_relevant: bool = False,
)
A directed edge from a parent node to a child node: child = W·parent + noise.
parent and child are node indices, oriented so the parent is the endpoint
nearer the tree's root. The edge is the linear-Gaussian factor
N(child; W·parent, Q):
coupling_matrix— W, shape(dim[child], dim[parent]). It maps the parent's state onto the child's and need not be square.coupling_noise— Q, shape(dim[child], dim[child]), positive-definite (it is inverted).
Where a GaussianTransition steps one node in time,
an edge couples two nodes within a slice. The maths is the same. A node's timescale
is its transition, so an edge carries none (ADR-074).
efe_relevant is a modeller's declaration that this edge carries information
the instrumental epistemic depends on. It is a physics call. An edge can be
observed and coupled and still carry nothing the epistemic needs. A carry partition
(ADR-016) that severs a flagged edge drops the cross-temporal covariance it holds,
and with it the integration of that information about a slow latent. Every graph
EFE entry point refuses such a partition (ADR-018). Default False. The flag
does not affect the factor or the filter.
Raises:
| Type | Description |
|---|---|
TypeError
|
if |
ValueError
|
if |
Source code in src/cpomdp/ffg/graph.py
GaussianTransition
dataclass
¶
Tier-1 dynamics factor N(x'; Ax + b, Q): how one node steps in time.
Holds the node's fixed transition and dynamics noise. A
CouplingGraphBackend takes one per node.
dynamics_matrix— A, shape(n, n).dynamics_noise— Q, shape(n, n), positive-definite (it is inverted).
Source code in src/cpomdp/ffg/factors/linear_gaussian.py
from_ou
classmethod
¶
Build a 1-D transition from Ornstein–Uhlenbeck (OU) parameters.
An Ornstein–Uhlenbeck process is a scalar state that relaxes toward zero on a
timescale tau while random noise keeps it wobbling with a stationary
variance stationary_var (Σ_stat). Exactly discretising it over a step dt
gives the linear-Gaussian transition x' = A·x + noise(Q) (ADR-017):
A = exp(−dt / tau) — the fraction of the state surviving a step
Q = stationary_var · (1 − A²) — the kick that holds the stationary variance
Scalar (1-D) only: the vector OU would need a matrix exponential and a Lyapunov solve, which no cpomdp node needs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tau
|
float
|
the relaxation timescale τ (same time unit as |
required |
stationary_var
|
float
|
the steady-state variance Σ_stat the node settles to; A (dynamics) and Q (dynamics_noise) are set so it holds this spread. |
required |
dt
|
float
|
the discretisation step. |
required |
Returns:
| Type | Description |
|---|---|
GaussianTransition
|
A |
GaussianTransition
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
if |
Source code in src/cpomdp/ffg/factors/linear_gaussian.py
tree_flatten ¶
Leaves for JAX: (dynamics, dynamics_noise), no static aux data.
Source code in src/cpomdp/ffg/factors/linear_gaussian.py
tree_unflatten
classmethod
¶
tree_unflatten(
aux_data: None,
children: tuple[
Float64[Array, "n n"], Float64[Array, "n n"]
],
) -> GaussianTransition
Rebuild from leaves without validating — the leaves may be tracers.