Source code for hybrid_aif.distributions.joint

"""Joint categorical over several discrete axes: one simplex, jointly normalized.

``JointCategorical`` normalizes over all ``event_ndims`` trailing axes jointly; ``event_ndims``
is a static field (the event/batch split is not shape-derivable). It is isomorphic to a
Categorical on the flattened event axes, which supplies ``log_prob``/``entropy``/``kl_to``.

Design: docs/design/conditional-families.md (joint families)
"""

import math

import equinox as eqx
import jax.numpy as jnp
from jax import Array

from hybrid_aif.distributions.base import Distribution
from hybrid_aif.distributions.categorical import Categorical
from hybrid_aif.distributions.conditional import ConditionalCategorical
from hybrid_aif.interval import Interval


[docs] class JointCategorical(Distribution): """Joint distribution over ``event_ndims`` discrete axes. Samples and ``log_prob`` arguments are stacked ``int32`` indices with a trailing axis of length ``event_ndims``, one index per event axis. """ #: Unnormalized log-probabilities over the trailing ``event_ndims`` axes jointly, #: ``(..., *event_shape)`` (a single additive gauge for the whole table). logits: Array #: The number of trailing event axes. event_ndims: int = eqx.field(static=True) def __check_init__(self) -> None: if self.event_ndims < 1: raise ValueError(f"need event_ndims >= 1, got {self.event_ndims}") if self.logits.ndim < self.event_ndims: raise ValueError(f"logits rank {self.logits.ndim} < event_ndims {self.event_ndims}") @property def batch_shape(self) -> tuple[int, ...]: return self.logits.shape[: self.logits.ndim - self.event_ndims] @property def event_shape(self) -> tuple[int, ...]: return self.logits.shape[self.logits.ndim - self.event_ndims :] def _flat(self) -> Categorical: """The isomorphic Categorical on the flattened (row-major) event axes.""" n = math.prod(self.event_shape) return Categorical(logits=self.logits.reshape(self.batch_shape + (n,))) @property def log_probs(self) -> Array: """Jointly normalized log-probability table, same shape as ``logits``.""" return self._flat().log_probs.reshape(self.logits.shape) @property def probs(self) -> Array: return self._flat().probs.reshape(self.logits.shape) @classmethod def from_probs(cls, table: Array, event_ndims: int) -> "JointCategorical": return cls(logits=jnp.log(table), event_ndims=event_ndims) def _flat_index(self, x: Array) -> Array: idx = jnp.asarray(x) strides = [math.prod(self.event_shape[i + 1 :]) for i in range(self.event_ndims)] return jnp.sum(idx * jnp.asarray(strides, jnp.int32), axis=-1)
[docs] def log_prob(self, x: Array) -> Array: """Log mass at stacked indices ``x`` (trailing axis of length ``event_ndims``).""" return self._flat().log_prob(self._flat_index(x))
[docs] def sample(self, key: Array, sample_shape: tuple[int, ...] = ()) -> Array: """Stacked ``int32`` indices, shape ``sample_shape + batch_shape + (event_ndims,)``.""" flat = self._flat().sample(key, sample_shape) return jnp.stack(jnp.unravel_index(flat, self.event_shape), axis=-1).astype(jnp.int32)
[docs] def mean(self) -> Array: """Moment view: the joint probability table (one-hot expectation).""" return self.probs
[docs] def entropy(self) -> Interval: return self._flat().entropy()
[docs] def kl_to(self, other: "JointCategorical") -> Interval: if other.event_shape != self.event_shape: raise ValueError(f"event shapes differ: {self.event_shape} vs {other.event_shape}") return self._flat().kl_to(other._flat())
[docs] def to_conditional(self, child_axis: int) -> ConditionalCategorical: """P(child | rest): normalize along one event axis per configuration of the others. ``child_axis`` indexes the event block (negatives allowed). The child axis moves to the front of the structure block and the other event axes become parent axes in order; normalization happens on read, so the conversion is a pure axis move. """ n = self.event_ndims if n < 2: raise ValueError("to_conditional needs event_ndims >= 2") if not -n <= child_axis < n: raise ValueError(f"child_axis {child_axis} out of range for event_ndims {n}") offset = self.logits.ndim - n moved = jnp.moveaxis(self.logits, offset + child_axis % n, offset) return ConditionalCategorical(log_table=moved, parent_ndims=n - 1)
[docs] def marginalize(self, axes: int | tuple[int, ...]) -> "JointCategorical | Categorical": """Sum OUT the given event axes (event-relative indices; negatives allowed). Returns the joint over the remaining event axes, or a :class:`Categorical` when exactly one remains. """ if isinstance(axes, int): axes = (axes,) n = self.event_ndims norm = sorted({a % n for a in axes}) if len(norm) != len(axes): raise ValueError(f"duplicate axes in {axes}") if len(norm) >= n: raise ValueError("marginalize must keep at least one event axis") offset = self.logits.ndim - n summed = self.probs.sum(axis=tuple(offset + a for a in norm)) remaining = n - len(norm) if remaining == 1: return Categorical(logits=jnp.log(summed)) return JointCategorical(logits=jnp.log(summed), event_ndims=remaining)