Inference API

moment(graph::GaussianFactorGraph; mean = 0.0, covariance = 1e6)

Create moment-form Gaussian belief propagation inference state.

Arguments

• graph: Gaussian factor graph or tree view.

Keywords

• mean: Default prior mean for variables without their own mean.
• covariance: Default prior covariance for variables without their own covariance.

Returns

A GaussianMomentInference object.

Notes

The returned object contains all messages and marginals needed by gbp!. Variables that were constructed without explicit priors use the provided default mean and covariance. Scalar defaults are expanded to the dimension of each variable. These defaults are stored and reused when new variables are added later through the warm-start addVariable! API. A unary Gaussian factor created with initialize = true overrides both the Gaussian variable prior and inference default for its connected variable.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph; covariance = 1e4)

canonical(graph::GaussianFactorGraph; mean = 0.0, covariance = 1e6)

Create canonical-form Gaussian belief propagation inference state.

Arguments

• graph: Gaussian factor graph or tree view.

Keywords

• mean: Default prior mean for variables without their own mean.
• covariance: Default prior covariance for variables without their own covariance.

Returns

A GaussianCanonicalInference object.

Notes

The default mean and covariance are converted to information/precision messages for variables without explicit priors. Scalar defaults are expanded to the dimension of each variable. These defaults are stored and reused when new variables are added later through the warm-start addVariable! API. A unary Gaussian factor created with initialize = true overrides both the Gaussian variable prior and inference default for its connected variable.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = canonical(graph; covariance = 1e4)

minsum(graph::GaussianFactorGraph; mean = 0.0, covariance = 1e6)

Create a Gaussian min-sum MAP inference state.

Arguments

• graph: Gaussian factor graph or tree view.

Keywords

• mean: Default prior mean for variables without their own mean.
• covariance: Default prior covariance for variables without their own covariance.

Returns

A GaussianMinSumInference object.

Notes

Gaussian min-sum runs in negative-log quadratic cost form. Messages are quadratic costs, and the stored estimates are MAP estimates. Marginal covariances are not computed by this inference object. The default mean and covariance are converted to initial quadratic messages for variables without their own initial belief.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = minsum(graph; covariance = 1e4)

sumproduct(graph::DiscreteFactorGraph)

Create a discrete sum-product inference state for graph.

The returned DiscreteSumProductInference stores probability-vector messages and marginals. Discrete variables with an initializing unary discrete factor use that factor as their initial belief; other variables use their own probability vector or a uniform default.

minsum(graph::DiscreteFactorGraph)

Create a discrete min-sum inference state for graph.

The returned DiscreteMinSumInference stores cost-vector messages and MAP state estimates. Variable probability vectors and initializing unary discrete factors are converted to negative-log costs.

addVariable!(
    graph::GaussianFactorGraph, inference::GaussianInference, variable::GaussianVariable;
    mean = inference default, covariance = inference default
)
addVariable!(
    graph::GaussianFactorGraph, inference::GaussianInference,
    id::VariableId, dimension::Int;
    label = string(id), components = 1:dimension, mean = nothing, covariance = nothing
)

Add a Gaussian variable node and extend an existing Gaussian inference state.

Existing messages and marginals are kept as a warm start. The new Gaussian variable is initialized using its own mean/covariance if provided, otherwise the defaults stored in inference are used. The returned value is the added GaussianVariable.

In the id/dimension convenience form, mean = nothing and covariance = nothing create a Gaussian variable without an explicit prior; the added variable is then initialized from the inference defaults.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

addVariable!(graph, inference, :x2, 1; label = "x2")

addFactor!(
    graph::GaussianFactorGraph, inference::GaussianInference, factor::GaussianFactor
)
addFactor!(
    graph::GaussianFactorGraph, inference::GaussianInference,
    variable::Union{VariableRef, GaussianVariable}..., mean, coefficient, covariance;
    label = "", initialize = false
)

Add a Gaussian factor node and extend an existing Gaussian inference state.

