Split in November 2026
Gradients, couplings, the graph adjoint and EM are in MyceliumLearning; this package is inference only. Where a section below describes them, it describes code that now lives there.
Sources: code:
Mycelium.jl,factors.jl,free_energy.jl,gaussian.jl,graph.jl,messages.jl,passing.jl,polarity_resolution.jl,schedules.jlTheory (CT-ML wiki): Lax Functor · Bayesian Inversion · Variational Free Energy · Lens · Bayesian Lens
Implements: factor graphs and message passing for Lenticulum. This is the layer with no counterpart in Lux, because in Lux the wiring is a DAG and the message order is implied by it.
Concept notes: Factor Graphs, Everything is a Factor, Messages are Inversions, Polarity Resolution, Schedules, Bethe Free Energy, Loopy Message Passing.
File map
| file | note | content |
|---|---|---|
graph.jl | graph | the bipartite structure, edge directions, istree / isdag |
polarity_resolution.jl | polarity_resolution | target + available messages → Polarity; legality |
messages.jl | messages | the store, combine, both exclusion principles |
schedules.jl | schedules | tree / flooding / forward-backward / residual |
passing.jl | passing | executing a schedule; convergence reporting |
free_energy.jl | free_energy | counting numbers, Bethe, the graded energy |
factors.jl | factors | data, priors, losses, optimisers, relays |
gaussian.jl | gaussian | the Gaussian rules: pooling by addition, densities, entropy, damping, products |
Dependencies
LenticulumCore (the factor interface and the belief/energy types), LuxCore (parameter
trees), Random, DispatchDoctor, and the LinearAlgebra standard library for the Gaussian rules. No graph library: the adjacency structure needed here is
small, bipartite and channel-labelled, and every graph package would need adapting rather than
using. No solver, no AD, no distributions — same discipline as LenticulumCore.
Status
Working and tested (test/runtests.jl): the graph structure and its two acyclicity notions,
polarity resolution and legality, both exclusion principles, all schedule generators, the
message loop with damping and convergence reporting, the counting-number arithmetic, the
graded/Bethe free energy, and the five structural factors including the three optimiser rules.
Still partial: general belief_logdensity / combine support and joint messages over
several channels. ResidualSchedule execution is implemented in passing.jl; the
ResidualSchedule, uninformative available_channels, PriorFactor, and Check 4 testset
checks convergence on a relay chain.
Three amendments made to LenticulumCore for this
These belong in the interface package, not downstream, so they were added there:
supported_polarities(factor)— the listable form ofsupports_polarity. It must be complete when listable and may throw above a documented cap. Structural predicates can be overridden without a list. Polarity resolution itself constructs the assignment from the target and available messages and testssupports_polarity.isunidirectional(factor)— exactly one supported polarity.islearnable(factor)/isfrozen(factor)— the user’s “non-learnable factors” made a trait.islearnabledefaults toparameterlength > 0and identifies optimiser candidates.isfrozenpins all parameters for this run while preserving input derivatives. Graph-localfreezeselects subtrees; optimiser state excludes frozen coordinates.
Mycelium adds a fourth, locally: issink(factor) — zero supported polarities. Losses and
monitors are sinks, and this is a third case beyond unidirectional and bidirectional.
Implementation difficulties
1. Two bugs the tests found that the design did not anticipate
Both produce plausible-looking wrong answers rather than errors, so both are worth recording.
Tree schedules must be pruned by edge direction. The first version generated all
messages and threw a PolarityError at the loss node: an Absorbing edge cannot carry a
factor → variable message. The fix filters, and TreeSchedule.pruned counts what was dropped —
surfaced rather than swallowed, so a genuinely mis-wired graph is visible. See schedules §1.
The exclusion principle has to be enforced twice. The variable-side exclusion
( omits ) was designed in; the factor-side one was not. When
computing , the incoming message on that same edge must not be counted among
the observed channels, or the target resolves as both Observed and Unobserved.
That it threw rather than silently miscomputing is luck attributable to a design decision
made for a different reason: Polarity{names} carries channel names in its type, so a
double assignment is a construction error. With a Dict one would have overwritten the other
and the factor would have quietly conditioned on its own prediction. The performance argument
for the type-domain representation (channels §“Why the polarity is in the type”) turned out
to be the lesser reason for it.
2. Two name collisions, again
Mycelium.scalar_free_energy clashed with LenticulumCore.scalar_free_energy. Resolution:
extend the existing function rather than define a new one — the scalar free energy of a
graph and of a factor are the same concept at two scales, and two exported bindings with that
name would force every user to disambiguate.
After that, an exhaustive scan of names(Mycelium) against Base and LenticulumCore shows
zero remaining collisions. Worth doing once per package rather than discovering them one test at
a time — this is the third and fourth such collision in the project (Channel, precision
were the first two).
3. combine is the real gap
Pooling two general beliefs needs densities. Implemented: TrivialBelief as unit,
DiracBelief idempotent, DiracBelief dominating (the clamp), and
contradictory Diracs throwing — two hard clamps in disagreement is a wiring error, not a
numerical one. Everything else throws informatively.
This is the same open question open_model.md §4 records: the belief representation cannot be
designed before there is one working factor to design it against. Every downstream feature
(particle messages, conjugate messages, moment matching) is blocked on it, and that is the
single most important thing to unblock next.
4. Convergence cannot always be verified
belief_distance returns Inf for pairs it cannot compare, which makes propagate! run to
maxsweeps and report that convergence is unverifiable. Returning 0 would have been more
convenient and would have produced silent false “converged” reports. A wasted sweep is much
cheaper than a wrong answer, so Inf it is; the reason string says so explicitly.
5. Parameters: hidden or exposed, and the graph decides
A factor’s parameters may live in ps (Lux style, hidden) or be exposed as a channel and
thus become a variable — which is what makes an optimiser an ordinary factor
(Everything is a Factor). Both are supported, but nothing yet checks that a graph is
consistent about it: exposing a parameter and also threading it through ps would double-count
it silently. A validation pass for this is missing.
6. What is not implemented, and why not
- Joint messages over several channels at once. A message addresses one variable, so a factor coupling several unobserved channels discards the correlation between them — the mean-field laxness of Remark 16 at the message level. Not an oversight; fixing it means deciding where to pay for joint representations.
- General residual diagnostics.
ResidualScheduleexecutes, but its convergence report measures message changes, not correctness of a loopy posterior. - Graph adjoints. Finite realised-schedule replay is implemented in gradient_couplings; graph_adjoint implements an opt-in CPU message fixed-point adjoint. Native Enzyme/Mooncake replay and device implicit coordinates remain open. Belief and parameter updates stay separate.
Related: LenticulumCore, AutoBayes to Lenticulum, Factor Graphs
LP-011 implementation (2026-10-27)
Per-edge couplings, detach, graph-local subset freezing and a separate StraightThroughFactor are implemented in the documented static CPU domains. See gradient_couplings for mixed semantics, uncertainty returns and explicit restrictions. The former option-2 limitations above are historical.
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.