Mycelium API: schedules and inference
Schedules, the execution of a schedule (step!, sweep!, propagate!, infer!), the hooks of the message rules (expectation propagation, mixture reduction, mean field), cluster nodes and structure edits. The rule types themselves are with the graph on the Mycelium API page.
Schedules
Mycelium.AbstractSchedule — Type
abstract type AbstractScheduleA plan for message passing. Subtypes differ in whether they are static (a fixed task list computed from the graph) or dynamic (recomputed from message residuals each step).
Mycelium.FloodingSchedule — Type
FloodingSchedule(tasks)All tasks computed from the previous sweep's messages and committed together (double-buffered). The classical parallel BP update.
Slower to propagate information than a sequential sweep (one edge per sweep rather than a whole path), but message-order-independent for stateless factors. Lux state still threads in task order, so stateful factors can retain order dependence.
Mycelium.ForwardBackwardSchedule — Type
ForwardBackwardSchedule(forward, backward)For a graph that is a DAG under its edge directions: a topological belief sweep, then a reverse sweep along whatever edges are Bidirectional.
[!note] The backward list is empty for a strictly unidirectional DAG — and that is correct A Lux-style graph (all edges
Emitting/Absorbing) has no backward belief flow. Its backward pass would carry cotangents, not beliefs. The per-edge parameter-driver couplings supply cotangent paths separately from these belief tasks (LP-011, L-SPEC-002). Seeingisempty(sched.backward)says "this graph is explicit; there is nothing to infer".
Mycelium.HybridSchedule — Type
HybridSchedule(tasks)A static schedule for a graph with MeanField nodes, built by hybrid_schedule. It sweeps like a SequentialSchedule of tasks; propagate! measures its convergence on the variables' marginals by default (criterion = :marginals).
Mycelium.MessageTask — Type
MessageTask(edge, kind)One atomic message. kind is :to_factor or :to_variable.
Mycelium.ResidualSchedule — Type
ResidualSchedule(; maxtasks)Dynamic: repeatedly send whichever pending message would change the most (Elidan, McGraw & Koller's residual belief propagation).
Converges on many loopy graphs where flooding oscillates, because it prioritises the parts of the graph that have not settled. Note that sweep! evaluates every legal task's residual with commit = false before committing the largest step, costing $O(|\text{tasks}|^2)$ message evaluations per sweep rather than maintaining a local priority queue. Requires a usable belief_distance; pairs returning Inf are tried first.
Mycelium.SequentialSchedule — Type
SequentialSchedule(tasks)A fixed list, executed in order, in place: each task sees the results of the ones before it in the same sweep. Faster-propagating than flooding, and the basis of tree and forward schedules.
Mycelium.TreeSchedule — Type
TreeSchedule(inward, outward, pruned)The two-sweep schedule for a tree: every edge carries one message towards the root, then one away from it.
On a tree with only
Bidirectionaledges this is exact. After the outward sweep,marginal(store, g, v)is the true marginal for everyv. This is the only schedule here with a correctness guarantee.
pruned counts the messages the edge directions forbade. A Emitting edge cannot carry a variable → factor message and an Absorbing edge cannot carry a factor → variable one, so a graph containing unidirectional edges has fewer than 2|E| legal messages and the sweeps are correspondingly shorter.
[!warning] Pruning weakens the exactness guarantee, and deliberately so A
LossFactoronAbsorbingedges never tells its input variable anything: in belief terms a sink is genuinely uninformative about what it consumes. What a loss "tells" its input is a cotangent, not a belief, and cotangents travel by theAbstractGradientCouplingmachinery in the parameter driver, with explicit static schedule replay for supported non-diagonal couplings (LP-011, L-SPEC-002). Sopruned > 0does not mean the schedule is broken — it means part of the graph is explicit rather than implicit. It is surfaced as a field rather than swallowed so that a genuinely mis-wired graph (an implicit factor accidentally given a unidirectional edge) is visible.
Mycelium.all_tasks — Method
all_tasks(g) -> Vector{MessageTask}Every message the edge directions permit: one :to_factor per absorbing edge, one :to_variable per emitting edge. A bidirectional edge yields both.
Mycelium.forward_backward_schedule — Method
forward_backward_schedule(g) -> ForwardBackwardScheduleTopological belief sweep, then the reverse sweep over bidirectional edges only.
Accepts a DAG or a tree. isdag excludes Bidirectional edges, so the DAG branch's backward list is empty. On a tree that is not a DAG, wraps the inward and outward lists from tree_schedule. Other graphs raise ArgumentError.
Mycelium.hybrid_schedule — Method
hybrid_schedule(g) -> HybridScheduleThe schedule of the hybrid message passing of Riegler et al. (2013) for a graph whose belief-propagation part (the graph with its MeanField nodes removed) is a forest. A sweep is:
- every belief-propagation cluster (a component of that forest) swept inward and outward, as
tree_schedulewould, with the mean-field messages already at its variables held fixed; - each mean-field node in turn: its message to each variable it can emit to, then that variable's cluster swept again, so the next message reads the updated marginals.
Within a cluster the beliefs are then exact given the mean-field messages, and each mean-field update is followed by the exact cluster posterior: block coordinate descent on the merged free energy when the mean-field node's other variables are in other clusters. On a fresh store the first pass of step 1 starts every cluster from its own factors (priors, data). Throws when a cluster has a loop. Without mean-field nodes it is the tree schedule of each component.
Mycelium.islegal — Method
islegal(g, task) -> BoolWhether the edge's direction permits this message. A :to_factor task needs an absorbing edge; a :to_variable task needs an emitting one.
Schedules filter on this rather than throwing, because a unidirectional edge is a legitimate modelling choice, not an error — see TreeSchedule.
Mycelium.spanning_tree_schedule — Method
spanning_tree_schedule(g; root = nothing) -> SequentialScheduleA static schedule for a loopy graph: the messages on the edges outside a spanning tree, then the tree's inward and outward sweeps, all in place. One sweep carries information across the whole tree, so on a graph with one loop a message goes once round the loop each way per sweep, where flooding moves it one edge.
The tree is the breadth-first one of tree_schedule, from root (as there) in the component containing it and from a node of each other component; on a tree the schedule is tree_schedule's inward and outward lists, but iterated like any SequentialSchedule rather than stopped after one sweep. These are the updates of tree-based reparameterisation (Wainwright, Jaakkola & Willsky, 2003).
There is no convergence guarantee on a loopy graph, and the fixed points are flooding's (a schedule changes the map, not its fixed points). Measured on the resistive divider (one loop of six edges; bench/bp_schedules.jl, vault/Control/Composing Optimisers.md §4.2), it needs 0.17 to 0.18 of flooding's message evaluations to an error of $10^{-10}$. For graphs with MeanField nodes use hybrid_schedule, which treats them separately.
Mycelium.tree_schedule — Method
tree_schedule(g; root = nothing) -> TreeScheduleRoot the tree (at root, or at the first leaf found) and produce the inward/outward sweeps.
Errors unless istree. The inward sweep is in reverse breadth-first order (children strictly before parents) and the outward sweep in breadth-first order, which is what makes each message computable exactly once from already-final inputs.
Mycelium.AndersonSchedule — Type
AndersonSchedule(inner; m = 3, ridge = 1e-14)Anderson acceleration (Walker & Ni, 2011; type II, undamped) of the schedule inner. One sweep runs one sweep of inner, a map $G$ on the stored messages, and then replaces its result by
\[x^+ = G(x_k) - \Delta G\,\gamma, \qquad \gamma = \arg\min_\gamma \lVert f_k - \Delta F\,\gamma\rVert_2,\]
where $f = G(x) - x$ and $\Delta F$, $\Delta G$ hold the differences of the last m + 1 residuals and images. A fixed point of $G$ has $f = 0$, so the fixed points are inner's. The cost is one sweep of inner per sweep, plus a least-squares problem of m columns.
Only Gaussian messages in Float64 arrays are mixed, in natural parameters ($\eta$ and the lower triangle of $\Lambda$), with the means and the precisions each scaled by their largest entry when the memory starts. Where any stored message is of another kind the sweep is inner's, unchanged. A mixed precision that loses positive semidefiniteness, or a non-finite step, is replaced by inner's result and the memory cleared (a restart). The memory is kept per MessageStore and cleared when the set of stored messages changes, so one schedule can serve several stores.
There is no convergence guarantee. Measured on the resistive divider (bench/bp_anderson.jl; vault/Control/Composing Optimisers.md §4.3), around spanning_tree_schedule with m = 2 or 3 it needs 0.09 to 0.19 of flooding's message evaluations, and about 700 times fewer than the plain spanning-tree order when the loop gain is near 1; around a flooding schedule it was slower in three of four settings, or failed. On Gaussian grids (bench/bp_grid.jl, §4.4) it needs 5 to 19 times fewer sweeps than the plain spanning-tree order in the slow regime, and there it also speeds up flooding. Parameter gradients through an AndersonSchedule (schedule replay) are not supported.
Mycelium.anderson_restarts — Method
anderson_restarts(sched::AndersonSchedule, store) -> IntHow many times the acceleration fell back to the plain sweep on store (a step that was not finite or would have made a precision indefinite).
Running inference
Mycelium.ConvergenceReport — Type
ConvergenceReport(converged, sweeps, residual, reason, exact = false)What propagate! reports. converged == false is not an error — on a loopy graph it is the expected outcome, and callers must decide whether to trust the marginals.
exact says that the marginals are the model's exact marginals, not only a fixed point. Only a tree schedule's single sweep claims it, and only when nothing on the way approximated (P13, exact_messages); reason then says "one sweep is exact", and otherwise names what approximated. An iterated schedule never claims it.
Mycelium.available_channels — Method
available_channels(store, g, fid; skip = 0) -> Tuple{Vararg{Symbol}}Channels of factor fid that currently have an informative incoming (variable → factor) message, optionally excluding one edge. Channels holding nothing or an uninformative belief (TrivialBelief() or uninformative(n)) are excluded so they resolve to Latent().
Mycelium.ep_divide — Method
ep_divide(p, cavity) -> belief$p / \pi$: the site that, combined with the cavity, gives p. Gaussians subtract canonical parameters; the result may be improper, even indefinite, and is declared improper unless its precision is positive definite. Dividing by an uninformative belief returns p.
Mycelium.ep_message — Method
ep_message(message, cavity) -> belief or nothingThe ExpectationPropagationRule message from the belief-propagation message to a target whose cavity (excluded marginal) is cavity. A message that is not a MixtureBelief is in its family and is returned as it is. A mixture is multiplied by the cavity (the tilted belief), projected (ep_project) and divided by the cavity (ep_divide); an uninformative cavity leaves the mixture itself as the tilted belief, and a point cavity (a pinned variable) makes the message irrelevant, so it is returned unchanged. Returns nothing when the update cannot be made: a Gaussian cavity that is not proper, or a tilted belief that ep_project cannot normalise.
Mycelium.ep_project — Method
ep_project(tilted) -> belief or nothingThe projection step of expectation propagation: the member of the target's family closest to tilted in $\mathrm{KL}(\text{tilted} \,\|\, q)$, i.e. the one with the same moments. Mycelium implements it for a mixture of Gaussians (the total mean and covariance), returning nothing when a component is not proper, and for a Gaussian (itself). A belief type opts in by adding a method.
Mycelium.exact_messages — Method
exact_messages(f) -> BoolWhether f's belief-propagation messages are the exact sum-product messages for every input it takes without collapsing it: point, categorical and Gaussian (also flat) messages. false by default, so a factor type is called exact only where it declares so (and has a test against a closed form); a mixture input is checked separately, at run time. propagate! reads it to decide whether a tree sweep is exact (P13, Bethe Free Energy.md, "What exact requires").
Mycelium.factor_message — Method
factor_message(factor, target::Symbol, polarity, inputs::NamedTuple, prior, ps, st)
-> (belief, st)Compute the outgoing belief on channel target.
The generic implementation is assemble(factor, polarity, ps, st) followed by invert(lens, prior, inputs, ps, st) — i.e. the composite of LenticulumCore's two interface functions. Structural factors (DataFactor, LossFactor, …) implement this directly instead, because for them the "lens" is trivial and building one would be ceremony.
inputs is a NamedTuple of the incoming beliefs keyed by channel, and prior is the excluded marginal at the target variable — the $\pi$ of $c'_\pi$.
Mycelium.factor_messages — Method
factor_messages(factors, target, polarity, inputs, priors, ps, st) -> (beliefs, st)The factor → variable messages to channel target of several tied replicas at once: factors[i] is replica i's factor (all of one type, with shared parameters ps; their other fields, such as data, may differ), and inputs[i] and priors[i] are what factor_message receives for it. beliefs[i] must be what factor_message returns. A plate sweep (PlateSchedule) calls this for a group of tied replicas. The default calls factor_message for each in turn, threading st; a factor type overrides it (dispatching on the element type of factors) to share the work that depends only on the parameters.
Mycelium.infer! — Method
infer!(g, sched, ps, st; kwargs...) -> (marginals::NamedTuple, report, st, store)Convenience: fresh store, propagate, read out every variable's marginal. The store is returned for the free energy and the gradients.
Mycelium.mean_field_energy — Method
mean_field_energy(factor, marginals::NamedTuple, ps, st) -> (𝐅, st)A MeanField node's term in the graph free energy: the average energy $\mathbb E_{\prod_i q_i}[-\log f]$ under the product of its variables' current marginals marginals (keyed by channel), graded like local_free_energy, with no entropy of its own (Riegler et al. 2013, eq. 17; the variables' entropies are counted at the variables, counting_number). Its parameter derivative at fixed marginals is the node's part of the graph gradient.
No generic implementation; a factor with a mean_field_message should add one, and Lenticulum does for LinearConstraintFactor and SwitchingConstraintFactor.
Mycelium.mean_field_message — Method
mean_field_message(factor, target::Symbol, polarity, beliefs::NamedTuple, ps, st)
-> (belief, st)The outgoing message of a MeanField node on channel target: $\exp \mathbb E_{\prod_{i \ne t} q_i}[\log f(x)]$ as a function of $x_t$, where beliefs holds the current marginals $q_i$ of the other channels' variables (not their cavity messages).
There is no generic implementation, because the expectation needs the factor's form; factors opt in by adding a method. Lenticulum implements it for LinearConstraintFactor and SwitchingConstraintFactor.
Mycelium.mixture_message — Method
mixture_message(factor, target::Symbol, polarity, inputs::NamedTuple, prior, ps, st) -> (belief, st)The factor → variable message when some inputs are MixtureBeliefs, computed exactly: each mixture input is expanded into its components, the message of every combination of components is weighted by the components' weights and by the evidence the combination gives, and the result is one mixture. factor_message collapses such inputs to their moments instead. MixtureReduction nodes call it. No generic implementation, since the evidence needs the factor's form; Lenticulum implements it for LinearConstraintFactor and SwitchingConstraintFactor.
Mycelium.propagate! — Method
propagate!(store, g, sched, ps, st; maxsweeps = 100, tol = 1e-8, damping = 0.0,
criterion = _default_criterion(sched))
-> (ConvergenceReport, st)Run the schedule to convergence, or to maxsweeps.
For a TreeSchedule without damping, on a graph of BeliefPropagation and MixtureReduction nodes, one sweep is enough: it is the fixed point, and the loop stops after one. The report calls it exact (report.exact) only when nothing approximated: every node that sends a message declares exact_messages, none is a MixtureReduction node, and no factor received a mixture on one edge and sent on another (it collapses the mixture to its moments); otherwise reason names each of these. ExpectationPropagationRule and MeanField messages also depend on the target's side, so such graphs are iterated. With damping a tree schedule is iterated and checked like any other, since a damped sweep keeps part of each previously stored message. For loopy graphs there is no guarantee: see Loopy Message Passing.md.
damping ∈ [0,1) mixes each new message with the previous one (0 = none, higher = more inertia), the standard remedy for oscillation. Damping only applies where can_damp is true; elsewhere it is a no-op. Callers can inspect can_damp; the convergence report does not automatically record unsupported damping.
criterion is what must change by at most tol between sweeps: :messages (the largest belief_distance of a sweep's messages to the ones they replace) or :marginals (the largest change of a variable's marginal, compared by moments: means and covariances, and the weights of a mixture or a categorical). Messages of mixtures with very narrow components have a rounding floor in natural parameters that their moments do not, so hybrid graphs default to :marginals (hybrid_schedule).
Mycelium.reduce_message — Method
reduce_message(belief, maxcomponents) -> beliefA message reduced to at most maxcomponents mixture components, for MixtureReduction nodes. A belief that is not a mixture, or has few enough components, is returned unchanged; a reduction to one component returns the component. Mixtures of Gaussians are reduced by Runnalls' merge (reduce_mixture, gaussian.jl); anything else is refused.
Mycelium.step! — Method
step!(store, g, task, ps, st; damping = 0.0, commit = true) -> (belief, residual, st)Execute one MessageTask.
ps and st are the graph-wide parameter and state trees, keyed by parameter_key (the factor name unless tied) — the same nested NamedTuple shape LuxCore.setup produces.
Returns the new belief, the belief_distance to the message it replaces (the residual, used for convergence and for ResidualSchedule), and the updated state. With commit = false the message is computed but not stored, which is what FloodingSchedule needs for double buffering. A skipped update (an expectation-propagation node without a proper cavity) returns the edge's current message (TrivialBelief() if it has none) and stores nothing, with either commit.
Mycelium.sweep! — Function
sweep!(store, g, sched, ps, st; damping = 0.0) -> (maxresidual, st)One pass of the schedule.
SequentialSchedule, TreeSchedule and ForwardBackwardSchedule execute in place, so later tasks see earlier results in the same sweep. FloodingSchedule is double buffered: every task is computed against the previous sweep's messages and all results are committed together.
Cluster nodes
Mycelium.ClusterFactor — Type
ClusterFactorA cluster node, built by cluster: the factors it replaces (names, factors, each with its channels wired to cluster variables, and the parameter key it read, keys), its variables and their dimensions, which of them are discrete, and the channels it exposes (boundary, one per variable shared with the rest of the graph, named after it). Its parameters are a NamedTuple keyed by those parameter keys, so factors tied inside the cluster still share one entry (cluster_parameters).
Mycelium.ClusterForm — Type
ClusterForm(A, C, Q, logw, switch)A factor as a cluster node reads it: the residual $r = \sum_c A_c x_c - C_{:,k}$ with noise $\mathcal N(0, Q)$ and log-weight $\log w_k$, so that $-\log f(x, k) = \tfrac12 r^\top Q^{-1} r + \tfrac12 \log\det 2\pi Q - \log w_k$. A is a NamedTuple of matrices keyed by the continuous channels, C has one column per outcome, logw one entry per outcome, and switch names the discrete channel the outcome is read from (nothing with one outcome), or a tuple of discrete channels whose joint state is the outcome (column-major: the first channel varies fastest, as LinearIndices). A discrete-only factor has m = 0 rows.
The coefficients and the noise may depend on the outcome: an entry of A may be an m × d × K array ($A_{c,k}$ = A[c][:, :, k]) and Q an m × m × K array ($Q_k$), with K the number of columns of C. The cluster then has one precision per combination of such outcomes (cluster.md, "Per-outcome coefficients and noise"). Returned by cluster_form.
Mycelium.FrozenClusterBelief — Type
FrozenClusterBeliefThe cluster's belief $b(x, a) \propto \prod_f f(x, a) \prod_v \mu_v$, held fixed: the posterior q over the discrete assignments, the means of the free continuous variables per assignment (columns of M), their covariance per precision class (Σ[class[a]]) and its conditional entropy $H(x \mid a)$ (H[class[a]]), the substituted points, and the assignments.
Mycelium.TableFactor — Type
TableFactor(dims::NamedTuple, logtable::AbstractArray)A fixed factor over several discrete variables: $f(k_1, …, k_n) = xp( exttt{logtable}[k_1, …, k_n])$, with channel c of dims[c] states (size(logtable) == values(dims)). Entries may be -Inf (impossible combinations), so a table can tie discrete variables together, e.g. make a switch's outcome agree with a cluster label. Without parameters.
Inside a cluster node it is a discrete term on the joint state of its channels (cluster_form with a tuple of switch channels). Outside one it sends exact belief-propagation messages (sums over the other channels' incoming categorical messages, or their observed states); it has no free energy of its own outside a cluster.
Mycelium.as_cluster — Method
as_cluster(factor) -> ClusterFactorOne factor as a cluster node over its own channels (variables named after them, parameters under the key :factor): its exact belief-propagation messages and Bethe free energy outside a cluster, for a factor that has only a cluster_form. Call the result with parameters (factor = ps,) and inputs keyed by the factor's channel names.
Mycelium.cluster — Method
cluster(g::FactorGraph, name::Symbol, factors) -> FactorGraph
cluster(g::FactorGraph, groups::AbstractVector{<:Pair}; params = nothing) -> FactorGraphThe graph with the factor nodes named in factors replaced by one ClusterFactor node name; the second form makes one node per name => factors pair, at once. Variables touched only by a group's factors become internal to its node; every other variable they touch becomes one of its channels, named after the variable, on a bidirectional edge. Inside the node inference is exact (cluster.md): each factor must have a cluster_form, a discrete variable is one some factor switches on (cluster_switch), and every variable needs an Int dimension (its number of states, if discrete).
A cluster node reads the parameter entry name, a NamedTuple keyed by its factors' parameter keys (cluster_parameters). With params, every node reads that one entry instead: the nodes are tied, which is how replicas of one model (one cluster per data point) share their parameters, and which requires every node to hold the same parameter keys.
Frozen parameter paths carry over: a clustered node's freeze becomes the cluster node's paths under its parameter key ((key, path...), or (key,) when frozen whole).
Refused: graphs with plates; groups that overlap; factors that are not belief-propagation nodes or share a parameter key with a node outside every group (or, without params, with a node in another group); tied groups that freeze different paths; unconnected channels; edges of the clustered factors that are not bidirectional, diagonal and attached.
Mycelium.cluster — Method
cluster(g, plate::Symbol, name::Symbol, factors; params = name) -> FactorGraphCluster the plate factors factors (template names) of every replica of plate into one node per replica, replica_name(name, i), tied (all read params). The new graph keeps the plate, with the cluster nodes in it, so plate schedules group their messages and the batched cluster methods (factor_messages, factor_beliefs) share the work that does not depend on the replica. Inside each node the variables carry their template names (:z, not Symbol("z[3]")): those are its channels, the same in every replica, and the names cluster_marginal takes. The graph must have this one plate only.
Mycelium.cluster_form — Method
cluster_form(factor, ps) -> ClusterFormThe factor as a conditionally linear-Gaussian term, for cluster nodes, and the discrete channel it switches on (structural, without parameters). Mycelium implements them for PriorFactors whose belief is a CategoricalBelief (a discrete term) or a proper GaussianBelief; Lenticulum for LinearConstraintFactor, SwitchingConstraintFactor, RegimeFactor, GaussianFactor and GaussianPrior (learned noise allowed, a noise prior not). A factor without a method cannot be put in a cluster.
Mycelium.cluster_marginal — Function
cluster_marginal(store, gc, name, v, ps, st = NamedTuple()) -> AbstractBeliefThe marginal of variable v of cluster node name (internal or a channel) under the cluster's exact belief given its current incoming messages: a mixture over the discrete assignments of the Gaussian of v given each (a GaussianBelief if there is one assignment), a categorical for a discrete variable, the point for a substituted one.
Mycelium.cluster_parameters — Method
cluster_parameters(gc, ps) -> NamedTuple
cluster_parameters(gc, name, ps) -> NamedTupleA parameter (or state) tree of the original graph as the clustered graph gc reads it: each cluster node's factors' entries are moved under the node's parameter key (its name, or the shared params of tied nodes), keyed by their parameter keys. The second form checks that name is a cluster node and converts for all of them.
Mycelium.cluster_switch — Method
cluster_switch(factor) -> Union{Symbol,Nothing,Tuple}The discrete channel (or tuple of channels) a factor switches on, read without parameters: what makes a variable discrete inside a cluster node. nothing by default.
Mycelium.factor_message — Method
Mycelium.factor_message(c::ClusterFactor, target, polarity, inputs, prior, ps, st)The exact message of the cluster to one of its channels, given the others' messages: every joint assignment of the discrete variables is enumerated, and the continuous variables other than the target are eliminated from that assignment's Gaussian. To a continuous channel the message is a mixture over the assignments (a GaussianBelief if there is one); its components have one precision per precision class; an improper component is the unnormalised exponential its weight multiplies. To a discrete channel a CategoricalBelief. Points are substituted; a Gaussian-mixture input is collapsed to its moments. Directions that nothing determines (a channel without a message, say) are integrated out in the diffuse limit (cluster.md, "Flat directions").
Mycelium.local_free_energy — Method
Mycelium.local_free_energy(c::ClusterFactor, msgs, ps, st)
Mycelium.belief_free_energy(c::ClusterFactor, b::FrozenClusterBelief, ps, st)$\mathbb E_b[-\log \prod_f f] - H(b)$ for the cluster's exact belief, graded as (fit, complexity, negentropy): fit is $\sum_f \sum_a q_a \tfrac12 \mathbb E[r_f^\top Q_{f,a}^{-1} r_f \mid a]$, complexity $\sum_f \sum_a q_a (\tfrac12 \log\det 2\pi Q_{f,a} - \log w_{f,a})$, and negentropy $-H(q) - \sum_a q_a H(x \mid a)$, closed form since given the assignment the continuous part is one Gaussian. belief_free_energy re-evaluates the factors' terms at ps with the belief fixed (the parameter gradient, LP-020).
Mycelium.overlap_groups — Method
overlap_groups(C::AbstractMatrix, maxsize) -> Vector{Vector{Int}}Groups of at most maxsize items by their pairwise overlaps C (symmetric, larger is more overlap), E7's rule (Composing Stochastic Factors): starting from singletons, merge the two groups whose largest overlap between members is largest, as long as the merged group fits and that overlap is positive. Lenticulum's switch_overlaps gives the overlaps of switching factors feeding one sum; the groups then go to cluster.
Mycelium.FrozenClusterBeliefs — Type
FrozenClusterBeliefsThe beliefs of tied cluster nodes over a plate whose joints share their structure, held fixed as one object: q (assignments × replicas), the means M (free coordinates × (assignments · replicas), replica-major), the covariance Σ[κ] and conditional entropy H[κ] of each precision class (class[a] for assignment a; one class unless a factor's coefficients or noise depend on its outcome), and the points of each substituted variable as columns. Returned by factor_beliefs for a vector of ClusterFactors; belief_free_energies evaluates all replicas in stacked products.
Mycelium.OverlayFactor — Type
OverlayFactor(:a => f₁, :b => f₂, …; normalise = nothing)Factors overlaid on the same variables, as one node: the product $\prod_i f_i$, each member with its own parameters (the overlay's parameters are a NamedTuple keyed by the members' names). The channels are the union of the members' channels; two members with a channel of one name share that variable, a switch channel included. Members must have a cluster_form.
With normalise = (:y, …) (continuous channels) the overlay is, for each joint outcome $k$ of the members' switches, the product normalised as a density of $y$ given the other channels:
\[f(y, x, k) = w_k\, \mathcal N\bigl(y;\ P_k^{-1} h_k(x),\ P_k^{-1}\bigr), \qquad P_k = \textstyle\sum_i A_{y,i}^\top Q_i^{-1} A_{y,i},\]
with $w_k$ the product of the members' weights. This is a mixture of experts normalised in $y$: it cannot satisfy observed $y$ by collapsing (LP-022), since $P_k$ must be invertible and a common scaling of the coefficients and the noise leaves it unchanged. Members that do not involve $y$ cancel in the normalisation.
Inside a cluster node the overlay is its cluster_form; outside one, its messages and free energy are those of a one-factor cluster (as_cluster). See overlay.md.
Structure edits
Mycelium.GraphBuilder — Method
GraphBuilder(g::FactorGraph) -> GraphBuilderA builder holding a copy of g's variables, factors and edges, to be edited (variable!, factor!, connect!, remove_factor!, remove_variable!, disconnect!, replace_factor!) and built again. Graphs with plates are refused: their replica records would not survive the edits.
Mycelium.disconnect! — Method
disconnect!(b::GraphBuilder, factor, channel) -> GraphBuilderRemove the edge of factor's channel; connect! can attach the channel again.
Mycelium.remove_factor! — Method
remove_factor!(b::GraphBuilder, name) -> GraphBuilderRemove a factor node and its edges. Ids are renumbered; names stay.
Mycelium.remove_variable! — Method
remove_variable!(b::GraphBuilder, name) -> GraphBuilderRemove a variable and its edges. A factor left with an unconnected channel is allowed, as at construction (its channel then resolves as latent).
Mycelium.replace_factor! — Method
replace_factor!(b::GraphBuilder, name, factor; freeze, rule, params) -> GraphBuilderPut factor in node name, keeping the node's edges whose channels factor still has and dropping the others; freeze, rule and params default to the node's. Its new channels are connected with connect! as usual. A sum node that gains an input is replaced this way.
Mycelium.transfer — Method
transfer(s::MessageStore, g_old, g_new) -> MessageStoreA store for g_new holding s's messages on every edge both graphs have: the same factor name, channel, variable name and variable space, in either direction, and the pins of the variables both have (with the same space). The other edges start empty. A warm start: a message kept next to an edit (into a node whose neighbourhood changed) is a starting point, and the schedule replaces it.