Source code for hybrid_aif.distributions.noise_priors

"""Conjugate priors over LG observation noise: inverse-Gamma and inverse-Wishart.

They sit in ``LinearGaussianObservation.noise`` in place of a point ``R_chol``; leading axes are
parent (mode) axes. Conditioning consumes a precision, so ``point()`` returns the Cholesky
factor of the inverse expected precision ``E[R⁻¹]⁻¹`` (``β/α`` per dimension; ``Ψ/ν``), not the
mean covariance (``mean()``, a diagnostic). ``expected_log_params`` and ``novelty`` raise:
nothing consumes ``E[log R]``, and continuous parameter novelty is deferred (D6). These families
have no canonical decay anchor (the improper limits are the floors decay must not cross), so
``decay < 1`` requires explicit anchors and raises otherwise.

Design: docs/design/parameter-learning.md D7, D8
"""

import equinox as eqx
import jax
import jax.numpy as jnp
import numpy as np
from jax import Array
from jax.scipy.linalg import cho_solve, solve_triangular

from hybrid_aif.distributions._deferrals import deferred_novelty
from hybrid_aif.distributions.gaussian import cholesky_of_inverse


def _anchored(x: Array, anchor: Array | None, stats: Array, lr, decay, what: str) -> Array:
    """Decayed-count kernel with a required anchor.

    A static ``decay == 1.0`` takes the pure-conjugate branch ``x + lr·stats`` (bitwise); any other
    decay, traced included, needs the anchor.
    """
    if isinstance(decay, int | float) and float(decay) == 1.0:
        return x + lr * stats
    if anchor is None:
        raise ValueError(
            f"decay < 1 on an LG noise prior requires an explicit {what} anchor: "
            "the improper limit is exactly the floor decay must not cross (D7)"
        )
    return decay * x + (1.0 - decay) * anchor + lr * stats


def _check_positive(name: str, value: Array | None) -> None:
    if value is None or isinstance(value, jax.core.Tracer):
        return
    v = np.asarray(value)
    if not np.all(np.isfinite(v) & (v > 0.0)):
        raise ValueError(f"{name} must be finite and strictly positive")


def _check_nu_floor(nu: Array, d: int) -> None:
    """Raise unless a concrete ``nu`` exceeds the inverse-Wishart propriety floor ``d − 1``."""
    if isinstance(nu, jax.core.Tracer):
        return
    v = np.asarray(nu)
    if not np.all(np.isfinite(v) & (v > d - 1.0)):
        raise ValueError(f"nu must exceed the propriety floor d - 1 = {d - 1}")


