"""Full-covariance multivariate Gaussian.
Stored parameterization: ``mean`` and lower-triangular Cholesky factor ``chol``
(numerically safest; log-dets and solves read off the factor). Event shape:
``(dim,)``. Natural view: ``eta1 = Σ⁻¹ μ``, ``eta2 = -0.5 Σ⁻¹``.
"""
import jax
import jax.numpy as jnp
from jax import Array
from jax.scipy.linalg import cho_solve, solve_triangular
from hybrid_aif.distributions.base import ExponentialFamily
from hybrid_aif.interval import Interval
_LOG_2PI = jnp.log(2.0 * jnp.pi)
[docs]
class Gaussian(ExponentialFamily):
"""A multivariate Gaussian with full covariance, batched over leading axes.
Stored as the mean ``loc`` and a lower-triangular Cholesky factor ``chol`` (log-determinants
and solves read off the factor); the event shape is ``(dim,)``. :meth:`from_cov` builds one
from a covariance, :attr:`cov` returns it, :meth:`kl_to` is the closed form (a
``MixtureGaussian`` other is handled through the mixture bounds), and the natural view is
``eta1 = Σ⁻¹ μ``, ``eta2 = -0.5 Σ⁻¹``.
"""
#: The mean, ``(..., dim)``.
loc: Array
#: The lower-triangular Cholesky factor of the covariance, ``(..., dim, dim)``. A preference
#: over a modality may instead give a diagonal standard deviation, the shape of ``loc``
#: (:attr:`diagonal`; :meth:`dense` expands it).
chol: Array
@property
def batch_shape(self) -> tuple[int, ...]:
return self.loc.shape[:-1]
@property
def dim(self) -> int:
return self.loc.shape[-1]
@property
def cov(self) -> Array:
return self.chol @ jnp.swapaxes(self.chol, -1, -2)
@property
def diagonal(self) -> bool:
"""Whether ``chol`` is a diagonal standard deviation ``(..., dim)``, the shape of ``loc``
(a full factor has one trailing axis more). Only a preference over a modality reads it as
such; every other method needs :meth:`dense`."""
return self.chol.shape == self.loc.shape
[docs]
def dense(self) -> "Gaussian":
"""The Gaussian with a full ``(..., dim, dim)`` factor (itself when it has one)."""
if not self.diagonal:
return self
eye = jnp.eye(self.dim, dtype=self.chol.dtype)
return Gaussian(loc=self.loc, chol=self.chol[..., :, None] * eye)
@classmethod
def from_cov(cls, loc: Array, cov: Array) -> "Gaussian":
return cls(loc=loc, chol=jnp.linalg.cholesky(cov))
def _half_log_det(self) -> Array:
return jnp.sum(jnp.log(jnp.diagonal(self.chol, axis1=-2, axis2=-1)), axis=-1)
[docs]
def log_prob(self, x: Array) -> Array:
dev = x - self.loc
z = solve_triangular(self.chol, dev[..., None], lower=True)[..., 0]
maha = jnp.sum(z**2, axis=-1)
return -0.5 * (self.dim * _LOG_2PI + maha) - self._half_log_det()
[docs]
def sample(self, key: Array, sample_shape: tuple[int, ...] = ()) -> Array:
eps = jax.random.normal(key, sample_shape + self.batch_shape + (self.dim,))
return self.loc + (self.chol @ eps[..., None])[..., 0]
[docs]
def mean(self) -> Array:
return self.loc
[docs]
def entropy(self) -> Interval:
return Interval.exact(0.5 * self.dim * (1.0 + _LOG_2PI) + self._half_log_det())
[docs]
def kl_to(self, other) -> Interval:
"""Closed-form Gaussian KL, computed via Cholesky solves.
A ``MixtureGaussian`` ``other`` is handled by promoting ``self`` to a 1-component mixture
and using the mixture bounds.
"""
from hybrid_aif.distributions.mixture import MixtureGaussian
if isinstance(other, MixtureGaussian):
return MixtureGaussian.from_gaussian(self).kl_to(other)
dev = other.loc - self.loc
z = solve_triangular(other.chol, dev[..., None], lower=True)[..., 0]
maha = jnp.sum(z**2, axis=-1)
m = solve_triangular(other.chol, self.chol, lower=True)
trace = jnp.sum(m**2, axis=(-2, -1))
log_det_ratio = 2.0 * (other._half_log_det() - self._half_log_det())
return Interval.exact(0.5 * (trace + maha - self.dim + log_det_ratio))
[docs]
def natural(self) -> tuple[Array, ...]:
prec = cho_solve((self.chol, True), jnp.broadcast_to(jnp.eye(self.dim), self.cov.shape))
eta1 = (prec @ self.loc[..., None])[..., 0]
return (eta1, -0.5 * prec)
[docs]
@classmethod
def from_natural(cls, eta1: Array, eta2: Array) -> "Gaussian":
chol = cholesky_of_inverse(-2.0 * eta2)
loc = (chol @ (jnp.swapaxes(chol, -1, -2) @ eta1[..., None]))[..., 0]
return cls(loc=loc, chol=chol)
def sigma_points(loc: Array, chol: Array, kappa: float = 1.0) -> tuple[Array, Array]:
"""Unscented-transform sigma points of ``N(loc, chol cholᵀ)``: ``2d+1`` points and weights.
The points are ``loc`` and ``loc ± √(d+κ) · chol[:, i]`` for each column ``i``; the weights
are ``κ/(d+κ)`` for the centre and ``1/(2(d+κ))`` for the rest. The weighted sum of ``f`` at
the points equals ``E[f(x)]`` exactly for every polynomial ``f`` of degree at most three, for
any ``κ > −d``; ``κ > 0`` makes every weight positive, so the estimate is a convex combination
of the point values.
Args:
loc: ``(..., d)`` mean; leading axes batch.
chol: ``(..., d, d)`` lower Cholesky factor of the covariance.
kappa: the centre's share of the spread (``κ`` above).
Returns:
``(points, weights)`` with shapes ``(..., 2d+1, d)`` and ``(2d+1,)``; point 0 is the
centre, points ``1..d`` the ``+`` side, ``d+1..2d`` the ``−`` side.
"""
d = loc.shape[-1]
scaled = jnp.sqrt(d + kappa) * jnp.swapaxes(chol, -1, -2) # (..., d, d): row i = column i
centre = loc[..., None, :]
points = jnp.concatenate([centre, centre + scaled, centre - scaled], axis=-2)
weights = jnp.concatenate(
[
jnp.asarray([kappa / (d + kappa)], dtype=loc.dtype),
jnp.full((2 * d,), 1.0 / (2.0 * (d + kappa)), dtype=loc.dtype),
]
)
return points, weights
def cholesky_of_inverse(a: Array) -> Array:
"""Lower Cholesky factor of ``A⁻¹`` for SPD ``A`` (leading batch axes allowed).
One Cholesky and one triangular solve: with ``J`` the index reversal and ``J A J = L Lᵀ``,
``J L⁻ᵀ J`` is the lower-triangular factor of ``A⁻¹``.
"""
rev = jnp.flip(jnp.flip(a, -1), -2)
l_rev = jnp.linalg.cholesky(rev)
eye = jnp.broadcast_to(jnp.eye(a.shape[-1], dtype=a.dtype), a.shape)
l_rev_inv = solve_triangular(l_rev, eye, lower=True)
return jnp.flip(jnp.flip(jnp.swapaxes(l_rev_inv, -1, -2), -1), -2)