"""Dirichlet distribution over probability vectors of ``num_levels`` outcomes.
Stored parameterization: ``concentration`` (positive counts). Event shape ``(num_levels,)``;
natural view ``eta = concentration - 1``. As a declaration (a learnable initial-state prior) it
satisfies :class:`~hybrid_aif.distributions.learnable.Learnable`.
Design: docs/design/parameter-learning.md D5
"""
import jax
import jax.core
import jax.numpy as jnp
import numpy as np
from jax import Array
from jax.scipy.special import digamma, gammaln
from hybrid_aif.distributions.base import ExponentialFamily
from hybrid_aif.distributions.categorical import Categorical
from hybrid_aif.interval import Interval
#: pymdp's MINVAL clip constant (shared by the exact ``spm_wnorm`` port below).
_MINVAL = float(jnp.finfo(jnp.float64).eps)
def _trigamma(x: Array) -> Array:
"""``ψ'(x)`` for ``x > 0``: the recurrence ``ψ'(x) = ψ'(x + 1) + 1/x²`` up to ``x ≥ 10``, then
the asymptotic series (relative error below 1e-11 there). Elementwise and cheap, where
``jax.scipy.special.polygamma(1, ·)`` (the derivative JAX gives ``digamma``) sums a Hurwitz
zeta series."""
acc = jnp.zeros_like(x)
for _ in range(10):
small = x < 10.0
acc = acc + jnp.where(small, 1.0 / (x * x), 0.0)
x = jnp.where(small, x + 1.0, x)
r = 1.0 / x
r2 = r * r
series = r2 * (1.0 / 6 - r2 * (1.0 / 30 - r2 * (1.0 / 42 - r2 / 30)))
return acc + r + 0.5 * r2 + r * series
@jax.custom_jvp
def _digamma(x: Array) -> Array:
"""``digamma`` with :func:`_trigamma` as its derivative: the same values, and a gradient
cheap enough to run at every step of a planning scan that differentiates novelty weights
of working counts (design: parameters-within-the-plan.md, "As built")."""
return digamma(x)
@_digamma.defjvp
def _digamma_jvp(primals, tangents):
(x,), (dx,) = primals, tangents
return digamma(x), _trigamma(x) * dx
def _wnorm(concentration: Array, child_axis: int) -> Array:
"""Exact Dirichlet novelty weights: pymdp's ``maths._exact_wnorm`` (pymdp/maths.py), after
SPM's ``spm_wnorm`` (the subfunction in ``toolbox/DEM/spm_MDP_VB_XXX.m``; Da Costa et al. 2020
eq. D.15), sign-flipped to better-when-larger. The ``(α > 0)`` mask is the one SPM's
``spm_MDP_VB_X`` applies to ``wA``/``wB``, carried by pymdp's
``control.calc_negative_pA_info_gain``. SPM also floors the weights at zero and skips tables
whose counts all reach 256; this clips at eps instead."""
safe = jnp.clip(concentration, _MINVAL)
safe_sum = jnp.clip(safe.sum(axis=child_axis, keepdims=True), _MINVAL)
w = (
jnp.log(safe_sum)
- jnp.log(safe)
+ 1.0 / safe
- 1.0 / safe_sum
+ _digamma(safe)
- _digamma(safe_sum)
)
return w * (concentration > 0.0)
def _absorbed(concentration: Array, alpha0: Array | None, stats: Array, lr, decay) -> Array:
"""Shared decayed-count kernel: ``decay·α + (1−decay)·anchor + lr·stats``.
A static ``decay == 1.0`` takes the pure-conjugate branch ``α + lr·stats``, bitwise identical to
the no-forgetting update, and never reads the anchor. Any other decay, traced included, needs
``alpha0``: the declaration's own concentration (forget toward the prior) or a scalar
(forget toward a uniform table) are the two usual choices; a declaration with none raises.
Anchors are validated strictly positive, but a very small anchor with ``decay < 1`` still
drives ``digamma(α)`` toward ``−∞`` in every expected-log consumer.
Design: docs/design/parameter-learning.md D7
"""
if isinstance(decay, int | float) and float(decay) == 1.0:
return concentration + lr * stats
if alpha0 is None:
raise ValueError(
"a decay other than a static 1.0 on a Dirichlet declaration needs an anchor to "
"relax toward, alpha0: its own concentration (the prior; one more table of "
"parameters) or a scalar 1.0 (a uniform table; free), as in "
"Dirichlet(concentration, alpha0=jnp.asarray(1.0)); ConditionalDirichlet.from_table "
"takes anchor='prior' or anchor='uniform' (D7)"
)
return decay * concentration + (1.0 - decay) * alpha0 + lr * stats
def anchor_for(concentration: Array, anchor: str | bool | Array | None) -> Array | None:
"""The ``alpha0`` a constructor stores for ``anchor``: ``"prior"`` or ``True`` is the
concentration itself, ``"uniform"`` a scalar ``1.0``, ``False`` or ``None`` nothing, and an
array is kept as given, in the concentration's dtype."""
if anchor is None or anchor is False:
return None
if anchor is True:
return concentration
if isinstance(anchor, str):
if anchor == "prior":
return concentration
if anchor == "uniform":
return jnp.asarray(1.0, concentration.dtype)
raise ValueError(
f"anchor must be 'prior', 'uniform', a bool, an array or None, got {anchor!r}"
)
return jnp.asarray(anchor, concentration.dtype)
def _concrete(value: Array):
"""``value`` as a NumPy array when it is concrete, ``None`` under a trace. The check goes
through NumPy because an array operation inside a trace is staged even on a constant."""
if isinstance(value, jax.core.Tracer):
return None
try:
return np.asarray(value)
except jax.errors.TracerArrayConversionError:
return None
def _check_anchor(alpha0: Array | None, concentration: Array) -> None:
"""Construction-time anchor validation (D7): a scalar or the concentration's shape; values
when concrete."""
if alpha0 is None:
return
if alpha0.ndim != 0 and alpha0.shape != concentration.shape:
raise ValueError(
f"alpha0 (decay anchor) has shape {alpha0.shape}, expected a scalar or the "
f"concentration shape {concentration.shape}"
)
value = _concrete(alpha0)
if value is not None and not bool(np.all(np.isfinite(value) & (value > 0.0))):
raise ValueError("alpha0 (decay anchor) must be finite and strictly positive")
def _check_growth(growth: Array | None) -> None:
"""Construction-time check of the growth propensity: a scalar, positive when concrete."""
if growth is None:
return
if growth.ndim != 0:
raise ValueError(f"growth (the growth propensity α) is a scalar, got shape {growth.shape}")
value = _concrete(growth)
if value is not None and not bool(np.isfinite(value) & (value > 0.0)):
raise ValueError("growth (the growth propensity α) must be finite and strictly positive")
[docs]
class Dirichlet(ExponentialFamily):
"""A Dirichlet distribution over the ``num_levels`` simplex, batched over leading axes.
The learnable form of a categorical prior (a point :class:`Categorical`'s conjugate):
:meth:`point` gives the expected categorical, :meth:`stats` and :meth:`absorb` are the count
update, :meth:`novelty` the novelty of the counts. Design: docs/design/parameter-learning.md
D7; docs/design/structure-learning.md S3.
"""
#: Positive counts, ``(..., num_levels)``.
concentration: Array
#: The decay anchor a ``decay < 1`` update relaxes toward: the prior's own concentration, a
#: scalar (uniform), or ``None``.
alpha0: Array | None = None
#: The growth propensity ``α`` of a growable state factor, a scalar or ``None``: the
#: pseudo-count the prior gives a level not yet live. A level with zero concentration is absent
#: from the family whatever ``growth`` says; ``growth`` is what lets such a level be woken, and
#: without it the level stays absent.
growth: Array | None = None
def __check_init__(self) -> None:
_check_anchor(self.alpha0, self.concentration)
_check_growth(self.growth)
@property
def batch_shape(self) -> tuple[int, ...]:
return self.concentration.shape[:-1]
@property
def num_levels(self) -> int:
return self.concentration.shape[-1]
def _total(self) -> Array:
return jnp.sum(self.concentration, axis=-1)
def _log_beta(self) -> Array:
return jnp.sum(gammaln(self.concentration), axis=-1) - gammaln(self._total())
[docs]
def log_prob(self, x: Array) -> Array:
return jnp.sum((self.concentration - 1.0) * jnp.log(x), axis=-1) - self._log_beta()
[docs]
def sample(self, key: Array, sample_shape: tuple[int, ...] = ()) -> Array:
return jax.random.dirichlet(key, self.concentration, shape=sample_shape + self.batch_shape)
[docs]
def mean(self) -> Array:
return self.concentration / self._total()[..., None]
[docs]
def mode(self) -> Array:
"""Density mode; defined only when all concentrations exceed 1."""
return (self.concentration - 1.0) / (self._total() - self.num_levels)[..., None]
[docs]
def expected_log_params(self) -> Array:
"""E[log p] per level (digamma differences), averaging over the parameters.
Unnormalized as a log-prior, so an FPI prior takes ``log(mean())`` via :meth:`point`
instead.
"""
return digamma(self.concentration) - digamma(self._total())[..., None]
[docs]
def point(self) -> Categorical:
"""Posterior-mean probability vector as a :class:`Categorical` (the slot's
point form).
"""
return Categorical(logits=jnp.log(self.mean()))
[docs]
def stats(self, child_obs: Array) -> Array:
"""One tick's sufficient statistic: onehot of an index, or a probability
vector (e.g. ``q(s_0)`` for an initial-prior count update) passed through."""
obs = jnp.asarray(child_obs)
if jnp.issubdtype(obs.dtype, jnp.integer):
obs = jax.nn.one_hot(obs, self.num_levels, dtype=self.concentration.dtype)
return obs
[docs]
def absorb(self, stats: Array, lr: float | Array = 1.0, decay: float | Array = 1.0):
"""Absorb one tick's statistic: ``decay·α + (1−decay)·anchor + lr·stats``.
A static ``decay=1.0`` is the exact conjugate update, bitwise; any other decay needs
``alpha0`` (see ``_absorbed``).
"""
return Dirichlet(
concentration=_absorbed(self.concentration, self.alpha0, stats, lr, decay),
alpha0=self.alpha0,
growth=self.growth,
)
[docs]
def novelty(self) -> Array:
"""Parameter-info-gain weights over the levels (exact ``spm_wnorm``,
better-when-larger, zero counts masked)."""
return _wnorm(self.concentration, -1)
[docs]
def entropy(self) -> Interval:
a, a0 = self.concentration, self._total()
h = (
self._log_beta()
+ (a0 - self.num_levels) * digamma(a0)
- jnp.sum((a - 1.0) * digamma(a), axis=-1)
)
return Interval.exact(h)
[docs]
def kl_to(self, other: "Dirichlet") -> Interval:
a, b = self.concentration, other.concentration
a0 = self._total()
kl = (
other._log_beta()
- self._log_beta()
+ jnp.sum((a - b) * (digamma(a) - digamma(a0)[..., None]), axis=-1)
)
return Interval.exact(kl)
[docs]
def natural(self) -> tuple[Array, ...]:
return (self.concentration - 1.0,)
[docs]
@classmethod
def from_natural(cls, eta: Array) -> "Dirichlet":
return cls(concentration=eta + 1.0)