implementation

Bethe free energy from incoming cavity messages, with an edge-direction guard for factors that read them and a per-variable entropy counting correction.

Sources: code: free_energy.jl

Theory (CT-ML wiki): Bayesian Inversion · Variational Free Energy · Statistical Game

Implements: the graph generalisation of Theorem 23 — the Bethe free energy, its counting numbers, and the graded per-factor breakdown. Theory: Bethe Free Energy.

The formula

Energies add; entropies need a counting correction. That is exactly the asymmetry Proposition 18 identifies, appearing again one level up — which is the reason this file exists rather than a one-line sum(local_free_energy, factors). The one-liner is the energy part, and it is right; the entropy part is what a naive implementation gets wrong.

The invariant worth asserting

1 for a tree, 1-L with L loops. One integer saying how badly the bookkeeping over-counts. Asserted against euler_characteristic in the tests, because it is the cheapest check that the graph and the accounting have not drifted apart.

Incoming messages and permitted edge directions

messages_into returns the variable-to-factor cavity messages, not the full variable marginals. Each factor forms its own belief from its potential and those messages:

Using the marginals here would include the factor’s outgoing evidence a second time. The variable counting correction, by contrast, uses the full variable marginals.

uses_cavity(factor) defaults to false. Every local_free_energy implementation that reads its incoming messages must override it with true, even if it returns zero when some message is absent. In factor_free_energies, such a factor’s edges are checked with absorbs(edge.direction) before its local evaluation. Emitting() raises ArgumentError naming the factor, channel and variable and recommending Bidirectional(). Absorbing() and Bidirectional() are permitted, including when their stored message is nothing. Factors returning a constant zero without reading messages keep the default. The check scans the existing edge indices without constructing a collection; error text is constructed only on failure. Message passing and scheduling do not change.

Both bethe_free_energy and graph scalar_free_energy call factor_free_energies, so all three graph entry points enforce the same requirement. Direct local_free_energy calls have no graph directions to check. chain_free_energy combines already evaluated terms.

The Mycelium testset “LP-014: cavity messages and edge directions” checks the three entry points, the diagnostic, missing messages on permitted edges, and an unchanged directed DataFactor/RelayFactor/LossFactor graph. AlgebraicFactors’ “LP-014: a prior on an Emitting edge” checks exact enumerated marginals with either prior edge direction, rejection of Emitting-prior free energy, and the Bidirectional result against . See LP-014 Emitting edges drop the cavity message from the free energy.

Two decompositions

bethe_free_energychain_free_energy
shapefactors + counting correctionTheorem 23 folded along an order
order-dependent?noyes
on a treeexactexact

They agree when every belief is a DiracBelief — all expectations are evaluations, all variable entropies vanish. That is the regime the test suite checks against a hand-computed 4.5.

Implementation difficulties

1. Theorem 23 needs a “downstream”, and a graph does not have one

This is a genuine gap in transporting the paper to graphs, not an implementation shortcut. Theorem 23 averages the upstream loss under the downstream inversion; on a chain that is unambiguous, on a graph “downstream” is a property of the message schedule, not the wiring. Two schedules give two decompositions of the same total.

Bethe is the standard way around it — it has no order in it at all. chain_free_energy is provided for reasoning about a specific message path, and the docstring says which to prefer for reporting.

2. Variable entropy needs an explicit belief representation

DiracBelief and TrivialBelief contribute 0.0; categorical beliefs and mixtures of categoricals use exact Shannon entropy. gaussian.jl adds the proper Gaussian entropy. Unsupported representations throw.

The Dirac convention deserves scrutiny: the differential entropy of a point mass is , but the correction term it contributes is taken as zero, on the grounds that a clamped variable carries no free bits. That is the convention BP uses for observed nodes and it is right, but it is a convention and it is stated rather than derived.

The counting correction cannot be computed without variable entropies; unsupported belief representations throw rather than silently approximate.