Existing messages and results are kept as a warm start. Moment inference extends Gaussian messages and marginals, canonical inference extends canonical messages and marginals, and min-sum inference extends quadratic messages and MAP estimates. In all cases, the returned value is the added GaussianFactor.

If initialize = true, the factor must be unary. The connected variable's initial belief and incident messages are reset in the representation used by the selected inference object.

Example

x1 = GaussianVariable(:x1, 1)

graph = factorGraph([x1], GaussianFactor[])
inference = moment(graph)

addFactor!(graph, inference, :x1, 0.0, 1.0, 0.1; label = "f1")

updateFactor!(
    graph::GaussianFactorGraph, inference::GaussianInference, factor::FactorRef;
    mean = nothing, coefficient = nothing, covariance = nothing, initialize = nothing
)
updateFactor!(
    graph::GaussianFactorGraph, inference::GaussianInference;
    factor::FactorRef,
    mean = nothing, coefficient = nothing, covariance = nothing, initialize = nothing
)

Update an existing Gaussian factor and refresh the matching Gaussian inference state.

The graph factor is updated first, then the inference object refreshes the representation it owns: moment messages, canonical messages, or min-sum quadratic messages and MAP estimates. When initialize = true, the updated factor must be unary and its value is copied into the connected variable's initial belief and incident messages.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

updateFactor!(graph, inference, "f1"; mean = 0.2)

addVariable!(
    graph::DiscreteFactorGraph, inference::DiscreteSumProductInference,
    variable::DiscreteVariable
)

Add a discrete variable to a graph and extend a matching sum-product inference state in place.

The inference object must be current with the graph topology. The added variable receives its initial sum-product message and marginal.

addVariable!(
    graph::DiscreteFactorGraph, inference::DiscreteMinSumInference,
    variable::DiscreteVariable
)

Add a discrete variable to a graph and extend a matching min-sum inference state in place.

The inference object must be current with the graph topology. The added variable receives its initial min-sum cost message and MAP estimate.

addFactor!(
    graph::DiscreteFactorGraph, inference::DiscreteSumProductInference,
    factorData::DiscreteFactor
)

Add a discrete factor to a graph and extend a matching sum-product inference state in place.

New edge messages are initialized from the connected variable beliefs. If the factor is an initializing unary factor, it updates the connected variable's initial belief and incident variable-to-factor messages.

addFactor!(
    graph::DiscreteFactorGraph, inference::DiscreteMinSumInference,
    factorData::DiscreteFactor
)

Add a discrete factor to a graph and extend a matching min-sum inference state in place.

New edge messages are initialized from the connected variable costs. If the factor is an initializing unary factor, it updates the connected variable's initial cost and MAP estimate.

updateFactor!(
    graph::DiscreteFactorGraph, inference::DiscreteSumProductInference,
    factorRef::FactorRef; table = nothing, initialize = nothing
)

Update a discrete factor and refresh a matching sum-product inference state.

If an initializing unary factor is updated, the connected variable's initial belief and incident variable-to-factor messages are refreshed.

updateFactor!(
    graph::DiscreteFactorGraph, inference::DiscreteMinSumInference,
    factorRef::FactorRef; table = nothing, initialize = nothing
)

Update a discrete factor and refresh a matching min-sum inference state.

If an initializing unary factor is updated, the connected variable's initial cost and MAP estimate are refreshed.

freezeFactor!(
    graph::AbstractFactorGraph, inference::AbstractInference, factor::FactorRef
)

Freeze all outgoing factor-to-variable messages for a factor.

Arguments

• graph: Gaussian or discrete factor graph.
• inference: Matching inference object.
• factor: Factor index or label.

Notes

While frozen, belief propagation iterations keep the selected outgoing messages unchanged.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

freezeFactor!(graph, inference, "f1")

unfreezeFactor!(
    graph::AbstractFactorGraph, inference::AbstractInference, factor::FactorRef
)

Unfreeze outgoing factor-to-variable messages for a factor.

Arguments

• graph: Gaussian or discrete factor graph.
• inference: Matching inference object.
• factor: Factor index or label.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

