DistributedFactorGraphs Types

DistributedFactorGraphs.jl provides a flexible factor graph API for use in the Caesar.jl ecosystem.

The package supplies:

• A standardized API for interacting with factor graphs
• Implementations of the API for in-memory and database-driven operation
• Visualization extensions to validate the underlying graph

abstract type AbstractDFG{V<:AbstractGraphVariable, F<:AbstractGraphFactor}

Abstract parent struct for a DFG graph.

abstract type AbstractDFGParams

Abstract parent struct for solver parameters.

abstract type AbstractGraphFactor <: AbstractGraphNode

An abstract DFG factor.

abstract type AbstractGraphNode

Abstract parent struct for DFG variables and factors.

abstract type AbstractGraphVariable <: AbstractGraphNode

An abstract DFG variable.

struct NoSolverParams <: AbstractDFGParams

Empty structure for solver parameters.

getDescription(node)

getLabel(node)

Get the label of the node.

getTimestamp(node)

Get the timestamp of a AbstractGraphNode.

isValidLabel(label)

Returns true if the label is valid for node.

struct VariableDFG{T<:AbstractStateType, P} <: AbstractGraphVariable

Complete variable structure for a DistributedFactorGraph variable.

Fields:

• label::Symbol: Variable label, e.g. :x1. Accessor: getLabel

• timestamp::TimesDates.TimeDateZone: Variable event timestamp (UTC-based) with timezone support.

  Note

  This single timestamp does not represent the temporal uncertainty of non-parametric beliefs. A single timestamp value cannot capture the distribution of temporal information across all particles/points in a belief. For problems where time is a state variable requiring inference (e.g., SGal3 which includes temporal components), include time as part of your state type rather than relying on this metadata field.

  Accessors: getTimestamp

• tags::Set{Symbol}: Variable tags, e.g [:POSE, :VARIABLE, and :LANDMARK]. Accessors: listTags, mergeTags!, and deleteTags!

• states::OrderedCollections.OrderedDict{Symbol, State{T, P}} where {T<:AbstractStateType, P}: Dictionary of state data. May be a subset of all solutions if a solver label was specified in the get call. Accessors: addState!, mergeState!, and deleteState!

• bloblets::OrderedCollections.LittleDict{Symbol, Bloblet, KS, VS} where {KS<:Union{Tuple{Vararg{Symbol}}, AbstractVector{Symbol}}, VS<:Union{Tuple{Vararg{Bloblet}}, AbstractVector{Bloblet}}}: Dictionary of small data associated with this variable. Accessors: getBloblet, addBloblet!

• blobentries::OrderedCollections.OrderedDict{Symbol, Blobentry}: Dictionary of large data associated with this variable. Accessors: addBlobentry!, getBlobentry, mergeBlobentry!, and deleteBlobentry!

• solvable::Base.RefValue{Int64}: Solvable flag for the variable. Accessors: getSolvable, setSolvable!

• statekind::AbstractStateType

• _autotype::Nothing

struct VariableSkeleton <: AbstractGraphVariable

Skeleton variable structure for a DistributedFactorGraph variable.

Fields:

• label::Symbol: Variable label, e.g. :x1. Accessor: getLabel

• tags::Set{Symbol}: Variable tags, e.g [:POSE, :VARIABLE, and :LANDMARK]. Accessors: listTags, mergeTags!, and deleteTags!

struct VariableSummary <: AbstractGraphVariable

Summary variable structure for a DistributedFactorGraph variable.

Fields:

• label::Symbol: Variable label, e.g. :x1. Accessor: getLabel

• timestamp::TimesDates.TimeDateZone: Variable event timestamp.

  Note

  This single timestamp does not represent the temporal uncertainty of non-parametric beliefs. A single timestamp value cannot capture the distribution of temporal information across all particles/points in a belief. For problems where time is a state variable requiring inference (e.g., SGal3 which includes temporal components), include time as part of your state type rather than relying on this metadata field.

  Accessors: getTimestamp

• tags::Set{Symbol}: Variable tags, e.g [:POSE, :VARIABLE, and :LANDMARK]. Accessors: listTags, mergeTags!, and deleteTags!

• solvable::Base.RefValue{Int64}: Solvable flag for the variable. Accessors: getSolvable, setSolvable!

• statekind::AbstractStateType: Symbol for the state type for the underlying variable.

patch!(dest, src)

Merge the contents of src into dest by only patching child collections/containers. Notes:

• Cascades into collections (tags, states, blobentries, bloblets).
• Assumes label, timestamp, and statekind are immutable and does not update them.

struct FactorDFG{T<:AbstractObservation, N} <: AbstractGraphFactor

Complete factor structure for a DistributedFactorGraph factor.

Fields:

• label::Symbol: Factor label, e.g. :x1f1. Accessor: getLabel

• tags::Set{Symbol}: Factor tags, e.g [:FACTOR]. Accessors: listTags, mergeTags!, and deleteTags!

• variableorder::NTuple{N, Symbol} where N: Ordered list of the neighbor variables. Accessors: getVariableOrder