[docs] class InverseGamma(eqx.Module): """Independent inverse-Gamma posteriors over per-dimension noise variances. ``alpha``/``beta`` are ``(*parent_shape, d_obs)``: one (shape, rate) pair per observation dimension per parent configuration. Isotropic noise is the ``d_obs = 1`` case. """ #: The shape parameters, ``(..., d_obs)``. alpha: Array #: The rate parameters, ``(..., d_obs)``. beta: Array #: The decay anchor for ``alpha`` (design D7); required iff ``decay < 1``. alpha0: Array | None = None #: The decay anchor for ``beta`` (design D7); required iff ``decay < 1``. beta0: Array | None = None def __check_init__(self) -> None: if self.alpha.shape != self.beta.shape: raise ValueError(f"alpha shape {self.alpha.shape} != beta shape {self.beta.shape}") for name, v in (("alpha", self.alpha), ("beta", self.beta)): _check_positive(name, v) for name, v in (("alpha0", self.alpha0), ("beta0", self.beta0)): if v is not None and v.shape != self.alpha.shape: raise ValueError(f"{name} shape {v.shape} != parameter shape {self.alpha.shape}") _check_positive(name, v)
[docs] @classmethod def from_R_chol(cls, R_chol: Array, strength: float = 1.0, anchor: bool = False): """Prior centred on a known noise level: ``point()`` reproduces ``R_chol`` exactly, and ``strength`` counts pseudo-observations (``α = strength/2``). ``anchor=True`` stores the initial parameters as the decay anchors.""" sigma2 = jnp.diagonal(R_chol @ jnp.swapaxes(R_chol, -1, -2), axis1=-2, axis2=-1) alpha = jnp.full_like(sigma2, strength / 2.0) beta = alpha * sigma2 return cls( alpha=alpha, beta=beta, alpha0=alpha if anchor else None, beta0=beta if anchor else None, )
@property def obs_dim(self) -> int: return self.alpha.shape[-1]
[docs] def expected_precision(self) -> Array: """``E[1/σ²] = α/β`` per dimension — what mean-field conditioning consumes.""" return self.alpha / self.beta
[docs] def point(self) -> Array: """``R_chol`` under the expected-precision substitution: ``diag(sqrt(β/α))``. Not the mean covariance (:meth:`mean`): conditioning consumes a precision. """ return _diag_chol(jnp.sqrt(self.beta / self.alpha))
[docs] def mean(self) -> Array: """``E[σ²] = β/(α−1)`` per dimension (α > 1) — diagnostic, not consumed.""" return self.beta / (self.alpha - 1.0)
[docs] def stats(self, scatter: Array, count: Array) -> tuple[Array, Array]: """Package one tick's statistic: the responsibility-weighted residual scatter diagonal ``(..., d_obs)`` and the responsibility mass ``(...,)`` (the degrees-of-freedom increment). """ return scatter, count
def absorb(self, stats: tuple[Array, Array], lr=1.0, decay=1.0) -> "InverseGamma": scatter, count = stats return InverseGamma( alpha=_anchored(self.alpha, self.alpha0, count[..., None] / 2.0, lr, decay, "alpha0"), beta=_anchored(self.beta, self.beta0, scatter / 2.0, lr, decay, "beta0"), alpha0=self.alpha0, beta0=self.beta0, )
[docs] def sample(self, key: Array) -> Array: """One noise draw as an ``R_chol`` array: ``σ² ~ InvGamma(α, β)`` per dim.""" return _diag_chol(jnp.sqrt(self.beta / jax.random.gamma(key, self.alpha)))
def expected_log_params(self) -> Array: raise NotImplementedError( "LG inference consumes the expected precision (point()), not an E[log R] " "table; no consumer exists (design: parameter-learning.md D8)" ) def novelty(self) -> Array: raise deferred_novelty("an LG noise posterior")
[docs] class InverseWishart(eqx.Module): """Inverse-Wishart posterior over a full noise covariance. ``Psi`` is ``(*parent_shape, d, d)`` (positive definite), ``nu`` is ``(*parent_shape,)`` with the propriety floor ``ν > d − 1`` (the mean exists from ``ν > d + 1``). """ #: The positive-definite scale matrices, ``(..., d, d)``. Psi: Array #: The degrees of freedom, ``(...,)``. nu: Array #: The decay anchor for ``Psi`` (design D7); required iff ``decay < 1``. Psi0: Array | None = None #: The decay anchor for ``nu`` (design D7); required iff ``decay < 1``. nu0: Array | None = None def __check_init__(self) -> None: d = self.Psi.shape[-1] if self.Psi.shape[-2] != d: raise ValueError(f"Psi must be square, got {self.Psi.shape}") if self.nu.shape != self.Psi.shape[:-2]: raise ValueError(f"nu shape {self.nu.shape} != Psi batch shape {self.Psi.shape[:-2]}") _check_nu_floor(self.nu, d) for name, v in (("Psi0", self.Psi0), ("nu0", self.nu0)): if v is not None: _check_positive(name if name == "nu0" else f"{name} diagonal", v) @property def obs_dim(self) -> int: return self.Psi.shape[-1]
[docs] def expected_precision(self) -> Array: """``E[R⁻¹] = ν Ψ⁻¹`` — what mean-field conditioning consumes.""" eye = jnp.broadcast_to(jnp.eye(self.obs_dim, dtype=self.Psi.dtype), self.Psi.shape) return self.nu[..., None, None] * cho_solve((jnp.linalg.cholesky(self.Psi), True), eye)
[docs] def point(self) -> Array: """``R_chol`` under the expected-precision substitution: ``chol(Ψ/ν)``.""" return jnp.linalg.cholesky(self.Psi / self.nu[..., None, None])
[docs] def mean(self) -> Array: """``E[R] = Ψ/(ν − d − 1)`` (ν > d+1) — diagnostic, not consumed.""" return self.Psi / (self.nu - self.obs_dim - 1.0)[..., None, None]
[docs] def stats(self, scatter: Array, count: Array) -> tuple[Array, Array]: """Package one tick's statistic: full residual scatter ``(..., d, d)`` and responsibility mass ``(...,)``.""" return scatter, count
def absorb(self, stats: tuple[Array, Array], lr=1.0, decay=1.0) -> "InverseWishart": scatter, count = stats return InverseWishart( Psi=_anchored(self.Psi, self.Psi0, scatter, lr, decay, "Psi0"), nu=_anchored(self.nu, self.nu0, count, lr, decay, "nu0"), Psi0=self.Psi0, nu0=self.nu0, )
[docs] def sample(self, key: Array) -> Array: """One noise draw as an ``R_chol`` array, via the Bartlett decomposition of ``W ~ Wishart(ν, Ψ⁻¹)`` and ``R = W⁻¹``.""" d = self.obs_dim batch = self.Psi.shape[:-2] kg, kn = jax.random.split(key) i = jnp.arange(d, dtype=self.Psi.dtype) # diag_j ~ sqrt(chi2(nu - j)) = sqrt(2 * Gamma((nu - j)/2)) df = (self.nu[..., None] - i) / 2.0 diag = jnp.sqrt(2.0 * jax.random.gamma(kg, df)) lower = jnp.tril(jax.random.normal(kn, (*batch, d, d)), k=-1) a = lower + _diag_embed(diag) # W = (L A)(L A)^T with L = chol(Psi^{-1}) and L A lower-triangular, so # R = W^{-1} = M^T M with M = (L A)^{-1} from one triangular solve. la = cholesky_of_inverse(self.Psi) @ a eye = jnp.broadcast_to(jnp.eye(d, dtype=la.dtype), la.shape) m = solve_triangular(la, eye, lower=True) return jnp.linalg.cholesky(jnp.swapaxes(m, -1, -2) @ m)
def expected_log_params(self) -> Array: raise NotImplementedError( "LG inference consumes the expected precision (point()), not an E[log R] " "table; no consumer exists (design: parameter-learning.md D8)" ) def novelty(self) -> Array: raise deferred_novelty("an LG noise posterior")
def _diag_chol(diag: Array) -> Array: """Embed per-dimension scales ``(..., d)`` as diagonal ``(..., d, d)`` factors.""" return _diag_embed(diag) def _diag_embed(diag: Array) -> Array: return diag[..., None] * jnp.eye(diag.shape[-1], dtype=diag.dtype)