Validation API

maxVariableMessageChange(
    graph::AbstractFactorGraph, current::AbstractInference, reference::Vector
)

Return the largest variable-to-factor message change from a previous message snapshot.

Arguments

• graph: Factor graph or tree view.
• current: Current inference object.
• reference: Previous current.variableToFactor snapshot.

Returns

The maximum message change.

Notes

The snapshot type must match current: Vector{GaussianMessage} for moment inference, Vector{CanonicalMessage} for canonical inference, Vector{QuadraticMessage} for Gaussian min-sum inference, and Vector{Vector{Float64}} for discrete inference.

Example

oldMessages = deepcopy(inference.variableToFactor)
messages!(graph, inference)

maxVariableMessageChange(graph, inference, oldMessages)

maxFactorMessageChange(
    graph::AbstractFactorGraph, current::AbstractInference, reference::Vector
)

Return the largest factor-to-variable message change from a previous message snapshot.

Arguments

• graph: Factor graph or tree view.
• current: Current inference object.
• reference: Previous current.factorToVariable snapshot.

Returns

The maximum message change.

Notes

The snapshot type must match current: Vector{GaussianMessage} for moment inference, Vector{CanonicalMessage} for canonical inference, Vector{QuadraticMessage} for Gaussian min-sum inference, and Vector{Vector{Float64}} for discrete inference.

Example

oldMessages = deepcopy(inference.factorToVariable)
messages!(graph, inference)

maxFactorMessageChange(graph, inference, oldMessages)

maxMessageChange(
    graph::AbstractFactorGraph, current::AbstractInference,
    referenceVariableToFactor::Vector, referenceFactorToVariable::Vector
)
maxMessageChange(
    graph::AbstractFactorGraph, current::AbstractInference, reference::AbstractInference
)

Return the largest message change from previous message snapshots or an inference state.

Arguments

• graph: Factor graph or tree view.
• current: Current inference object.
• referenceVariableToFactor: Previous variable-to-factor message snapshot.
• referenceFactorToVariable: Previous factor-to-variable message snapshot.
• reference: Previous inference object.

Returns

The maximum message change across both message directions.

Notes

The current inference object must match graph. For moment-form inference this compares message means and covariances. For canonical-form inference this compares information vectors and precision matrices. Both variable-to-factor and factor-to-variable messages are included.

Snapshot arguments must match the message storage type used by current: Vector{GaussianMessage} for moment inference, Vector{CanonicalMessage} for canonical inference, Vector{QuadraticMessage} for Gaussian min-sum inference, and Vector{Vector{Float64}} for discrete inference.

This is useful for custom convergence loops. Prefer passing previous variableToFactor and factorToVariable message snapshots to avoid copying an entire inference object.

Example

oldVarMessages = deepcopy(inference.variableToFactor)
oldFacMessages = deepcopy(inference.factorToVariable)
messages!(graph, inference)

maxMessageChange(graph, inference, oldVarMessages, oldFacMessages)

maxMarginalChange(
    graph::AbstractFactorGraph, current::AbstractInference, referenceMarginal::Vector
)
maxMarginalChange(
    graph::AbstractFactorGraph, current::AbstractInference, reference::AbstractInference
)

Return the largest marginal change from previous marginals or an inference state.

Arguments

• graph: Factor graph or tree view.
• current: Current inference object.
• referenceMarginal: Previous marginal snapshot.
• reference: Previous inference object.

Returns

The maximum marginal change.

Notes

The current inference object must match graph. The comparison uses marginal means and covariance matrices for moment and canonical inference states, and probability vectors for sum-product inference.

Example

oldMarginals = deepcopy(inference.marginal)
gbp!(graph, inference; iterations = 1)

maxMarginalChange(graph, inference, oldMarginals)

maxEstimateChange(
    graph::AbstractFactorGraph, inference::AbstractMinSumInference,
    previous::Union{Vector, AbstractMinSumInference}
)

Return the largest change between current and previous MAP estimates.

Arguments

• graph: Matching factor graph or tree view.
• inference: Current Gaussian or discrete min-sum inference object.
• previous: Previous estimate snapshot or previous matching min-sum inference object.

Returns

For Gaussian min-sum, the largest Euclidean change between corresponding numeric MAP estimate vectors. For discrete min-sum, 0.0 if all MAP state references match, otherwise 1.0.

Example

oldEstimates = deepcopy(inference.estimate)
gbp!(graph, inference; iterations = 1)

maxEstimateChange(graph, inference, oldEstimates)

residuals(
    graph::Union{GaussianFactorGraph, TreeFactorGraph{GaussianFactorGraph}},
    inference::GaussianSumProductInference
)

