Skip to content

Diagnostics

Whether a state-dependent R(x) earns its keep is a question about the states an action can actually reach. A noise that varies only where no policy goes is, for every purpose the filter and the objective have, a constant. probe_model samples the reachable set and reports back a ProbeReport: whether R is positive definite at every sample, whether it moves at all, and whether the epistemic value moves with it. The set is sampled, not exhausted, so a negative is evidence rather than proof.

probe_model

probe_model(
    model: LinearGaussianModel | GraphBackend,
    belief: Belief,
    actions: Sequence[ArrayLike],
    *,
    tol: float = 1e-12,
) -> ProbeReport

Probe a model's sensor over the predicted means a set of actions reaches.

Each action is pushed through the prediction step to get (μ⁻, Σ⁻); the sensor is linearized at each μ⁻ and the four conditions are evaluated over the resulting sample. This is the reachable set the conditions are about — vary actions to widen it. A state-dependent Q(x) enters Σ⁻ at each μ⁻, where the EFE kernel evaluates it.

Parameters:

Name Type Description Default
model LinearGaussianModel | GraphBackend

a LinearGaussianModel, or a backend exposing model and predicted_belief (CouplingGraphBackend does).

required
belief Belief

the belief to predict from — the shared prior every action starts at.

required
actions Sequence[ArrayLike]

the candidate actions to sample.

required
tol float

below this, two noise covariances or two epistemic values count as equal.

1e-12

Returns:

Type Description
ProbeReport

Raises:

Type Description
TypeError

If model is a coupled graph backend's model, which leaves out the couplings.

ValueError

If actions is empty, or if a state-dependent Q(x) is not a covariance at one of the sampled means.

Source code in src/cpomdp/diagnostics.py
def probe_model(
    model: "LinearGaussianModel | GraphBackend",
    belief: "Belief",
    actions: Sequence[ArrayLike],
    *,
    tol: float = 1e-12,
) -> ProbeReport:
    """Probe a model's sensor over the predicted means a set of actions reaches.

    Each action is pushed through the prediction step to get ``(μ⁻, Σ⁻)``; the sensor is
    linearized at each ``μ⁻`` and the four conditions are evaluated over the resulting
    sample. This is the reachable set the conditions are about — vary ``actions`` to
    widen it. A state-dependent ``Q(x)`` enters ``Σ⁻`` at each ``μ⁻``, where the EFE
    kernel evaluates it.

    Args:
        model: a [`LinearGaussianModel`][cpomdp.LinearGaussianModel], or a backend
            exposing ``model`` and ``predicted_belief``
            ([`CouplingGraphBackend`][cpomdp.CouplingGraphBackend] does).
        belief: the belief to predict from — the shared prior every action starts at.
        actions: the candidate actions to sample.
        tol: below this, two noise covariances or two epistemic values count as equal.

    Returns:
        A [`ProbeReport`][cpomdp.ProbeReport].

    Raises:
        TypeError: If ``model`` is a coupled graph backend's model, which leaves
            out the couplings.
        ValueError: If ``actions`` is empty, or if a state-dependent ``Q(x)`` is not a
            covariance at one of the sampled means.
    """
    if len(actions) == 0:
        raise ValueError("probe_model needs at least one action to predict under.")

    if hasattr(model, "predicted_belief"):  # a graph backend
        backend = cast("GraphBackend", model)
        sensor_model = backend.model
        predicted = [backend.predicted_belief(belief, np.asarray(a)) for a in actions]
        means = np.asarray([np.asarray(p.mean, dtype=float) for p in predicted])
        covs = [np.asarray(p.cov, dtype=float) for p in predicted]
        dynamics_spread = 0.0  # the graph's transitions carry a fixed Q
    else:  # a flat LinearGaussianModel
        _refuse_graph_interface(model, "probe_model")
        sensor_model = model
        dynamics_matrix = np.asarray(model.dynamics_matrix, dtype=float)
        prior_mean = np.asarray(belief.mean, dtype=float)
        prior_cov = np.asarray(belief.cov, dtype=float)
        # A control-free model goes nowhere under any action, which is itself an answer:
        # every sample lands on the same predicted mean and the noise cannot move.
        if model.control_matrix is None:
            means = np.asarray([dynamics_matrix @ prior_mean for _ in actions])
        else:
            control_matrix = np.asarray(model.control_matrix, dtype=float)
            means = np.asarray(
                [
                    dynamics_matrix @ prior_mean
                    + control_matrix @ np.asarray(a, dtype=float).ravel()
                    for a in actions
                ]
            )
        propagated = dynamics_matrix @ prior_cov @ dynamics_matrix.T
        dynamics_noises = _dynamics_noises(
            model.dynamics_noise_model, model.dynamics_noise, means
        )
        covs = [propagated + q for q in dynamics_noises]
        dynamics_spread = _spread(dynamics_noises)
    observation_matrix = np.asarray(sensor_model.observation_matrix, dtype=float)
    noises = [
        np.asarray(sensor_model.observation_noise_at(mu), dtype=float) for mu in means
    ]

    rank = int(np.linalg.matrix_rank(observation_matrix))
    n_obs = int(observation_matrix.shape[0])

    indefinite = tuple(
        tuple(float(v) for v in mu)
        for mu, r in zip(means, noises, strict=True)
        if not is_positive_definite(r)
    )

    spread = _spread(noises)

    epistemics = [
        epistemic_value(cov, observation_matrix, r)
        for cov, r in zip(covs, noises, strict=True)
    ]
    finite = [e for e in epistemics if np.isfinite(e)]
    lo, hi = (min(finite), max(finite)) if finite else (float("nan"), float("nan"))

    # The extreme pair is the one most likely to be ordered; a strictly ordered pair is
    # enough on its own, so there is no need to walk every combination.
    comparable = False
    if finite and len(noises) > 1:
        i_lo = int(np.argmin([e if np.isfinite(e) else np.inf for e in epistemics]))
        i_hi = int(np.argmax([e if np.isfinite(e) else -np.inf for e in epistemics]))
        comparable = loewner_order(noises[i_lo], noises[i_hi]) in ("a<b", "b<a")

    return ProbeReport(
        n_samples=len(actions),
        n_observations=n_obs,
        observation_matrix_rank=rank,
        observation_matrix_full_row_rank=rank == n_obs,
        observation_noise_definite=not indefinite,
        observation_noise_indefinite_at=indefinite,
        observation_noise_varies=spread > tol,
        observation_noise_spread=spread,
        observation_noise_loewner_ordered=comparable,
        dynamics_noise_varies=dynamics_spread > tol,
        dynamics_noise_spread=dynamics_spread,
        epistemic_varies=bool(finite) and (hi - lo) > tol,
        epistemic_range=(lo, hi),
    )

