Source code for hybrid_aif.distributions.base

"""The distribution contract: the interface every belief, message payload and preference obeys.

This package is the pure-math bottom layer: no wiring, no block ids, no update rules.

1. **Pytree, value-semantic.** A Distribution is an ``equinox.Module`` whose leaves are
   ``jax.Array`` parameters, with no callables or shared mutable state, so it crosses any jit,
   vmap, scan or serialization boundary unchanged.
2. **Structure from shapes.** Static structure (event dim, number of states, mixture size K) is
   derived from leaf shapes; static fields only where it is not shape-derivable.
3. **Batch semantics.** Event/parameter structure occupies a fixed number of trailing axes,
   documented per class; ``batch_shape`` is everything to the left, with no ``to_event()``-style
   reinterpretation. Elementwise operations broadcast over batch axes; discrete selection
   (``reduce``, ``condition_on``) and heterogeneous-list inputs (``fpi``) batch via ``vmap``.
   Leaves carry mutually consistent, materialized batch axes (``broadcast_to`` at construction).
4. **Dual parameter views.** Each family stores its numerically safest parameterization;
   exponential-family members also provide ``natural()``/``from_natural()``, a round trip up to
   gauge and float error. Conjugate updates add in natural coordinates; rollouts read moments.
5. **Interval-typed uncertainty.** ``entropy()`` and ``kl_to()`` always return an
   :class:`~hybrid_aif.interval.Interval`: zero-width where a closed form exists, a genuine
   bound pair otherwise (mixtures).
6. **Sampling.** ``sample(key, sample_shape)`` takes a JAX PRNG key and a static sample shape;
   discrete draws are ``int32``. It is the default PRNG backend's kernel; distributions never
   change per backend.
7. **Dtype.** float32 unless a class documents otherwise.
"""

import abc

import equinox as eqx
from jax import Array

from hybrid_aif.interval import Interval


[docs] class Distribution(eqx.Module): """Abstract base for every belief, message payload and preference object. A Distribution is an ``equinox.Module`` whose leaves are ``jax.Array`` parameters (no callables, no shared mutable state), so it crosses any ``jit``, ``vmap``, ``scan`` or serialization boundary unchanged. Its family's event and parameter structure occupies a fixed number of trailing axes, documented per class; :attr:`batch_shape` is everything to the left, and elementwise methods broadcast over it. Static structure (event dimension, number of levels, mixture size) is read off the leaf shapes. Every subclass provides :attr:`batch_shape`, :meth:`log_prob`, :meth:`sample` (a JAX PRNG key and a static sample shape; discrete draws are ``int32``), :meth:`mean` (the moment view), and :meth:`entropy` and :meth:`kl_to`, which return an :class:`~hybrid_aif.interval.Interval`: zero-width where a closed form exists, a bound pair otherwise (mixtures). Arrays are float32 unless a class says otherwise. The full contract is the docstring of :mod:`hybrid_aif.distributions.base`. """ @property @abc.abstractmethod def batch_shape(self) -> tuple[int, ...]: """Leading (batch) axes: leaf shape minus the family's fixed trailing structure."""
[docs] @abc.abstractmethod def log_prob(self, x: Array) -> Array: """Log density/mass at ``x``; broadcasts over batch axes."""
[docs] @abc.abstractmethod def sample(self, key: Array, sample_shape: tuple[int, ...] = ()) -> Array: """Draw samples with shape ``sample_shape + batch_shape + event_shape``."""
[docs] @abc.abstractmethod def mean(self) -> Array: """Mean (moment view)."""
[docs] @abc.abstractmethod def entropy(self) -> Interval: """Differential/discrete entropy as an Interval (zero-width when exact)."""
[docs] @abc.abstractmethod def kl_to(self, other: "Distribution") -> Interval: """KL(self ‖ other) for ``other`` of the same family, as an Interval."""
[docs] class ExponentialFamily(Distribution): """A :class:`Distribution` in the exponential family, with a natural-parameter view. Each family stores its numerically safest parameterization and also provides :meth:`natural` and :meth:`from_natural`, a round trip up to a gauge constant and float error. Conjugate updates add in natural coordinates; rollouts read moments. """
[docs] @abc.abstractmethod def natural(self) -> tuple[Array, ...]: """Natural parameters as a tuple of arrays (gauge documented per class)."""
[docs] @classmethod @abc.abstractmethod def from_natural(cls, *natural_params: Array) -> "ExponentialFamily": """Inverse of :meth:`natural`, up to gauge and float error."""