Factors

DiffusionFactor carves one vector space into named channel blocks; the Polarity decides which blocks are clamped and how hard, which is the selection-matrix formulation $P = \rho_{in}P_{in} + \rho_{out}P_{out} + \rho_{latent}P_{latent}$.

Its inversion is chosen by prox:

prox =inversionmessage
REDDiff(λ, steps)RED-Diff's stochastic proximal solvea DiracBelief
ImplicitProx(nodes; …)the deterministic implicit solver, with convergence and stability reported (implicit_solution) and a backward pass (implicit_factor_pullback)a DiracBelief, or with message = :gaussian the Laplace Gaussian with the target's anchor divided out
ProxDM(prox; t, λ, …)proximal inference (prox_infer) with a learned or exact prox; the same report and backward pass (through prox_pullback)a DiracBelief

With ProxDM the factor has two parameter trees, (predictor = …, prox = …): the NoisePredictor for the free energy's score term, and the prox for the inversion (ProxDM).

ImplicitProx(nodes; batched = true, linsolve = KrylovSolve()) passes the cost options of Implicit inference on to the factor.

API

RED-Diff

VariationalDiffusion.REDDiff — Type
REDDiff(; λ = 0.25, steps = 200, lr = 0.1, samples = 1, adam = true,
          β₁ = 0.9, β₂ = 0.999, ϵ = 1e-8, rng = Random.default_rng())

The RED-Diff proximal operator: configuration for the inner optimisation that is the Bayesian inversion.

fieldmeaning
λregulariser strength; enters as $\lambda_t = \lambda\sigma_t/\alpha_t$
stepsinner iterations L of Algorithm 1
lrstep size
samplesMonte-Carlo draws of $(t,\varepsilon)$ per step (the paper uses 1)
adamAdam vs plain gradient descent; the paper uses Adam

λ = 0.25 is the value Mardani et al. tuned across their experiments. It is not a universal constant, and for a Gaussian data distribution there is exactly one λ that makes the implied prior correct — see calibrate_lambda and reddiff.md §4, which is the sharpest thing this package has to say about RED-Diff.

source
VariationalDiffusion.calibrate_lambda — Function
calibrate_lambda(s::AbstractNoiseSchedule, v₀ = 1.0; nodes = 2000) -> Real

The unique λ for which RED-Diff's regulariser is the exact negative log-prior gradient of a Gaussian data distribution $\mathcal{N}(0, v_0 I)$.

For that data distribution $\varepsilon_\theta$ is available in closed form, and the regulariser gradient collapses to a linear shrinkage:

\[\nabla_x\mathrm{reg}(x) \;=\; \kappa\,x, \qquad \kappa \;=\; \frac{\lambda}{1-t_{\min}}\int_{t_{\min}}^{1}\frac{\sigma_t^2}{\alpha_t^2 v_0 + \sigma_t^2}\,dt\]

for $t \sim U[t_{\min},1]$, whereas the true prior gradient is $x/v_0$. Setting $\kappa = 1/v_0$ gives the returned value. Computed by the trapezoidal rule; the integrand is smooth on $[t_{\min},1]$.

[!important] Why this matters beyond the test suite λ is presented in the paper as a tuned hyperparameter, and here it is derived. That tells you what tuning λ is really doing: choosing how strong the learned prior is, with a wrong value biasing every posterior by a known factor. See reddiff.md §4.

source
VariationalDiffusion.reddiff_solve — Method
reddiff_solve(pred, cfg, x_init, datagrad, hard, ps, st) -> (x, st)

Algorithm 1: steps iterations of

\[x \leftarrow \mathrm{Optim}\bigl(x,\ \underbrace{\nabla_x \tfrac12\|P(x_0-x)\|^2}_{\texttt{datagrad}} + \underbrace{\mathbb{E}[\lambda_t(\varepsilon_\theta - \varepsilon)]}_{\text{Prop. 2}}\bigr)\]

datagrad(x) -> g supplies the clamp's gradient; keeping it a closure is what makes this operator reusable for a general forward model $f$ rather than only the diagonal $P$.

hard is a (mask, values) pair applied by projection after every step: coordinates with $\rho_{in} = \infty$ are overwritten rather than penalised, because an infinite precision is not a number you can put in a gradient. That projection is the categorical cup of Copiers Cups and Caps.md, and it is the one place the $\rho \to \infty$ limit is taken literally rather than numerically.

source
VariationalDiffusion.reddiff_weight — Method
reddiff_weight(cfg, s, t) -> Real

$\lambda_t = \lambda/\sqrt{\mathrm{SNR}_t} = \lambda\,\sigma_t/\alpha_t$.

