Types

AbstractFactorGraph

Abstract supertype for factor graph models and tree views.

Notes

GaussianFactorGraph and DiscreteFactorGraph represent factor graph models, while TreeFactorGraph represents a tree view over an existing factor graph.

TreeFactorGraph{G <: AbstractFactorGraph}

Tree view over an existing factor graph.

TreeFactorGraph wraps a Gaussian or discrete factor graph and stores the tree root, parent-edge orientation, and traversal orders. It shares the underlying graph and does not copy variables, factors, edges, or messages.

Fields

• graph: Wrapped Gaussian or discrete factor graph.
• rootVariableIndex: Internal root variable index.
• variableParentEdge: Parent edge for each variable node.
• factorParentEdge: Parent edge for each factor node.
• forwardOrder: Leaf-to-root edge traversal order.
• backwardOrder: Root-to-leaf edge traversal order.
• forwardIndex: Internal cursor used by forwardStep!.
• backwardIndex: Internal cursor used by backwardStep!.

Notes

The type parameter G is the wrapped graph type. For example, TreeFactorGraph{DiscreteFactorGraph} is a tree view over a DiscreteFactorGraph.

Most fields are internal and should not be modified directly. Construct tree views with treeFactorGraph.

Example

x1 = GaussianVariable(:x1, 1)
x2 = GaussianVariable(:x2, 1)

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

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

Edge

Graph edge connecting one factor node to one variable node.

Each Edge represents one factor-variable incidence relation in a factor graph.

GaussianVariable(
    id::VariableId, dimension::Int;
    label = string(id), components = 1:dimension, mean = nothing, covariance = nothing
)

Create a Gaussian variable node.

Arguments

• id: Symbolic or integer ID used by factors.
• dimension: Dimension of the continuous state vector.

Keywords

• label: Human-readable label that can also be used for lookup.
• components: References for entries of the continuous state vector.
• mean: Optional initial mean used by Gaussian inference.
• covariance: Optional initial covariance used by Gaussian inference.

Notes

If label is omitted, the variable ID is converted to a default label with string(id). For example, :x_1 becomes "x_1". Explicit labels are kept unchanged.

If mean and covariance are provided, they define the initial belief used when a Gaussian inference object is created. If they are omitted, moment, canonical, and Gaussian minsum use their own default initial-belief arguments instead.

The initial belief is used only to initialize Gaussian belief propagation messages. Scalar values are accepted for one-dimensional variables.

Example

x1 = GaussianVariable(:x1, 1; label = "x1", mean = 0.0, covariance = 1.0)
x2 = GaussianVariable(:x2, 2; mean = [0.0, 0.0], covariance = [1.0, 1.0])
x3 = GaussianVariable(:x3, 2; label = "x3", components = [:position, :velocity])

GaussianFactor(
    variable::Union{VariableRef, GaussianVariable}..., mean, coefficient, covariance;
    label = "", initialize = false
)

Create a linear Gaussian factor node.

Arguments

• variable...: Connected variable references or Gaussian variable nodes.
• mean: Observed or target value.
• coefficient: Linear coefficient matrix.
• covariance: Measurement or factor covariance.

Keywords

• label: Human-readable label. If omitted inside a graph, a label is assigned.
• initialize: Whether a unary factor initializes the connected variable belief.

Notes

GaussianFactor represents a linear Gaussian relation mean = coefficient * x + noise, where mean is the observed or target value and covariance is the noise covariance.

The constructor takes one or more Gaussian variable references or nodes followed by mean, coefficient, and covariance. The length of mean defines the factor dimension. The columns of coefficient are ordered by concatenating the connected variable state vectors in the same order as variable....

Scalar means, scalar coefficients, and one-element coefficient vectors are accepted for one-dimensional factors. Higher-dimensional factors must use a matrix coefficient. A scalar covariance is expanded to an isotropic covariance matrix matching the factor mean dimension.

If initialize = true, the factor must be unary. Its Gaussian information is used as the initial belief for the connected variable when a Gaussian inference object is created or extended.

Example

x1 = GaussianVariable(:x1, 1)
x2 = GaussianVariable(:x2, 1)

f1 = GaussianFactor(:x1, 0.25, 1.0, 0.15; label = "f1", initialize = true)
f2 = GaussianFactor(x1, x2, [0.4, -0.2], [1.0 0.5; -0.4 1.2], [0.3, 0.25])

GaussianFactorGraph(
    variables::AbstractVector{GaussianVariable}, factors::AbstractVector{GaussianFactor}
)
GaussianFactorGraph()

Construct a Gaussian factor graph from variables and factors, or create an empty graph.

Arguments

• variables: Gaussian variable nodes.
• factors: Gaussian factor nodes.

Fields