ProbeReport dataclass

ProbeReport(
    n_samples: int,
    n_observations: int,
    observation_matrix_rank: int,
    observation_matrix_full_row_rank: bool,
    observation_noise_definite: bool,
    observation_noise_indefinite_at: tuple[
        tuple[float, ...], ...
    ],
    observation_noise_varies: bool,
    observation_noise_spread: float,
    observation_noise_loewner_ordered: bool,
    dynamics_noise_varies: bool,
    dynamics_noise_spread: float,
    epistemic_varies: bool,
    epistemic_range: tuple[float, float],
)

What probe_model found over the sampled reachable set.

Each field is named for the object it describes: the observation matrix C, the observation noise R, the dynamics noise Q or the epistemic value.

Attributes:

Name Type Description
n_samples int

how many predicted means were probed.

n_observations int

the number of observation channels, C's row count.

observation_matrix_rank int

the rank of C.

observation_matrix_full_row_rank bool

whether C has no redundant channels.

observation_noise_definite bool

whether R was positive definite at every sampled mean.

observation_noise_indefinite_at tuple[tuple[float, ...], ...]

the sampled means where it was not.

observation_noise_varies bool

whether R took more than one value across the samples.

observation_noise_spread float

the largest pairwise distance between the sampled R.

observation_noise_loewner_ordered bool

whether the extreme pair of sampled R is strictly ordered, the cheap sufficient condition for the epistemic value to move.

dynamics_noise_varies bool

whether Q took more than one value across the samples. Always False for a fixed Q.

dynamics_noise_spread float

the largest pairwise distance between the sampled Q.

epistemic_varies bool

whether the epistemic value differed across the samples.

epistemic_range tuple[float, float]

its smallest and largest sampled values, in nats.

flattens property

flattens: bool

Whether the sampled evidence says the noise is a constant in disguise.

True when neither R nor Q moved across the sampled means: the covariance recursion then never consults the action, so a fixed noise schedule reproduces the agent and the epistemic term cannot tell two policies apart. A Q(x) that moves keeps it False with R fixed, since the action then reaches the recursion through Q.

summary

summary() -> str

A few lines a human can read, one per condition.

Source code in src/cpomdp/diagnostics.py
def summary(self) -> str:
    """A few lines a human can read, one per condition."""
    lo, hi = self.epistemic_range
    mark = {True: "yes", False: "NO "}
    return "\n".join(
        [
            f"sampled {self.n_samples} predicted mean(s)",
            f"  full row rank C   {mark[self.observation_matrix_full_row_rank]}  "
            f"(rank {self.observation_matrix_rank} of {self.n_observations})",
            f"  R positive def.   {mark[self.observation_noise_definite]}  "
            f"({len(self.observation_noise_indefinite_at)} failing sample(s))",
            f"  R varies          {mark[self.observation_noise_varies]}  "
            f"(spread {self.observation_noise_spread:.3e})",
            f"  Q varies          {mark[self.dynamics_noise_varies]}  "
            f"(spread {self.dynamics_noise_spread:.3e})",
            f"  epistemic varies  {mark[self.epistemic_varies]}  "
            f"({lo:.6f} .. {hi:.6f} nats)",
            f"  R Loewner-ordered {mark[self.observation_noise_loewner_ordered]}",
        ]
    )

__str__

__str__() -> str

The same text summary returns.

Source code in src/cpomdp/diagnostics.py
def __str__(self) -> str:
    """The same text ``summary`` returns."""
    return self.summary()

A flat LinearGaussianModel and a graph backend reach their predicted means by different routes, so probe_model takes either. Pass a CouplingGraphBackend as the second.