This weights the stop-gradient residual under uniform time sampling. It is finite at $t=1$ for the default VP schedule, with limit $\lambda\sqrt{e^{10.05}-1}$; it diverges only if the terminal signal vanishes. Here SNR is the power ratio $\alpha_t^2/\sigma_t^2$. This field weight is not the squared-error coefficient in the continuous ELBO; see schedule.md §3 and reddiff.md §3.

source
VariationalDiffusion.regulariser_gradient — Method
regulariser_gradient(pred, x, cfg, ps, st) -> (g, st)

$\nabla_x \mathrm{reg}(x) = \mathbb{E}_{t,\varepsilon}[\lambda_t(\varepsilon_\theta(x_t,t) - \varepsilon)]$ — Proposition 2, by Monte Carlo with cfg.samples draws.

This is the entire prior contribution: one forward pass of the network per draw, no Jacobian, no backward pass. The estimator is unbiased in $(t,\varepsilon)$ but the underlying gradient is not the true gradient of the regulariser — the denoiser Jacobian has been dropped. reddiff.md §2 is about what that costs.

source

The factor

VariationalDiffusion.DiffusionFactor — Type
DiffusionFactor(blocks::NamedTuple, predictor; prox = REDDiff())

A factor whose prior over its own state space is a diffusion model, and whose Bayesian inversion is a RED-Diff proximal solve.

blocks names the channels and their dimensions; they tile one vector space $\mathbb{R}^n$, $n = \sum_i \dim_i$, in declaration order. predictor is a NoisePredictor over that whole $\mathbb{R}^n$ — one network for the joint state, not one per channel, which is what makes this a relation rather than a collection of conditionals.

f = DiffusionFactor((obs = 4, hidden = 4), NoisePredictor(unet, VPSDE());
                    prox = REDDiff(λ = 1.0, steps = 300))

This is the diffusion family of implicit learners. The prox selects RED-Diff's stochastic solve, deterministic implicit inference, or ProxDM. All use the LenticulumCore.ProximalInversion interface.

source
VariationalDiffusion.DiffusionModel — Type
DiffusionModel(factor, polarity)

The open model the polarity selects: an implicit relation on $\mathbb{R}^n$, restricted to predicting the unobserved block from the observed ones.

Not pure. The unobserved and latent blocks are both reconstructed by the prox, and the latent ones are exactly AutoBayes' $\llbracket c \rrbracket$ — internal coordinates the inversion has to fill in and nobody reads.

source
LenticulumCore.energy — Method
LenticulumCore.energy(f::DiffusionFactor, x, a, y, ps, st)

The graded energy at a point: (clamp = ½‖P(x₀-x)‖², score = one MC sample of the score-matching loss). A hard coordinate contributes zero when its state equals its reference value, and Inf otherwise.

x is the full state vector, y the reference $x_0$, and a the polarity (the slot AutoBayes reserves for $\llbracket c \rrbracket$, used here to carry the thing that determines $P$). That reuse is ugly and is discussed in factor.md §4.

source
LenticulumCore.energyspace — Method
LenticulumCore.energyspace(::DiffusionFactor)

$E_c = \mathbb{R}^2$, graded as (clamp, score):

summandisrole
clamp$\tfrac12|P(x_0-x)|^2$the energy $\mathbf{l}^c$ — data consistency
score$\mathbb{E}_{t,\varepsilon}[\omega(t)|\varepsilon_\theta - \varepsilon|^2]$denoising surrogate for the learned prior

The score summand is not posterior entropy or a normalised negative ELBO. Use free_energy_upper_bound for the separately specified finite-chain variational bound; its model and energy accounting differ from this graph surrogate (LP-009).

source
LenticulumCore.invert — Method
LenticulumCore.invert(lens, π, inputs, ps, st) -> (belief, st)

Run the prox and return a joint belief on the concatenated unobserved blocks in channel order. Point messages return a DiracBelief; ImplicitProx can instead return a joint Gaussian or mixture. likelihood_message removes the diagonal anchor on those same coordinates, retaining the diffusion prior. Mixture anchor removal throws if any component becomes improper, because normalized weights would be undefined. factor_message remains per-target.

The default return type is a DiracBelief; the implicit solver also offers message = :gaussian and message = :mixture. For RED-Diff that is faithful rather than lazy: RED-Diff's variational family is $q = \mathcal{N}(\mu, \sigma^2 I)$ with $\sigma \to 0$, so the posterior it computes is a point mass. The consequence is recorded in factor.md §5 — a Dirac message dominates every combine it meets, so a diffusion factor in a graph overrides its neighbours rather than negotiating with them.