unfreezeFactor!(graph, inference, "f1")

isFrozenFactor(
    graph::AbstractFactorGraph, inference::AbstractInference, factor::FactorRef
)

Return whether outgoing messages from a factor are frozen.

Arguments

• graph: Gaussian or discrete factor graph.
• inference: Matching inference object.
• factor: Factor index or label.

Returns

true if the selected factor is frozen.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

isFrozenFactor(graph, inference, "f1")

freezeVariable!(
    graph::AbstractFactorGraph, inference::AbstractInference, variable::VariableRef
)

Freeze all outgoing variable-to-factor messages for a variable.

Arguments

• graph: Gaussian or discrete factor graph.
• inference: Matching inference object.
• variable: Variable ID or label.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

freezeVariable!(graph, inference, :x1)

unfreezeVariable!(
    graph::AbstractFactorGraph, inference::AbstractInference, variable::VariableRef
)

Unfreeze outgoing variable-to-factor messages for a variable.

Arguments

• graph: Gaussian or discrete factor graph.
• inference: Matching inference object.
• variable: Variable ID or label.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

unfreezeVariable!(graph, inference, :x1)

isFrozenVariable(
    graph::AbstractFactorGraph, inference::AbstractInference, variable::VariableRef
)

Return whether outgoing messages from a variable are frozen.

Arguments

• graph: Gaussian or discrete factor graph.
• inference: Matching inference object.
• variable: Variable ID or label.

Returns

true if the selected variable is frozen.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

isFrozenVariable(graph, inference, :x1)

freezeEdge!(
    graph::AbstractFactorGraph, inference::AbstractInference;
    variable::VariableRef, factor::FactorRef
)

Freeze both message directions on the edge connecting variable and factor.

Arguments

• graph: Gaussian or discrete factor graph.
• inference: Matching inference object.

Keywords

• variable: Variable ID or label.
• factor: Factor index or label.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

freezeEdge!(graph, inference; variable = :x1, factor = "f1")

unfreezeEdge!(
    graph::AbstractFactorGraph, inference::AbstractInference;
    variable::VariableRef, factor::FactorRef
)

Unfreeze both message directions on the edge connecting variable and factor.

Arguments

• graph: Gaussian or discrete factor graph.
• inference: Matching inference object.

Keywords

• variable: Variable ID or label.
• factor: Factor index or label.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

unfreezeEdge!(graph, inference; variable = :x1, factor = "f1")

isFrozenEdge(
    graph::AbstractFactorGraph, inference::AbstractInference;
    variable::VariableRef, factor::FactorRef
)

Return whether both message directions on an edge are frozen.

Arguments

• graph: Gaussian or discrete factor graph.
• inference: Matching inference object.

Keywords

• variable: Variable ID or label.
• factor: Factor index or label.

Returns

true if the selected edge is frozen.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

isFrozenEdge(graph, inference; variable = :x1, factor = "f1")

dampEdges!(
    graph::AbstractFactorGraph, inference::AbstractInference;
    variable = nothing, factor = nothing, prob = 0.6, alpha = 0.4
)

Enable damping for selected edges.

Arguments

• graph: Gaussian or discrete factor graph.
• inference: Matching inference object.

Keywords

• variable: Optional variable ID or label.
• factor: Optional factor index or label.
• prob: Damping probability.
• alpha: Previous-message mixing weight.

Notes

If both variable and factor are provided, only that edge is selected. If only variable is provided, all edges incident to that variable are selected. If only factor is provided, all edges incident to that factor are selected. If neither is provided, all graph edges are selected.

Example

x1 = GaussianVariable(:x1, 1)
x2 = GaussianVariable(:x2, 1)
f1 = GaussianFactor(:x1, :x2, 0.0, [1.0 -1.0], 0.1; label = "f1")

graph = factorGraph([x1, x2], [f1])
inference = moment(graph)

dampEdges!(graph, inference; variable = :x2, factor = "f1", prob = 1.0, alpha = 0.35)

