Source code for hybrid_aif.inference.detail
"""Structured record of what one ``infer_states`` sweep computed internally.
``infer_states`` always returns ``(beliefs, detail)``; ``detail=False`` puts ``None`` in the
second slot, and the beliefs are bitwise identical either way. The record surfaces quantities
inference would otherwise discard, such as a switching LG modality's grown mixture before
``pad_mixture`` loses the mode pairing.
Design: docs/design/parameter-learning.md O3
"""
from collections.abc import Mapping
import equinox as eqx
from jax import Array
#: A per-node field: a mapping keyed by name at the faces, a tuple in node order inside.
PerNode = Mapping[str, object] | tuple
[docs]
class InferenceDetail(eqx.Module):
"""Per-modality internals of one sweep; ``None`` where inapplicable.
The first three fields have one entry per modality, ``unsupported`` one per state factor. As
:meth:`System.infer_states <hybrid_aif.system.System.infer_states>` returns it (and
:meth:`~hybrid_aif.system.System.learn` takes it) each field is a mapping keyed by modality or
state factor name; inside, the same record holds tuples in declaration order
(``System.from_positional("detail", ...)`` / ``to_positional`` convert). Structure is static
for a fixed model, so the object is jit-safe.
"""
#: Per modality, a ``MixtureGaussian`` or ``None``. For a switching linear-Gaussian modality:
#: the grown ``K·M`` mixture before padding and reduction, its components pairing a mode
#: configuration with a prior component: the mode-conditional posterior the reduced belief no
#: longer carries.
pre_reduce: PerNode
#: Per modality, an array or ``None``. For a switching linear-Gaussian modality: the
#: integrated log-evidence per mode configuration (the boundary message read before
#: reduction). For a linear-Gaussian modality on a mode-aligned mixture: the per-component
#: observation log-likelihoods that formed the mode message.
mode_log_evidence: PerNode
#: Per modality, an array or ``None``. For any linear-Gaussian modality: the integrated
#: ``log p(y)`` under the beliefs the tick holds before this modality's message (after the
#: tabular stage), ``condition``'s second return; for a switching or mode-aligned mixture
#: modality, the total over mode configurations under that mode belief.
log_evidence: PerNode
#: Per state factor, a 0-d bool: ``True`` when no level was compatible with every present
#: tabular modality and the prior (``inference.discrete.unsupported``; Z1/Z2). It does not
#: attribute the contradiction: under mean-field, co-parents' flags fire too (exact
#: attribution: ``description.check_joint_support``). ``None`` for a continuous state factor.
#: Read off the tabular fixed-point stage, before any linear-Gaussian mode message.
unsupported: PerNode = ()
#: The tick's variational free energy, a scalar: the mean-field posteriors' KL from their
#: priors, less the expected tabular log-likelihoods, less every linear-Gaussian or neural
#: modality's integrated log-evidence (a neural modality's read linearised at the belief the
#: state factor holds when the modality is reached, so the bound is on the linearised model:
#: the ``approximate`` status of the planner's intervals), plus ``- log Z + E_q[log m]`` for
#: each recognition message ``m`` and ``- E_q[log p(o | s)]`` under the final belief for each
#: modality a recognition entry covers. ``-free_energy`` bounds the tick's log evidence from
#: below and equals it where every modality is linear-Gaussian or one categorical state
#: factor carries every tabular one (``inference.discrete.mean_field_free_energy``). ``None``
#: on the amortized path.
free_energy: Array | None = None
#: Analytic path with recognition entries: per entry, keyed ``"recognition:<variable>"``, the
#: log normaliser ``log Z`` of its message applied to the belief the tick holds before it
#: (``condition``'s log evidence for a Gaussian or mixture state factor, ``log sum_k q_k r_k``
#: for a categorical one); 0.0 for an entry absent at the tick. It is not a modality evidence
#: term: it enters ``free_energy`` through ``- log Z + E_q[log m]``.
recognition_log_evidence: Mapping[str, Array] = eqx.field(default_factory=dict)
#: Analytic path with recognition entries: per modality an entry covers, keyed by modality
#: name at the faces and inside alike, the ``- E_q[log p(o | s)]`` term it adds to
#: ``free_energy`` under the tick's final belief (a linear-Gaussian, emission or tabular
#: modality in closed form, a neural one to second order at each component's mean); 0.0 for
#: a covered modality absent at the tick. An uncovered modality has no entry. Each is a cost
#: (the negative of an expected log-likelihood), so it adds to ``free_energy`` where an
#: evidence term subtracts.
covered_terms: Mapping[str, Array] = eqx.field(default_factory=dict)