• variables: Gaussian variable nodes in internal order.
• factors: Gaussian factor nodes in internal order.
• referenceIndex: Lookup from variable IDs and labels to internal indices.
• edges: Factor-variable edges.
• factorEdges: Edge IDs adjacent to each factor.
• variableEdges: Edge IDs adjacent to each variable.
• topologyVersion: Counter used to detect stale inference states.

Notes

The graph stores the factor-variable topology, edge list, and adjacency lists used by Gaussian message passing. Variables and factors may be added incrementally with addVariable! and addFactor!. Existing Gaussian factor means, coefficients, and covariances may be updated with updateFactor!.

Example

x1 = GaussianVariable(:x1, 1)
x2 = GaussianVariable(:x2, 1)

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

graph = GaussianFactorGraph([x1, x2], [f1, f2])

DiscreteVariable(
    id::VariableId, cardinality::Int;
    label = string(id), states = 1:cardinality, probability = nothing
)

Create a discrete variable node.

Arguments

• id: Symbolic or integer ID used by factors.
• cardinality: Number of states.

Keywords

• label: Human-readable label that can also be used for lookup.
• states: State references for entries of the finite state set.
• probability: Optional initial probability vector.

Notes

If label is omitted, the variable ID is converted to a default label with string(id). For example, :x_1 becomes "x_1". Explicit labels are kept unchanged.

The state order defines the corresponding dimension order in connected factor tables.

If probability is provided, it defines the variable's initial belief for future discrete inference objects. A unary DiscreteFactor with initialize = true can override this initial belief for the connected variable. The initial belief is used only to initialize belief-propagation messages. It is not a replacement for a unary factor when the prior should be part of the model. If probability is omitted, sumproduct uses a uniform initial message and minsum uses the corresponding uniform initial cost.

Example

x1 = DiscreteVariable(:x1, 2; label = "x1")
x2 = DiscreteVariable(:x2, 2; states = [:off, :on], probability = [0.8, 0.2])

DiscreteFactor(
    variable::Union{VariableRef, DiscreteVariable}..., table;
    label = "", initialize = false
)

Create a discrete factor node.

Arguments

• variable...: Connected variable references or discrete variable nodes.
• table: Nonnegative factor table.

Keywords

• label: Human-readable label. If omitted inside a graph, a label is assigned.
• initialize: Whether a unary factor initializes the connected variable belief.

Notes

The table stores a nonnegative potential over the connected variables in the same order as variables. The table does not need to be normalized. Its dimensions are validated against the connected variable cardinalities when the factor is added to a DiscreteFactorGraph.

If initialize = true, the factor must be unary. Its table is used as the initial belief for the connected variable when a compatible discrete inference object is created or extended.

Example

x1 = DiscreteVariable(:x1, 2; label = "x1")
x2 = DiscreteVariable(:x2, 2; label = "x2")

f1 = DiscreteFactor(x1, [0.8, 0.2]; label = "f1", initialize = true)
f2 = DiscreteFactor(x1, x2, [0.9 0.1; 0.2 0.8]; label = "f2")

DiscreteFactorGraph(
    variables::AbstractVector{DiscreteVariable}, factors::AbstractVector{DiscreteFactor}
)
DiscreteFactorGraph()

Construct a discrete factor graph from variables and factors, or create an empty graph.

Arguments

• variables: Discrete variable nodes.
• factors: Discrete factor nodes.

Fields

• variables: Discrete variable nodes in internal order.
• factors: Discrete factor nodes in internal order.
• referenceIndex: Lookup from variable IDs and labels to internal indices.
• edges: Factor-variable edges.
• factorEdges: Edge IDs adjacent to each factor.
• variableEdges: Edge IDs adjacent to each variable.
• topologyVersion: Counter used to detect stale inference states.

Notes

The graph stores the factor-variable topology, edge list, and adjacency lists used by discrete message passing. Variables and factors may be added incrementally with addVariable! and addFactor!. Existing discrete factor tables may be updated with updateFactor!.

Example

x1 = DiscreteVariable(:x1, 2; label = "x1", states = [:off, :on])
f1 = DiscreteFactor(:x1, [0.8, 0.2]; label = "f1")

graph = DiscreteFactorGraph([x1], [f1])

AbstractInference

Abstract supertype for belief-propagation inference states.

Notes

GaussianInference and DiscreteInference are subtypes of AbstractInference. Concrete inference states store algorithm-specific messages, results, update-control flags, and the graph topology version they were built for.

AbstractSumProductInference

Union alias for sum-product belief-propagation inference states.

Notes

AbstractSumProductInference includes GaussianSumProductInference and DiscreteSumProductInference. It is a union alias rather than an abstract supertype because Julia types have a single immediate supertype, and DiscreteSumProductInference already belongs to the DiscreteInference hierarchy.

AbstractMinSumInference

Union alias for min-sum belief-propagation inference states.

Notes

