Explicit finite schedule derivatives, per-edge cuts, parameter subset freezing, terminal score estimators and a separate straight-through factor. The diagonal default holds each factor’s belief fixed (since LP-020, 2026-11-01; it held the cavities fixed before). Supported domains and limits are explicit below.
Sources: original implementation; AutoBayes Definition 29 and Remark 30; code:
gradient_couplings.jl,free_energy.jl,graph.jl; tests:lib/MyceliumLearning.jl/test/gradient_couplings.jl,test/gradient_couplings.jl.Bibliography: St Clere Smithe & Perin 2025
Theory (CT-ML wiki): Statistical Game · Automatic Differentiation of Expected Values
API and domain (2026-10-27)
connect!(...; coupling=DiagonalCoupling(), detach=false) labels one factor-port
attachment, in both message directions. factor!(...; freeze=()) accepts :all,
one subtree path (:encoder,), or several paths ((:encoder,), (:decoder, :bias)).
Tuple components may use integer indices. Missing paths throw when ps is supplied.
free_energy_gradient(store,g,ps,st; ad, schedule, nsweeps=1) retains the old
fixed-store driver when every edge is diagonal. Otherwise it differentiates a fresh,
empty-store replay of the specified schedule. The supplied store is not a record of
inference history and is not replayed. Sequential, tree, forward/backward, flooding and residual schedules are supported,
including damping (the batch C contract below). A finite unroll computes the derivative of
that iteration, including local free energies and Bethe variable corrections. It is
not a fixed-point derivative or a guarantee of exact inference in a loopy graph.
Reference differences, DI AutoForwardDiff() and AutoZygote() are supported for
the tested scalar/array Dirac and Gaussian cases. Other schedule backends and nonpositive sweep counts raise ArgumentError. The existing
diagonal driver retains its LP-002 factor backend support.
Mixed Jacobians
Write each scheduled message as a function of earlier messages and parameters. A Jacobian path is the product of its local Jacobians; different paths add. At each crossed boundary:
detach=truemakes the entire boundary derivative zero, regardless of coupling.- Diagonal holds that message at its reference value. Local explicit parameter derivatives survive; derivatives entering through that message are dropped.
- Exact retains the full derivative of the computed belief representation.
- Pathwise retains Gaussian/Dirac representation derivatives. Gaussian moments propagate analytically: this is the Rao–Blackwellised Gaussian reparametrisation rule, without differentiating a random-number generator. Other informative families throw; uninformative identity messages are allowed.
- Score replaces a terminal incoming Gaussian/categorical distribution by a fixed sampled Dirac and adds its density score weighted by the terminal factor cost.
Thus a path crossing both exact and pathwise boundaries survives; one crossing a diagonal or detached boundary is cut. This is a schedule-level realisation of the blocks omitted in AutoBayes Definition 29, rather than a single graph-wide switch. Each factor-port attachment is a boundary: a factor-variable-factor connection has two attachments, both of which must permit the desired derivative.
Score estimates
ScoreFunctionCoupling(; baseline=nothing) uses a fixed finite scalar baseline
(zero when omitted). Supply an explicit rng and nsamples >= 2. Samples are drawn
outside AD; each differentiated replicate contains the direct loss derivative and
(reference_terminal_loss - baseline) * (logq - reference_logq). The score accounts
for parameter-dependent probabilities, including categorical messages. The baseline
is independent of both parameters and the current draw, so its expected score is zero.
This implementation supports one sweep and terminal factors whose ports are all
Absorbing. Categorical probabilities must be strictly positive; a changing-support boundary
has no supplied derivative. Duplicate ports for the same variable in a sampled terminal
factor require a joint sampling rule and throw. Bidirectional sampling would replace BP densities and entropies with
particles and change the objective; it is rejected. Unsupported samplers/densities
throw. The estimated objective is the expectation of terminal point costs under
those sampled messages, plus the other analytic local terms and Bethe variable
corrections. Replacing a terminal distribution by a Dirac does not estimate its entropy. Multiple
terminal score edges can coexist with exact/pathwise/diagonal boundaries upstream.
GradientEstimate.value and .standard_error have ps’s shape, with componentwise
sample standard errors and .nsamples. A score parameter_step returns a fourth
entry containing this estimate; deterministic steps retain their three entries.
No confidence guarantee or exactness is asserted for a sampled value. A coupled
parameter step commits inference plus one local-energy state advance from its first
replicate; other replicates start from the same initial state and do not accumulate
state updates. The diagonal step retains its previous fixed-store state advance.
Freezing and straight-through values
islearnable=false identifies an intrinsically nontrainable factor; isfrozen=true
pins all parameters for this run without changing learnable_factors. Both preserve
input derivatives. A graph-local freeze selects a subset. Frozen coordinates have
zero graph parameter gradient and no entries in the optimiser vectors; fully pinned
factors have no optimiser key. Look-ahead and update operate on the remaining coordinates.
Input cotangents still pass through the factor, including when every parameter is pinned.
StraightThroughFactor(forward,surrogate; channels=(:in,:out)) is a parameterless
directed factor with zero local game cost. Its message is the forward value, with the
surrogate input Jacobian. The callables are fixed functions of one scalar/array input.
Core’s straight_through has a ChainRules reverse rule using the surrogate pullback
and a ForwardDiff extension preserving surrogate dual partials. Other graph derivative
backends, including reference differences, throw: differences of round cannot
recover an identity surrogate. Arbitrary outer AD calls must choose a supported backend.
Verification and difficulties
The tests independently derive the linear chain derivative and the Gaussian marginal likelihood derivative. They check cuts, mixed boundaries, subset/all freezing, learnability, optimiser state, categorical/Gaussian score means and variance reduction, and round/identity surrogate derivatives against surrogate differences.
The legacy diagonal gradient holds cavities, not full factor posteriors, fixed.
Gaussian local_free_energy recomputes its posterior from these cavities and its own
parameters. It therefore differs from true EM even at a BP solution. The Gaussian test
derives this local derivative separately and checks that true fixed-posterior EM equals
the marginal-likelihood derivative (the envelope identity). This distinction is retained
for compatibility rather than calling the legacy result an EM gradient.
Reverse AD through the mutable inference store caused aliased cotangent accumulation;
replay uses an immutable store with copied message vectors. Graph structure and freeze indices are constants.
The ordinary infer! reverse rule replays its realised sweep count and task choices, ignoring
cotangents of state/reports; it does not differentiate convergence decisions. Graph descriptions (including data
stored inside them) are fixed in the reverse rule; expose a differentiable source
through its parameter tree. No graph/data cotangent interface is claimed. Gaussian
schedule messages use functional matrix inverses, and belief_cov has the inverse
matrix pullback, avoiding inverse-of-Cholesky mutation. Ordinary inference arithmetic
is retained. Gaussian joint precision assembly now preserves promoted element types.
Replay copies an edge-sized vector for each message task. With K tasks and E edges, storage/copying can grow as O(K E), in addition to backend tapes. Forward mode also scales with parameter dimension. The opt-in implicit graph adjoint is documented in graph_adjoint. General device support, higher-order score rules and stochastic solver-inversion derivatives are not claimed.
LP-002 batch A endpoint state policy (2026-10-27)
NeuralODE factors can opt into state_policy=:fixed: constant incoming Lux state
per solve and one final endpoint update. The existing diagonal graph parameter
gradient and parameter_step driver use the factor’s policy and fixed state
subtree. lib/ImplicitLayers.jl/test/lp002_batch_a.jl checks these gradients
against a state-dependent affine closed form with ForwardDiff, Zygote, Mooncake
and runtime-activity Enzyme reverse. Default evaluation-state threading is
unchanged; state derivatives, schedule replay backends and graph adjoint scope
are unchanged. flow records the solver/backend restrictions.
LP-002 batch B device replay (2026-10-27)
lib/ImplicitLayers.jl/test/device_arrays.jl extends finite static replay to
JLArrays Float32/Float64, with scalar indexing disabled, using ForwardDiff/Zygote.
Dirac and diagonal Gaussian messages cover exact/pathwise/diagonal couplings,
attachment detach, subset/all freezing, raw static infer! AD and parameter steps.
A quadratic terminal factor has a closed Gaussian expectation: its variance term
is included, as is the graph’s Bethe variable-entropy correction. Comparing only
the terminal expectation would omit a precision derivative in this exposed graph.
Active-coordinate gathers upload host integer metadata once and use device array indexing. Frozen replacement gathers from concatenated old/active coordinates; masking and pinning broadcast. Integer metadata has no tangent. Scalar host comprehensions of parameter values previously broke both replay and diagonal steps.
Terminal diagonal-Gaussian score tests use an explicit host RNG, bulk-copy noise to the device and compare gradient estimates and componentwise standard errors with CPU using common draws. This tests the finite estimator, not its statistical convergence or a native GPU RNG. Device Gaussian density/entropy use elementwise algebra. Dense Gaussian message factorisations, categorical score devices, nonterminal score rules, other schedules/backends and hardware GPUs remain outside this coverage. Enzyme/Mooncake replay continues to throw a backend error.
Raw inference also exposed a tuple/vector cotangent mismatch when final replay
message vectors were converted by splatting into Any[...]. A normal vector copy
preserves the vector tangent representation. Device Gaussian convergence distances
strip duals (reports are metadata) and use typed reduction initializers; Float64
initializers could not hold a Float32 dual maximum. Pooled diagonal-Gaussian
messages are checked against the analytic pooled mean/variance/entropy derivative.
Implicit messages select their derivative backend
Replay now carries ad as a constant context into _gradient_message. The
ImplicitLayers DI extension routes DEQ messages through solve_state/solve_input
with that backend, so the nonzero downstream graph loss uses the IFT primitive
rather than root-iteration AD. Ordinary inference and diagonal (fixed-belief)
training keep their existing primal/default behavior. The raw ChainRules inference
replayer uses the same hook with a reverse-mode sentinel selecting AutoZygote.
Device tests check both DEQ and Euler-flow message directions, graph gradients and
parameter steps against dense closed forms; raw Zygote static inference is checked
too. Raw ForwardDiff through implicit infer! is not an automatic IFT interface:
use free_energy_gradient(...; ad=AutoForwardDiff(), schedule=...) for explicit
backend selection. Reverse-input DEQ replay with nonempty Lux state is rejected:
its ordinary inversion threads evaluation state while the explicit IFT equation
fixes it. Forward-state DEQ messages retain fixed-state solves. No general graph
fixed-point adjoint or new native replay backend is introduced.
Raw ForwardDiff DEQ messages now reject dual-valued unannotated solves with an ArgumentError pointing to the explicit graph gradient driver, preventing accidental root-iteration differentiation. Ordinary primal messages are unchanged.
The backend-context migration also includes the top-level GaussianFactor, GaussianPrior and GaussianComposite specialisations. Their existing matrix-inverse formulas remain the replay path; omitting the new argument bypassed those rules and exposed inverse-of-Cholesky mutation in the first full CPU regression run. The existing top-level closed marginal-likelihood oracle detects this failure.
Batch C: realised schedules (2026-10-28)
free_energy_gradient(...; schedule, nsweeps, damping=0.0) starts from empty
messages and differentiates exactly that finite computation, with reference
differences, ForwardDiff or Zygote. The all-diagonal default still uses its
fixed-store partial derivative. adjoint=:implicit explicitly selects the
converged-message equation in graph_adjoint, including for all-diagonal graphs.
Sequential/tree/forward-backward tasks read all preceding updates. Flooding
captures a store at each sweep boundary: every candidate reads that snapshot,
while functional Lux state threads in task order as in ordinary sweep!.
Residual scheduling runs the actual priority executor outside AD, recording
every committed task in order (including tie-breaking and early exit). Replay
then executes that fixed sequence, with the same initial state. Probe-only
state updates are discarded, as in ordinary residual scheduling. Factors must
not mutate incoming state or hide randomness/side effects: replay assumes a
deterministic functional factor evaluation. The raw ChainRules infer! rule
records residual choices in its own reference pass. Its existing rule detaches
state after every task and returns no state/report cotangents. The parameter
driver includes functional state dependencies in its finite computation, as
before; these two state contracts therefore differ for stateful factors.
This is the derivative of the realised schedule, a piecewise-defined computation. Task choices, convergence counts, message families and polarity branches are fixed during differentiation. At a residual tie or stopping threshold it is a selected-branch derivative, not a derivative of argmax or a guarantee that perturbed inference picks the same tasks. Reference differences for residual tests freeze the recorded sequence too. Reconverged differences are a separate oracle for the implicit path.
For each :to_variable update, compute the candidate, then call exactly
damp(candidate, old, 1-damping) if an old message exists and damping is positive.
Variable-to-factor pools are undamped; unsupported belief damping remains the
ordinary inspectable no-op. Gaussian canonical parameters and numeric Diracs
are tested. Device damping weights are cast to payload precision to avoid
Float32 widening; CPU primal arithmetic is unchanged. Score estimators retain
their one-undamped-static-sweep restriction.
test/graph_adjoint.jl checks loopy and tree Gaussian replay against ordinary
inference and fixed-sequence differences, for exact/pathwise couplings, damping
and raw Zygote inference. test/graph_adjoint_devices.jl checks Float32/Float64
diagonal Gaussian tree/loop replay with JLArrays scalar indexing disabled against
CPU derivatives of the same recorded operations. This is emulation, not hardware
GPU validation. The implicit coordinate adapter is CPU-only even with Krylov.
Enzyme/Mooncake replay remains explicitly rejected. The standalone reproducer
lib/MyceliumLearning.jl/examples/lp002_replay_backends.jl bypasses that guard to probe
the actual implementation with runtime-activity Enzyme modes and Mooncake.
Mooncake succeeds on the minimal Dirac probe but fails on Gaussian Bethe
entropy at _improper_check’s try/catch. Runtime-activity Enzyme forward
fails in messages_into; reverse fails in Base’s setindex_widen_up_to.
The dated LP-002 section records versions and commands. The public backend
guard is retained; no general native backend support follows from a Dirac probe
or from factor-local endpoint rules.
Fully cut factors at fixed beliefs (LP-021, 2026-11-02)
The objective of the coupled drivers (_graph_scalar, used by the unrolled replay and by the
implicit adjoint’s loss) evaluated every factor’s local free energy at its messages. A factor
whose edges are all diagonal or detached has constant messages, so its parameter derivative was
the fixed-message one, which LP-020 showed is not the free-energy gradient: with default couplings
adjoint = :implicit was 0.58 off on a three-variable tree, and one ExactCoupling edge anywhere
switched every fully cut factor from the default driver’s fixed-belief gradient to this one.
_frozen_beliefs now evaluates factor_belief for those factors at the reference messages,
outside AD, and _graph_scalar differentiates belief_free_energy at that belief. Factors with a
derivative path, and factors without factor_belief, are unchanged. test/lp021.jl checks the
all-diagonal, one-exact-edge and all-exact cases against central differences.
Mixed cuts: couplings only in a replay (LP-021 option 3, 2026-11-04)
At a fixed point the free-energy gradient is the envelope one, whatever the couplings; a coupling
can only change the derivative of a computation that is not at its fixed point, or of another
loss. So free_energy_gradient without schedule uses the envelope driver for graphs with
diagonal, exact or pathwise couplings (_deterministic_couplings; before, non-diagonal edges
required a replay), and adjoint = :implicit returns the envelope gradient at its converged fixed
point when the graph is mixed (_mixed_cuts: a cut and a differentiated edge, both carrying
messages that depend on the parameters; a data factor’s edges and an observed variable’s do not
count). On a graph that is not mixed the implicit adjoint is kept; it equals the envelope gradient
there (test/lp021.jl, test/graph_adjoint.jl). A replay with schedule still differentiates the
replayed sweeps, and warns on a mixed graph: holding a parameter-dependent message fixed next to
differentiated ones gave errors of 0.18–0.73 against the free-energy gradient, at convergence
(the LP-021 note has the table). Score-function couplings and StraightThroughFactor keep the
replay semantics.