mixle.ops module

Operations — the verbs that transform distributions, and how they change capabilities.

The missing third axis of mixle: alongside objects (distributions) and capabilities (what they support), the operations that move an object from one capability set to another. Each verb documents its capability signature — what it requires of its input and what the output gains — so “what can I do to a distribution, and what does it become?” has one home.

quantize(dist, bits) : any Distribution -> FiniteSupport · Enumerable · RankableByIndex truncate(dist, …) : Distribution -> Distribution (Enumerable preserved) condition(dist, observed) : Conditionable -> Distribution marginalize(dist, keep) : Marginalizable -> Distribution mixture(dists, w) : Distributions -> LatentStructured transform(dist, f) : Distribution + inv. f -> Distribution (Jacobian-corrected) tilt(dist, theta) : ExponentialFamily -> Distribution project(source, target) : Sampleable x Fittable -> Distribution (forward-KL M-projection) product_of_experts(dists) : tractable family -> Distribution (geometric/log-linear pool)

See docs/ARCHITECTURE.md and the operation table in docs/CAPABILITIES.md.

quantize(dist, bits=8, *, lo_q=1e-3, hi_q=1.0 - 1e-3, n_samples=200_000, seed=0)

Discretize a continuous dist into a finite distribution over 2**bits bins.

Capability signature: any Distribution -> FiniteSupport · Enumerable · RankableByIndex. The result is a CategoricalDistribution over bin midpoints; the bin masses are exact (via the base cdf when available) or sampled otherwise. This is the concrete answer to “if I quantize a distribution, what does it become and how” — describe(quantize(g)) shows the gained capabilities.

Parameters:

• dist (Any)

• bits (int)

• lo_q (float)

• hi_q (float)

• n_samples (int)

• seed (int)

truncate(dist, *, allowed=None, forbidden=None)

Restrict dist to (allowed) or away from (forbidden) a finite set; mass renormalizes.

Parameters:

• dist (Any)

• allowed (Any)

• forbidden (Any)

condition(dist, observed)

Condition dist on a subset of coordinates. Requires the Conditionable capability.

Parameters:

• dist (Any)

• observed (dict[int, float])

marginalize(dist, keep)

Marginalize dist to the kept coordinates. Requires the Marginalizable capability.

Parameters:

• dist (Any)

• keep (Any)

mixture(dists, w=None)

Weighted mixture of dists — a latent-variable model (LatentStructured).

Parameters:

• dists (Any)

• w (Any)

transform(dist, f)

Change of variables y = f(x) with a Jacobian-corrected density (f is a Transform).

Parameters:

• dist (Any)

• f (Any)

tilt(dist, theta)

Exponentially tilt dist by theta. Requires the ExponentialFamily capability.

Parameters:

• dist (Any)

• theta (Any)

project(source, target, *, n_samples=20_000, seed=0, max_its=50)

Variationally project source onto the family of target (the sample-based M-projection).

Capability signature: Sampleable source x Fittable target -> Distribution. Draws n_samples from source and fits target to them by maximum likelihood – which is exactly the projection minimizing the forward divergence KL(source || target_family) (the M-/moment projection). Works for any source exposing a sampler (a distribution, mixture, GP, or a trained neural model) onto any fittable target family, so e.g. a neural sequence model can be distilled onto an HMM.

target may be a distribution (its estimator() supplies the family) or an estimator directly. The returned model is a member of the target family; describe(project(...)) shows its capabilities.

Parameters:

• source (Any)

• target (Any)

• n_samples (int)

• seed (int)

• max_its (int)

product_of_experts(dists, weights=None)

Geometric (log-linear) pooling of densities — a Product of Experts.

Capability signature: tractable family -> Distribution. Multiplies the expert densities, p(x) ∝ ∏_k p_k(x)**w_k i.e. log p(x) = Σ_k w_k·log p_k(x) − log Z, with raw exponent weights w_k (default 1.0 each — not normalized to sum to one, since PoE weights are exponents). Only the cases with a tractable normalizer are constructed exactly; the general continuous case raises CapabilityError.

• Categorical / finite shared support (the LLM-vocab fusion case): exact over the intersection of supports — new_pmap[x] ∝ ∏_k p_k(x)**w_k for x with positive mass under every expert, then renormalized. Returns a CategoricalDistribution.

• Gaussian (closed form): a Gaussian with precision-weighted combination 1/σ² = Σ_k w_k/σ_k² and μ = σ²·Σ_k w_k·μ_k/σ_k². Returns a GaussianDistribution.

Parameters:

• dists (Any) – the experts to pool (an iterable of distributions, all of the same tractable kind).

• weights (Any) – per-expert exponents w_k; None (default) uses 1.0 for each expert.

Raises:

CapabilityError – if the experts have no shared finite support and are not all Gaussian — the PoE normalizer Z = ∫ ∏_k p_k(x)**w_k dx is then intractable in closed form.