Source code for hybrid_aif.cells

"""A categorical field over a continuous state: the grid that discretises a continuous factor
into cells, and the read from a position belief to a belief over the cell it falls in.

``System(cells={"x": Grid(...)})`` declares the grid; a tabular factor may then name ``x`` in
its ``B_deps``, its table's axis for that parent having one entry per cell, row-major over the
grid's shape. Design: docs/design/terrain-field.md.
"""

import dataclasses
import math

import jax
import jax.numpy as jnp
import numpy as np
from jax import Array
from jax.scipy.special import ndtr

from hybrid_aif.distributions import Categorical, Gaussian, MixtureGaussian


def _tuple(value, n: int, what: str, cast) -> tuple:
    """``value`` (a number, a sequence or an array, numpy or JAX) as ``n`` Python numbers: one
    number stands for every axis."""
    items = np.atleast_1d(np.asarray(value)).tolist()
    if len(items) == 1:
        items = items * n
    if len(items) != n:
        raise ValueError(
            f"Grid: {what} has {len(items)} entries for {n} axis/axes; give one per entry of "
            "shape, or a single number for every axis"
        )
    return tuple(cast(v) for v in items)


[docs] @dataclasses.dataclass(frozen=True) class Grid: """A rectangular grid over some coordinates of a continuous state factor's state. The cells are flattened in C order over ``shape``, so a table's parent axis for the state factor has :attr:`n_cells` entries. The first and last cell on each axis absorb the tail beyond the extent. """ #: The number of cells along each spanned axis. shape: tuple[int, ...] #: The lower end of the extent along each axis (one number each, or one number for every axis). low: tuple[float, ...] #: The upper end of the extent along each axis (one number each, or one number for every axis). high: tuple[float, ...] #: The state coordinates spanned, in order (``None``: ``0, 1, ...``). axes: tuple[int, ...] | None = None def __post_init__(self) -> None: shape = tuple(int(n) for n in np.atleast_1d(np.asarray(self.shape)).tolist()) k = len(shape) axes = ( tuple(range(k)) if self.axes is None else tuple(int(a) for a in np.atleast_1d(np.asarray(self.axes)).tolist()) ) low = _tuple(self.low, k, "low", float) high = _tuple(self.high, k, "high", float) if len(axes) != k: raise ValueError( f"Grid: axes={axes} names {len(axes)} coordinate(s) for shape={shape}; give one " "axis per entry of shape" ) if k == 0 or any(n < 1 for n in shape): raise ValueError(f"Grid: shape={shape} needs at least one cell along every axis") if len(set(axes)) != k or any(a < 0 for a in axes): raise ValueError(f"Grid: axes={axes} must be distinct non-negative coordinates") if any(not h > lo for lo, h in zip(low, high, strict=True)): raise ValueError(f"Grid: every axis needs low < high, got low={low}, high={high}") object.__setattr__(self, "shape", shape) object.__setattr__(self, "axes", axes) object.__setattr__(self, "low", low) object.__setattr__(self, "high", high) @property def n_cells(self) -> int: """The number of cells: the product of ``shape``.""" return math.prod(self.shape)
def _axis_masses(mean: Array, std: Array, n: int, low: float, high: float) -> Array: """The mass of ``Normal(mean, std)`` in each of ``n`` equal cells over ``[low, high]``, the first and last absorbing the tails: ``(..., n)``, summing to one.""" edges = jnp.linspace(low, high, n + 1)[1:-1] cdf = ndtr((edges - mean[..., None]) / std[..., None]) zeros = jnp.zeros((*cdf.shape[:-1], 1), cdf.dtype) # an axis of one cell has no edges cdf = jnp.concatenate([zeros, cdf, zeros + 1.0], axis=-1) return cdf[..., 1:] - cdf[..., :-1] def _gaussian_mass(loc: Array, chol: Array, grid: Grid) -> Array: """:func:`cell_mass` of one Gaussian: ``(..., cells)``.""" var = jnp.sum(chol**2, axis=-1) # the marginal variances: the squared row norms of the factor mass = jnp.ones((*loc.shape[:-1], 1), loc.dtype) for a, n, low, high in zip(grid.axes, grid.shape, grid.low, grid.high, strict=True): floor = 1e-6 * (high - low) std = jnp.sqrt(jnp.maximum(var[..., a], floor**2)) axis = _axis_masses(loc[..., a], std, n, low, high) mass = (mass[..., :, None] * axis[..., None, :]).reshape(*mass.shape[:-1], -1) return mass
[docs] def cell_mass(belief: Gaussian | MixtureGaussian, grid: Grid) -> Array: """The probability vector over the cells of ``grid`` that ``belief`` puts its mass in. A Gaussian's mass in a rectangular cell is the product of its marginal masses along the grid's axes, each a difference of the normal distribution function at the cell edges (the correlation between axes is dropped); the first and last cell on each axis absorb the tails. A mixture's is the weight-sum of its components' masses. Returns ``(*batch, cells)``, cells row-major over ``grid.shape``, summing to one, and smooth in the means. """ if isinstance(belief, MixtureGaussian): per = _gaussian_mass(belief.means, belief.chols, grid) # (..., K, cells) w = jax.nn.softmax(belief.log_weights, axis=-1) return jnp.sum(w[..., None] * per, axis=-2) if isinstance(belief, Gaussian): return _gaussian_mass(belief.loc, belief.chol, grid) raise TypeError( f"cell_mass reads a Gaussian or MixtureGaussian belief, got {type(belief).__name__}" )
def component_cell_mass(belief: MixtureGaussian, grid: Grid) -> Array: """Each component's :func:`cell_mass` of a mixture: ``(*batch, K, cells)``, the weights left out (the per-component read of a closed pair, design: parameters-within-the-plan.md D2).""" return _gaussian_mass(belief.means, belief.chols, grid) def cell_index(point: Array, grid: Grid) -> Array: """The cell of ``grid`` that ``point`` (a state of shape ``(..., dim)``) falls in, as an ``int32`` index into the cells in :class:`Grid`'s order (``(...)``): the first and last cell on each axis absorb the tail beyond the extent, as :func:`cell_mass` does.""" index = jnp.zeros(point.shape[:-1], jnp.int32) for a, n, low, high in zip(grid.axes, grid.shape, grid.low, grid.high, strict=True): edges = jnp.linspace(low, high, n + 1)[1:-1] along = jnp.sum(point[..., a, None] > edges, axis=-1).astype(jnp.int32) index = index * n + along return index def with_cell_parents(beliefs: tuple, grids: dict) -> tuple: """``beliefs`` with each factor in ``grids`` (factor index to :class:`Grid`) replaced by a :class:`~hybrid_aif.distributions.Categorical` over its cells, so a tabular reader sees a cell parent as it sees any categorical one.""" if not grids: return beliefs return tuple( Categorical.from_probs(jnp.maximum(cell_mass(q, grids[i]), 1e-30)) if i in grids else q for i, q in enumerate(beliefs) )