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

Types valid for small data.

abstract type AbstractDFG{T<:AbstractParams}

Abstract parent struct for a DFG graph.

abstract type AbstractDFGFactor <: DFGNode

An abstract DFG factor.

abstract type AbstractDFGVariable <: DFGNode

An abstract DFG variable.

abstract type AbstractParams

Abstract parent struct for solver parameters.

abstract type DFGNode

Abstract parent struct for DFG variables and factors.

struct NoSolverParams <: AbstractParams

Empty structure for solver parameters.

struct MeanMaxPPE <: AbstractPointParametricEst

Data container to store Parameteric Point Estimate (PPE) for mean and max.

mutable struct PackedVariableNodeData

Packed VariableNodeData structure for serializing DFGVariables.

Fields:

• id::Union{Nothing, Base.UUID}

• vecval::Vector{Float64}

• dimval::Int64

• vecbw::Vector{Float64}

• dimbw::Int64

• BayesNetOutVertIDs::Vector{Symbol}

• dimIDs::Vector{Int64}

• dims::Int64

• eliminated::Bool

• BayesNetVertID::Symbol

• separator::Vector{Symbol}

• variableType::String

• initialized::Bool

• infoPerCoord::Vector{Float64}

• ismargin::Bool

• dontmargin::Bool

• solveInProgress::Int64

• solvedCount::Int64

• solveKey::Symbol

• covar::Vector{Float64}

• _version::String

struct VariableCompute{T<:InferenceVariable, P, N} <: AbstractDFGVariable

Complete variable structure for a DistributedFactorGraph variable.

Fields:

• id::Union{Nothing, Base.UUID}: The ID for the variable

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

• timestamp::TimeZones.ZonedDateTime: Variable timestamp. Accessors: getTimestamp, setTimestamp

• nstime::Dates.Nanosecond: Nanoseconds since a user-understood epoch (i.e unix epoch, robot boot time, etc.)

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

• ppeDict::Dict{Symbol, AbstractPointParametricEst}: Dictionary of parametric point estimates keyed by solverDataDict keys Accessors: addPPE!, updatePPE!, and deletePPE!

• solverDataDict::Dict{Symbol, VariableNodeData{T, P, N}} where {T<:InferenceVariable, P, N}: Dictionary of solver data. May be a subset of all solutions if a solver key was specified in the get call. Accessors: addVariableSolverData!, updateVariableSolverData!, and deleteVariableSolverData!

• smallData::Dict{Symbol, Union{Bool, Float64, Int64, Vector{Bool}, Vector{Float64}, Vector{Int64}, Vector{String}, String}}: Dictionary of small data associated with this variable. Accessors: getMetadata, setMetadata!

• dataDict::Dict{Symbol, BlobEntry}: Dictionary of large data associated with this variable. Accessors: addBlobEntry!, getBlobEntry, updateBlobEntry!, and deleteBlobEntry!

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

VariableCompute(label, T; timestamp, solvable, kwargs...)

The default VariableCompute constructor.

struct VariableDFG <: AbstractDFGVariable

The Variable information packed in a way that accomdates multi-lang using json.