undampEdges!(
    graph::AbstractFactorGraph, inference::AbstractInference;
    variable = nothing, factor = nothing
)

Disable damping for selected edges.

Arguments

• graph: Gaussian or discrete factor graph.
• inference: Matching inference object.

Keywords

• variable: Optional variable ID or label.
• factor: Optional factor index or label.

Notes

If both variable and factor are provided, only that edge is selected. If only variable is provided, all edges incident to that variable are selected. If only factor is provided, all edges incident to that factor are selected. If neither is provided, all graph edges are selected.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

undampEdges!(graph, inference; variable = :x1, factor = "f1")

areDampedEdges(
    graph::AbstractFactorGraph, inference::AbstractInference;
    variable = nothing, factor = nothing
)

Return whether all selected edges are marked for damping.

Arguments

• graph: Gaussian or discrete factor graph.
• inference: Matching inference object.

Keywords

• variable: Optional variable ID or label.
• factor: Optional factor index or label.

Notes

If both variable and factor are provided, only that edge is selected. If only variable is provided, all edges incident to that variable are selected. If only factor is provided, all edges incident to that factor are selected. If neither is provided, all graph edges are selected.

Returns

true if all selected edges are damped.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

areDampedEdges(graph, inference; variable = :x1, factor = "f1")

factorToVariableMessages!(
    graph::GaussianFactorGraph, inference::GaussianInference;
    damping = false, prob = 0.6, alpha = 0.4, rng = Random.default_rng(),
    broadcast = false
)

Run one Gaussian factor-to-variable message update pass.

Arguments

• graph: Gaussian factor graph.
• inference: Matching Gaussian inference object.

Keywords

• damping: Enable global factor-to-variable message damping.
• prob: Damping probability.
• alpha: Previous-message mixing weight.
• rng: Random number generator used by damping.
• broadcast: Compute messages in grouped broadcast form.

Notes

This updates only messages sent from factor nodes to variable nodes. It does not recompute marginals or MAP estimates; call marginals! for moment and canonical inference, or estimates! for min-sum inference.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

factorToVariableMessages!(graph, inference)

variableToFactorMessages!(
    graph::GaussianFactorGraph, inference::GaussianInference;
    broadcast = false
)

Run one Gaussian variable-to-factor message update pass.

Arguments

• graph: Gaussian factor graph.
• inference: Matching Gaussian inference object.

Keywords

• broadcast: Compute messages in grouped broadcast form.

Notes

This updates only messages sent from variable nodes to factor nodes. It does not recompute marginals or MAP estimates.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

variableToFactorMessages!(graph, inference)

messages!(
    graph::GaussianFactorGraph, inference::GaussianInference;
    damping = false, prob = 0.6, alpha = 0.4, rng = Random.default_rng(),
    schedule = nothing, updateFraction = nothing, updateCount = nothing,
    broadcast = false
)

Run one complete Gaussian message update step.

Arguments

• graph: Gaussian factor graph.
• inference: Matching Gaussian inference object.

Keywords

• damping: Enable global factor-to-variable message damping.
• prob: Damping probability.
• alpha: Previous-message mixing weight.
• rng: Random number generator used by damping.
• schedule: :sequential, :flooding, :residual, a schedule object, or nothing.
• updateFraction: Residual-schedule fraction when schedule = :residual.
• updateCount: Residual-schedule count when schedule = :residual.
• broadcast: Compute sequential or flooding passes in grouped form.

Notes

This updates messages stored in inference. Call marginals! afterwards for moment and canonical inference, or estimates! for min-sum inference.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

messages!(graph, inference)

marginals!(graph::GaussianFactorGraph, inference::GaussianSumProductInference)

Recompute Gaussian variable marginals from the current sum-product messages.

marginals!(graph::DiscreteFactorGraph, inference::DiscreteSumProductInference)

Recompute all discrete sum-product marginals from the current incoming factor-to-variable messages.

estimates!(graph::GaussianFactorGraph, inference::GaussianMinSumInference)

Recompute MAP estimates from current Gaussian min-sum messages.

Arguments

