MyceliumLearning
Learning on a Mycelium graph: what changes the parameters. Inference (graphs, messages, schedules, the free energy) is in Mycelium, which does not depend on this package.
| what | functions |
|---|---|
| the gradient of the graph free energy at fixed factor beliefs (the envelope gradient) | free_energy_gradient(store, g, ps, st) |
| one optimiser step | parameter_step |
| differentiating through a finite schedule, score estimates | the edge couplings; GradientEstimate, StraightThroughFactor |
| the implicit adjoint of a converged message fixed point | free_energy_gradient(...; adjoint = :implicit) |
| expectation maximisation with closed-form M-steps | em_step, fit_em, m_step |
| the gradient averaged over samples (Monte Carlo EM) | sample_gradient |
At a fixed point of message passing on a tree whose messages are exact, the envelope gradient is the gradient of $-\log p$ of the data; the condition is in the vault's Bethe Free Energy.
The gradient and the optimiser step
LenticulumCore.free_energy_gradient — Method
LenticulumCore.free_energy_gradient(store, g, ps, st; ad = nothing, ε = 1e-6,
schedule = nothing, nsweeps = 1, damping = 0.0, adjoint = :unrolled,
maxsweeps = 1000, tol = 1e-10, linear_solver = :dense,
linear_tol = 1e-10, linear_maxiter = 1000)Parameter gradient of the graph scalar free energy with each factor's belief held fixed: $\sum_c \partial_\theta F_c(b_c, \theta)$, with $b_c$ from factor_belief and $F_c$ from belief_free_energy. At a belief-propagation fixed point this is the derivative of the Bethe free energy (the envelope theorem), so on a tree it is the gradient of $-\log p$ (LP-020). A factor without factor_belief is differentiated at fixed incoming messages instead, which agrees when those messages are points; otherwise that is not the free-energy gradient, and a warning says so. A MeanField node's term is differentiated at the fixed marginals of its variables, which is the envelope gradient of the merged free energy at a fixed point of the hybrid message passing; non-diagonal couplings, adjoint = :implicit and sampling refuse such nodes. Bethe variable corrections are constant with respect to parameters at fixed beliefs. Exact for the default linear scalarisations, as the envelope argument is about the summed free energy. Nonlearnable subtrees receive zeros. Frozen coordinates receive zeros too. The result has ps's structure. Couplings (LP-021). At a fixed point the free-energy gradient does not depend on the edges' couplings, so without schedule a graph whose couplings are diagonal, exact or pathwise gets this gradient at the store's beliefs too. A coupling changes the result only in a replay: with schedule, non-diagonal edges replay finite nsweeps (default 1) from empty messages and differentiate that computation, a cut (diagonal) edge holding its message fixed. When cut and differentiated edges whose messages depend on the parameters meet in one graph (the mixed case), that is not the free-energy gradient even when the replay converges (off by 0.2–0.7 in test/lp021.jl), and a warning says so; adjoint = :implicit returns the envelope gradient at its converged fixed point for such a graph instead. Score edges also require rng and nsamples >= 2, returning a GradientEstimate. No input store or state is mutated. Replay includes flooding snapshots, realised residual task choices and outgoing damping. adjoint=:implicit instead differentiates a converged synchronous BP fixed point, found from empty messages using schedule, maxsweeps and tol. It requires CPU Gaussian/Dirac messages, empty message state and an invertible I-DT; diagonal/detach rows are constant cuts, and a factor whose edges are all cut is held at its fixed belief, as in the diagonal driver (LP-021). Dense is the reference linear solve; :krylov needs Krylov.jl. Both check their original linear residual. Reference differences, ForwardDiff and Zygote are supported. See graph_adjoint.md and gradient_couplings.md for equations, estimator domains, costs and mixed rules.
MyceliumLearning.parameter_step — Method
parameter_step(store, g, ps, st; ad = nothing, rule = GradientDescent(0.01), optimiser_state = nothing)
-> (ps_new, st_new, optimiser_state_new)One graph free-energy parameter step with an explicit AD backend (nothing selects reference differences). Inference must populate incoming messages first. The rule's get supplies a look-ahead parameter vector per learnable factor, the gradient is computed at those parameters with the factor beliefs fixed (see free_energy_gradient), and put applies the update. Optimiser state is a NamedTuple of vectors keyed by learnable factor name, initialised to zero if omitted. Pass the returned state on the next step (Momentum/Nesterov). Lux state advances once, by evaluating local energies at the look-ahead parameters. Frozen coordinates are excluded from state vectors; fully frozen factors have no entry. Non-diagonal drivers forward schedule, nsweeps, rng, nsamples to the gradient API. Score steps return (ps_new, st_new, optimiser_state_new, estimate) so uncertainty is available to the caller; deterministic steps retain the three-tuple return. Coupled steps commit inference and one local-energy state advance from the first replicate; other replicates do not accumulate Lux state. This does not update the input message store or exposed OptimiserFactor wires.
Gradient couplings
MyceliumLearning.GradientEstimate — Type
GradientEstimate(value, standard_error, nsamples)Monte Carlo parameter gradient and componentwise standard error, both shaped like ps. This is an estimate of an expectation, not an exact derivative or confidence bound.
MyceliumLearning.StraightThroughFactor — Type
StraightThroughFactor(forward, surrogate; channels=(:in, :out))Parameterless directed factor: forward values use forward, input derivatives use surrogate. Callables must have matching scalar/array output shape. ForwardDiff and ChainRules reverse AD are supported. Reference differences of the primal see forward.
Expectation maximisation
MyceliumLearning.MomentStats — Type
MomentStatsThe moment statistics of one factor's continuous channels under a belief, per outcome k of the factor (one outcome without a switch): n[k] the mass, m[:, k] the sum of the means, S[:, :, k] the sum of the second moments $\mathbb E[x x^\top]$, with x the channels channels (dimensions dims) stacked in that order. Sums over the assignments of a cluster node's belief, the tied nodes and the replicas of a plate. Read by m_step.
MyceliumLearning.em_step — Method
em_step(store, g, ps, st) -> ps′One M-step: from every cluster node's exact belief under the store's messages, the moment statistics of each clustered factor (pooled over tied nodes and plate replicas), and each factor's closed-form m_step; a factor without one keeps its parameters, as do frozen paths. A node outside a cluster takes part when its belief is a FrozenClusterBelief (a factor computed as a one-factor cluster, as_cluster). Run inference to convergence first: with exact beliefs this is one step of EM and does not increase the free energy (em.md).
MyceliumLearning.fit_em — Method
fit_em(g, ps, st; schedule, sweeps = 2, iters = 100, tol = 1e-8, store = nothing, accelerate = false,
mstep = em_step) -> (ps, Fs, store)Expectation maximisation on g: sweeps sweeps of schedule (the E-step; exact when every learned factor is in a cluster node on a forest), the free energy, then em_step, until the free energy changes by less than tol or iters steps. Returns the parameters, the free energy before each M-step and, last, at the returned parameters (non-increasing for exact beliefs), and the store, holding the messages at the returned parameters. A warm store is reused.
With accelerate = true each step is a SQUAREM cycle (Varadhan & Roland 2008, scheme S3): two EM steps θ₁ = M(θ₀), θ₂ = M(θ₁), the extrapolation θ′ = θ₀ − 2αr + α²v with r = θ₁ − θ₀, v = θ₂ − 2θ₁ + θ₀, α = −‖r‖/‖v‖ (at most −1), then one EM step from θ′; a cycle whose free energy exceeds θ₀'s falls back to θ₂. EM converges slowly when a latent variable is almost determined by the parameters (a switch with small noise feeding a sum: each M-step moves the offsets by little), and the extrapolation takes the long steps EM will not (em.md). Fs then holds one entry per cycle.
mstep(store, g, ps, st) -> ps′ replaces em_step, for a parameterisation with constraints the factors' m_steps do not know (built on moment_statistics); it must return parameters of the same tree shape.
MyceliumLearning.m_step — Method
m_step(factor, stats::MomentStats, ps, frozen) -> parameters or nothingThe parameters of factor that minimise $\mathbb E_b[-\log f]$ given its moment statistics, leaving the paths in frozen (:all, or a tuple of parameter paths relative to the factor) at their values in ps. nothing (the default) means no closed form: em_step keeps ps. Lenticulum implements it for its constraint factors.
MyceliumLearning.m_step_signature — Method
m_step_signature(factor)What of a factor besides its parameters enters its m_step's minimiser (a fixed output coefficient, say). Tied factors pool their statistics only when their signatures are equal; nothing by default.
MyceliumLearning.moment_statistics — Method
moment_statistics(store, g, ps, st) -> DictThe moment statistics em_step uses, for a caller with its own M-step (a parameterisation with constraints the factors' m_step do not know): a Dict from (node key, factor key) (the factor key is nothing outside a cluster node) to (factor, stats::MomentStats, frozen), pooled over tied nodes and plate replicas. Only factors with an m_step method are included. A plate row of cluster nodes whose replicas share their structure is read from its stacked beliefs at once (batched = false takes every node alone).
Sample gradients
MyceliumLearning.sample_gradient — Method
sample_gradient(buffer, sampler, ps, st; ad = nothing, ε = 1e-6, through_inference = false)
-> gradientThe weighted average, over the stored samples, of the gradient of each sample's pinned total $-\log p(\text{data}, \text{pins})$ at the current parameters ps. With samples from the posterior and an exact pinned graph (a tree), this is the Monte Carlo EM gradient of $-\log p(\text{data})$. Samples drawn under older parameters bias it, which is what the buffer's horizon limits.
Each sample's points are pinned and belief propagation runs the sampler's schedule at ps. Then:
- by default,
free_energy_gradientis taken with the factor beliefs held fixed (LP-020): one inference per sample, exact when that inference has converged, as on a tree. A factor withoutfactor_beliefgets the fixed-message derivative. - with
through_inference = true, the scalar free energy is differentiated through the inference instead: central differences of stepεforad = nothing, or the given AD backend. That costs an inference per sample and, with differences, per parameter coordinate, and needs no factor hook. It is the reference the default is checked against.
Factors that are not learnable get zero gradients. The result has ps's structure.
MyceliumLearning.MyceliumLearning — Module
MyceliumLearningLearning on a Mycelium factor graph: what changes the parameters, as opposed to what infers the beliefs.
| file | what |
|---|---|
gradient.jl | free_energy_gradient of a graph (the envelope gradient at fixed factor beliefs, LP-020) and parameter_step |
gradient_couplings.jl | per-edge couplings: replay of a finite schedule, score estimates, StraightThroughFactor |
graph_adjoint.jl | the implicit adjoint of a converged message fixed point |
em.jl | closed-form M-steps from cluster beliefs: em_step, fit_em, the m_step hook |
sample_gradient.jl | the gradient averaged over the samples of a SampleBuffer |
Inference (graphs, messages, schedules, plates, cluster nodes, the free energy itself) is in Mycelium, which does not depend on this package. A factor type opts in to learning by implementing Mycelium.factor_belief and Mycelium.belief_free_energy (for the gradient) and MyceliumLearning.m_step (for EM).