mixle.ppl.vmp module

Variational Message Passing (VMP) engine for mixle.ppl.

A message-passing engine for conjugate-exponential (Gaussian-Gamma) models (Winn & Bishop, 2005). Each unobserved node carries a variational factor q in an exponential family, holds its natural parameters, and exchanges messages with the factors it touches —

node posterior natural params = prior natural params + sum of incoming factor messages

Coordinate ascent updates each node from the others’ expected sufficient statistics; the ELBO is computed each sweep and increases monotonically.

The graph is built from a model by object identity: the same RandomVariable handle used in multiple positions becomes ONE node that combines messages from every factor touching it (parameter tying / shared latents). Priors that are themselves handles become parent nodes — hierarchies of any depth. Use Graph directly for multi-factor models, or fit(how="vmp") which auto-builds a single-factor graph.

class MeanConst(v)

Bases: object

Constant mean term used where the graph expects a Gaussian mean node.

ex()

Return E[x] for the constant mean.

ex2()

Return E[x^2] for the constant mean.

class PrecConst(v)

Bases: object

Constant precision term used where the graph expects a precision node.

et()

Return E[tau] for the constant precision.

elogt()

Return E[log tau] for the constant precision.

class GaussianVNode(prior_mean, prior_prec)

Bases: object

Node q(x) = Normal(m, s2); prior Normal(prior_mean, 1/prior_prec) where prior_mean may be another node (hierarchy). inbox holds message thunks from the factors / children touching this node — the mechanism behind sharing.

ex()

Return the variational expectation E[x].

ex2()

Return the second moment E[x^2] under q(x).

update()

Apply one coordinate-ascent natural-parameter update.

entropy()

Return the entropy of the Gaussian variational factor.

cross_prior()

Return E_q[log p(x | parent)] for the Gaussian prior factor.

class GammaVNode(a0, b0)

Bases: object

Node q(t) = Gamma(a, b) over a precision.

et()

Return the expected precision E[tau].

elogt()

Return the expected log precision E[log tau].

update()

Apply one coordinate-ascent update from accumulated messages.

entropy()

Return the entropy of the Gamma variational factor.

cross_prior()

Return E_q[log p(tau)] under the Gamma prior.

class DirichletVNode(alpha0)

Bases: object

Node q(pi) = Dirichlet(alpha) over a simplex (categorical probabilities).

expected()

Return the simplex mean E[pi].

expected_log()

Return the vector E[log pi_k].

update()

Apply one coordinate-ascent update from categorical count messages.

entropy()

Return the entropy of the Dirichlet variational factor.

cross_prior()

Return E_q[log p(pi)] under the Dirichlet prior.

class GraphResult(node_of, elbo_trace)

Bases: object

Fitted VMP graph with posterior accessors for graph node handles.

posterior(rv)

Return posterior parameters for a latent handle in the fitted graph.

samples(rv, n=4000, rng=None)

Draw samples from the variational factor attached to rv.

Parameters:

n (int)

class Graph

Bases: object

A VMP factor graph for arbitrary conjugate-Gaussian DAGs with shared variables.

mu = Normal(0, 10) # one shared latent handle fit = (Graph()

.observe(Normal(mu, 1.0), data_a) # factor A uses mu .observe(Normal(mu, 2.0), data_b) # factor B uses the SAME mu .fit())

fit.posterior(mu) # evidence from A and B combined

A prior that is itself a RandomVariable becomes a parent node (hierarchy, any depth). A Gamma in a scale slot is read as a prior on the precision (the conjugate choice).

observe(model, data)

Add an observed likelihood factor and return self for chaining.

Return type:

Graph

fit(*, max_its=300, tol=1e-8)

Run coordinate-ascent VMP and return the fitted graph result.

Parameters:

• max_its (int)

• tol (float)

Return type:

GraphResult

vmp_fit(rv, data, *, max_its=300, tol=1e-8, rng=None)

Auto-build a single-factor VMP graph for a nested Gaussian model and fit it.

Handles Normal(mean, scale) where mean is a (possibly deeply nested) Normal prior chain and scale is a constant sd or a Gamma prior on the precision — e.g. Normal(Normal(0,10), Gamma(1,1)) (unknown mean + precision) or Normal(Normal(Normal(0,100), 5), 1) (mean with a hyperprior). For multi-factor models or shared variables across datasets, use Graph directly.

Parameters:

• rv (RandomVariable)

• max_its (int)

• tol (float)

Return type:

RandomVariable

class MixtureVMPResult(weights, comps, responsibilities, elbo_trace, normalizer_trace)

Bases: object

Variational result for a scalar Gaussian mixture with discrete responsibilities.

summary()

Return mixture weights, component summaries, and objective metadata.

mixture_vmp(data, K, *, max_its=300, tol=1e-7, rng=None, m0=None, s0=None, a0=1.0, b0=1.0, alpha0=1.0)

Bayesian Gaussian mixture by variational message passing (VBEM).