3. chain_free_energy folds with a singleton wrapper

compose_free_energy([Fs[i]], acc) passes a one-element sample vector, so the “expectation under the downstream inversion” is an evaluation at a single point. That is exact for deterministic (Dirac) inference and degenerate otherwise — it silently computes with a one-sample mean.

Documented, but this is the weakest function in the file. A faithful implementation needs the actual samples from the downstream inversion, which needs a belief type that can be sampled, which is the same blocker as everywhere else.

4. LenticulumCore.scalar_free_energy is extended, not shadowed

The first version defined Mycelium.scalar_free_energy and the test suite immediately hit UndefVarError … two or more modules export different bindings with this name. The scalar free energy of a graph and of a factor are the same concept at two scales; two exported bindings would force every downstream user to disambiguate. Extending is the right call and multiple dispatch makes it free.

Third and fourth name collision in the project (Channel, precision were the first two), which is why an exhaustive names() scan against Base and LenticulumCore is now part of the routine rather than something discovered one test at a time.

5. The grading is nested and the arithmetic assumes it

bethe_free_energy returns GradedEnergy((; factors = GradedEnergy(...), variables = ...)) — a GradedEnergy whose leaves are themselves GradedEnergys. LenticulumCore’s +, -, * on GradedEnergy recurse correctly, so this works, but it is exactly the nested-grading awkwardness energy §2 warns about: the names come from a fold rather than from the graph in one step.

Here the names do come from the graph in one step (factor names, variable names), so the E_G = ⊕_f E_f grading is built correctly. It is only the outer two-way split that is a fold.

Related: Bethe Free Energy, Scalar and Multivariate Energy, energy, graph

The gradient code moved (2026-11-10)

free_energy_gradient of a graph and parameter_step are now in MyceliumLearning (gradient). The sections below on parameter training describe that code; the free energy itself, the checks and the belief hooks are still in this file.

Parameter training at fixed beliefs (LP-002, 2026-10-26)

Superseded in part by LP-020 (2026-11-01)

As first written, the derivative below held the incoming messages fixed. It now holds each factor’s belief fixed, for factors that implement factor_belief; see the section Fixed beliefs, not fixed messages below.

free_energy_gradient(store, g, ps, st; ad) differentiates each scalarised local free energy and assembles a tree matching ps. Nonlearnable factors get zero subtrees. Messages are snapshotted outside AD. Bethe variable corrections are constant under this partial derivative, so the result is the parameter gradient of their sum plus those corrections. The same cavity edge validation as reporting applies. Each learnable factor’s _check_factor_ad(ad, factor, factor_state) validation runs before its local derivative, using that factor’s state subtree. It rejects SciML AD with nonempty Lux state and reports a missing Enzyme Euler/RK4 runtime-activity setting before entering AD (see neuralode). parameter_step uses the same graph gradient check.

parameter_step(store, g, ps, st; ad, rule, optimiser_state) evaluates the rule’s look-ahead parameters, obtains that gradient, and applies rule_put to each learnable factor’s flattened vector. It returns (ps_new, st_new, optimiser_state_new); Lux state advances once at the look-ahead parameters. Pass the returned optimiser state on the next call for Momentum/Nesterov. The existing OptimiserFactor still operates on exposed parameter wires with an externally supplied gradient; schedules do inference only. There was no graph train/learn driver supplying those gradients.

This is the smallest training driver: alternate inference and parameter steps as appropriate for the model. It neither differentiates through inference schedules nor implements per-edge couplings, parameter sharing, stochastic gradient estimators or frozen cotangent semantics. ImplicitLayers/test/parameter_ad.jl learns the coefficient of a discrete scalar ODE to its known generating value and checks the Nesterov look-ahead formula, with ForwardDiff, Zygote, Mooncake and runtime-activity Enzyme in Reverse and Forward modes.

Fixed beliefs, not fixed messages (LP-020, 2026-11-01)

