Inspecting rules

which_message_update_rule(node, target; m, q, clusters, algorithm)

The RuleSpec that call_message_update_rule would run for these inputs, without running it. It displays the rule with its source, file and line. @which_message_update_rule is the same query written with keywords only.

Arguments

• node: the node, as declared with @define_factor_node: a type, NormalMeanVariance, or a function, +. A function node is the function itself: its type, typeof(+), is an ArgumentError saying so.

• target: the interface the message goes to: :out, or (:m, k) for member k of the group m, as (:in, 2).

Keywords

All optional; only the inputs' types matter, as they are what selects a rule.

• m: the inbound messages, a NamedTuple keyed by the interfaces' declared names: m = (μ = NormalMeanVariance(0.0, 1.0), v = PointMass(1.0)). A group is a tuple of its members in order, m = (in = (m₁, m₂),); for a rule that selects some members, nothing may stand for the others, as an engine gives them. Default: none.

• q: the marginals of single interfaces, keyed the same way: q = (v = Gamma(1.0, 1.0),). Default: none.

• clusters: the joint marginals of structural clusters, a tuple of pairs from the cluster's members, in interface order, to its joint: clusters = ((:y, :x) => q_yx,). (:in,) => q is the joint over the group in. Default: none.

• algorithm: the algorithm value to run under, with its parameters: algorithm = ARVMP(Multivariate, 2, ARsafe()). Rule lookup selects the rules of its type, and for a DefaultAlgorithmExtension the default's as well; an inherited rule runs with the value it was written for (rule_algorithm). Default: the node's, default_algorithm(node).

When no rule fits, the query throws a RuleNotFoundError, which lists the closest rules and why each does not fit.

which_marginal_update_rule(node, target; m, q, clusters, algorithm)

The RuleSpec that call_marginal_update_rule would run for these inputs, without running it. It displays the rule with its source, file and line. @which_marginal_update_rule is the same query written with keywords only.

Arguments

• node: the node, as declared with @define_factor_node: a type, NormalMeanVariance, or a function, +. A function node is the function itself: its type, typeof(+), is an ArgumentError saying so.

• target: the cluster whose joint marginal to compute, its members in interface order: (:out, :μ), or (:out, (:T, 1)) with a group member.

Keywords

All optional; only the inputs' types matter, as they are what selects a rule.

• m: the inbound messages, a NamedTuple keyed by the interfaces' declared names: m = (μ = NormalMeanVariance(0.0, 1.0), v = PointMass(1.0)). A group is a tuple of its members in order, m = (in = (m₁, m₂),); for a rule that selects some members, nothing may stand for the others, as an engine gives them. Default: none.

• q: the marginals of single interfaces, keyed the same way: q = (v = Gamma(1.0, 1.0),). Default: none.

• clusters: the joint marginals of structural clusters, a tuple of pairs from the cluster's members, in interface order, to its joint: clusters = ((:y, :x) => q_yx,). (:in,) => q is the joint over the group in. Default: none.

• algorithm: the algorithm value to run under, with its parameters: algorithm = ARVMP(Multivariate, 2, ARsafe()). Rule lookup selects the rules of its type, and for a DefaultAlgorithmExtension the default's as well; an inherited rule runs with the value it was written for (rule_algorithm). Default: the node's, default_algorithm(node).

When no rule fits, the query throws a RuleNotFoundError, which lists the closest rules and why each does not fit.

which_average_energy(node; q, clusters, m, algorithm)

The RuleSpec that call_average_energy would run for these marginals, without running it. It displays the energy with its source, file and line. @which_average_energy is the same query written with keywords only.

Arguments

• node: the node, as declared with @define_factor_node: a type, NormalMeanVariance, or a function, +. A function node is the function itself: its type, typeof(+), is an ArgumentError saying so.

Keywords

All optional; only the inputs' types matter, as they are what selects the energy.

• m: the inbound messages, a NamedTuple keyed by the interfaces' declared names: m = (μ = NormalMeanVariance(0.0, 1.0), v = PointMass(1.0)). A group is a tuple of its members in order, m = (in = (m₁, m₂),); for a rule that selects some members, nothing may stand for the others, as an engine gives them. Default: none.

• q: the marginals of single interfaces, keyed the same way: q = (v = Gamma(1.0, 1.0),). Default: none.

• clusters: the joint marginals of structural clusters, a tuple of pairs from the cluster's members, in interface order, to its joint: clusters = ((:y, :x) => q_yx,). (:in,) => q is the joint over the group in. Default: none.

