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.

mutable struct State{T<:AbstractStateType, P, N}

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. N: Manifold dimension. Fields:

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

• val::Vector: Vector of on-manifold points used to represent a ManifoldKernelDensity (or parametric) belief.

• bw::Matrix{Float64}: Common kernel bandwith parameter used with ManifoldKernelDensity, see field covar for the parametric covariance.

• covar::Array{StaticArraysCore.SMatrix{N, N, Float64}, 1} where N: Parametric (Gaussian) covariance.

• separator::Vector{Symbol}

• 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 information (per measurement dimension) 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.

• statetype::Symbol

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

Complete variable structure for a DistributedFactorGraph variable.

Fields:

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

• timestamp::TimesDates.TimeDateZone: Variable timestamp. 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, N}} where {T<:AbstractStateType, P, N}: 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!

• statetype::Symbol

• _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 timestamp. Accessors: getTimestamp

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

• statetype::Symbol: Symbol for the state type for the underlying variable.

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

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

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.

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

GraphsDFG(; ...)

Create an in-memory GraphsDFG with the following 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

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")