• timestamp::TimesDates.TimeDateZone: Variable timestamp. Accessors: getTimestamp

• solvable::Base.RefValue{Int64}: Solvable flag for the factor. Accessors: getSolvable, setSolvable!

• bloblets::OrderedCollections.LittleDict{Symbol, Bloblet, KS, VS} where {KS<:Union{Tuple{Vararg{Symbol}}, AbstractVector{Symbol}}, VS<:Union{Tuple{Vararg{Bloblet}}, AbstractVector{Bloblet}}}: Dictionary of small data associated with this variable. Accessors: getBloblet, addBloblet!

• observation::AbstractObservation: Observation function or measurement for this factor. Accessors: getObservation(@ref)

• hyper::DistributedFactorGraphs.Recipehyper: Hyperparameters associated with this factor.

• state::DistributedFactorGraphs.Recipestate: Describes the current state of the factor. Persisted in serialization.

• solvercache::Base.RefValue{<:AbstractFactorCache}: Temporary, non-persistent memory used internally by the solver for intermediate numerical computations and buffers. solvercache is lazily allocated and only used during factor operations; it is not serialized or retained after solving. Accessors: getCache, setCache!

• blobentries::OrderedCollections.OrderedDict{Symbol, Blobentry}: Blobentries associated with this factor.

• _autotype::Nothing: Internal: used for automatic type metadata generation.

struct FactorSkeleton <: AbstractGraphFactor

Skeleton factor structure for a DistributedFactorGraph factor.

Fields:

• label::Symbol: Factor label, e.g. :x1f1. Accessor: getLabel

• tags::Set{Symbol}: Factor tags, e.g [:FACTOR]. Accessors: listTags, mergeTags!, and deleteTags!

• variableorder::Tuple{Vararg{Symbol}}: Ordered list of the neighbor variables. Accessors: getVariableOrder

struct FactorSummary <: AbstractGraphFactor

Read-only summary factor structure for a DistributedFactorGraph factor.

Fields:

• label::Symbol: Factor label, e.g. :x1f1. Accessor: getLabel

• tags::Set{Symbol}: Factor tags, e.g [:FACTOR]. Accessors: listTags, mergeTags!, and deleteTags!

• variableorder::Tuple{Vararg{Symbol}}: Ordered list of the neighbor variables. Accessors: getVariableOrder

• timestamp::TimesDates.TimeDateZone: Variable timestamp. Accessors: getTimestamp

• solvable::Base.RefValue{Int64}: Solvable flag for the factor. Accessors: getSolvable, setSolvable!

patch!(dest, src)

Merge the contents of src into dest by only patching child collections/containers. Notes:

• Cascades into collections (tags, blobentries, bloblets).
• Assumes label, timestamp, and statekind are immutable and does not update them.
• Throws MergeConflictError when factor types differ (different observation or arity).

AbstractHomotopyTopology

Describes the physical layout of the nodes within a StoredHomotopyBelief.

Since all beliefs in the Caesar ecosystem are fundamentally Homotopy densities, this trait acts as a lightweight dispatch hint (a "Lens Selector"). It indicates which parts of the tree (Roots vs. Leaves) are currently populated and how they are wired, without requiring downstream packages to inspect the underlying vectors.

Role of the Topology Trait:

• DFG: Determines how to serialize and spatial-index the belief in the database.
• Visualizers: Decides how to render the data (e.g., drawing ellipses for roots vs. a point cloud for leaves).
• IIF/AMP: Selects the correct mathematical view to construct (e.g., MvNormal vs. ManifoldKernelDensity vs. a full HomotopyDensity).

Extending: If the standard tree-based Homotopy model does not fit your specific data layout or solver requirements, you are encouraged to extend this abstract type with your own custom topology struct. Alternatively, if you believe your use case represents a missing core layout, please open an issue to discuss adding it to the foundational ecosystem.

Full tree using adjacency lists. (Schema: L1, L2, and Parent arrays fully populated.)

Tree packed in arrays using 2i, 2i+1 math.(Schema: L1 and L2 populated. Parent arrays empty.)

L2 raw samples only. No L1 structure. (Schema: points, bandwidths populated. means empty.)

L1 structural nodes only. No L2 samples. (Schema: means, weights, shapes populated. points empty.)

mutable struct State{T<:AbstractStateType, P}

Data container for solver-specific data.

T: Variable type, such as Position1, or RoME.Pose2, etc. P: Variable point type, the type of the manifold point. Fields:

• label::Symbol: Identifier associated with this State object.

• statekind::AbstractStateType: Singleton type for the state, eg. Pose{3}(), Position{2}(), etc. Used for dispatch and serialization.

• belief::DistributedFactorGraphs.StoredHomotopyBelief: Generic stored belief for this state.

• separator::Vector{Symbol}: List of symbols for separator variables for this state, used in variable elimination and inference computations.

• initialized::Bool: False if initial numerical values are not yet available or stored values are not ready for further processing yet.

• observability::Vector{Float64}: Stores the amount of information captured in each coordinate dimension.

• marginalized::Bool: Should this state be treated as marginalized in inference computations.