• algorithm: the algorithm value to run under, with its parameters: algorithm = ARVMP(Multivariate, 2, ARsafe()). Rule lookup selects the rules of its type, and for a DefaultAlgorithmExtension the default's as well; an inherited rule runs with the value it was written for (rule_algorithm). Default: the node's, default_algorithm(node).

When no energy fits, the query throws a RuleNotFoundError, which lists the closest ones and why each does not fit.

@which_message_update_rule(node = ..., target = ..., m = (...), q = (...), clusters = (...), algorithm = ...)

The RuleSpec that @call_message_update_rule would run for these inputs, without running it; it displays the rule with its source, file and line. The macro takes keyword arguments only; node and target are required, the rest optional. It is which_message_update_rule with node and target given by name.

Required keywords

• node: the node, as declared with @define_factor_node: a type, NormalMeanVariance, or a function, +. A function node is the function itself: its type, typeof(+), is an ArgumentError saying so.

• target: the interface the message goes to: :out, or (:m, k) for member k of the group m, as (:in, 2).

Optional keywords

Only the inputs' types matter, as they are what selects a rule.

• m: the inbound messages, a NamedTuple keyed by the interfaces' declared names: m = (μ = NormalMeanVariance(0.0, 1.0), v = PointMass(1.0)). A group is a tuple of its members in order, m = (in = (m₁, m₂),); for a rule that selects some members, nothing may stand for the others, as an engine gives them. Default: none.

• q: the marginals of single interfaces, keyed the same way: q = (v = Gamma(1.0, 1.0),). Default: none.

• clusters: the joint marginals of structural clusters, a tuple of pairs from the cluster's members, in interface order, to its joint: clusters = ((:y, :x) => q_yx,). (:in,) => q is the joint over the group in. Default: none.

• algorithm: the algorithm value to run under, with its parameters: algorithm = ARVMP(Multivariate, 2, ARsafe()). Rule lookup selects the rules of its type, and for a DefaultAlgorithmExtension the default's as well; an inherited rule runs with the value it was written for (rule_algorithm). Default: the node's, default_algorithm(node).

When no rule fits, the query throws a RuleNotFoundError, which lists the closest rules and why each does not fit.

@which_marginal_update_rule(node = ..., target = (:y, :x), m = (...), q = (...), clusters = (...), algorithm = ...)

The RuleSpec that @call_marginal_update_rule would run for these inputs, without running it; it displays the rule with its source, file and line. The macro takes keyword arguments only; node and target are required, the rest optional. It is which_marginal_update_rule with node and target given by name.

Required keywords

• node: the node, as declared with @define_factor_node: a type, NormalMeanVariance, or a function, +. A function node is the function itself: its type, typeof(+), is an ArgumentError saying so.

• target: the cluster whose joint marginal to compute, its members in interface order: (:out, :μ), or (:out, (:T, 1)) with a group member.

Optional keywords

Only the inputs' types matter, as they are what selects a rule.

• m: the inbound messages, a NamedTuple keyed by the interfaces' declared names: m = (μ = NormalMeanVariance(0.0, 1.0), v = PointMass(1.0)). A group is a tuple of its members in order, m = (in = (m₁, m₂),); for a rule that selects some members, nothing may stand for the others, as an engine gives them. Default: none.

• q: the marginals of single interfaces, keyed the same way: q = (v = Gamma(1.0, 1.0),). Default: none.

• clusters: the joint marginals of structural clusters, a tuple of pairs from the cluster's members, in interface order, to its joint: clusters = ((:y, :x) => q_yx,). (:in,) => q is the joint over the group in. Default: none.

• algorithm: the algorithm value to run under, with its parameters: algorithm = ARVMP(Multivariate, 2, ARsafe()). Rule lookup selects the rules of its type, and for a DefaultAlgorithmExtension the default's as well; an inherited rule runs with the value it was written for (rule_algorithm). Default: the node's, default_algorithm(node).

When no rule fits, the query throws a RuleNotFoundError, which lists the closest rules and why each does not fit.

@which_average_energy(node = ..., q = (...), clusters = (...), m = (...), algorithm = ...)

The RuleSpec that @call_average_energy would run for these marginals, without running it; it displays the energy with its source, file and line. The macro takes keyword arguments only; node is required, the rest optional. It is which_average_energy with node given by name.

Required keywords

• node: the node, as declared with @define_factor_node: a type, NormalMeanVariance, or a function, +. A function node is the function itself: its type, typeof(+), is an ArgumentError saying so.

Optional keywords

Only the inputs' types matter, as they are what selects the energy.

• m: the inbound messages, a NamedTuple keyed by the interfaces' declared names: m = (μ = NormalMeanVariance(0.0, 1.0), v = PointMass(1.0)). A group is a tuple of its members in order, m = (in = (m₁, m₂),); for a rule that selects some members, nothing may stand for the others, as an engine gives them. Default: none.

