mixle.ppl.autograd module

Analytic-gradient joint log-target for mixle.ppl (Torch autograd).

The Bayesian fitters (MAP / HMC / VI) need the gradient of the joint log p(data | theta) + log p(theta) in the unconstrained space. Rather than finite-difference it (slow, O(d) target evals per gradient) or use derivative-free optimizers, this module builds the same target in Torch and differentiates it with autograd — reusing each distribution’s existing backend_log_density_from_params (no density math is reimplemented).

It is entirely optional: if Torch is missing, or any family in the model has no Torch scorer (e.g. Categorical), grad_target() returns None and the caller falls back to the numerical path. The target is numerically identical to mixle.ppl.inference._build_target so results and tests are unchanged — only faster.

torch_available()[source]
Return type:

bool

class GradTarget(rv, data, slots, build, unpack, dmean, dstd, missing='error')[source]

Bases: object

A differentiable joint log-target over the unconstrained parameter vector u.

Mirrors inference._build_target exactly (data log-likelihood + prior log-densities + positivity Jacobian) but is backed by Torch autograd, so value_and_grad returns the analytic gradient. slots/build/unpack/dmean/dstd are shared with the numerical builder so the caller constructs results identically.

log_target(u_np)[source]
Return type:

float

value_and_grad(u_np)[source]
Return type:

tuple[float, ndarray]

grad(u_np)[source]
Return type:

ndarray

advi(u0, s0, *, samples, mc, steps, lr, rng, batch_size=None, family='meanfield', alpha=1.0)[source]

Fit a Gaussian variational posterior by reparameterized-MC stochastic optimization (Adam).

family: meanfield (diagonal q — independent params) or fullrank (a full covariance via a Cholesky factor — captures posterior correlations). alpha: the Renyi / tilted objective L_alpha = 1/(1-alpha) log E_q[(p/q)^(1-alpha)]. alpha=1 is the usual KL-ELBO; alpha=0 is the importance-weighted (IWAE) bound — both mass-covering directions that widen the often-too-narrow KL fit (the importance weights w=p/q are tilted by 1-alpha). batch_size subsamples the data per step (SGVB). Returns (value_samples, mean_u, scale_u, objective) where objective is the final variational objective value (ELBO for alpha=1, otherwise the tilted Renyi bound).

Parameters:
Return type:

tuple[ndarray, ndarray, ndarray, float]

class MixtureGradTarget(rv, data, slots, build, dmean, dstd, comp_layouts, weight, comp_family)[source]

Bases: GradTarget

Differentiable joint log-target for a finite mixture of leaf components — the analytic composite case. Overrides the per-batch likelihood with logsumexp_k(log w_k + comp_k(x)) so HMC / NUTS / full-rank & tilted VB get analytic gradients over the component parameters and (Gamma-represented) mixture weights. Other combinators (HMM, sequence) stay on the numeric path.

grad_target(rv, data, missing='error')[source]

Build a Torch autograd target for a flat model or a mixture-of-leaves, or None.

Returns None (caller falls back to the numerical path) when Torch is missing, or the model is neither a flat Sample nor a supported mixture, or any family has no Torch scorer. missing='marginalize' integrates NaN observations out of the likelihood (flat models only here).

Parameters:

  • rv (RandomVariable)

  • missing (str)