AbstractMinSumInference includes GaussianMinSumInference and DiscreteMinSumInference. Gaussian min-sum stores numeric MAP estimate vectors, while discrete min-sum stores MAP state references.

GaussianInference

Abstract supertype for Gaussian belief-propagation inference states.

Notes

GaussianMomentInference, GaussianCanonicalInference, and GaussianMinSumInference are subtypes of GaussianInference, so APIs that work with any Gaussian inference state can dispatch on this type.

GaussianSumProductInference

Abstract supertype for Gaussian sum-product inference states.

Notes

GaussianMomentInference and GaussianCanonicalInference are subtypes of GaussianSumProductInference. Gaussian min-sum inference is not a sum-product inference state because it stores MAP estimates instead of marginals.

GaussianMomentInference

Inference state for moment-form Gaussian belief propagation.

Fields

• initial: Initial variable beliefs.
• variableToFactor: Variable-to-factor messages.
• factorToVariable: Factor-to-variable messages.
• marginal: Stored variable marginals.
• nextVariableToFactor: Flooding buffer for variable-to-factor messages.
• nextFactorToVariable: Flooding buffer for factor-to-variable messages.
• frozenEdges: Edge freeze flags.
• frozenVariables: Variable freeze flags.
• frozenFactors: Factor freeze flags.
• dampedEdges: Edge damping flags.
• edgeDampingProb: Per-edge damping probabilities.
• edgeDampingAlpha: Per-edge damping mixing weights.
• defaultMean: Default mean used for warm-start variable additions.
• defaultCovariance: Default covariance used for warm-start variable additions.
• graphVersion: Topology version used to detect stale inference states.

Notes

Moment form stores Gaussian messages directly as means and covariances, with precision and information cached for efficient multiplication of messages. Create instances with moment.

Example

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

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

GaussianCanonicalInference

Inference state for canonical-form Gaussian belief propagation.

Fields

• initial: Initial variable beliefs.
• variableToFactor: Variable-to-factor canonical messages.
• factorToVariable: Factor-to-variable canonical messages.
• marginal: Stored canonical marginals.
• nextVariableToFactor: Flooding buffer for variable-to-factor messages.
• nextFactorToVariable: Flooding buffer for factor-to-variable messages.
• frozenEdges: Edge freeze flags.
• frozenVariables: Variable freeze flags.
• frozenFactors: Factor freeze flags.
• dampedEdges: Edge damping flags.
• edgeDampingProb: Per-edge damping probabilities.
• edgeDampingAlpha: Per-edge damping mixing weights.
• defaultMean: Default mean used for warm-start variable additions.
• defaultCovariance: Default covariance used for warm-start variable additions.
• graphVersion: Topology version used to detect stale inference states.

Notes

Canonical form represents Gaussian messages as information vectors and precision matrices. It is often convenient for algebraic message products. Create instances with canonical.

Example

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

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

GaussianMinSumInference

Inference state for Gaussian min-sum belief propagation.

Fields

• variableToFactor: Variable-to-factor quadratic messages.
• factorToVariable: Factor-to-variable quadratic messages.
• estimate: Stored MAP estimates.
• nextVariableToFactor: Flooding buffer for variable-to-factor messages.
• nextFactorToVariable: Flooding buffer for factor-to-variable messages.
• frozenEdges: Edge freeze flags.
• frozenVariables: Variable freeze flags.
• frozenFactors: Factor freeze flags.
• dampedEdges: Edge damping flags.
• edgeDampingProb: Per-edge damping probabilities.
• edgeDampingAlpha: Per-edge damping mixing weights.
• defaultMean: Default mean used for warm-start variable additions.
• defaultCovariance: Default covariance used for warm-start variable additions.
• graphVersion: Topology version used to detect stale inference states.

Notes

Gaussian min-sum is the negative-log MAP form of Gaussian max-product belief propagation. It stores quadratic cost messages and MAP estimates, not marginal variances. Create instances with minsum.

Example

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

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

QuadraticMessage

Quadratic message used by Gaussian min-sum belief propagation.

Fields

• J: Quadratic precision matrix.
• h: Linear information vector.
• c: Constant offset.

Notes

The message stores a quadratic cost over one variable. J controls curvature, h controls the linear term, and c stores a constant offset that shifts the cost without changing the minimizing value.

Example

message = QuadraticMessage([1.0;;], [0.0], 0.0)

DiscreteInference

Abstract supertype for discrete belief-propagation inference states.

Notes

DiscreteSumProductInference and DiscreteMinSumInference are subtypes of DiscreteInference, so APIs that work with any discrete inference state can dispatch on this type.

DiscreteSumProductInference

Inference state for sum-product discrete belief propagation.

Fields