• q: the marginals of single interfaces, keyed the same way: q = (v = Gamma(1.0, 1.0),). Default: none.

• clusters: the joint marginals of structural clusters, a tuple of pairs from the cluster's members, in interface order, to its joint: clusters = ((:y, :x) => q_yx,). (:in,) => q is the joint over the group in. Default: none.

• algorithm: the algorithm value to run under, with its parameters: algorithm = ARVMP(Multivariate, 2, ARsafe()). Rule lookup selects the rules of its type, and for a DefaultAlgorithmExtension the default's as well; an inherited rule runs with the value it was written for (rule_algorithm). Default: the node's, default_algorithm(node).

When no energy fits, the query throws a RuleNotFoundError, which lists the closest ones and why each does not fit.

RuleSpec

A rule as data, and the thing that runs: what a definition macro builds, what resolution (find_message_rule and its siblings) returns, and what execute_rule runs. Its body, preallocation, scratch and log-scale functions and its algorithm type are type parameters, RuleSpec{B, P, S, L, A}: where resolution is inferred, as at an engine's call site, which reaches one rule, it returns one concrete spec, and the body call is static. It shows itself at the REPL with its inputs, flags, source, file and line.

What it declares, read as fields:

• kind: :message, :marginal or :average_energy;
• node, algorithm: the node, and the algorithm type the rule is defined for;
• target: the target's type, a Target, IndexedTarget or ClusterTarget type, or Nothing for an average energy;
• inputs: its typed inputs, InputSpecs; for a rule declared with default among its args (default is true), only the typed ones beside it;
• inplace, pure, services: whether it writes into a given buffer, whether it is pure (declared, or its algorithm's ispure), and the context services it declares;
• annotates: whether its body takes the ann slot, and so may write annotations on its result; an engine gives a rule that does not an annotation store nobody writes to;
• logscale: what a message rule declares about its result's log scale: nothing for none, a number, a function, from_body or improper; reads_logscale: whether it reads its inbound messages' log scales;
• args_check: the source of the check its inputs must pass as its body starts, or nothing for none (the definition macros' args_check keyword; a failure is a RuleInputError);
• source, file, line: its body's source and where it was defined.

The other fields are internal: signature, the RuleArgs type it dispatches on; body, prealloc and scratch, the macro-generated functions over the full slot lists, the body over (output, scratch, algo, ctx, args, ann, target) and the others over (algo, ctx, args, target). Run a rule through execute_rule or a call, never by calling them.

InputSpec

One typed input a rule declares in its args, as a RuleSpec records it. Fields:

• container::Symbol: :m for a message, :q for a marginal;
• key: the interface's name, or a cluster's tuple of members;
• selection::Symbol: :single for an interface, :cluster for a joint, and for a group :all (m[:in...]), :aligned (m[:in][k]) or :allbutself (m[:in][!k]);
• type: the declared type, of each member for a group.

list_rules(node, edge::Union{Nothing, Symbol} = nothing; algorithm = nothing) -> Vector{RuleSpec}

The rules defined for node in every loaded module, as RuleSpecs: all of them, message and marginal rules and average energies, or, with edge, only the message rules towards edge, a group's name standing for all its members.

Keywords

• algorithm: an algorithm value, keeping only the rules it can select: its own, and for a DefaultAlgorithmExtension the default's as well. Default: nothing, every algorithm.

MessagePassingRulesBase.list_rules(NormalMeanVariance, :out)                 # every rule towards `out`
MessagePassingRulesBase.list_rules(NormalMeanVariance; algorithm = DefaultAlgorithm())

RuleCoverage

Which rules exist for a node, as rule_coverage makes it: rows are message targets (→ out, and → (m, k) for a group), marginal clusters (q(out, μ)) and the average energy; columns are algorithms, the node's default first; each cell counts the rules. It shows itself as a text table at the REPL, ✓ for one rule and ✓×n for several, and as an HTML table in a notebook or on a documentation page.

rule_coverage(node) -> RuleCoverage

The RuleCoverage table of node: what can be computed, under which algorithm, from the rules in every loaded module. Every interface of a declared node has a row, so a target without rules shows as an empty row.

A marginal rule over any cluster, declared target = members, has the row q(any cluster). A column is an algorithm type, labelled with its parameters, so the variants of a parametric algorithm are told apart; the node's own algorithm has a column even without rules, unless the rules are declared on a type that covers it.

For a node Shift with interfaces out and in and a single rule, towards out:

julia> MessagePassingRulesBase.rule_coverage(Shift)
Rule coverage for Shift
        │ DefaultAlgorithm
  → out │ ✓
  → in  │

prettify_modules(text::AbstractString) -> String

text, a printed name, type or value, without the modules Julia generates: Documenter's sandboxes (Main.var"__atexample__named__page".Gaussian becomes Gaussian), test items' and gensym'd modules. A package's module stays. The displays of this package print through it.

drawing(x) -> Drawing

x drawn as a standalone SVG, the drawing its card shows: a NodeSpec as its node and interfaces, a RuleSpec or a RuleResult as what the rule consumes and computes, and a DependenciesSpec as one small node per target. The Drawing shows as an image in notebooks and in the documentation; write("node.svg", drawing(x)) saves it, for slides or notes. Its colours are the light palette's, on a white background.

Drawing

The drawing drawing returns: a standalone SVG document, with its colours written on its elements, so that it needs no stylesheet and looks the same in a browser, a slide or a document. It shows as image/svg+xml in notebooks and in the documentation, and write saves it, write("node.svg", d).

check_rules(modules::Module...) -> Vector{RuleIssue}

Check every rule defined in modules, by default in every loaded module, against its node's declaration and the dependency declarations, and return the problems as RuleIssues; an empty vector means none. It checks:

• that the rule's node is declared;
• its target: an interface of the node, a group written (:m, k) and a single interface not, and a cluster's members existing, in interface order, a group's members by index, and not a lone single interface, whose marginal is written q[:x];
• each input: an existing interface, a group selected as [:m...], [k] or [!k] and a single interface not, and a cluster as for the target;
• for a message rule whose algorithm has a dependency declaration (its own, or for a DefaultAlgorithmExtension that declares none, the default's) listing its target: that it consumes exactly the declared inputs, or, for a target declared with default, at least the added ones. A rule declared with default in its args is not compared;
• for a message rule whose algorithm has no dependency declaration, that it does not read the message on its own edge, m[:e] towards :e or m[:g][k] towards (:g, k), which the default scheme never delivers.

A package's tests call it on the package's own module.

RuleIssue

A problem check_rules found with one rule. Fields: rule, the RuleSpec, and message, a sentence saying what is wrong. It shows itself as RuleIssue(file:line: message).

check_rule_ambiguities(modules::Module...) -> Vector{Tuple{RuleSpec, RuleSpec}}

The pairs of rules defined in modules, by default in every loaded module, that some call could match equally well, so that resolution would throw a MethodError; an empty vector means none. Only rules consuming the same set of inputs can overlap, so candidates are grouped by kind, node, target and input names first. Within a group, each rule's own method of find_message_rule, find_marginal_rule or find_average_energy is compared with Julia's Base.isambiguous.

Julia's check, not a hand-made typeintersect, because the signatures bound their inputs as Messages{N, <:Tuple{…}}: when a slot is disjoint, the intersection is a valid but empty type such as Messages{N, Union{}} or PointMass{Union{}}, never Union{} itself, so an intersection test reports every disjoint pair. Base.isambiguous ignores ambiguities only a Union{} parameter could trigger.

duplicate_rules() -> Vector{Vector{Pair{Module, RuleSpec}}}

Rules with identical signatures defined in more than one loaded module, one group per signature, each rule with its module. Within one module Julia itself rejects the second definition during precompilation; across modules the later method silently replaces the earlier, which this reports. Ambiguity, overlapping but different signatures, is a separate question, answered by check_rule_ambiguities.

Registry

The rules, nodes and dependency declarations one module defines, in its fields rules (RuleSpecs), nodes (NodeSpecs) and dependencies (DependenciesSpecs). The definition macros create it in the defining module, as the constant __message_passing_registry__, and fill it at the module's top level, so a package's precompile image carries its own entries. A redefinition, at the REPL say, replaces the entry with the same key.

It is for introspection only: listing, checking and displaying rules, and suggesting candidates when no rule fits. Resolution, finding which rule runs, does not use it: Julia's dispatch finds the rule. See What the registry is for.

See also registries, registered_rules.

registries(modules::Module...) -> Vector{Pair{Module, Registry}}

Every Registry in modules and their submodules, each with the module that owns it; with no argument, in Main and every loaded module.

registered_rules(modules::Module...) -> Vector{RuleSpec}

Every rule defined in modules and their submodules; with no argument, in every loaded module.

registered_nodes(modules::Module...) -> Vector{NodeSpec}

Every node declared in modules and their submodules; with no argument, in every loaded module.

registered_dependencies(modules::Module...) -> Vector{DependenciesSpec}

Every DependenciesSpec declared in modules and their submodules; with no argument, in every loaded module.