mutable struct VariableNodeData{T<:InferenceVariable, 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:

• variableType::InferenceVariable: DEPRECATED remove in DFG v0.22

• id::Union{Nothing, Base.UUID}: Globally unique identifier.

• 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.

• BayesNetOutVertIDs::Vector{Symbol}

• dimIDs::Vector{Int64}

• dims::Int64

• eliminated::Bool: Flag used by junction (Bayes) tree construction algorithm to know whether this variable has yet been included in the tree construction.

• BayesNetVertID::Symbol

• separator::Vector{Symbol}

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

• infoPerCoord::Vector{Float64}: Stores the amount information (per measurement dimension) captured in each coordinate dimension.

• ismargin::Bool: Should this variable solveKey be treated as marginalized in inference computations.

• dontmargin::Bool: Should this variable solveKey always be kept fluid and not be automatically marginalized.

• solveInProgress::Int64: Convenience flag on whether a solver is currently busy working on this variable solveKey.

• solvedCount::Int64: How many times has a solver updated this variable solveKey estimte.

• solveKey::Symbol: solveKey identifier associated with this VariableNodeData object.

• events::Dict{Symbol, Base.GenericCondition{ReentrantLock}}: Future proofing field for when more multithreading operations on graph nodes are implemented, these conditions are meant to be used for atomic write transactions to this VND.

struct VariableSkeleton <: AbstractDFGVariable

Skeleton variable structure for a DistributedFactorGraph variable.

Fields:

• id::Union{Nothing, Base.UUID}: The ID for the variable

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

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

struct VariableSummary <: AbstractDFGVariable

Summary variable structure for a DistributedFactorGraph variable.

Fields:

• id::Union{Nothing, Base.UUID}: The ID for the variable

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

• timestamp::TimeZones.ZonedDateTime: Variable timestamp. Accessors: getTimestamp, setTimestamp

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

• ppeDict::Dict{Symbol, <:AbstractPointParametricEst}: Dictionary of parametric point estimates keyed by solverDataDict keys Accessors: addPPE!, updatePPE!, and deletePPE!

• variableTypeName::Symbol: Symbol for the variableType for the underlying variable. Accessor: getVariableType

• dataDict::Dict{Symbol, BlobEntry}: Dictionary of large data associated with this variable. Accessors: addBlobEntry!, getBlobEntry, updateBlobEntry!, and deleteBlobEntry!

getEstimateFields(_)

Return the fields of MeanMaxPPE that are estimates. NOTE: This is needed for each AbstractPointParametricEst. Closest we can get to a decorator pattern.

struct FactorCompute{T, N} <: AbstractDFGFactor

Complete factor structure for a DistributedFactorGraph factor.

DevNotes

• TODO make consistent the order of fields skeleton Skeleton, Summary, thru FactorCompute

  • e.g. timestamp should be a later field.

  ---

Fields:

• id::Union{Nothing, Base.UUID}: The ID for the factor

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

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

• _variableOrderSymbols::Tuple{Vararg{Symbol, N}} where N: Internal cache of the ordering of the neighbor variables. Rather use getVariableOrder to get the list as this is an internal value. Accessors: getVariableOrder

• timestamp::TimeZones.ZonedDateTime: Variable timestamp. Accessors: getTimestamp, setTimestamp

• nstime::Dates.Nanosecond: Nano second time, for more resolution on timestamp (only subsecond information)

• solverData::Base.RefValue{GenericFunctionNodeData{T}} where T: Solver data. Accessors: getSolverData, setSolverData!

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

• smallData::Dict{Symbol, Union{Bool, Float64, Int64, Vector{Bool}, Vector{Float64}, Vector{Int64}, Vector{String}, String}}: Dictionary of small data associated with this variable. Accessors: getMetadata, setMetadata!

FactorCompute(
    label,
    timestamp,
    nstime,
    tags,
    solverData,
    solvable,
    _variableOrderSymbols;
    id,
    smallData
)

Construct a DFG factor given a label.

struct FactorDFG <: AbstractDFGFactor

The Factor information packed in a way that accomdates multi-lang using json.

struct FactorSkeleton <: AbstractDFGFactor

Skeleton factor structure for a DistributedFactorGraph factor.

Fields:

• id::Union{Nothing, Base.UUID}: The ID for the factor

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

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

• _variableOrderSymbols::Vector{Symbol}: Internal cache of the ordering of the neighbor variables. Rather use listNeighbors to get the list as this is an internal value. Accessors: getVariableOrder

struct FactorSummary <: AbstractDFGFactor

Read-only summary factor structure for a DistributedFactorGraph factor.

Fields:

• id::Union{Nothing, Base.UUID}: The ID for the factor

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

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

• _variableOrderSymbols::Vector{Symbol}: Internal cache of the ordering of the neighbor variables. Rather use listNeighbors to get the list as this is an internal value. Accessors: getVariableOrder

• timestamp::TimeZones.ZonedDateTime: Variable timestamp. Accessors: getTimestamp

mutable struct GenericFunctionNodeData{T<:(Union{var"#s14", var"#s13", var"#s12"} where {var"#s14"<:AbstractPackedFactor, var"#s13"<:AbstractFactor, var"#s12"<:FactorOperationalMemory})}

Notes

• S::Symbol

Designing (WIP)

• T <: Union{FactorOperationalMemory, AbstractPackedFactor}
• in IIF.CCW{T <: DFG.AbstractFactor}
• in DFG.AbstractRelativeMinimize <: AbstractFactor
• in Main.SomeFactor <: AbstractRelativeMinimize

abstract type InferenceType <: AbstractPackedFactor

Abstract parent type for all InferenceTypes, which are the functions inside of factors.

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

E.g.

using GraphPlot
using DistributedFactorGraphs, DistributedFactorGraphs.DFGPlots
# ... Make graph...
# Using GraphViz plotting
plotDFG(fg)
# Save to PDF
using Compose
draw(PDF("/tmp/graph.pdf", 16cm, 16cm), plotDFG(fg))

More information at GraphPlot.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

packDFGMetadata(fg)

Packing function to serialize DFG metadata from.

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

_getDuplicatedEmptyDFG(dfg)

Gets an empty and unique GraphsDFG derived from an existing DFG.

loadDFG!(dfgLoadInto, dst; overwriteDFGMetadata)

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; saveMetadata)

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