"""Mean-field fixed-point iteration for factorized discrete models.
Each modality's likelihood is a raw log-likelihood tensor ``(num_obs_m, *[num_levels_f for f in
A_deps[m]])``, a :class:`ConditionalCategorical` (its normalized log table) or a
:class:`ConditionalDirichlet` (its ``expected_log_params`` table); priors are one
:class:`Categorical` per factor; observations are integer indices, one-hot arrays or probability
vectors (a soft observation), one per modality. Collections are canonically tuples; any sequence
is accepted. The iteration is
``Q(s_f) ∝ exp(E_{q(-f)}[log P(o|s)] + log prior_f)`` for a fixed number of sweeps (static
shapes, jit-safe, vmappable). Adapted from pymdp's ``algos.run_factorized_fpi`` (pymdp/algos.py);
pymdp is the parity oracle in tests/test_discrete_parity.py.
Design: docs/design/zero-support-evidence.md (tempering and the support flag);
nesting-and-coupling.md N8
"""
import math
import string
import jax
import jax.numpy as jnp
from jax import Array
from hybrid_aif.distributions import Categorical, ConditionalCategorical, ConditionalDirichlet
_AXES = string.ascii_lowercase
Likelihood = Array | ConditionalCategorical | ConditionalDirichlet
#: The tempering clip (``zero-support-evidence.md`` Z4): every log term the FPI reads is
#: clipped here, so ``-inf`` is a legal table entry and an all-impossible row normalises
#: instead of producing NaN. ``exp`` of it is exactly 0.0 in float32; it is not -1e30 because
#: a finite term added to -1e30 is lost to the ulp, and every impossible level would tie.
LOG_ZERO = -1.0e4
#: The default support floor of :func:`unsupported` (Z1/Z7), ``log(1e-12)``: below any
#: probability a composer meant to be possible, above any tempered zero.
SUPPORT_FLOOR = math.log(1e-12)
def unsupported(
log_priors: list[Array],
messages: list[list[Array]],
support_floor: float = SUPPORT_FLOOR,
) -> tuple[Array, ...]:
"""Per factor: is no level acceptable to every modality and the prior?
``messages[f]`` are the converged expected log-likelihood messages each present modality sends
factor ``f``; the prior is one more term. A level is acceptable to a term above
``support_floor``; the factor is unsupported when the maximum over levels of the minimum over
terms is below it. A masked-out modality sends the zero message, which no floor rejects.
Design: docs/design/zero-support-evidence.md Z1
"""
out = []
for lp, msgs in zip(log_priors, messages, strict=True):
worst = jnp.min(jnp.stack([lp, *msgs]), axis=0) if msgs else lp
out.append(jnp.max(worst, axis=-1) < support_floor)
return tuple(out)
def _as_log_likelihood(ll: Likelihood) -> Array:
"""Lower a likelihood input to the child-first log-likelihood tensor, tempered.
The clip at :data:`LOG_ZERO` happens before normalisation, so an all-``-inf`` parent column
does not normalise to ``NaN``. Every reader of a tabular likelihood lowers through here.
"""
if isinstance(ll, ConditionalDirichlet):
return jnp.maximum(ll.expected_log_params(), LOG_ZERO)
if isinstance(ll, ConditionalCategorical):
raw = ll.log_table
normalised = jax.nn.log_softmax(jnp.maximum(raw, LOG_ZERO), axis=ll._child_axis)
# an entry impossible before normalisation stays impossible after it (an all -inf
# column must not normalise to a uniform emission)
return jnp.where(raw <= LOG_ZERO, LOG_ZERO, normalised)
return jnp.maximum(jnp.asarray(ll), LOG_ZERO)
def _observed_log_likelihood(log_likelihood: Array, obs: Array) -> Array:
"""Contract the modality axis with an observation: an int index selects its slice; a float
vector, a one-hot or a probability vector, gives the expected log-likelihood under it (the
soft observation). Against the log of the expected likelihood it is a lower bound, exact when
the vector is a one-hot or the likelihood is constant over its support.
Design: nesting-and-coupling.md N8.
"""
if jnp.issubdtype(obs.dtype, jnp.integer):
return jnp.take(log_likelihood, obs, axis=0)
return jnp.tensordot(obs, log_likelihood, axes=([0], [0]))
def _marginalize_keep(ll: Array, qs: list[Array], keep: int) -> Array:
"""E_q[ll] over all local axes except ``keep``; static einsum from dep structure."""
in_sub = _AXES[: ll.ndim]
other = [(qs[j], _AXES[j]) for j in range(ll.ndim) if j != keep]
spec = ",".join([in_sub] + [s for _, s in other]) + "->" + _AXES[keep]
return jnp.einsum(spec, ll, *[q for q, _ in other])
def mean_field_free_energy(
log_likelihoods: tuple[Likelihood, ...],
A_deps: tuple[tuple[int, ...], ...],
priors: tuple[Categorical, ...],
posteriors: tuple[Categorical, ...],
observations: tuple[Array, ...],
masks: tuple[bool | Array, ...] | None = None,
) -> Array:
"""The variational free energy of mean-field ``posteriors`` for one tick's observations:
``Σ_f KL(q_f ‖ prior_f) − Σ_m E_{q(parents_m)}[log A_m[o_m | parents_m]]``, a scalar.
``−F`` is a lower bound on the tick's log evidence ``log p(o)`` under the priors, exact for
one factor whose posterior the sweep found; the terms are tempered as :func:`fpi` tempers
them, and a masked-out modality contributes nothing.
"""
total = jnp.zeros(())
for prior, q in zip(priors, posteriors, strict=True):
log_prior = jnp.maximum(prior.log_probs, LOG_ZERO)
probs = q.probs
total = total + jnp.sum(jax.scipy.special.xlogy(probs, probs) - probs * log_prior)
for m, (ll, obs, deps) in enumerate(zip(log_likelihoods, observations, A_deps, strict=True)):
present = True if masks is None else masks[m]
if present is False:
continue
observed = _observed_log_likelihood(_as_log_likelihood(ll), jnp.asarray(obs))
expected = observed
for f in reversed(deps): # contract the parent axes, last first
expected = jnp.tensordot(expected, posteriors[f].probs, axes=([expected.ndim - 1], [0]))
if present is not True:
expected = jnp.where(jnp.asarray(present), expected, jnp.zeros_like(expected))
total = total - expected
return total
[docs]
def fpi(
log_likelihoods: tuple[Likelihood, ...],
A_deps: tuple[tuple[int, ...], ...],
priors: tuple[Categorical, ...],
observations: tuple[Array, ...],
num_iters: int = 16,
masks: tuple[bool | Array, ...] | None = None,
) -> tuple[Categorical, ...]:
"""Mean-field posteriors over state factors given one observation per modality.
:func:`fpi_support` is the same sweep, also returning the per-factor ``unsupported`` flags.
Every log term is clipped at :data:`LOG_ZERO` on the way in, so ``-inf`` entries are legal and
an observation no state can explain gives a finite posterior rather than ``NaN``. The returned
logits are unnormalised (messages plus log prior).
``masks``, one entry per modality, marks which observations are present; a masked-out modality
contributes the zero message. A Python ``False`` skips the modality statically and never reads
its observation (which may be ``None``); a traced flag selects at run time, so padding of the
right shape must be there.
Design: docs/design/zero-support-evidence.md Z4
"""
return fpi_support(log_likelihoods, A_deps, priors, observations, num_iters, masks)[0]
def fpi_support(
log_likelihoods: tuple[Likelihood, ...],
A_deps: tuple[tuple[int, ...], ...],
priors: tuple[Categorical, ...],
observations: tuple[Array, ...],
num_iters: int = 16,
masks: tuple[bool | Array, ...] | None = None,
support_floor: float = SUPPORT_FLOOR,
support_exempt: tuple[int, ...] = (),
) -> tuple[tuple[Categorical, ...], tuple[Array, ...]]:
""":func:`fpi`, returning ``(beliefs, unsupported)`` — see :func:`unsupported`.
``support_exempt`` names modalities whose messages the support check skips: a density's
scores (a Gaussian emission's) are not probabilities, and a density has every level in its
support.
"""
obs_lls = []
for m, (ll, obs) in enumerate(zip(log_likelihoods, observations, strict=True)):
tensor = _as_log_likelihood(ll) # tempered on the way in: -inf is legal
present = True if masks is None else masks[m]
if present is False: # statically absent: the observation is never read
obs_lls.append(jnp.zeros(tensor.shape[1:], tensor.dtype))
continue
observed = _observed_log_likelihood(tensor, jnp.asarray(obs))
if present is not True:
observed = jnp.where(jnp.asarray(present), observed, jnp.zeros_like(observed))
obs_lls.append(observed)
log_priors = [jnp.maximum(p.log_probs, LOG_ZERO) for p in priors]
def messages(log_q: list[Array], skip: tuple[int, ...] = ()) -> list[list[Array]]:
q = [jax.nn.softmax(lq, axis=-1) for lq in log_q]
per_factor: list[list[Array]] = [[] for _ in log_priors]
for m, deps in enumerate(A_deps):
if m in skip:
continue
local_qs = [q[f] for f in deps]
for i, f in enumerate(deps):
per_factor[f].append(_marginalize_keep(obs_lls[m], local_qs, i))
return per_factor
def sweep(log_q: list[Array], _: None) -> tuple[list[Array], None]:
per_factor = messages(log_q)
return [
sum(msgs, jnp.zeros_like(lp)) + lp
for msgs, lp in zip(per_factor, log_priors, strict=True)
], None
init = [jnp.zeros_like(lp) for lp in log_priors]
log_q, _ = jax.lax.scan(sweep, init, None, length=num_iters)
flags = unsupported(log_priors, messages(log_q, tuple(support_exempt)), support_floor)
return tuple(Categorical(logits=lq) for lq in log_q), flags