Defining rules

@define_message_update_rule(
    node = ..., target = ..., args = (...), body = (...) -> ...,
    algorithm = ..., logscale = ..., reads_logscale = ..., ctx = (...),
    inplace = ..., preallocate = ..., scratch = ..., pure = ..., args_check = ...,
)

Define the rule for the message a node sends towards one of its interfaces. The macro takes keyword arguments only; node, target, args and body are required, the rest optional. An unknown or repeated keyword is an error at definition time, naming the valid ones.

The rule becomes a method of find_message_rule: it is found for its node, target, algorithm and the types of the inputs args names, from any module, and its module's registry lists it for introspection (list_rules, check_rules).

Required keywords

• node: the node, as declared with @define_factor_node: a type, NormalMeanVariance, or a function, +.

• target: the interface the message goes to:

  • :out, a single interface;
  • (:m, k), any member of the group m. The name k is bound to the member's index, an Int, in body and in the preallocate, scratch, logscale and args_check functions, without being listed among their parameters; args can select by it.

• args: the inputs the rule consumes, a tuple of entries container[key]::T, the container m for a message or q for a marginal. A type left out is Any; the types are what the rule dispatches on. For a single interface:

  • m[:μ]::T, q[:μ]::T: the message or the marginal on μ;
  • q[:y, :x]::T, or q[(:y, :x)]::T: the joint marginal of a structural cluster, its members in interface order. A group in a cluster means all its members jointly: q[(:in,)] is the joint over the group in. (:in, 1), with a literal index, is one member: q[:out, (:in, 1)] is the joint of out and in's first member.

  For a group, whose value is a tuple in member order:

  • m[:in...]::T: every member, each of type T;
  • m[:in][k]::T: the target's own member, k being the name an indexed target binds;
  • m[:in][!k]::T: every member but the target's own.

  With a selection, the tuple keeps every position and holds nothing where the selection leaves a member out, so args.m[:in][k] is member k whatever was selected.

  default among the entries stands for whatever inputs the default scheme delivers under the graph's factorisation. The rule then takes them all, requires the typed entries beside default, and walks them with rule_inputs: one rule for every factorisation.

• body: the rule itself, an ordinary lambda returning the message, whose parameters are some of the slots (output, scratch, algo, ctx, args, ann).

  Name only the slots the rule uses, in the order given; a slot that is misspelled, repeated or out of order is an error.

  • output: the buffer to write into, for an in-place rule only, and then first;
  • scratch: the rule's working memory, when it declares scratch;
  • algo: the algorithm value the rule runs under, and so its parameters;
  • ctx: the RuleContext, whose services the rule reads as ctx.name;
  • args: the inputs, read as args.m[:μ], args.q[:y, :x], args.m[:in][k];
  • ann: the annotations: those that arrived with the inputs, ann.m[:μ], and the rule's own, written with annotate!(ann, key, value).

Optional keywords

• algorithm: the algorithm the rule runs under, a type, or a value whose type is used. Default: the node's own, default_algorithm(node), usually DefaultAlgorithm; the node must then be declared before the rule is loaded. Almost every rule leaves it out; naming one is for a rule switcher, a DefaultAlgorithmExtension, or a node's own algorithm. With a parametric algorithm type T, algorithm = T matches every T{…}, while leaving it out binds the rule to the type of the node's default instance only.

