Rules implementation

rule(fform, on, vconstraint, mnames, messages, qnames, marginals, meta, __node)

This function is used to compute an outbound message for a given node

Arguments

• fform: Functional form of the node in form of a type of the node, e.g. ::Type{ <: NormalMeanVariance } or ::typeof(+)
• on: Outbound interface's tag for which a message has to be computed, e.g. ::Val{:out} or ::Val{:μ}
• vconstraint: Variable constraints for an outbound interface, e.g. Marginalisation or MomentMatching
• mnames: Ordered messages names in form of the Val type, eg. ::Val{ (:mean, :precision) }
• messages: Tuple of message of the same length as mnames used to compute an outbound message
• qnames: Ordered marginal names in form of the Val type, eg. ::Val{ (:mean, :precision) }
• marginals: Tuple of marginals of the same length as qnames used to compute an outbound message
• meta: Extra meta information
• addons: Extra addons information
• __node: Node reference

For all available rules, see ReactiveMP.print_rules_table().

See also: @rule, marginalrule, @marginalrule

@rule NodeType(:Edge, Constraint) (Arguments..., [ meta::MetaType ]) = begin
    # rule body
    return ...
end

The @rule macro help to define new methods for the rule function. It works particularly well in combination with the @node macro. It has a specific structure, which must specify:

• NodeType: must be a valid Julia type. If some attempt to define a rule for a Julia function (for example +), use typeof(+)
• Edge: edge label, usually edge labels are defined with the @node macro
• Constrain: DEPRECATED, please just use the Marginalisation label
• Arguments: defines a list of the input arguments for the rule
  • m_* prefix indicates that the argument is of type Message from the edge *
  • q_* prefix indicates that the argument is of type Marginal on the edge *
• Meta::MetaType - optionally, a user can specify a Meta object of type MetaType. This can be useful is some attempts to try different rules with different approximation methods or if the rule itself requires some temporary storage or cache. The default meta is nothing.

Here are various examples of the @rule macro usage:

1. Belief-Propagation (or Sum-Product) message update rule for the NormalMeanVariance node toward the :μ edge with the Marginalisation constraint. Input arguments are m_out and m_v, which are the messages from the corresponding edges out and v and have the type PointMass.

@rule NormalMeanVariance(:μ, Marginalisation) (m_out::PointMass, m_v::PointMass) = NormalMeanVariance(mean(m_out), mean(m_v))

1. Mean-field message update rule for the NormalMeanVariance node towards the :μ edge with the Marginalisation constraint. Input arguments are q_out and q_v, which are the marginals on the corresponding edges out and v of type Any.

@rule NormalMeanVariance(:μ, Marginalisation) (q_out::Any, q_v::Any) = NormalMeanVariance(mean(q_out), mean(q_v))

1. Structured Variational message update rule for the NormalMeanVariance node towards the :out edge with the Marginalisation constraint. Input arguments are m_μ, which is a message from the μ edge of type UnivariateNormalDistributionsFamily, and q_v, which is a marginal on the v edge of type Any.

@rule NormalMeanVariance(:out, Marginalisation) (m_μ::UnivariateNormalDistributionsFamily, q_v::Any) = begin
    m_μ_mean, m_μ_cov = mean_cov(m_μ)
    return NormalMeanVariance(m_μ_mean, m_μ_cov + mean(q_v))
end

See also: rule, marginalrule, [@marginalrule], @call_rule

@call_rule NodeType(:edge, Constraint) (argument1 = value1, argument2 = value2, ..., [ meta = ..., addons = ... ])

The @call_rule macro helps to call the rule method with an easier syntax. The structure of the macro is almost the same as in the @rule macro, but there is no begin ... end block, but instead each argument must have a specified value with the = operator.

The @call_rule accepts optional list of options before the functional form specification, for example:

@call_rule [ return_addons = true ] NodeType(:edge, Constraint) (argument1 = value1, argument2 = value2, ..., [ meta = ..., addons = ... ])

The list of available options is:

• return_addons - forces the @call_rule to return the tuple of (result, addons)
• fallback - specifies the fallback rule to use in case the rule is not defined for the given NodeType and specified arguments

See also: @rule, rule, @call_marginalrule

call_rule_create_node(::Type{ NodeType }, fformtype)

Creates a node object that will be used inside @call_rule macro.

call_rule_macro_parse_fn_args(inputs; specname, prefix, proxy)

Do not use this function directly. This function is private and does not belong to the public API.

This function is used to parse an arguments tuple for message and marginal calling rules specification.

@call_rule MvNormalMeanPrecision(:out, Marginalisation) (m_μ = NormalMeanPrecision(...), m_τ = PointMass(...)) = begin 
                                                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                                        `arguments` vector
    ...
end

Accepts a vector of (name, value) elements, specname, name prefix and proxy type. Returns parsed names without prefix and proxied values

See also: @rule