• graph: Gaussian factor graph.
• inference: Matching Gaussian min-sum inference object.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = minsum(graph)

messages!(graph, inference)
estimates!(graph, inference)

gbp!(
    graph::GaussianFactorGraph, inference::GaussianInference;
    iterations = 10, tolerance = nothing,
    damping = false, prob = 0.6, alpha = 0.4, rng = Random.default_rng()
    schedule = nothing, updateFraction = nothing, updateCount = nothing
)

Run Gaussian belief propagation updates in place.

Arguments

• graph: Gaussian factor graph or tree view.
• inference: Matching Gaussian inference object.

Keywords

• iterations: Maximum number of belief propagation iterations to run.
• tolerance: Optional early-stopping tolerance.
• damping: Enable global factor-to-variable message damping.
• prob: Damping probability.
• rng: Random number generator used for damping.
• alpha: Damping mixing weight.
• schedule: :sequential, :flooding, :residual, or nothing.
• broadcast: Compute sequential or flooding message passes in grouped form.
• updateFraction: Residual-schedule fraction when schedule = :residual.
• updateCount: Residual-schedule count when schedule = :residual.

Notes

Each iteration updates messages, then updates the result state owned by the inference object: marginals for moment and canonical inference, or MAP estimates for min-sum inference. When schedule is omitted, gbp! uses the sequential schedule.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

gbp!(graph, inference; iterations = 20, tolerance = 1e-6)

factorToVariableMessages!(
    graph::DiscreteFactorGraph, inference::DiscreteSumProductInference;
    damping = false, prob = 0.6, alpha = 0.4, rng = Random.default_rng()
)

Update all factor-to-variable sum-product messages in place.

When damping is enabled, each updated message is mixed with its previous value with probability prob and damping weight alpha. Per-edge damping settings configured with dampEdges! are also honored.

factorToVariableMessages!(
    graph::DiscreteFactorGraph, inference::DiscreteMinSumInference;
    damping = false, prob = 0.6, alpha = 0.4, rng = Random.default_rng()
)

Update all factor-to-variable min-sum cost messages in place.

When damping is enabled, each updated message is mixed with its previous value with probability prob and damping weight alpha. Per-edge damping settings configured with dampEdges! are also honored.

variableToFactorMessages!(
    graph::DiscreteFactorGraph, inference::DiscreteSumProductInference
)

Update all variable-to-factor sum-product messages in place.

variableToFactorMessages!(
    graph::DiscreteFactorGraph, inference::DiscreteMinSumInference
)

Update all variable-to-factor min-sum cost messages in place.

messages!(
    graph::DiscreteFactorGraph, inference::DiscreteSumProductInference;
    damping = false, prob = 0.6, alpha = 0.4, schedule = nothing,
    updateFraction = nothing, updateCount = nothing, rng = Random.default_rng()
)

Run one discrete sum-product message update sweep.

The default schedule updates factor-to-variable messages and then variable-to-factor messages. Pass schedule = :flooding for simultaneous message commits, or pass schedule = :residual with updateFraction or updateCount for one residual-scheduled step.

messages!(
    graph::DiscreteFactorGraph, inference::DiscreteMinSumInference;
    damping = false, prob = 0.6, alpha = 0.4, schedule = nothing,
    updateFraction = nothing, updateCount = nothing, rng = Random.default_rng()
)

Run one discrete min-sum message update sweep.

The default schedule updates factor-to-variable messages and then variable-to-factor messages. Pass schedule = :flooding for simultaneous message commits, or pass schedule = :residual with updateFraction or updateCount for one residual-scheduled step.

marginals!(graph::DiscreteFactorGraph, inference::DiscreteSumProductInference)

Recompute all discrete sum-product marginals from the current incoming factor-to-variable messages.

estimates!(graph::DiscreteFactorGraph, inference::DiscreteMinSumInference)

Recompute all discrete min-sum MAP estimates from the current incoming factor-to-variable cost messages.