• solves::Int64: How many times has a solver updated this state estimate.

StoredHomotopyBelief{T <: StateType, P}

A multi-resolution "Grove of Trees" representing a manifold belief. Each tree can be as deep (ExplicitTreeTopology) or as shallow (RootsOnlyTopology) as the evidence requires, but they all speak the same language of Nodes and Parents.

These are the internal raw beliefs and need to be viewed through a lens such as provided by AMP for features like pdf evaluation. Organized into structural Tree/Branch layers (L1) and empirical Leaf layers (L2).

@defStateType StructName manifold point_identity

A macro to create a new variable type with name StructName associated with a given manifold and identity point.

• StructName is the name of the new variable type, which will be defined as a subtype of StateType.
• manifold is an object that must be a subtype of ManifoldsBase.AbstractManifold.
• point_identity is the identity point on the manifold, used as a reference for operations.

This macro is useful for defining variable types that are not parameterized by dimension, and for associating them with a specific manifold and identity point.

See the Manifolds.jl documentation on creating your own manifolds for more information.

Example:

DFG.@defStateType Pose2 SpecialEuclideanGroup(2) ArrayPartition([0;0.0],[1 0; 0 1.0])

@defStateTypeN StructName manifold point_identity

A macro to create a new variable type with name StructName that is parameterized by N and associated with a given manifold and identity point.

• StructName is the name of the new variable type, which will be defined as a subtype of StateType{N}.
• manifold is an object that must be a subtype of ManifoldsBase.AbstractManifold.
• point_identity is the identity point on the manifold, used as a reference for operations.

This macro is useful for defining variable types that are parameterized by dimension or other type parameters (e.g., Pose{N}), and for associating them with a specific manifold and identity point.

See the Manifolds.jl documentation on creating your own manifolds for more information.

Example:

DFG.@defStateTypeN Pose{N} SpecialEuclideanGroup(N) ArrayPartition(zeros(SVector{N, Float64}), SMatrix{N, N, Float64}(I))

deleteTags!(node, tags)

Remove the tags from the node (setdiff)

emptyTags!(node)

Empty all tags from the node (empty)

hasTags(node, tags)

Determine if the variable or factor neighbors have the tags::Vector{Symbol}`.

listTags(node)

mergeTags!(node, tags)

Merge add tags to a variable or factor (union)

IdExistsError(Id)

Error thrown when attempting to add an Id that already exists in the collection.

IdNotFoundError(Id, available)

Error thrown when a requested Id is not found.

LabelExistsError(label)

Error thrown when attempting to add a label that already exists in the collection.

LabelNotFoundError(label, available)

Error thrown when a requested label is not found in the factor graph.

LinkConstraintError(msg)

Error thrown when an operation violates a structural dependency, e.g., deleting a graph that is still in use by a model.

MergeConflictError(msg)

Error thrown when a merge conflict occurs.

SerializationError(msg)

Error thrown when serialization or deserialization fails.

Plots the structure of the factor graph. GraphMakie must be imported before DistributedFactorGraphs for these functions to be available. Returns the plot context.

E.g.

using GraphMakie
using DistributedFactorGraphs
# ... Make graph...
plotDFG(fg)

More information at GraphMakie.jl

An in-memory DistributedFactorGraph based on Graphs.jl with parameters:

• T: Solver parameters (defaults to NoSolverParams())
• V: Variable type
• F: Factor type

savedot_attributes(io, dfg)

A replacement for to_dot that saves only hardcoded factor graph plotting attributes.

traverseGraphTopologicalSort(fg, s)
traverseGraphTopologicalSort(fg, s, fs_tree)

Return a topological sort of a factor graph as a vector of vertex labels in topological order. Starting from s::Symbol

addAgent!(dfg, agent)

deleteAgent!(dfg, label)

getAgent(dfg, label)

hasAgent(dfg, label)

listAgents(dfg)

mergeAgent!(dfg, agent)

loadDFG!(dfgLoadInto, file)

Load a DFG from a saved folder.

Example

using DistributedFactorGraphs, IncrementalInference
# Create a DFG - can make one directly, e.g. GraphsDFG{NoSolverParams}() or use IIF:
dfg = initfg()
# Load the graph
loadDFG!(dfg, "/tmp/savedgraph.tar.gz")
# Use the DFG as you do normally.
ls(dfg)

See also: loadDFG, saveDFG

loadDFG(file)

Convenience graph loader into a default LocalDFG.

See also: loadDFG!, saveDFG

saveDFG(folder, dfg)

Save a DFG to a folder. Will create/overwrite folder if it exists.

DevNotes:

• TODO remove compress kwarg.

Example

using DistributedFactorGraphs, IncrementalInference
# Create a DFG - can make one directly, e.g. GraphsDFG{NoSolverParams}() or use IIF:
dfg = initfg()
# ... Add stuff to graph using either IIF or DFG:
v1 = addVariable!(dfg, :a, ContinuousScalar, tags = [:POSE], solvable=0)
# Now save it:
saveDFG(dfg, "/tmp/saveDFG.tar.gz")