The defect. The local free energy recomputes the factor’s belief from its incoming messages. Holding the messages fixed, the belief moves with , and the derivative picks up , which is not zero. On the two-variable tree of test/lp020.jl that derivative was against the true , and alternating inference with it stopped at instead of the maximum-likelihood . See LP-020 The fixed-message parameter gradient is not the free-energy gradient.

The fix. The Bethe free energy is a function of beliefs and parameters, , and belief propagation’s fixed points are its stationary points in under the normalisation and marginal-consistency constraints (Yedidia–Freeman–Weiss). The constraints do not involve , so by the envelope theorem the derivative of the free energy at the fixed point is the partial derivative at fixed beliefs:

The variable entropies drop out. Two hooks in factors.jl express it:

  • factor_belief(factor, msgs, ps, st) returns the factor’s belief in some form of the factor’s choosing. The gradient evaluates it once, outside AD.
  • belief_free_energy(factor, b, ps, st) is at that fixed belief, graded like local_free_energy, and equal to it at the belief it was evaluated at.

free_energy_gradient differentiates belief_free_energy at the fixed belief. On a tree at the fixed point this is the gradient of . On a loopy graph it is the gradient of the Bethe approximation at the loopy fixed point, which is what training against that approximation means.

Implementations. In Lenticulum (src/gaussian.jl, FrozenGaussianBelief): GaussianFactor (with learnable noise), GaussianPrior (learnable noise), LinearConstraintFactor, SwitchingConstraintFactor (whose frozen belief includes the outcome posterior , so , and the log-weights all get the envelope gradient), and the collapsed Gaussian composite. Every one of these has an affine residual , so one function builds the frozen joint Gaussian of the non-point channels. belief_free_energy re-evaluates the residual’s mean and covariance under it at the current parameters.

In AlgebraicFactors (2026-11-02): ToricFactor, whose frozen belief is the joint table over its states (ToricBelief), and the degree-one PolynomialFactor, whose frozen belief is the joint Gaussian of its free coordinates (PolynomialBelief); toric.md and polynomial.md give the formulas and the checks in lib/AlgebraicFactors.jl/test/lp020.jl.

What it does not do.

  • A factor without factor_belief keeps the fixed-message derivative. That is the same thing when every incoming message is a point (the belief is then a point too), and in general it is not. A factor with uses_cavity whose messages are not all points logs a warning once. The hook-less learnable factors in the repository are the neural and diffusion factors, whose graph uses are with point messages. PriorFactor has no hook and needs none: neither its belief nor its nlogp reads the parameters, so its parameter derivative is zero either way.
  • The argument is about the summed free energy. A nonlinear per-factor scalarisation changes the objective that belief propagation does not minimise, and the fixed-belief derivative is then not its gradient.
  • The fixed point must be at the parameters the gradient is evaluated at. parameter_step with a look-ahead rule evaluates at look-ahead parameters with the current messages, as before.
  • Non-diagonal couplings and adjoint = :implicit differentiate through inference (gradient_couplings, graph_adjoint) and are unchanged. sample_gradient uses this gradient per sample by default (sampling).

Checked in test/lp020.jl. On four trees (the linear constraint above; a Gaussian factor and a Gaussian prior, both with learnable noise; the collapsed composite; a switching constraint) the graph gradient matches central differences of the converged Bethe free energy, with inference re-run at every perturbed parameter, to with reference differences, ForwardDiff and Zygote. belief_free_energy equals local_free_energy at the frozen belief to . On the linear constraint, alternating inference with gradient steps now converges to the maximum-likelihood .

Difficulties.

  1. The switching test first put a Gaussian prior on the latent channel. That prior then receives the factor’s Gaussian-mixture message, and no Gaussian factor’s free energy accepts a mixture (its entropy has no closed form). The test uses a degree-1 latent instead. Its belief is proper because is invertible.
  2. Even a degree-1 variable had its marginal’s entropy evaluated, and multiplied by the counting number 0. That threw for the mixture marginal. Degree-1 variables are now skipped (_variable_term).
  3. Zygote has no rule for inv(::Cholesky). The constraint factor’s fixed-belief energy uses inv(Symmetric(Q)), as the Gaussian factor already did.
  4. A bounded review by Mistral (vibe) of the diff found no correctness bug. It made one change: trivial and missing messages are not points, so they trigger the fallback warning.