• logscale: the message's log scale, the scalar with message = exp(logscale) · result for the normalised result the rule returns: a rule's result may stand for an unnormalised function, as a belief-propagation message does, and this is the log of its normaliser. One of:

  • a number: logscale = 0, or logscale = loghalf (StatsFuns'); an Irrational keeps the message's float type, while -logtwo would not, being a Float64;
  • a function of the inputs, over the slots (algo, ctx, args), in that order: logscale = (args) -> -log(abs(mean(args.m[:A])));
  • from_body: the body returns with_logscale(result, logscale), for a log scale computed alongside the result;
  • improper: the message has no normalising constant, so no log scale exists, as for an exact message whose integral is infinite.

  Default: none declared. The message's log scale is then an UndefinedLogScale naming the rule, which propagates through products; only require_logscale turns it into an error. Declaring improper gives an undefined log scale too, whose reason says that none exists, where an omitted declaration says that it is not known.

• reads_logscale: true if the rule reads the log scales of its inbound messages, as args.logscale.m[:x]. Its caller must then provide them: an engine does when it tracks log scales, and a call by hand takes them as logscale = (...); without them the call is an error (check_reads_logscale). Default: false.

• ctx: the context services the rule reads, a tuple of symbols, ctx = (:rng,) or ctx = (:node, :matrix_correction). Any name is allowed, so a rule may need a service of its own. An engine checks that its context supplies each one when it resolves the rule (check_services); a call by hand does not. Default: (), none.

• inplace: true for a rule that writes its result into a buffer it is given rather than allocating one. It needs preallocate, and its body takes output first. Default: false.

• preallocate: for an in-place rule, a function building the buffer from the inputs, over the slots (algo, ctx, args): preallocate = (args) -> similar(mean(args.m[:μ])). Allowed only with inplace = true.

• scratch: working memory, a function building it from the inputs over the slots (algo, ctx, args), given to the body as its scratch slot: scratch = (args) -> (work = similar(mean(args.m[:μ])),). An engine keeps one per outbound stream and reuses it, so it is write-before-read: it carries nothing between calls, and the engine may keep, drop or rebuild it whenever it likes. It never leaves the rule, is never shared with another rule, keeps the rule pure, and combines with inplace. The body takes scratch exactly when this is given. An engine keeping it between calls infers its type from the inputs' types (rule_scratch_type), so a function whose result type infers, built from the inputs with similar or zeros(eltype(...), ...), runs the rule on a concretely typed scratch; one that does not infer runs it on an untyped one, a dynamic call per call. Default: none.

• pure: false for a rule with side effects, true for a pure rule under an impure algorithm. Default: the algorithm's declaration, ispure, true for almost every algorithm. A pure rule mutates neither its inputs nor state shared beyond one call, and draws randomness only from ctx.rng.

• args_check: a check of the inputs, run as the body starts, for what their types cannot say: a value in range, a vector's length, a variate form an Any input must have. A function over the slots (algo, ctx, args), in that order, returning

  • true when the inputs pass;
  • false when they do not: the rule raises a RuleInputError quoting the check's source, args_check = (args) -> length(mean(args.q[:out])) == 2;
  • a string when they do not, and the error says that instead: for a check that combines several conditions, whose source would read poorly, or that names the offending value, args_check = (args) -> 0 <= mean(args.m[:out]) <= 1 || lazy"a probability in [0, 1]; got $(mean(args.m[:out]))".

  A string is always a failure. A failed check is an error, not a reason to select another rule: resolution has already chosen this one.

  The check costs nothing where it depends on the inputs' types only, since it folds away when the rule is compiled for them, and one comparison where it reads a value; its error path is outlined, so it allocates nothing until it fails. It runs after a preallocate or scratch helper, which see the same inputs. Performance trap: build the message only where the check fails. After || it is: cond || "...$x" builds nothing on a passing call. A message bound before the condition, or formatted by a helper before it decides, is built and allocated on every call. A lazy"..." string is the safe habit, since it defers the formatting until the error is shown. Default: none.

Examples

@define_message_update_rule(
    node     = NormalMeanVariance,
    target   = :out,
    args     = (m[:μ]::PointMass, m[:v]::PointMass),
    logscale = 0,
    body     = (args) -> NormalMeanVariance(mean(args.m[:μ]), mean(args.m[:v])),
)

# Towards any member of the group `m`, reading the aligned member of the group `p`;
# `k` is bound in the body without being listed:
@define_message_update_rule(
    node   = NormalMixture,
    target = (:m, k),
    args   = (q[:out]::Any, q[:switch]::Categorical, q[:p][k]::Any),
    body   = (args) -> … probvec(args.q[:switch])[k] …,
)

@define_marginal_update_rule(
    node = ..., target = (:y, :x), args = (...), body = (...) -> ...,
    algorithm = ..., ctx = (...), inplace = ..., preallocate = ..., scratch = ..., pure = ...,
    args_check = ...,
)

Define the rule for the joint marginal of a structural cluster: the marginal of, say, (:y, :x) a node computes from the messages on the cluster's members and the marginals of its other interfaces. The macro takes keyword arguments only; node, target, args and body are required, the rest optional. An unknown or repeated keyword is an error at definition time, naming the valid ones.

The rule becomes a method of find_marginal_rule, found for its node, cluster, algorithm and input types, from any module. A marginal carries no log scale, so logscale and reads_logscale are not accepted.

Required keywords

• node: the node, as declared with @define_factor_node: a type, NormalMeanVariance, or a function, +.

• target: the cluster, its members in interface order:

  • (:y, :x), a cluster of interfaces;
  • (:out, (:T, 1)), with a member of a group written with a literal index;
  • a bare name, target = members: any cluster of the node, the name bound to the cluster's key in body and in the preallocate and scratch functions, without being listed among their parameters. Used with default in args, for one rule over every factorisation.

• args: the inputs the rule consumes, a tuple of entries container[key]::T, the container m for a message or q for a marginal. A type left out is Any; the types are what the rule dispatches on. For a single interface:

  • m[:μ]::T, q[:μ]::T: the message or the marginal on μ;
  • q[:y, :x]::T, or q[(:y, :x)]::T: the joint marginal of a structural cluster, its members in interface order. A group in a cluster means all its members jointly: q[(:in,)] is the joint over the group in. (:in, 1), with a literal index, is one member: q[:out, (:in, 1)] is the joint of out and in's first member.

  For a group, whose value is a tuple in member order:

  • m[:in...]::T: every member, each of type T;
  • m[:in][k]::T: the target's own member, k being the name an indexed target binds;
  • m[:in][!k]::T: every member but the target's own.

  With a selection, the tuple keeps every position and holds nothing where the selection leaves a member out, so args.m[:in][k] is member k whatever was selected.

  default among the entries stands for whatever inputs the default scheme delivers under the graph's factorisation. The rule then takes them all, requires the typed entries beside default, and walks them with rule_inputs: one rule for every factorisation.

  A marginal rule typically reads the messages on the cluster's members, m[:y] and m[:x], and the marginals of the node's other interfaces.

• body: the rule itself, an ordinary lambda returning the joint marginal, whose parameters are some of the slots (output, scratch, algo, ctx, args, ann).

  Name only the slots the rule uses, in the order given; a slot that is misspelled, repeated or out of order is an error.

  • output: the buffer to write into, for an in-place rule only, and then first;
  • scratch: the rule's working memory, when it declares scratch;
  • algo: the algorithm value the rule runs under, and so its parameters;
  • ctx: the RuleContext, whose services the rule reads as ctx.name;
  • args: the inputs, read as args.m[:μ], args.q[:y, :x], args.m[:in][k];
  • ann: the annotations: those that arrived with the inputs, ann.m[:μ], and the rule's own, written with annotate!(ann, key, value).

Optional keywords

• algorithm: the algorithm the rule runs under, a type, or a value whose type is used. Default: the node's own, default_algorithm(node), usually DefaultAlgorithm; the node must then be declared before the rule is loaded. Almost every rule leaves it out; naming one is for a rule switcher, a DefaultAlgorithmExtension, or a node's own algorithm. With a parametric algorithm type T, algorithm = T matches every T{…}, while leaving it out binds the rule to the type of the node's default instance only.

• ctx: the context services the rule reads, a tuple of symbols, ctx = (:rng,) or ctx = (:node, :matrix_correction). Any name is allowed, so a rule may need a service of its own. An engine checks that its context supplies each one when it resolves the rule (check_services); a call by hand does not. Default: (), none.

• inplace: true for a rule that writes its result into a buffer it is given rather than allocating one. It needs preallocate, and its body takes output first. Default: false.

• preallocate: for an in-place rule, a function building the buffer from the inputs, over the slots (algo, ctx, args): preallocate = (args) -> similar(mean(args.m[:μ])). Allowed only with inplace = true.

• scratch: working memory, a function building it from the inputs over the slots (algo, ctx, args), given to the body as its scratch slot: scratch = (args) -> (work = similar(mean(args.m[:μ])),). An engine keeps one per outbound stream and reuses it, so it is write-before-read: it carries nothing between calls, and the engine may keep, drop or rebuild it whenever it likes. It never leaves the rule, is never shared with another rule, keeps the rule pure, and combines with inplace. The body takes scratch exactly when this is given. An engine keeping it between calls infers its type from the inputs' types (rule_scratch_type), so a function whose result type infers, built from the inputs with similar or zeros(eltype(...), ...), runs the rule on a concretely typed scratch; one that does not infer runs it on an untyped one, a dynamic call per call. Default: none.

• pure: false for a rule with side effects, true for a pure rule under an impure algorithm. Default: the algorithm's declaration, ispure, true for almost every algorithm. A pure rule mutates neither its inputs nor state shared beyond one call, and draws randomness only from ctx.rng.

• args_check: a check of the inputs, run as the body starts, for what their types cannot say: a value in range, a vector's length, a variate form an Any input must have. A function over the slots (algo, ctx, args), in that order, returning

  • true when the inputs pass;
  • false when they do not: the rule raises a RuleInputError quoting the check's source, args_check = (args) -> length(mean(args.q[:out])) == 2;
  • a string when they do not, and the error says that instead: for a check that combines several conditions, whose source would read poorly, or that names the offending value, args_check = (args) -> 0 <= mean(args.m[:out]) <= 1 || lazy"a probability in [0, 1]; got $(mean(args.m[:out]))".

  A string is always a failure. A failed check is an error, not a reason to select another rule: resolution has already chosen this one.

  The check costs nothing where it depends on the inputs' types only, since it folds away when the rule is compiled for them, and one comparison where it reads a value; its error path is outlined, so it allocates nothing until it fails. It runs after a preallocate or scratch helper, which see the same inputs. Performance trap: build the message only where the check fails. After || it is: cond || "...$x" builds nothing on a passing call. A message bound before the condition, or formatted by a helper before it decides, is built and allocated on every call. A lazy"..." string is the safe habit, since it defers the formatting until the error is shown. Default: none.

Example

@define_marginal_update_rule(
    node   = NormalMeanVariance,
    target = (:out, :μ),
    args   = (m[:out]::NormalMeanVariance, m[:μ]::NormalMeanVariance, q[:v]::PointMass),
    body   = (args) -> …,
)

@define_average_energy(node = ..., args = (...), body = (...) -> ..., algorithm = ..., ctx = (...), pure = ..., args_check = ...)

Define a node's average energy, E_q[-log f] under the marginals of its clusters: the node's term of the Bethe free energy before the clusters' entropies are subtracted. The macro takes keyword arguments only; node, args and body are required, the rest optional. An unknown or repeated keyword is an error at definition time, naming the valid ones.

The energy becomes a method of find_average_energy, found for its node, algorithm and input types, from any module. It has no target, returns a number and has no log scale, so target, inplace, preallocate, scratch, logscale and reads_logscale are not accepted.

Required keywords

• node: the node, as declared with @define_factor_node: a type, NormalMeanVariance, or a function, +.

• args: the marginals the energy reads, one per cluster of the node's factorisation, a tuple of entries q[key]::T. A type left out is Any; the types are what the energy dispatches on.

  • q[:μ]::T: the marginal of a single interface, a cluster of its own;
  • q[:y, :x]::T, or q[(:y, :x)]::T: the joint marginal of a structural cluster, its members in interface order; q[(:in,)] is the joint over the group in, and (:in, 1) one member;
  • q[:in...]::T: every member of a group, each a cluster of its own, as a tuple in member order.

  default among the entries stands for whatever clusters the graph's factorisation delivers; the energy then takes them all, requires the typed entries beside default, and walks them with rule_inputs: one energy for every factorisation.

• body: the energy, an ordinary lambda returning a real number, whose parameters are some of the slots (algo, ctx, args, ann), named in that order:

  • algo: the algorithm value, and so its parameters;
  • ctx: the RuleContext, whose services the energy reads as ctx.name;
  • args: the marginals, read as args.q[:μ], args.q[:y, :x];
  • ann: the annotations that arrived with the marginals, ann.q[:μ].

Optional keywords

• algorithm: the algorithm the rule runs under, a type, or a value whose type is used. Default: the node's own, default_algorithm(node), usually DefaultAlgorithm; the node must then be declared before the rule is loaded. Almost every rule leaves it out; naming one is for a rule switcher, a DefaultAlgorithmExtension, or a node's own algorithm. With a parametric algorithm type T, algorithm = T matches every T{…}, while leaving it out binds the rule to the type of the node's default instance only.

• ctx: the context services the rule reads, a tuple of symbols, ctx = (:rng,) or ctx = (:node, :matrix_correction). Any name is allowed, so a rule may need a service of its own. An engine checks that its context supplies each one when it resolves the rule (check_services); a call by hand does not. Default: (), none.

• pure: false for a rule with side effects, true for a pure rule under an impure algorithm. Default: the algorithm's declaration, ispure, true for almost every algorithm. A pure rule mutates neither its inputs nor state shared beyond one call, and draws randomness only from ctx.rng.

• args_check: a check of the inputs, run as the body starts, for what their types cannot say: a value in range, a vector's length, a variate form an Any input must have. A function over the slots (algo, ctx, args), in that order, returning

  • true when the inputs pass;
  • false when they do not: the rule raises a RuleInputError quoting the check's source, args_check = (args) -> length(mean(args.q[:out])) == 2;
  • a string when they do not, and the error says that instead: for a check that combines several conditions, whose source would read poorly, or that names the offending value, args_check = (args) -> 0 <= mean(args.m[:out]) <= 1 || lazy"a probability in [0, 1]; got $(mean(args.m[:out]))".

  A string is always a failure. A failed check is an error, not a reason to select another rule: resolution has already chosen this one.

  The check costs nothing where it depends on the inputs' types only, since it folds away when the rule is compiled for them, and one comparison where it reads a value; its error path is outlined, so it allocates nothing until it fails. It runs after a preallocate or scratch helper, which see the same inputs. Performance trap: build the message only where the check fails. After || it is: cond || "...$x" builds nothing on a passing call. A message bound before the condition, or formatted by a helper before it decides, is built and allocated on every call. A lazy"..." string is the safe habit, since it defers the formatting until the error is shown. Default: none.

Example

@define_average_energy(
    node = NormalMeanVariance,
    args = (q[:out]::Any, q[:μ]::Any, q[:v]::Any),
    body = (args) -> begin
        m_out, v_out = mean_var(args.q[:out])
        m_μ, v_μ = mean_var(args.q[:μ])
        (log(2π) + mean(log, args.q[:v]) + mean(inv, args.q[:v]) * (v_out + v_μ + abs2(m_out - m_μ))) / 2
    end,
)

Target(edge::Symbol)
Target{E}()

The target of a message rule towards the single interface E, written target = :out in a rule's declaration. The edge is a type parameter, so a rule dispatches on it. An engine and the message_passing_* calls pass one to find_message_rule; a rule's body never sees it.

julia> using MessagePassingRulesBase: Target, target_edge

julia> target_edge(Target(:out))
:out

See also IndexedTarget, ClusterTarget.

IndexedTarget(edge::Symbol, index::Integer)
IndexedTarget{E}(index)

The target of a message rule towards member index of the interface group E, written target = (:m, k) in a rule's declaration. The index is a field rather than a type parameter, so every member of a group shares one rule, which reads its member's index as the name k it binds.

julia> using MessagePassingRulesBase: IndexedTarget, target_edge, target_index

julia> t = IndexedTarget(:m, 2); (target_edge(t), target_index(t))
(:m, 2)

See also Target, ClusterTarget.

ClusterTarget(members::Tuple)
ClusterTarget{K}()

The target of a marginal rule: the structural cluster K, written target = (:y, :x) in a rule's declaration, its members in interface-declaration order. A member of a group is written (:T, 1), as in (:out, (:T, 1)), the joint of out and the group T's first member. A rule declared with a bare name, target = members, is defined for every ClusterTarget of its node.

julia> using MessagePassingRulesBase: ClusterTarget, cluster_members

julia> cluster_members(ClusterTarget((:out, (:T, 1))))
(:out, (:T, 1))

See also Target, IndexedTarget.

target_edge(target::Union{Target, IndexedTarget}) -> Symbol

The interface a message rule's target points at: the interface's name for a Target, the group's name for an IndexedTarget.

target_index(target::IndexedTarget) -> Int

The index of the group member an IndexedTarget points at, counted from 1.

cluster_members(target::ClusterTarget) -> Tuple

The members of a cluster, in interface-declaration order: an interface's name, or (group, k) for member k of a group.

RuleArgs(; m = NamedTuple(), q = NamedTuple(), logscale = nothing)
RuleArgs(m::Messages, q::Marginals[, logscale])

The inputs a rule's body receives as args, and the value rules dispatch on.

• args.m: the inbound messages, a Messages;
• args.q: the marginals, a Marginals;
• args.logscale: the log scales that arrived with the messages, a RuleLogScales read as args.logscale.m[:out], when the caller tracks them, and nothing otherwise.

Rules dispatch on the keys and types of m and q alone; a rule reads args.logscale only when declared with reads_logscale = true.

Keywords

• m: the messages, a NamedTuple or a Messages. Default: none.
• q: the marginals of single interfaces, a NamedTuple or a Marginals. Joints need the Marginals constructor. Default: none.
• logscale: the messages' log scales, a NamedTuple keyed like m, or nothing when they are not tracked. Default: nothing.

Examples

julia> using MessagePassingRulesBase: RuleArgs

julia> args = RuleArgs(m = (μ = 1.0,), q = (v = 2.0,));

julia> args.m[:μ], args.q[:v], args.logscale
(1.0, 2.0, nothing)

Messages(values::NamedTuple)

The inbound messages a rule receives as args.m, keyed by interface name: args.m[:μ]. A group is a tuple of its members in order under the group's name, args.m[:inputs][k], with nothing for a member the rule does not take. The keys are held sorted, so the order a caller gives them in does not matter. keys(m) gives the names; indexing by a name m does not hold throws a KeyError.

julia> using MessagePassingRulesBase: Messages

julia> m = Messages((μ = 1.0, inputs = (2.0, 3.0)));

julia> m[:μ], m[:inputs][2], keys(m)
(1.0, 3.0, (:inputs, :μ))

See also Marginals, RuleArgs.

Marginals(singles::NamedTuple = NamedTuple())
Marginals(singles::NamedTuple, Val(cluster_keys), joints::Tuple)

The marginals a rule receives as args.q. Single interfaces and groups are reached like messages, args.q[:name] and args.q[:p][k]. A structural cluster is reached by the tuple of its members, in interface-declaration order: args.q[(:y, :x)], or args.q[:y, :x] for short. Inside a cluster a group's name stands for all its members jointly, so args.q[(:in,)] is the joint over the group in, while args.q[:in] is the tuple of its members' marginals. One member of a group is (:in, 1): args.q[:out, (:in, 1)] is the joint of out and that member.

The second form takes the joints' keys, as a Val of a tuple of member tuples, and the joints in the same order. A cluster's key is carried in the type and never turned into a symbol, so no name is derived and none can collide: q[:y_x] below is an interface named y_x, not the cluster.

Throws

• ArgumentError when the numbers of cluster keys and joints differ;
• KeyError when indexed by a name or a cluster it does not hold.

Examples

julia> using MessagePassingRulesBase: Marginals

julia> q = Marginals((τ = 2.0, y_x = 1.0), Val(((:y, :x),)), (0.5,));

julia> q[:τ], q[:y, :x], q[(:y, :x)], q[:y_x]
(2.0, 0.5, 0.5, 1.0)

See also Messages, RuleArgs.

canonical_cluster_keys(keys) -> Tuple

Sort joint-cluster keys into the order a Marginals holds them: by the names of their members, a group member's index after its group's name. A rule's dispatch signature and the containers an engine builds both use this order, so neither needs the other's spelling.

julia> using MessagePassingRulesBase: canonical_cluster_keys

julia> canonical_cluster_keys(((:y, :x), (:out, (:T, 2)), (:out, (:T, 1))))
((:out, (:T, 1)), (:out, (:T, 2)), (:y, :x))

rule_inputs(node, container::Union{Messages, Marginals}) -> Tuple{Vararg{Pair}}

The inputs in a rule's args.m or args.q as a tuple of key => value pairs: an interface by its name, a member of a group as (group, k), and a joint by its key, as (:out, (:T, 1)). Members a group does not deliver, nothing in its tuple, are left out. node tells which names are groups. It is for a rule declared with default, whose body walks the inputs the factorisation delivered; the pairs have known types and constant keys, so the walk is type-stable.

julia> using MessagePassingRulesBase: Messages, rule_inputs

julia> struct Tensor end

julia> @define_factor_node(node = Tensor, type = Stochastic, interfaces = [:out, :T...])

julia> rule_inputs(Tensor, Messages((out = 1.0, T = (2.0, nothing, 3.0))))
((:T, 1) => 2.0, (:T, 3) => 3.0, :out => 1.0)

buffer_like(x)
buffer_like(x::AbstractArray, T::Type)

Uninitialised storage shaped like x, with element type T if given, for an in-place rule's preallocate. It dispatches on the type of x, so the buffer is of a kind that matches: similar for arrays, which keeps a static array static-sized and mutable and a device array on its device; elementwise for tuples and named tuples. Array types and devices that need something else add a method.

Throws

ArgumentError for a number, which has no storage to write into.

Examples

julia> using MessagePassingRulesBase: buffer_like

julia> b = buffer_like([1.0, 2.0]); (typeof(b), size(b))
(Vector{Float64}, (2,))

RuleAnnotations(; m = NamedTuple(), q = NamedTuple(), out = NoAnnotations())

The ann a rule body receives, carrying annotations in both directions. The ones that arrived with the inputs are keyed exactly like them, ann.m[:out] and ann.q[:μ]; the rule writes its own with annotate!(ann, key, value), which lands in out, and reads them back with hasannotation and getannotation. Annotations never take part in dispatch.

Keywords

• m: the annotations of the inbound messages, a NamedTuple keyed like args.m. Default: none.
• q: the annotations of the marginals, keyed like args.q. Default: none.
• out: where the rule's own annotations go, an AnnotationStore or a NoAnnotations. Default: NoAnnotations(), dropping them.

AnnotationStore()

A mutable store of annotations keyed by symbol, which collects what a rule writes with annotate!. Its dictionary is created on the first write, so an empty store allocates nothing more. Pass one as a call's ann to read afterwards what the rule annotated, through getannotations(result).

julia> using MessagePassingRulesBase: AnnotationStore, annotate!, hasannotation, getannotation

julia> store = AnnotationStore(); annotate!(store, :iterations, 3);

julia> hasannotation(store, :iterations), getannotation(store, :iterations), getannotation(store, :other, 0)
(true, 3, 0)

See also NoAnnotations, RuleAnnotations.

NoAnnotations()

An annotation store that records nothing: annotate! on it does nothing, hasannotation is always false, and getannotation finds nothing. It has no fields, so a call that collects no annotations pays nothing for the rule's writes. It is the default for the message_passing_* calls, and the out of a RuleAnnotations unless one is given.

annotate!(annotations, key::Symbol, value) -> nothing

Record value under key, replacing any earlier value. annotations is an AnnotationStore, a NoAnnotations, which drops it, or a rule's ann, a RuleAnnotations, which writes to its out. A rule body calls it as annotate!(ann, key, value).

hasannotation(annotations, key::Symbol) -> Bool

Whether annotations holds a value under key; always false for a NoAnnotations. On a rule's ann it looks at what the rule wrote, not at the inputs' annotations.

getannotation(annotations, key::Symbol)
getannotation(annotations, key::Symbol, default)

The annotation recorded under key, or default when there is none. On a rule's ann it reads what the rule wrote, not the inputs' annotations.

Throws

KeyError when key holds nothing and no default is given.

public_equivalent(d)

d as the type users expect: the same distribution, converted from an efficient working type to its public counterpart. The identity by default.

Rules may compute in types chosen for the arithmetic rather than for the reader. ExponentialFamily's WishartFast, for instance, stores the inverse of its scale matrix, which is what the Wishart rules and products need, while users and most code expect Distributions' Wishart. A package whose rules return such a working type adds a method for it:

MessagePassingRulesBase.public_equivalent(d::WishartFast) = convert(Wishart, d)

An engine applies it to every marginal it forms from messages, so a posterior reaches its reader, and the rules that consume that marginal, in the public type. A method must return the same distribution, up to rounding; it is a change of representation, never of meaning. A working type that no reader should see is its use case; a type that is public already needs no method.