Return one residual vector per Gaussian factor using the current marginal means.

Arguments

• graph: Gaussian factor graph or tree view.
• inference: Matching Gaussian inference object with stored marginal means.

Returns

A vector of named tuples with factor, index, and value fields.

Notes

For each Gaussian factor this computes GaussianFactor.mean - GaussianFactor.coefficient * x, where x is the stacked vector of current marginal means for the variables connected to that factor.

Example

inference = moment(graph)
gbp!(graph, inference)

residuals(graph, inference)

normalizedResiduals(
    graph::Union{GaussianFactorGraph, TreeFactorGraph{GaussianFactorGraph}},
    inference::GaussianSumProductInference
)

Return residuals scaled by each Gaussian factor component's standard deviation.

Arguments

• graph: Gaussian factor graph or tree view.
• inference: Matching Gaussian inference object with stored marginal means.

Returns

A vector of named tuples with factor, index, and normalized value fields.

Notes

This uses the diagonal entries of the Gaussian factor covariance matrix, so each component is computed as residual / sqrt(covariance_component). The return format matches residuals.

Example

inference = moment(graph)
gbp!(graph, inference)

normalizedResiduals(graph, inference)

solveWLS(graph::Union{GaussianFactorGraph, TreeFactorGraph{GaussianFactorGraph}})

Solve the equivalent centralized weighted least-squares problem.

Arguments

• graph: Gaussian factor graph or tree view.

Returns

A WeightedLeastSquaresResult.

Notes

This is useful as a reference solution for Gaussian belief propagation. The solver assembles the global normal equations from all factors and returns a WeightedLeastSquaresResult. An error is thrown if the normal matrix is not positive definite, which usually means the model is unobservable or insufficiently constrained.

Example

result = solveWLS(graph)

compareMeanWithWLS(
    graph::Union{GaussianFactorGraph, TreeFactorGraph{GaussianFactorGraph}},
    inference::GaussianSumProductInference, result::WeightedLeastSquaresResult
)

Print per-Gaussian-variable mean differences between Gaussian belief propagation marginals and WLS.

Arguments

• graph: Gaussian factor graph or tree view.
• inference: Matching Gaussian inference object.
• result: Weighted least-squares result.

Notes

Use maxMeanError when a numeric error value is needed instead of formatted output.

Example

inference = moment(graph)
gbp!(graph, inference)

result = solveWLS(graph)
compareMeanWithWLS(graph, inference, result)

maxMeanError(
    graph::Union{GaussianFactorGraph, TreeFactorGraph{GaussianFactorGraph}},
    inference::GaussianSumProductInference, result::WeightedLeastSquaresResult
)

Return the maximum norm of per-Gaussian-variable mean errors against WLS.

Arguments

• graph: Gaussian factor graph or tree view.
• inference: Matching Gaussian inference object.
• result: Weighted least-squares result.

Returns

The maximum Euclidean mean error across variables.

Notes

The returned scalar is maximum(norm(gbpMean - wlsMean)) across all variables.

Example

inference = moment(graph)
gbp!(graph, inference)

result = solveWLS(graph)
maxMeanError(graph, inference, result)

compareCovarianceWithWLS(
    graph::Union{GaussianFactorGraph, TreeFactorGraph{GaussianFactorGraph}},
    inference::GaussianSumProductInference, result::WeightedLeastSquaresResult
)

Print per-Gaussian-variable covariance differences between Gaussian belief propagation marginals and WLS.

Arguments

• graph: Gaussian factor graph or tree view.
• inference: Matching Gaussian inference object.
• result: Weighted least-squares result.

Notes

Use maxCovarianceError when a numeric error value is needed.

Example

inference = moment(graph)
gbp!(graph, inference)

result = solveWLS(graph)
compareCovarianceWithWLS(graph, inference, result)

maxCovarianceError(
    graph::Union{GaussianFactorGraph, TreeFactorGraph{GaussianFactorGraph}},
    inference::GaussianSumProductInference, result::WeightedLeastSquaresResult
)

Return the maximum norm of per-Gaussian-variable covariance errors against WLS.

Arguments

• graph: Gaussian factor graph or tree view.
• inference: Matching Gaussian inference object.
• result: Weighted least-squares result.

Returns

The maximum covariance-matrix norm error across variables.

Notes

The returned scalar is maximum(norm(gbpCovariance - wlsCovariance)) across all variables.

Example

inference = moment(graph)
gbp!(graph, inference)

result = solveWLS(graph)
maxCovarianceError(graph, inference, result)