call_rule_is_node_required(fformtype)

Returns either CallRuleNodeRequired() or CallRuleNodeNotRequired() depending on if a specific fformtype requires an access to the corresponding node in order to compute a message update rule. Returns CallRuleNodeNotRequired() for all known functional forms by default and CallRuleNodeRequired() for all unknown functional forms.

rule_macro_parse_on_tag(expression)

Do not use this function directly. This function is private and does not belong to the public API.

This function is used to parse an on tag for message rules and marginal rules specification.

@rule MvNormalMeanPrecision(:out, Marginalisation) (...) = begin 
                            ^^^^
                            `on` tag
    ...
end

or

@rule NormalMixture((:m, k), Marginalisation) (...) = begin 
                    ^^^^^^^
                    `on` tag
    ...
end

Accepts either a quoted symbol expressions or a (name, index) tuple expression. Returns name expression, index expression and index initialisation expression.

See also: @rule

rule_macro_parse_fn_args(inputs; specname, prefix, proxy)

Do not use this function directly. This function is private and does not belong to the public API.

This function is used to parse an arguments tuple for message rules and marginal rules specification.

@rule MvNormalMeanPrecision(:out, Marginalisation) (m_μ::NormalMeanPrecision, m_τ::PointMass) = begin 
                                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                                   `arguments` vector
    ...
end

Accepts a vector of (name, type) elements, specname, name prefix and proxy type. Returns parsed names without prefix, proxied types and initialisation code block.

See also: @rule

rule_macro_check_fn_args(inputs; allowed_inputs, allowed_prefixes)

This function checks if all inputs are either in the allowed_inputs or have prefixes in the allowed_prefixes.

See also: @rule

marginalrule(fform, on, mnames, messages, qnames, marginals, meta, __node)

This function is used to compute a local joint marginal for a given node

Arguments

• fform: Functional form of the node in form of a type of the node, e.g. ::Type{ <: NormalMeanVariance } or ::typeof(+)
• on: Local joint marginal tag , e.g. ::Val{ :mean_precision } or ::Val{ :out_mean_precision }
• mnames: Ordered messages names in form of the Val type, eg. ::Val{ (:mean, :precision) }
• messages: Tuple of message of the same length as mnames used to compute an outbound message
• qnames: Ordered marginal names in form of the Val type, eg. ::Val{ (:mean, :precision) }
• marginals: Tuple of marginals of the same length as qnames used to compute an outbound message
• meta: Extra meta information
• __node: Node reference

See also: rule, @rule @marginalrule

@marginalrule NodeType(:Cluster) (Arguments..., [ meta::MetaType ]) = begin
    # rule body
    return ...
end

The @marginalrule macro help to define new methods for the marginalrule function. It works particularly well in combination with the @node macro. It has a specific structure, which must specify:

• NodeType: must be a valid Julia type. If some attempt to define a rule for a Julia function (for example +), use typeof(+)
• Cluster: edge cluster that contains joined edge labels with the _ symbol. Usually edge labels are defined with the @node macro
• Arguments: defines a list of the input arguments for the rule
  • m_* prefix indicates that the argument is of type Message from the edge *
  • q_* prefix indicates that the argument is of type Marginal on the edge *
• Meta::MetaType - optionally, a user can specify a Meta object of type MetaType. This can be useful is some attempts to try different rules with different approximation methods or if the rule itself requires some temporary storage or cache. The default meta is nothing.

The @marginalrule can return a NamedTuple in the return statement. This would indicate some variables in the joint marginal for the Cluster are independent and the joint itself is factorised. For example if some attempts to compute a marginal for the q(x, y) it is possible to return (x = ..., y = ...) as the result of the computation to indicate that q(x, y) = q(x)q(y).

Here are various examples of the @marginalrule macro usage:

1. Marginal computation rule around the NormalMeanPrecision node for the q(out, μ). The rule accepts arguments m_out and m_μ, which are the messages

from the out and μ edges respectively, and q_τ which is the marginal on the edge τ.

@marginalrule NormalMeanPrecision(:out_μ) (m_out::UnivariateNormalDistributionsFamily, m_μ::UnivariateNormalDistributionsFamily, q_τ::Any) = begin
    xi_out, W_out = weightedmean_precision(m_out)
    xi_μ, W_μ     = weightedmean_precision(m_μ)

    W_bar = mean(q_τ)

    W  = [W_out+W_bar -W_bar; -W_bar W_μ+W_bar]
    xi = [xi_out; xi_μ]

    return MvNormalWeightedMeanPrecision(xi, W)
end

1. Marginal computation rule around the NormalMeanPrecision node for the q(out, μ). The rule accepts arguments m_out and m_μ, which are the messages from the

out and μ edges respectively, and q_τ which is the marginal on the edge τ. In this example the result of the computation is a NamedTuple