gbp!(
    graph::DiscreteFactorGraph, inference::DiscreteSumProductInference;
    iterations = 10, tolerance = nothing,
    damping = false, prob = 0.6, alpha = 0.4, schedule = nothing,
    updateFraction = nothing, updateCount = nothing, rng = Random.default_rng()
)

Run iterative discrete sum-product belief propagation in place.

Each iteration updates messages and recomputes marginals. If tolerance is provided, iteration stops once the maximum marginal change is at most that tolerance.

gbp!(
    graph::DiscreteFactorGraph, inference::DiscreteMinSumInference;
    iterations = 10, tolerance = nothing,
    damping = false, prob = 0.6, alpha = 0.4, schedule = nothing,
    updateFraction = nothing, updateCount = nothing, rng = Random.default_rng()
)

Run iterative discrete min-sum belief propagation in place.

Each iteration updates messages and recomputes MAP estimates. If tolerance is provided, iteration stops once the maximum estimate change is at most that tolerance.

sequentialSchedule(graph::AbstractFactorGraph, inference::AbstractInference)

Create a sequential schedule for low-level message updates.

Arguments

• graph: Gaussian or discrete factor graph.
• inference: Matching inference object.

Returns

A SequentialSchedule.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

schedule = sequentialSchedule(graph, inference)
messages!(graph, inference, schedule)

floodingSchedule(graph::AbstractFactorGraph, inference::AbstractInference)

Create a flooding schedule for low-level message updates.

Arguments

• graph: Gaussian or discrete factor graph.
• inference: Matching inference object.

Returns

A FloodingSchedule.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

schedule = floodingSchedule(graph, inference)
messages!(graph, inference, schedule)

residualSchedule(
    graph::AbstractFactorGraph, inference::AbstractInference;
    updateFraction = 0.1, updateCount = nothing
)

Create a residual schedule for belief propagation.

Arguments

• graph: Gaussian or discrete factor graph.
• inference: Matching inference object.

Keywords

• updateFraction: Fraction of directed candidates to update per step.
• updateCount: Fixed number of directed candidates to update per step.

Returns

A mutable ResidualSchedule.

Notes

Each candidate is one directed message update. If updateCount is omitted, each residual step updates the largest updateFraction of candidate messages. If updateCount is provided, it updates at most that many messages. The two selection keywords are mutually exclusive.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

schedule = residualSchedule(graph, inference; updateCount = 4)

residualStep!(
    graph::AbstractFactorGraph, inference::AbstractInference, schedule::ResidualSchedule;
    damping = false, prob = 0.6, alpha = 0.4, rng = Random.default_rng()
)

Recompute residuals for all directed messages and update the selected largest-residual batch in place.

Arguments

• graph: Gaussian or discrete factor graph.
• inference: Matching inference object.
• schedule: Residual schedule created for the same graph and inference object.

Keywords

• damping: Enable damping for residual updates.
• prob: Damping probability.
• alpha: Damping mixing weight.
• rng: Random number generator used by damping.

Returns

The updated schedule.

Notes

The schedule's lastUpdated field stores the selected candidate indices from the most recent step. Returns the same schedule. This is equivalent to calling messages! with the schedule as the third argument.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

schedule = residualSchedule(graph, inference)
residualStep!(graph, inference, schedule)

messages!(
    graph::AbstractFactorGraph,
    inference::AbstractInference,
    schedule::ResidualSchedule;
    damping = false,
    prob = 0.6,
    alpha = 0.4,
    rng = Random.default_rng()
)

Run one residual-scheduled message update step without recomputing marginals.

Arguments

• graph: Gaussian or discrete factor graph.
• inference: Matching inference object.
• schedule: Residual schedule created for the same graph and inference object.

Keywords

• damping: Enable damping for residual updates that support it.
• prob: Damping probability.
• alpha: Damping mixing weight.
• rng: Random number generator used by damping.

Returns

The updated schedule.

Notes

This is the low-level residual scheduling entry point. It recomputes residuals for all directed messages, updates the selected largest-residual batch, and stores the selected candidate indices in schedule.lastUpdated. Call marginals! afterwards when you want marginals to reflect the latest messages.

