Mycelium API: plates and message blocks

Plates (one template replicated over observations, with tied parameters) and the message blocks that hold a plate's messages for all replicas at once. The rest of the API is on the Mycelium API page.

Plates

Mycelium.Plate — Type
Plate

The record of one plate in a FactorGraph: its name, its size n, and the node and edge ids of each replica, as matrices with one column per replica and one row per template position (variables, factors, edges). Row k of edges is the same template edge in every replica. Read it with plates.

source
Mycelium.PlateSchedule — Type
PlateSchedule(groups)

A static schedule of groups of tasks. A group is one template task of a plate lifted to every replica (or a single task outside it). A sweep gives the same messages as the SequentialSchedule of tasks(sched). Where the members of a group are independent, a group of factor → variable messages is computed in one call of factor_messages, with the polarity resolved once: a belief-propagation node, tied replicas (one parameter key), the same available channels, and a different target variable for each member (a shared target would see the earlier members' messages in its prior). Otherwise the members run one by one. Build one with plate_schedule, which also finds each lifted group's structure once (plans); the polarity of such a group is resolved and checked on its first member. A schedule built from groups alone checks every group at run time.

source
Mycelium.as_plate — Method
as_plate(g, name::Symbol, n::Integer) -> FactorGraph

g with the nodes named replica_name(base, i), i = 1:n, recorded as a plate name: the graph plate! would build from a template declaring each base, with the same nodes, factors, edges and parameter keys. Every other node is shared. A factor whose replicas read one parameter key is tied; one whose replica i reads replica_name(key, i) is untied. The replicas must be alike as plate! requires (checked by it), and an edge may not join two replicas.

This is how a graph changed by structure edits (GraphBuilder(g), which refuses plates) gets its plate back, so that plate schedules and batched messages apply to it. g must have no plates.

source
Mycelium.connect! — Method
connect!(p::PlateBuilder, factor, channel, variable; kwargs...) -> Int

Connect inside a plate. A name declared in this replica (by variable!(p, ...) or factor!(p, ...)) refers to the replica's own node; any other name refers to a node of the enclosing graph, shared by all replicas. Other keywords are those of connect!.

source
Mycelium.ep_block — Method
ep_block(message::BeliefBlock, cavity::BeliefBlock) -> BeliefBlock or nothing

ep_message of every column, for a plate of ExpectationPropagationRule() nodes: a block of mixtures of Gaussians with one precision times a Gaussian cavity block is projected and divided in one pass; anything else goes column by column. nothing when some column's update would be skipped, so the group takes the per-edge path and skips exactly those.

source
Mycelium.factor! — Method
factor!(p::PlateBuilder, name, factor; params = name, tie = true, kwargs...) -> Int

Add replica p.index's copy of the plate factor name. With tie = true (the default) every replica reads the parameter entry params, so the replicas share one parameter vector; with tie = false each reads its own, replica_name(params, i). Other keywords are those of factor!.

source
Mycelium.plate! — Method
plate!(template, b::GraphBuilder, name::Symbol, n::Integer) -> Plate

Replicate a template n times: template(p, i) is called for i = 1:n with a PlateBuilder p, and adds replica i's nodes through variable!(p, ...), factor!(p, ...) and connect!(p, ...). Use it as a do block:

plate!(b, :obs, N) do p, i
    variable!(p, :z, k); variable!(p, :x, d)
    factor!(p, :prior, GaussianPrior(:z, zeros(k), I(k)))
    factor!(p, :lik, LinearConstraintFactor((x = d, z = k), d))   # parameters :lik, shared
    factor!(p, :data, DataFactor(:x, X[:, i]))
    connect!(p, :prior, :z, :z); connect!(p, :lik, :z, :z); connect!(p, :lik, :x, :x)
    connect!(p, :data, :x, :x; direction = Emitting())
end

Replica i's nodes are named replica_name(name, i) (:x becomes Symbol("x[3]")). Factors are tied across replicas by default (factor!(p, ...; tie)), so their gradient is the sum over replicas. A name not declared in the replica is a node of the enclosing graph, shared by all replicas: a shared latent variable couples the replicas, a shared parameter does not. Every replica must declare the same nodes and edges in the same order, with the same directions, couplings and shared nodes; otherwise this throws. The data may differ. Plates do not nest.

source
Mycelium.plate_schedule — Method
plate_schedule(g, replica_tasks; plate = nothing) -> PlateSchedule
plate_schedule(g, sched::AbstractSchedule; plate = nothing) -> PlateSchedule
plate_schedule(g; plate = nothing) -> PlateSchedule

Lift a schedule written for replica 1 to every replica. Each task on an edge of replica 1 becomes the group of the same template task in replicas 1:n; a task on an edge outside the plate stays a group of one; a task on another replica's edge throws.

Without a schedule, each connected component gets its tree schedule, or its hybrid_schedule when it has mean-field nodes, and replica 1's component is lifted. This needs the replicas to be separate components (parameters shared, no shared variable) and every component (or, for a hybrid one, every belief-propagation cluster) to be a tree; otherwise it throws. A schedule lifted from a hybrid one converges on marginals in propagate!. A graph with shared variables can use tree_schedule(g) directly, or a hand-written replica schedule. plate names the plate when the graph has more than one.

source
Mycelium.replica_name — Method
replica_name(name::Symbol, i::Integer) -> Symbol

The graph name of replica i of a plate node declared as name: Symbol("name[i]").

source

Message blocks

Mycelium.BeliefBlock — Type
BeliefBlock

The messages of n replicas on one template edge, as one value. Column i is replica i's belief, read with replica. Implemented:

blockholdscolumn i
TrivialBlock(n)nothingTrivialBelief()
PointBlock(X)points as the columns of a d × n matrixDiracBelief(X[:, i])
GaussianBlock(η, Λ, improper)information vectors η (d × n), precisions ΛGaussianBelief(η[:, i], Λᵢ, improper[i])
CategoricalBlock(logp, labels)normalised log-probabilities as the columns of a K × n matrixCategoricalBelief(logp[:, i])
MixtureBlock(η, Λ, logw, improper)K Gaussian components per replica, η of size d × K × n, one precision Λ for all, log-weights K × nMixtureBelief of GaussianBelief(η[:, k, i], Λ, improper)
ComponentMixtureBlock(η, Λs, logw, improper)as a MixtureBlock, but component k has its own precision Λs[k] and flag improper[k], the same in every replicaMixtureBelief of GaussianBelief(η[:, k, i], Λs[k], improper[k])
VectorBlock(beliefs)any beliefs, one per replicabeliefs[i]

Λ of a GaussianBlock is one matrix shared by every replica, or a vector of n matrices. Build a block from per-replica beliefs with belief_block.

source
Mycelium.CategoricalBlock — Type
CategoricalBlock(logp, labels = nothing)

n categorical beliefs over one support of K states: the normalised log-probabilities as the columns of the K × n matrix logp, the labels shared. Replica i is CategoricalBelief(logp[:, i]). A plate of switching factors sends its outcome messages as one.

source
Mycelium.ComponentMixtureBlock — Type
ComponentMixtureBlock(η, Λs, logw, improper)

n mixtures of K Gaussians whose component k has the precision Λs[k] and the flag improper[k] in every replica: component k of replica i is GaussianBelief(η[:, k, i], Λs[k], improper[k]), its normalised log-weight logw[k, i]. What a plate of tied cluster nodes sends to a continuous channel when the outcomes give it different precisions (cluster_batch.jl, I21). belief_block does not build it; operations without a method of their own take it column by column.

source
Mycelium.EdgeMessages — Type
EdgeMessages

The messages of one direction, one per edge: what store.to_variable and store.to_factor are. Indexing returns the edge's Message or nothing, as a Vector{Any} would. The edges of a plate's template position form a block row; a row can hold one Message whose belief is a BeliefBlock, and an edge of that row then reads as a view, its column. Assigning to one edge of a row held as a block first writes every column back as a per-edge message.

source
Mycelium.MixtureBlock — Type
MixtureBlock(η, Λ, logw, improper)

n mixtures of K Gaussians whose components all share one precision Λ (and one improper flag): component k of replica i is GaussianBelief(η[:, k, i], Λ, improper), its normalised log-weight logw[k, i]. What a plate of tied switching factors sends to a continuous channel when their inputs share one precision.

source
Mycelium.belief_block — Method
belief_block(beliefs::AbstractVector) -> BeliefBlock

The block of per-replica beliefs: a TrivialBlock when all are trivial, a PointBlock when all are points that are real vectors of one length, a GaussianBlock when all are Gaussians of one dimension (with a shared precision when every belief holds the same precision object), and a VectorBlock otherwise. replica of the result returns beliefs equal to the inputs.

source
Mycelium.replica — Function
replica(block, i) -> AbstractBelief
replicas(block) -> Vector{Any}

Replica i's belief in a BeliefBlock (a view built on demand: a new belief holding column i), and all of them.

source