• initial: Initial variable messages.
• variableToFactor: Variable-to-factor probability messages.
• factorToVariable: Factor-to-variable probability messages.
• marginal: Stored variable marginals.
• nextVariableToFactor: Flooding buffer for variable-to-factor messages.
• nextFactorToVariable: Flooding buffer for factor-to-variable messages.
• frozenEdges: Edge freeze flags.
• frozenVariables: Variable freeze flags.
• frozenFactors: Factor freeze flags.
• dampedEdges: Edge damping flags.
• edgeDampingProb: Per-edge damping probabilities.
• edgeDampingAlpha: Per-edge damping mixing weights.
• graphVersion: Topology version used to detect stale inference states.

Notes

Stores variable-to-factor and factor-to-variable probability messages, marginals, and update-control flags. Create instances with sumproduct.

Example

x1 = DiscreteVariable(:x1, 2; states = [:off, :on])
f1 = DiscreteFactor(:x1, [0.8, 0.2]; label = "f1")

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

DiscreteMinSumInference

Inference state for discrete min-sum MAP belief propagation.

Fields

• initial: Initial variable cost messages.
• variableToFactor: Variable-to-factor cost messages.
• factorToVariable: Factor-to-variable cost messages.
• estimate: Stored MAP state estimates.
• nextVariableToFactor: Flooding buffer for variable-to-factor messages.
• nextFactorToVariable: Flooding buffer for factor-to-variable messages.
• frozenEdges: Edge freeze flags.
• frozenVariables: Variable freeze flags.
• frozenFactors: Factor freeze flags.
• dampedEdges: Edge damping flags.
• edgeDampingProb: Per-edge damping probabilities.
• edgeDampingAlpha: Per-edge damping mixing weights.
• graphVersion: Topology version used to detect stale inference states.

Notes

Stores variable-to-factor and factor-to-variable cost messages, MAP estimates, and update-control flags. Create instances with minsum.

Example

x1 = DiscreteVariable(:x1, 2; states = [:off, :on])
f1 = DiscreteFactor(:x1, [0.8, 0.2]; label = "f1")

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

SequentialSchedule

Stateless sequential message schedule.

Notes

Use sequentialSchedule to create one for low-level messages! calls.

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

Stateless flooding message schedule.

Notes

Use floodingSchedule to create one for low-level messages! calls.

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

Mutable schedule state for residual belief propagation.

Fields

• edgeIds: Candidate edge IDs.
• directions: Candidate directions; true is factor-to-variable.
• residuals: Current candidate residual values.
• updateFraction: Fraction used when updateCount is omitted.
• updateCount: Optional fixed number of candidates to update.
• lastUpdated: Candidate indices updated by the most recent step.

Notes

Use messages! with schedule = :residual for one residual-scheduled step, or use gbp! with schedule = :residual for a complete iterative loop. Create a ResidualSchedule explicitly when you want to inspect or reuse the selected low-level schedule object.

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; schedule = :residual, updateFraction = 0.25)

ForwardBackwardSchedule

Mutable cursor used by forward/backward tree inference.

Fields

• forwardIndex: Next position in the forward edge order.
• backwardIndex: Next position in the backward edge order.

Notes

Use reset! to restart a schedule or a tree's default step cursor.

The schedule stores the next edge position for the forward pass and the next edge position for the backward pass. It lets callers step through tree inference manually with forwardStep! and backwardStep!.

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)

VariableId

Accepted variable identifiers: Int or Symbol.

Notes

Use an ID when you want a compact programmatic reference to a variable, for example :x1 or 1.

VariableRef

Accepted variable references: Int, Symbol, or String.

Notes

Symbols and integer IDs reference variable IDs; strings reference variable labels. Most public functions accept either form, so both :x1 and "x1" can refer to the same variable when its ID is :x1 and its label is "x1".

FactorRef

Accepted factor references: Int, Symbol, or String.

Notes

Integer references select factor indices. Symbols and strings reference factor labels, so both :f1 and "f1" can refer to the same factor when its label is "f1".

StateRef

Accepted discrete state references: Int, Symbol, or String.

Notes

State references are local to a DiscreteVariable. They define the order used by factor table dimensions.

ComponentRef

Accepted Gaussian component references: Int, Symbol, or String.

Notes

Component references are local to a GaussianVariable. They name the entries of the variable's continuous state vector.

WeightedLeastSquaresResult

Weighted least-squares solution returned by solveWLS.

Fields

• mean: Full stacked state mean.
• covariance: Full stacked state covariance.
• variableMean: Per-variable mean blocks.
• variableCovariance: Per-variable covariance blocks.

Notes

Fields include the full mean and covariance, plus per-Gaussian-variable variableMean and variableCovariance blocks.

The full state is ordered in the same order as graph.variables. Per-Gaussian-variable blocks make it easier to compare WLS with Gaussian belief propagation marginals.

Example

result = solveWLS(graph)