forwardBackwardSchedule(tree::TreeFactorGraph)

Create a new forward/backward schedule for a tree factor graph.

Arguments

• tree: Tree factor graph.

Returns

A ForwardBackwardSchedule.

Notes

The returned schedule starts before the first forward and backward messages.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
tree = treeFactorGraph(graph; root = :x1)
inference = moment(graph)

schedule = forwardBackwardSchedule(tree)
forwardBackward!(tree, inference, schedule)

reset!(schedule::ForwardBackwardSchedule)

Reset a ForwardBackwardSchedule to the first forward and backward message.

Arguments

• schedule: Schedule to reset.

Returns

The same schedule.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
tree = treeFactorGraph(graph; root = :x1)

schedule = forwardBackwardSchedule(tree)
reset!(schedule)

reset!(tree::TreeFactorGraph)

Reset a TreeFactorGraph's default forward/backward step cursor.

Arguments

• tree: Tree factor graph.

Returns

The same tree.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
tree = treeFactorGraph(graph; root = :x1)

reset!(tree)

refresh!(tree::TreeFactorGraph; root = nothing)

Recompute the orientation and message order of a TreeFactorGraph.

Arguments

• tree: Tree factor graph to refresh.

Keywords

• root: Optional replacement root variable. If omitted, the previous root is reused.

Returns

The same tree.

Notes

Use this after graph topology changes when the underlying graph is still a tree. If root is omitted, the previous root variable is reused. Returns the same tree object.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
tree = treeFactorGraph(graph; root = :x1)

refresh!(tree; root = :x1)

forwardStep!(tree::TreeFactorGraph, inference::AbstractInference)
forwardStep!(
    tree::TreeFactorGraph, inference::AbstractInference, schedule::ForwardBackwardSchedule
)
forwardStep!(
    tree::TreeFactorGraph, inference::AbstractInference;
    variable::VariableRef, factor::FactorRef
)
forwardStep!(
    tree::TreeFactorGraph, inference::AbstractInference, edgeId::Int
)

Perform one forward tree message update.

Arguments

• tree: Tree factor graph.
• inference: Matching inference object.
• schedule: Optional forward/backward schedule.
• edgeId: Explicit edge ID to update.

Keywords

• variable: Variable ID or label for selected-edge update.
• factor: Factor index or label for selected-edge update.

Returns

The updated edge ID, or nothing when the scheduled pass is complete.

Notes

Without an explicit edge, the next edge in the forward schedule is updated and the step cursor is advanced. Returns the updated edge ID, or nothing when the forward pass is complete.

The edge order is determined by treeFactorGraph. A forward pass sends messages from leaves toward the selected root.

When schedule is omitted, the tree's default step cursor is advanced. Use reset! on the tree before reusing that cursor.

Passing an edge ID, or selecting an edge by variable and factor, updates only that selected forward message and does not advance any cursor.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
tree = treeFactorGraph(graph; root = :x1)
inference = moment(graph)

schedule = forwardBackwardSchedule(tree)
forwardStep!(tree, inference, schedule)

backwardStep!(tree::TreeFactorGraph, inference::AbstractInference)
backwardStep!(
    tree::TreeFactorGraph, inference::AbstractInference, schedule::ForwardBackwardSchedule
)
backwardStep!(
    tree::TreeFactorGraph, inference::AbstractInference;
    variable::VariableRef, factor::FactorRef
)
backwardStep!(
    tree::TreeFactorGraph, inference::AbstractInference, edgeId::Int
)

Perform one backward tree message update.

Arguments

• tree: Tree factor graph.
• inference: Matching inference object.
• schedule: Optional forward/backward schedule.
• edgeId: Explicit edge ID to update.

Keywords

• variable: Variable ID or label for selected-edge update.
• factor: Factor index or label for selected-edge update.

Returns

The updated edge ID, or nothing when the scheduled pass is complete.

Notes

Without an explicit edge, the next edge in the backward schedule is updated and the step cursor is advanced. Returns the updated edge ID, or nothing when the backward pass is complete.