The merged free energy of belief propagation and mean field (2026-11-02)

L-SPEC-005 The Hybrid Free Energy. A graph with MeanField() nodes is scored by Riegler et al. (2013), §III, eq. (17), checked against the paper (arXiv:1112.0467v3):

  • factor_free_energies calls mean_field_energy(factor, marginals_into(s, g, f), ps, st) for a mean-field node: the marginals, which are what its messages read, not the cavities.
  • counting_number(g, v) = 1 - bp_degree(g, v). A variable whose neighbours are all mean-field nodes counts 1, its full entropy, as in naive mean field. So total_counting_number is the Euler characteristic only when every node is on belief propagation.
  • The gradient differentiates mean_field_energy at fixed marginals. At a fixed point of the hybrid messages, a stationary point of (their Theorem 2), this is the derivative of the converged free energy, by the same envelope argument as LP-020.
  • _check_energy_edges(g; mean_field = false) keeps the refusal on the paths written for belief propagation: the coupled and implicit adjoints, which differentiate through inference, and the sample buffer, which records residual moments from cavity messages. The cavity edge-direction check (LP-014) skips mean-field nodes, which read marginals.

Difficulty. Building the product of the marginals inside the differentiated function made Zygote trace push!. Lenticulum’s ChainRulesCore extension marks the builder non-differentiable: it depends on the marginals only, which the gradient holds fixed.

Checked in Lenticulum’s test/mean_field_free_energy.jl; the numbers are in L-SPEC-005.

LP-011 implementation (2026-10-27)

The all-diagonal driver retained its fixed-cavity derivative (replaced by the fixed-belief one, LP-020) and now masks frozen coordinates. Other couplings use the explicit replay implementation. parameter_step applies look-ahead and updates only active coordinates; fully pinned factors have no optimiser key. Score steps return their GradientEstimate as a fourth entry. Factor free-energy evaluation uses a functional map with the same per-factor state threading, so reverse AD avoids mutating a values array.

Evidence: lib/MyceliumLearning.jl/test/gradient_couplings.jl and test/gradient_couplings.jl. API, mixed Jacobians, costs and unsupported combinations are specified in gradient_couplings and L-SPEC-002 Stop Gradient.

Device parameter driver (2026-10-27)

The GPUArraysCore extension implements active-coordinate gathering, replacement, masking and pinning without host scalar reads. Default diagonal gradients and coupled replay use the same helpers. CPU helpers retain their original arithmetic. Device parameter steps cast GradientDescent/Momentum/Nesterov coefficients to parameter precision, preserving Float32 even with the default Float64 learning rate. Optimiser vectors still contain only active coordinates. Tests in lib/ImplicitLayers.jl/test/device_arrays.jl check closed-form Gaussian/Dirac objectives, cut/freeze behavior, score estimates and actual DEQ/ODE factor scoring. See gradient_couplings for the supported device subset and its limits.

Batch C graph parameter adjoints (2026-10-28)

free_energy_gradient and parameter_step forward damping and support adjoint=:implicit, maxsweeps, tol, linear_solver=:dense/:krylov, linear_tol and linear_maxiter. Defaults retain local all-diagonal training (fixed-belief since LP-020) and finite replay for non-diagonal graphs. The implicit opt-in starts reference inference from empty messages and includes both local losses and Bethe corrections in its adjoint RHS. The resulting tree gradient has a dense Gaussian negative-log-partition oracle; loopy tests reconverge the Bethe objective at every perturbation. See graph_adjoint for the equation, costs, cuts, CPU/empty-message-state restriction and residual checks.

