MixtureGaussian#

class hybrid_aif.MixtureGaussian[source]#

Bases: Distribution

Gaussian mixture belief.

log_weights are defined up to an additive gauge: every method is gauge-invariant in them and may return any gauge (reduce returns normalized weights).

log_weights: Array#

The components’ log weights, (..., K), up to an additive gauge.

means: Array#

The components’ means, (..., K, dim).

chols: Array#

The components’ lower-triangular Cholesky factors, (..., K, dim, dim).

property batch_shape: tuple[int, ...]#

Leading (batch) axes: leaf shape minus the family’s fixed trailing structure.

property components: Gaussian#

The K components as a Gaussian with a trailing batch axis of size K.

classmethod from_gaussian(g)[source]#

Promote a Gaussian to the equivalent single-component (K=1) mixture.

log_prob(x)[source]#

Log density/mass at x; broadcasts over batch axes.

sample(key, sample_shape=())[source]#

Draw samples with shape sample_shape + batch_shape + event_shape.

mean()[source]#

Mean (moment view).

cov()[source]#

Exact mixture covariance: E[Σ_z] + Cov[μ_z].

moment_match()[source]#

Exact single-Gaussian collapse (preserves mean and covariance).

entropy()[source]#

Kolchinsky–Tracey pairwise bounds: Ĥ_D = Σᵢwᵢ H(pᵢ) − Σᵢwᵢ log Σⱼwⱼ e^{−D(pᵢ‖pⱼ)}.

D = Bhattacharyya → lower bound; D = KL → upper bound.

cross_entropy_to(other)[source]#

CE(f, g) = −E_f[log g] bounds (Kolchinsky–Tracey §4), f = self.

  • upper (variational): CE ≤ Σ_i w_i H(f_i) − Σ_i w_i log Σ_j v_j e^{−KL(f_i‖g_j)};

  • lower (Jensen): E_{f_i}[−log g] ≥ −log Σ_j v_j Z_ij, with Z_ij = ∫ f_i g_j = N(μ_i; ν_j, Σ_i + Λ_j).

A plain Gaussian other is promoted via from_gaussian(). When g has one component the upper bound equals the exact cross-entropy and the interval collapses to a point, which makes a Gaussian preference’s utility over a mixture observation exact.

kl_to(other)[source]#

Mixture-mixture KL bounds via KL(f‖g) = CE(f,g) − H(f) (Kolchinsky–Tracey §4).

Lower = CE_lo − H_hi, clamped at 0; upper = CE_hi − H_lo. With a single-component other the width is f’s entropy-bound width, zero when f is a single Gaussian.

reduce(k, aux=None)[source]#

Runnalls (2007) greedy reduction to exactly k components.

Exactly K−k merge iterations (a fixed trip count). Each merges the valid pair of least cost B(i,j) = ½[(w_i+w_j)·logdet Σ_ij − w_i·logdet Σ_i − w_j·logdet Σ_j] (Σ_ij the moment-matched merge) into slot min(i,j) and retires slot max(i,j). Dead (-inf) components are merged first; a surplus of dead components survives as dead output slots. The output is compacted to the top-k slots by log-weight (descending, ties by slot index) and renormalized. Gradients are defined a.e. but discontinuous at merge-decision boundaries.

aux is a per-component side statistic (a pytree of arrays, each with the component axis where log_weights has it, (..., K, ...)): it rides through the reduction by the assignment that merges the moments, a merged slot holding its members’ weight-average, and the call returns (mixture, aux). It never steers a merge, so the moments are those of the call without it (design: parameters-within-the-plan.md D2).

reduce_mode_aligned(k, num_modes, aux=None)[source]#

Mode-aligned grouped Runnalls reduction to k components (IMM/GPB2).

On a mixture in the component-major grow layout of propagate() (slot s produced by mode s % num_modes), Runnalls runs within each producing-mode group, reducing it to k // num_modes components. The output is contiguous blocks of k // num_modes slots per mode, so the mass of block g is the posterior mass of mode g. k and the component count must both be multiples of num_modes. aux is a per-component side statistic merged by the same assignment, as reduce() takes it; the call then returns (mixture, aux).

Design: docs/design/mixture-filtering.md D2; parameters-within-the-plan.md D2

__init__(log_weights, means, chols)#