A backward pass sends messages from the selected root toward the leaves.

When schedule is omitted, the tree's default step cursor is advanced. Use reset! on the tree before reusing that cursor.

Passing an edge ID, or selecting an edge by variable and factor, updates only that selected backward message and does not advance any cursor.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
tree = treeFactorGraph(graph; root = :x1)
inference = moment(graph)

schedule = forwardBackwardSchedule(tree)
backwardStep!(tree, inference, schedule)

forward!(
    tree::TreeFactorGraph, inference::AbstractInference, schedule::ForwardBackwardSchedule
)

Run forward tree message updates until the forward pass is complete.

Arguments

• tree: Tree factor graph.
• inference: Matching inference object.
• schedule: Optional forward/backward schedule.

Returns

The schedule after it has advanced past the final forward edge.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
tree = treeFactorGraph(graph; root = :x1)
inference = moment(graph)

schedule = forwardBackwardSchedule(tree)
forward!(tree, inference, schedule)

backward!(
    tree::TreeFactorGraph, inference::AbstractInference, schedule::ForwardBackwardSchedule
)

Run backward tree message updates until the backward pass is complete.

Arguments

• tree: Tree factor graph.
• inference: Matching inference object.
• schedule: Optional forward/backward schedule.

Returns

The schedule after it has advanced past the final backward edge.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
tree = treeFactorGraph(graph; root = :x1)
inference = moment(graph)

schedule = forwardBackwardSchedule(tree)
backward!(tree, inference, schedule)

forwardBackward!(
    tree::TreeFactorGraph, inference::AbstractInference, schedule::ForwardBackwardSchedule
)

Run a complete forward pass followed by a complete backward pass.

Arguments

• tree: Tree factor graph.
• inference: Matching inference object.
• schedule: Optional forward/backward schedule.

Returns

The schedule after both passes complete.

Notes

On a valid Gaussian tree factor graph, this computes exact marginals in one forward/backward sweep for moment and canonical inference. For Gaussian min-sum inference, the same API computes MAP estimates instead.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
tree = treeFactorGraph(graph; root = :x1)
inference = moment(graph)

schedule = forwardBackwardSchedule(tree)
forwardBackward!(tree, inference, schedule)

marginals(inference::AbstractSumProductInference)

Return the current marginals stored in a sum-product inference object.

marginal(
    graph::AbstractFactorGraph, inference::AbstractSumProductInference,
    variable::VariableRef
)

Validate and return the current marginal for one variable.

estimates(graph::AbstractFactorGraph, inference::AbstractMinSumInference)

Validate and return all stored MAP estimates from a min-sum inference object.

estimate(
    graph::AbstractFactorGraph, inference::AbstractMinSumInference,
    variable::VariableRef
)

Validate and return the stored MAP estimate for one variable.

marginalMean(
    graph::GaussianFactorGraph, inference::GaussianSumProductInference,
    variable::VariableRef
)

Return the current marginal mean for one variable.

Arguments

• graph: Gaussian factor graph or tree view.
• inference: Matching moment or canonical inference object.
• variable: Variable ID or label.

Returns

The marginal mean vector.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

marginalMean(graph, inference, :x1)

marginalCovariance(
    graph::GaussianFactorGraph, inference::GaussianSumProductInference,
    variable::VariableRef
)

Return the current marginal covariance for one variable.

Arguments

• graph: Gaussian factor graph or tree view.
• inference: Matching moment or canonical inference object.
• variable: Variable ID or label.

Returns

The marginal covariance matrix.

Example

x1 = GaussianVariable(:x1, 1)
f1 = GaussianFactor(:x1, 0.0, 1.0, 0.1; label = "f1")

graph = factorGraph([x1], [f1])
inference = moment(graph)

marginalCovariance(graph, inference, :x1)

marginalProbability(
    graph::DiscreteFactorGraph, inference::DiscreteSumProductInference,
    variableRef::VariableRef, state::StateRef
)

Return the stored marginal probability for one variable state.