Flooding/residual/damped finite derivatives and their realised-schedule semantics are specified in gradient_couplings and tested in test/graph_adjoint.jl and test/graph_adjoint_devices.jl. Native Enzyme/Mooncake replay is still rejected; the reproducer and backend findings are recorded in LP-002.

Tied parameters (2026-11-02)

free_energy_gradient returns one entry per parameter key (parameter_keys(g)). For a key read by several nodes it evaluates each node’s term outside AD as before (its belief, its mean-field marginals, or its messages for a factor without factor_belief) and differentiates the sum of their scalars in one AD call (_gradient_item, _tied_scalar); one node is differentiated as before. parameter_step keeps one optimiser state per key. factor_free_energies still reports one energy per node, keyed by node name, and threads state by key. scalar_free_energy sums the same terms as a vector (_factor_terms), so it does not build a type with one field per node, which recompiled for every plate size (plates.md). Checked in test/plates.jl against the sum of separate graphs’ gradients. The coupled drivers differentiate the whole of ps and sum tied entries without change.

Batched energies over plates (2026-11-03)

With message blocks (blocks.md, L-ADR-0010 Plates get batched message blocks), a plate factor row whose incoming messages are blocks is evaluated in one call: _factor_terms and scalar_free_energy use local_free_energies(factors, msgs, ps, st), and free_energy_gradient gives the row one item, _beliefs_scalar over factor_beliefs (evaluated outside AD) and belief_free_energies (differentiated). Rows are found by _energy_rows: belief-propagation nodes on one key, edges in block rows in one channel order, replica in column , none detached. A variable row’s Bethe terms are the entropies of its marginal block (_variable_terms_rows). A store without rows (the coupled drivers’ replay, or one built from vectors) takes the per-node path unchanged, which also keeps that path free of mutation for Zygote. The scalar sum over a row is a function of the concretely typed factor vector, so scalarisation is not dispatched per node. Tested in test/plates.jl against the same messages per edge; timings in blocks.md.

Since 2026-11-15 (I21) the rows are kept in the graph (FactorGraph.energy_rows) with the store’s block layout they were found for, and found again only for a store with another layout: they depend on the graph and the layout, not on the messages, and finding them was 14% of fit_em on a plate of 3 000 regime factors (1.3 ms a call, several calls per iteration). The graph is not edited in place (edits build a new graph), and a layout is compared by identity, then by value. Test: Lenticulum test/regime_plate.jl, “energy rows kept per store layout”.

Zygote on block rows (P20, 2026-11-16)

Zygote.gradient of scalar_free_energy in ps failed on a store with block rows, while it worked on the same messages held per edge. Mistral’s review of 2026-11-11 found it at the sum(...; init = 0.0) of _row_scalar, for which ChainRules has no rule. Fixing that showed three more blockers, met one after the other: the masks of covered nodes are written in place (covered[row.fids] .= true), the variable rows’ entropies build typed index vectors (_variable_row_term), and every factor type’s batched local_free_energies fills arrays (the default writes into a Vector{Any}, the Gaussian prior’s factor_beliefs pushes, _blockdiag fills a matrix of zeros).

  • _row_scalar is sum(map(...)); a row has at least one factor.
  • The masks are written by _mark!, and _variable_terms_rows is @non_differentiable: it reads only the store’s blocks, which do not depend on ps, and a store built inside AD from message vectors has no block rows.
  • A row’s scalar energy goes through _row_scalar_energy, whose rrule (MyceliumChainRulesCoreExt) keeps the batched primal and runs the caller’s AD through _columns_scalar: the same energy replica by replica, each through local_free_energy on its column, cut outside AD. Every replica gets the incoming state, which is empty on a row (_check_tied_state; untied rows only when every key’s state is empty). No tangent reaches the messages, the factors or the state.