source
LenticulumCore.likelihood_message — Method
LenticulumCore.likelihood_message(lens, π, inputs, ps, st) -> (belief, st)

A joint message on the concatenated unobserved blocks in channel order. Uses the same construction as invert; for implicit Gaussian/mixture messages, divides out the product of diagonal target anchors. The diffusion prior remains. An improper mixture component throws because normalized weights would be undefined; improper Gaussians are allowed.

source
LenticulumCore.supported_polarities — Method
LenticulumCore.supported_polarities(f::DiffusionFactor)

All $3^n - 2^n$ assignments with at least one unobserved channel, for at most four channels (65 assignments). The one-target/all-other-observed entries come first, in channel order; the remainder follows LenticulumCore.polarities order.

Above four channels this throws ArgumentError: use supports_polarity for membership or polarities for lazy traversal. Structural predicates do not enumerate.

source
Mycelium.factor_message — Method
Mycelium.factor_message(f::DiffusionFactor, target, polarity, inputs, prior, ps, st)

The factor → variable message: a DiracBelief on target, from a RED-Diff prox over the joint space, or, for ImplicitProx(…; message = :gaussian), a GaussianBelief with the target's own anchor divided out (see ImplicitProx).

[!warning] This is the posterior, not the likelihood Every other factor in this project returns a likelihood here, with the prior divided out, because a variable of degree d would otherwise count the prior d times (gaussian.jl's invert docstring). A diffusion factor cannot divide its prior out — the prior is a neural network and there is no subtraction available in canonical form.

So on a graph where the target variable has degree > 1, this message double-counts. It is correct for a degree-1 target (the usual inverse-problem setting: one prior, one measurement) and approximate otherwise. factor.md §5.

source
Mycelium.local_free_energy — Method
Mycelium.local_free_energy(f::DiffusionFactor, msgs, ps, st)

The factor's Bethe contribution, evaluated at the prox's own solution — i.e. at the point the inversion actually returned, which is the only point where the two summands are comparable.

This is a denoising surrogate, not a normalised Bethe/game free energy: a continuous Dirac posterior has no finite Lebesgue differential entropy, and score does not supply it. REDDiff samples the score term; fixed-node solvers evaluate a deterministic quadrature. The separately typed finite-chain ELBO bound is available through free_energy_upper_bound.

source
VariationalDiffusion.assemble_state — Method
assemble_state(f, inputs, π) -> x₀

Build the reference configuration $x_0$ of $\tfrac12\|P(x_0-x)\|^2$ by laying each channel's incoming belief into its block.

A DiracBelief contributes its value; anything with a mean contributes that; a channel with no message contributes zeros. The prior π fills unobserved blocks without incoming points. For multiple targets, a point of the concatenated target dimension is split in channel order. Otherwise the point is reused on each target block (and must match each block's dimension). A missing point leaves a zero reference. A positive precision then anchors that channel to zero; a zero precision ignores the reference.

source
VariationalDiffusion.blockranges — Method
blockranges(f::DiffusionFactor) -> NamedTuple

The index range of each channel inside $\mathbb{R}^n$. These are the selection matrices $P_{in}, P_{out}, P_{latent}$ of ImplicitREDDiff.md, stored as ranges because a diagonal 0/1 matrix is a wasteful way to write a range.

source
VariationalDiffusion.precision_vector — Method
precision_vector(f, p::Polarity) -> (ρ, hardmask)

The diagonal of $P = \rho_{in}P_{in} + \rho_{out}P_{out} + \rho_{latent}P_{latent}$, as a vector of length n, together with a BitVector marking the coordinates whose precision is infinite.

Infinite entries are split off rather than stored as Inf: they cannot participate in a gradient, and the honest treatment is projection. default_precision(Observed()) == Inf, so by default every observed channel lands in hardmask and is clamped exactly.

source

The implicit solver as the inversion

VariationalDiffusion.implicit_factor_pullback — Method
implicit_factor_pullback(f, polarity, inputs, π, z̄, ps, st)
    -> (inputs = NamedTuple, prior = π̄, ps = ps̄, precisions = NamedTuple)

The backward pass of the factor's inversion, by the adjoint of implicit_pullback. z̄ is the cotangent of a downstream loss with respect to the inferred state, given per channel as a NamedTuple (e.g. (y = ȳ,); channels left out have zero cotangent).

Returns the cotangents with respect to

  • each channel's incoming point (inputs): the clamped value for an observed channel, the anchor for a soft one;
  • the prior's point (prior): fills the corresponding ranges for a joint prior point, sums the blocks for a shared-block point, zero when incoming points override it, and nothing if π carries no point;
  • the predictor's parameters (ps);
  • each channel's precision (precisions; zero for hard-clamped channels, whose precision is infinite and not a differentiable quantity).

Throws if the solve did not converge, as implicit_pullback does. For a ProxDM inversion the adjoint is prox_pullback, and ps is (predictor = 0, prox = ps̄): the inversion does not read the prior's parameters.

source
VariationalDiffusion.implicit_solution — Method
implicit_solution(f::DiffusionFactor, polarity, inputs, π, ps, st) -> (ImplicitSolution, st)

Run the factor's implicit inversion and return the whole ImplicitSolution: the full state, the residual, and the converged / stable flags. invert and factor_message return the unobserved blocks jointly (invert) or one target (factor_message) as a belief; this is the call to make when the report matters.

The reference configuration is assemble_state(f, inputs, π): inputs on their channels, and the prior π's point (if any) on the others. It doubles as the warm start, which is how a message schedule reuses the previous belief: as in ImplicitLayers' DEQ factor, the prior seeds the solver. Whether it also pulls the solution is decided by the polarity's precision on the unobserved channels — default_precision(Unobserved()) == 1, an anchor; set it to 0 for a pure conditional.

For a ProxDM inversion the solver is prox_infer instead, with the same problem and warm start.

source

Conformance and game-level limits

test/conformance.jl runs the shared default lens checker on all five accepted binary assignments and the unary point polarity. Fixed zero-noise quadrature and a unit Gaussian predictor give independent linear-field and energy fixtures, including the two-coordinate posterior from an N(0,I) anchor and a site of precision c I.

supported_polarities lists all 3^n - 2^n assignments through four channels (65 entries), with one-target/all-other-observed entries first. Above that cap it throws; use supports_polarity or the lazy polarities iterator. Structural sink/direction checks do not enumerate. Joint inversion and likelihood messages concatenate the unobserved blocks in channel order. Gaussian/mixture messages restrict the full-state construction to those blocks; likelihood messages divide out their diagonal anchors. Improper mixture components throw because their normalized weights are undefined. Graph factor_message stays per target.

The LP-017 testsets check complete lists, lazy traversal, structural answers above the cap, joint point/Gaussian/mixture messages, correlated covariance and anchor removal. Its four broken assertions now pass. Game checks retain an explicit opt-out: the graph's score coordinate is a denoising surrogate, not posterior entropy, and its inferred polarity/trivial prior cannot preserve an explicit game's split and precisions (LP-009). These checks do not certify arbitrary priors, joint latent posteriors, stochastic REDDiff or learned ProxDM.

Labelled finite-chain ELBO bounds

LenticulumCore.free_energy_upper_bound(f,x,ps,st;times) defines a normalised finite VP reverse chain on the full joint point x: terminal N(0,I), reverse variances βᵢ I, a Gaussian decoder, and the forward-chain variational law conditioned on x. It includes all normalisers. Analytic single-Gaussian predictors return FreeEnergyUpperBound(value). General predictors use estimate_free_energy_upper_bound(...;times,rng,nsamples) and return FreeEnergyBoundEstimate(value,standard_error,nsamples). A sampled estimate is not itself a numerical upper bound. Access to .value is explicit; neither wrapper is a number or accepted by ordinary scalarisation. Exact game entropy and partial evidence remain unsupported. The graph surrogate is a different objective.

LenticulumCore.free_energy_upper_bound — Function
free_energy_upper_bound(f::DiffusionFactor, x, ps, st; times) -> (FreeEnergyUpperBound, st)

Exact negative ELBO of a finite, normalised VP Gaussian reverse chain for full joint point evidence x (Lebesgue coordinates). times explicitly defines the model: terminal N(0,I), reverse variance βᵢ I including the decoder, mean (z-βᵢ εθ(z,tᵢ)/σᵢ)/aᵢ. The variational law is the forward chain conditioned on x. All normalisers are included.

Analytic expectation is supported for a one-component GaussianMixtureEps with the default input adapter and no device transfer. Other predictors must use the explicitly sampled estimate_free_energy_upper_bound. This bound concerns this finite chain's negative log evidence; it is not a bound on the graph's (clamp,score) surrogate or a continuous-time likelihood. No partial-evidence marginalisation or prox posterior entropy is claimed.

source
LenticulumCore.estimate_free_energy_upper_bound — Function
estimate_free_energy_upper_bound(f, x, ps, st; times, nsamples=1024, rng)

Monte Carlo negative-ELBO estimate for the same finite chain. Returns FreeEnergyBoundEstimate(value, standard_error, nsamples); an individual estimate is not a numerical upper bound. Predictor calls must preserve inference-mode state. Each replicate uses independent forward marginals at every time; the q posterior covariance is analytic.

source