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 = | inversion | message |
|---|---|---|
REDDiff(λ, steps) | RED-Diff's stochastic proximal solve | a 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.
| field | meaning |
|---|---|
λ | regulariser strength; enters as $\lambda_t = \lambda\sigma_t/\alpha_t$ |
steps | inner iterations L of Algorithm 1 |
lr | step size |
samples | Monte-Carlo draws of $(t,\varepsilon)$ per step (the paper uses 1) |
adam | Adam 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.
VariationalDiffusion.calibrate_lambda — Function
calibrate_lambda(s::AbstractNoiseSchedule, v₀ = 1.0; nodes = 2000) -> RealThe 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. Seereddiff.md§4.
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.
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.
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.
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.
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.
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.
LenticulumCore.energyspace — Method
LenticulumCore.energyspace(::DiffusionFactor)$E_c = \mathbb{R}^2$, graded as (clamp, score):
| summand | is | role |
|---|---|---|
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).
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.
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.
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.
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
dwould otherwise count the priordtimes (gaussian.jl'sinvertdocstring). 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.
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.
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.
VariationalDiffusion.blockranges — Method
blockranges(f::DiffusionFactor) -> NamedTupleThe 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.
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.
VariationalDiffusion.statedim — Method
statedim(f::DiffusionFactor) -> Int$n$, the dimension of the joint space the diffusion prior lives on.
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, andnothingifπ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.
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.
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.
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.