That is the derivative at fixed messages, what ForwardDiff computes. A first version took the envelope argument of free_energy_gradient instead (the rrule differentiated belief_free_energies at the frozen factor_beliefs). On the factor-analysis plate it agreed with free_energy_gradient to 2e-16 and differed from ForwardDiff by 0.78, at the converged messages and away from them (a scratch script, not kept). The two gradients are different quantities (LP-020), and a rule must give the derivative of the function it is attached to, so that version was dropped.

What it does not do. The reverse pass is the per-replica code, so it is only as differentiable as the factor’s local_free_energy is. For LinearConstraintFactor and for switching factors with EP sites it was not (an in-place _blockdiag, push! and inv(::Cholesky)); since P23 it is (Lenticulum constraint.md, “Zygote through the cavity free energy”; test/zygote_cavity.jl, and both plates in test/plates.jl on blocks and per edge). It assumes that a factor’s batched local_free_energies equals the sum of its per-replica energies, which the tests check for the Gaussian prior and observed switching factors (ForwardDiff on blocks is the oracle). On a clustered regime plate the values agree (to 1e-14, a scratch probe), but no gradient can be compared: neither Zygote (a push!) nor ForwardDiff (Float64(::Dual)) takes that free energy, per edge as on blocks (P24, @test_broken in Lenticulum test/regime_plate.jl), while free_energy_gradient does, through the fixed-belief energies. The reverse pass costs one local_free_energy per replica, not one batched call.

Tests: Lenticulum test/plates.jl, “Zygote through the free energy on message blocks (P20)” (random plates of priors with a learned noise, against ForwardDiff on blocks and Zygote per edge) and the observed switching plates in “Plates of switching factors on message blocks”. Before the change the switching testset stopped with the MethodError of _row_scalar.

Expectation-propagation and mixture-reduction nodes (2026-11-03)

An ExpectationPropagationRule() node is counted like a belief-propagation node: its local_free_energy at its incoming messages, and its edges in each variable’s counting number (bp_degree counts both rules, _cavity_rule in graph.jl). At an EP fixed point the factor belief’s marginals match the variables’ Gaussian marginals in their moments rather than exactly, and the same expression is the free energy whose stationary points those fixed points are: test/mixture_rules.jl checks it numerically, the fixed-belief gradient against the derivative of the re-converged free energy (passing.md). The default drivers accept EP nodes; the paths that differentiate through inference (non-diagonal couplings, adjoint = :implicit) and the residual-moment recorder still refuse anything but belief propagation. Energy rows of a plate (_energy_row) accept EP nodes too, when every node of the row has the same rule.

A MixtureReduction(M) node is refused by every energy path (_check_energy_edges). Its fixed points are not the stationary points of a free energy we can name, and Lenticulum’s local free energies collapse mixture inputs to their moments, so the number would describe other beliefs than the ones the node sent.

The Bethe free energy of a belief-propagation graph whose marginal is a Gaussian mixture is not available either: variable_entropy has no method for a Gaussian mixture, which has no closed-form entropy. A latent mixture on a plain BP graph therefore has messages but no free energy; on EP nodes its marginals are Gaussian and it has both.

Learned relations that are not densities of their data (2026-11-04, LP-022)

free_energy_gradient warns once per session when a learnable node whose factor learns_unnormalised (a hook, false by default; Lenticulum’s constraint factors without an output, AlgebraicFactors’ unnormalised ToricFactor) has no frozen A and a channel on a variable that a DataFactor observes; inside a cluster node it looks at the clustered factors through their wiring. Such a factor is normalised in its residual, so its free energy on data can fall without fitting (LP-022). It is a warning, not a refusal: a fit may hold the coefficients fixed in its own loop. Detection only covers data from DataFactors. Test: Lenticulum test/lp022.jl.

Since 2026-11-05 the hook also has a form by channel, learns_unnormalised(factor, observed) (the channels a DataFactor observes), which by default is the one-argument form when any channel is observed; DEQFactor overrides it to fire only with its state observed.