@marginalrule NormalMeanPrecision(:out_μ) (m_out::PointMass, m_μ::UnivariateNormalDistributionsFamily, q_τ::Any) = begin
    return (out = m_out, μ = prod(ClosedProd(), NormalMeanPrecision(mean(m_out), mean(q_τ)), m_μ))
end

@call_marginalrule NodeType(:edge) (argument1 = value1, argument2 = value2, ..., [ meta = ... ])

The @call_marginalrule macro helps to call the marginalrule method with an easier syntax. The structure of the macro is almost the same as in the @marginalrule macro, but there is no begin ... end block, but instead each argument must have a specified value with the = operator.

See also: @marginalrule, marginalrule, @call_rule

@test_rules [options] rule [ test_entries... ]

The @test_rules macro generates test cases for message update rules for probabilistic programming models that follow the "message passing" paradigm. It takes a rule specification as input and generates a set of tests based on that specification. This macro is provided by ReactiveMP.

Note: The Test module must be imported explicitly. The @test_rules macro tries to use the @test macro, which must be defined globally.

Arguments

The macro takes three arguments:

• options: An optional argument that specifies the options for the test generation process. See below for details.
• rule: A rule specification in the same format as the @rule macro, e.g. Beta(:out, Marginalisation) or NormalMeanVariance(:μ, Marginalisation).
• test_entries: An array of named tuples (input = ..., output = ...). The input entry has the same format as the input for the @rule macro. The output entry specifies the expected output.

Options

The following options are available:

• check_type_promotion: By default, this option is set to false. If set to true, the macro generates an extensive list of extra tests that aim to check the correct type promotion within the tests. For example, if all inputs are of type Float32, then the expected output should also be of type Float32. See the paramfloattype and convert_paramfloattype functions for details.
• atol: Sets the desired accuracy for the tests. The tests use the custom_rule_isapprox function from ReactiveMP to check if outputs are approximately the same. This argument can be either a single number or an array of key => value pairs.
• extra_float_types: A set of extra float types to be used in the check_type_promotion tests. This argument has no effect if check_type_promotion is set to false.

The default values for the atol option are:

• Float32: 1e-4
• Float64: 1e-6
• BigFloat: 1e-8

Examples

@test_rules [check_type_promotion = true] Beta(:out, Marginalisation) [
    (input = (m_a = PointMass(1.0), m_b = PointMass(2.0)), output = Beta(1.0, 2.0)),
    (input = (m_a = PointMass(2.0), m_b = PointMass(2.0)), output = Beta(2.0, 2.0)),
    (input = (m_a = PointMass(3.0), m_b = PointMass(3.0)), output = Beta(3.0, 3.0))
]

@test_rules [check_type_promotion = true] Beta(:out, Marginalisation) [
    (input = (q_a = PointMass(1.0), q_b = PointMass(2.0)), output = Beta(1.0, 2.0)),
    (input = (q_a = PointMass(2.0), q_b = PointMass(2.0)), output = Beta(2.0, 2.0)),
    (input = (q_a = PointMass(3.0), q_b = PointMass(3.0)), output = Beta(3.0, 3.0))
]

See also: ReactiveMP.@test_marginalrules

@test_marginalrules [options] rule [ test_entries... ]

Effectively the same as @test_rules, but for marginal computation rules. See the documentation for @test_rules for more info.

See also: ReactiveMP.@test_rules

NodeFunctionRuleFallback(extractfn = mean)

A fallback rule for Stochastic nodes that uses a specified function (default: mean) to transform messages and marginals into a value. It calls the nodefunction method to create the message.

When a node is defined with the @node macro:

1. The nodefunction typically calls logpdf associated with the node's distribution. 2. The first edge in the @node specification is used to evaluate logpdf at. 3. Other edges are used to instantiate the associated distribution object.

julia> using ReactiveMP, BayesBase, Distributions

julia> struct MyBeta{A, B} <: ContinuousUnivariateDistribution
             a::A
             b::B
       end

julia> BayesBase.logpdf(d::MyBeta, x) = logpdf(Beta(d.a, d.b), x)

julia> BayesBase.insupport(d::MyBeta, x::Real) = true

julia> @node MyBeta Stochastic [out, a, b]

julia> message = @call_rule [fallback = NodeFunctionRuleFallback()] MyBeta(:out, Marginalisation) (m_a = Beta(2, 3), m_b = Beta(3, 2));

julia> logpdf(message, 0.5)
-0.5017644952110732

julia> message = @call_rule [fallback = NodeFunctionRuleFallback(mode)] MyBeta(:out, Marginalisation) (m_a = Beta(2, 3), m_b = Beta(3, 2)); # evaluate at `mode`

julia> logpdf(message, 0.5)
-0.5954237415153454

nodefunction(::Type{T}) where {T}

Returns a function that represents a node of type T. The function typically takes arguments that represent the node's input and output variables in the same order as defined in the @node macro.