DistributedFactorGraphs Functions Reference

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 DFGVariable{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: getSmallData, setSmallData!

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

DFGVariable(
    label,
    T;
    estimateDict,
    timestamp,
    solvable,
    kwargs...
)

The default DFGVariable constructor.

struct DFGVariableSummary <: 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!

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 SkeletonDFGVariable <: 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 Variable <: 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.

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 DFGFactor{T, N} <: AbstractDFGFactor

Complete factor structure for a DistributedFactorGraph factor.

DevNotes

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

  • 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: getSmallData, setSmallData!

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

Construct a DFG factor given a label.

struct DFGFactorSummary <: 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"#s15", var"#s14", var"#s13"} where {var"#s15"<:AbstractPackedFactor, var"#s14"<:AbstractFactor, var"#s13"<:FactorOperationalMemory})}

Notes

• S::Symbol

Designing (WIP)

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

struct SkeletonDFGFactor <: 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

_getDuplicatedEmptyDFG(dfg)

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

Add a DFGFactor to a DFG.

addFactor!(dfg, factor)

addFactor!(dfg, variables, factor)

addFactor!(dfg, variableLabels, factor)

addVariable!(dfg, variable)

Add a DFGVariable to a DFG.

buildSubgraph(, dfg, variableFactorLabels; ...)
buildSubgraph(
    ,
    dfg,
    variableFactorLabels,
    distance;
    solvable,
    sessionId,
    kwargs...
)

Build a deep subgraph copy from the DFG given a list of variables and factors and an optional distance. Note: Orphaned factors (where the subgraph does not contain all the related variables) are not returned. Related:

• copyGraph!
• getNeighborhood
• deepcopyGraph
• mergeGraph!

Dev Notes

• Bulk vs node for node: a list of labels are compiled and the sugraph is copied in bulk.

copyGraph!(destDFG, sourceDFG; ...)
copyGraph!(destDFG, sourceDFG, variableLabels; ...)
copyGraph!(
    destDFG,
    sourceDFG,
    variableLabels,
    factorLabels;
    copyGraphMetadata,
    overwriteDest,
    deepcopyNodes,
    verbose,
    showprogress
)

Common function for copying nodes from one graph into another graph. This is overridden in specialized implementations for performance. Orphaned factors are not added, with a warning if verbose. Set overwriteDest to overwrite existing variables and factors in the destination DFG. NOTE: copyGraphMetadata not supported yet. Related:

• deepcopyGraph
• deepcopyGraph!
• buildSubgraph
• getNeighborhood
• mergeGraph!

deepcopyGraph!(destDFG, sourceDFG; ...)
deepcopyGraph!(destDFG, sourceDFG, variableLabels; ...)
deepcopyGraph!(
    destDFG,
    sourceDFG,
    variableLabels,
    factorLabels;
    kwargs...
)

Copy nodes from one graph into another graph by making deepcopies. see copyGraph! for more detail. Related:

• deepcopyGraph
• buildSubgraph
• getNeighborhood
• mergeGraph!

deepcopyGraph(, sourceDFG; ...)
deepcopyGraph(, sourceDFG, variableLabels; ...)
deepcopyGraph(
    ,
    sourceDFG,
    variableLabels,
    factorLabels;
    sessionId,
    kwargs...
)

Copy nodes from one graph into a new graph by making deepcopies. see copyGraph! for more detail. Related:

• deepcopyGraph!
• buildSubgraph
• getNeighborhood
• mergeGraph!

deleteFactor!(dfg, factor; suppressGetFactor)

Delete the referened DFGFactor from the DFG.

deleteFactor!(dfg, label; suppressGetFactor)

Delete a DFGFactor from the DFG using its label.

deleteVariable!(dfg, variable)

Delete a referenced DFGVariable from the DFG.

Notes

• Returns Tuple{AbstractDFGVariable, Vector{<:AbstractDFGFactor}}

deleteVariable!(dfg, label)

Delete a DFGVariable from the DFG using its label.

exists(dfg, node)

True if the variable or factor exists in the graph.

findClosestTimestamp(setA, setB)

Find and return the closest timestamp from two sets of Tuples. Also return the minimum delta-time (::Millisecond) and how many elements match from the two sets are separated by the minimum delta-time.

findFactorsBetweenNaive(dfg, from, to)
findFactorsBetweenNaive(dfg, from, to, assertSingles)

Relatively naive function counting linearly from-to

DevNotes

• Convert to using Graphs shortest path methods instead.

findVariableNearTimestamp(dfg, timest; ...)
findVariableNearTimestamp(
    dfg,
    timest,
    regexFilter;
    tags,
    solvable,
    warnDuplicate,
    number
)

Find and return nearest variable labels per delta time. Function will filter on regexFilter, tags, and solvable.

Notes

• Returns Vector{Tuple{Vector{Symbol}, Millisecond}}

DevNotes:

• TODO number should allow returning more than one for k-nearest matches.
• Future versions likely will require some optimization around the internal getVariable call.
  • Perhaps a dedicated/efficient getVariableTimestamp for all DFG flavors.

Related

ls, listVariables, findClosestTimestamp

getAddHistory(dfg)

getAdjacencyMatrixSymbols(dfg; solvable)

Get a matrix indicating relationships between variables and factors. Rows are all factors, columns are all variables, and each cell contains either nothing or the symbol of the relating factor. The first row and first column are factor and variable headings respectively. Note:

• rather use getBiadjacencyMatrix
• Returns either of ::Matrix{Union{Nothing, Symbol}}

getBiadjacencyMatrix(dfg; solvable)

Get a matrix indicating adjacency between variables and factors. Returned as a named tuple: B::SparseMatrixCSC{Int}, varLabels::Vector{Symbol) facLabels::Vector{Symbol). Rows are the factors, columns are the variables, with the corresponding labels in varLabels,facLabels.

Notes

• Returns ::NamedTuple{(:B, :varLabels, :facLabels), Tuple{SparseMatrixCSC, Vector{Symbol}, Vector{Symbol}}}

getDFGInfo(dfg)

Convenience function to get all the metadata of a DFG

getDescription(dfg)

getFactor(dfg, label)

Get a DFGFactor from a DFG using its label.

getFactorOperationalMemoryType(dummy)

Method must be overloaded by the user for Serialization to work. E.g. IncrementalInference uses CommonConvWrapper <: FactorOperationalMemory.

getFactors(dfg; ...)
getFactors(dfg, regexFilter; tags, solvable)

List the DFGFactors in the DFG. Optionally specify a label regular expression to retrieves a subset of the factors.

getNeighborhood(dfg, label, distance)

Build a list of all unique neighbors inside 'distance'

Notes

• Returns Vector{Symbol}

Related:

• copyGraph!
• buildSubgraph
• deepcopyGraph
• mergeGraph!

getRobotData(dfg)

Get the robot data associated with the graph.

getRobotLabel(dfg)

getSessionData(dfg)

Get the session data associated with the graph.

getSessionLabel(dfg)

getSolverParams(dfg)

getSummary(dfg)

Get a summary of the graph (first-class citizens of variables and factors). Returns a DFGSummary.

Notes

• Returns ::DFGSummary

getSummaryGraph(dfg)

Get a summary graph (first-class citizens of variables and factors) with the same structure as the original graph.

Notes

• this is a copy of the original.
• Returns ::GraphsDFG{NoSolverParams, DFGVariableSummary, DFGFactorSummary}

getUserData(dfg)

Get the user data associated with the graph.

getUserLabel(dfg)

getVariable(dfg, label, solveKey)

Get a DFGVariable with a specific solver key. In memory types still return a reference, other types returns a variable with only solveKey.

getVariable(dfg, label)

Get a DFGVariable from a DFG using its label.

getVariables(dfg; ...)
getVariables(dfg, regexFilter; tags, solvable, detail)

List the DFGVariables in the DFG. Optionally specify a label regular expression to retrieves a subset of the variables. Tags is a list of any tags that a node must have (at least one match).

hasTags(dfg, sym, tags; matchAll)

Determine if the variable or factor neighbors have the tags:;Vector{Symbol}, and matchAll::Bool.

hasTagsNeighbors(dfg, sym, tags; matchAll)

Determine if the variable or factor neighbors have the tags:;Vector{Symbol}, and matchAll::Bool.

isConnected(dfg)

Checks if the graph is fully connected, returns true if so.

isFactor(dfg, sym)

Return whether sym::Symbol represents a factor vertex in the graph DFG. Checks whether it both exists in the graph and is a factor. (If you rather want a quicker for type, just do node isa DFGFactor)

isPathFactorsHomogeneous(dfg, from, to)

Return (::Bool,::Vector{TypeName}) of types between two nodes in the factor graph

DevNotes

• Only works on LigthDFG at the moment.

Related

GraphsDFG.findShortestPathDijkstra

isVariable(dfg, sym)

Return whether sym::Symbol represents a variable vertex in the graph DFG. Checks whether it both exists in the graph and is a variable. (If you rather want a quick for type, just do node isa DFGVariable)

listFactors(dfg; ...)
listFactors(dfg, regexFilter; tags, solvable)

Get a list of the labels of the DFGFactors in the DFG. Optionally specify a label regular expression to retrieves a subset of the factors.

listNeighbors(dfg, label; solvable)

Retrieve a list of labels of the immediate neighbors around a given variable or factor specified by its label.

listSolveKeys(variable::DFGVariable) -> Set{Symbol}
listSolveKeys(
    variable::DFGVariable,
    filterSolveKeys::Union{Nothing, Regex}
) -> Set{Symbol}
listSolveKeys(
    variable::DFGVariable,
    filterSolveKeys::Union{Nothing, Regex},
    skeys
) -> Any

List all the solvekeys used amongst all variables in the distributed factor graph object.

Related

listSupersolves, getSolverDataDict, listVariables

listVariables(dfg; ...)
listVariables(dfg, regexFilter; tags, solvable)

Get a list of labels of the DFGVariables in the graph. Optionally specify a label regular expression to retrieves a subset of the variables. Tags is a list of any tags that a node must have (at least one match).

Notes

• Returns ::Vector{Symbol}

Example

listVariables(dfg, r"l", tags=[:APRILTAG;])

See also: ls

ls(dfg; ...)
ls(dfg, regexFilter; tags, solvable)

List the DFGVariables in the DFG. Optionally specify a label regular expression to retrieves a subset of the variables. Tags is a list of any tags that a node must have (at least one match).

Notes:

• Returns Vector{Symbol}

ls(dfg; ...)
ls(dfg, node; solvable)

Retrieve a list of labels of the immediate neighbors around a given variable or factor.

ls2(dfg, label)

Helper to return neighbors at distance 2 around a given node.

lsTypes(dfg)

Return Vector{Symbol} of all unique variable types in factor graph.

lsTypesDict(dfg)

Return ::Dict{Symbol, Vector{Symbol}} of all unique variable types with labels in a factor graph.

lsWho(dfg, type)

Gives back all factor labels that fit the bill: lsWho(dfg, :Pose3)

Notes

• Returns Vector{Symbol}

Dev Notes

• Cloud versions will benefit from less data transfer
• ls(dfg::C, ::T) where {C <: CloudDFG, T <: ..}

Related

ls, lsf, lsfPriors

lsf(dfg; ...)
lsf(dfg, regexFilter; tags, solvable)

List the DFGFactors in the DFG. Optionally specify a label regular expression to retrieves a subset of the factors.

Notes

• Return Vector{Symbol}

lsfPriors(dfg)

Return vector of prior factor symbol labels in factor graph dfg.

Notes:

• Returns Vector{Symbol}

lsfTypes(dfg)

Return Vector{Symbol} of all unique factor types in factor graph.

lsfTypesDict(dfg)

Return ::Dict{Symbol, Vector{Symbol}} of all unique factors types with labels in a factor graph.

lsfWho(dfg, type)

Gives back all factor labels that fit the bill: lsfWho(dfg, :Point2Point2)

Notes

• Returns Vector{Symbol}

Dev Notes

• Cloud versions will benefit from less data transfer
• ls(dfg::C, ::T) where {C <: CloudDFG, T <: ..}

Related

ls, lsf, lsfPriors

mergeGraph!(destDFG, sourceDFG; ...)
mergeGraph!(destDFG, sourceDFG, variableLabels; ...)
mergeGraph!(
    destDFG,
    sourceDFG,
    variableLabels,
    factorLabels;
    ...
)
mergeGraph!(
    destDFG,
    sourceDFG,
    variableLabels,
    factorLabels,
    distance;
    solvable,
    kwargs...
)

Merger sourceDFG to destDFG given an optional list of variables and factors and distance. Notes:

• Nodes already in the destination graph are updated from sourceDFG.
• Orphaned factors (where the subgraph does not contain all the related variables) are not included.

Related:

• copyGraph!
• buildSubgraph
• getNeighborhood
• deepcopyGraph

mergeGraphVariableData!(destDFG, sourceDFG, varSyms)

Common function to update all solver data and estimates from one graph to another. This should be used to push local solve data back into a cloud graph, for example.

Notes

• Returns ::Nothing

mergeVariableData!(dfg, sourceVariable)

Merges and updates solver and estimate data for a variable (variable can be from another graph). Note: Makes a copy of the estimates and solver data so that there is no coupling between graphs.

rebuildFactorMetadata!(dfg, factor)
rebuildFactorMetadata!(dfg, factor, neighbors)

Method must be overloaded by the user for Serialization to work.

setDescription!(dfg, description)

setRobotData!(dfg, data)

Set the robot data associated with the graph.

setSessionData!(dfg, data)

Set the session data associated with the graph.

setUserData!(dfg, data)

Set the user data associated with the graph.

toDot(dfg)

Produces a dot-format of the graph for visualization.

Notes

• Returns ::String

toDotFile(dfg)
toDotFile(dfg, fileName)

Produces a dot file of the graph for visualization. Download XDot to see the data

Note

• Default location "/tmp/dfg.dot" – MIGHT BE REMOVED
• Can be viewed with the xdot system application.
• Based on graphviz.org

updateFactor!(dfg, factor)

Update a complete DFGFactor in the DFG.

updateVariable!(dfg, variable)

Update a complete DFGVariable in the DFG.

emptyTags!(dfg, sym)

Empty all tags from the node (empty)

getLabel(v)

Return the label for a DFGNode.

getSolvable(dfg, sym)

Get 'solvable' parameter for either a variable or factor.

getSolvable(var)

Variables or factors may or may not be 'solvable', depending on a user definition. Useful for ensuring atomic transactions.

Related:

• isSolveInProgress

getSolveInProgress(var)
getSolveInProgress(var, solveKey)

Which variables or factors are currently being used by an active solver. Useful for ensuring atomic transactions.

DevNotes:

• Will be renamed to data.solveinprogress which will be in VND, not DFGNode – see DFG #201

Related

isSolvable

getTags(v)

Return the tags for a DFGNode.

getTimestamp(v)

Get the timestamp of a DFGNode.

isSolvable(node)

Variables or factors may or may not be 'solvable', depending on a user definition. returns true if getSolvable > 0 Related:

• getSolvable(@ref)

listTags(dfg, sym)

Return the tags for a variable or factor.

mergeTags!(dfg, sym, tags)

Merge add tags to a variable or factor (union)

removeTags!(dfg, sym, tags)

Remove the tags from the node (setdiff)

setSolvable!(dfg, sym, solvable)

Set the solvable parameter for either a variable or factor.

setSolvable!(node, solvable)

Set the solvable parameter for either a variable or factor.

setTags!(f, tags)

Set the tags for a DFGNode.

setTimestamp!(dfg, lbl, ts)

Set the timestamp of a Variable/Factor object in a factor graph. Note: Since timestamp is not mutable setTimestamp! calls updateVariable! internally. See also setTimestamp

addPPE!(dfg, sourceVariable)
addPPE!(dfg, sourceVariable, ppekey)

Add a new PPE entry from a deepcopy of the source variable PPE. NOTE: Copies the PPE.

addPPE!(dfg, variablekey, ppe)

Add variable PPE, errors if it already exists.

addSmallData!(dfg, label, pair)

Add a small data pair key=>value for variable label in dfg

addVariableSolverData!(dfg, sourceVariable)
addVariableSolverData!(dfg, sourceVariable, solveKey)

Add a new solver data entry from a deepcopy of the source variable solver data. NOTE: Copies the solver data.

addVariableSolverData!(dfg, variablekey, vnd)

Add variable solver data, errors if it already exists.

cloneSolveKey!(
    dest_dfg,
    dest,
    src_dfg,
    src;
    solvable,
    labels,
    verbose
)

Duplicate a solveKey` into a destination from a source.

Notes

• Can copy between graphs, or to different solveKeys within one graph.

deletePPE!(dfg, sourceVariable)
deletePPE!(dfg, sourceVariable, ppekey)

Delete PPE data, returns the deleted element.

deletePPE!(dfg, variablekey)
deletePPE!(dfg, variablekey, ppekey)

Delete PPE data, returns the deleted element.

deleteSmallData!(dfg, label, key)

Delete a small data entry at key for variable label in dfg

deleteVariableSolverData!(dfg, sourceVariable)
deleteVariableSolverData!(dfg, sourceVariable, solveKey)

Delete variable solver data, returns the deleted element.

deleteVariableSolverData!(dfg, variablekey)
deleteVariableSolverData!(dfg, variablekey, solveKey)

Delete variable solver data, returns the deleted element.

emptySmallData!(dfg, label)

Empty all small data from variable label in dfg

getCoordinates(, p)
getCoordinates(, p, basis)

Default reduction of a variable point value (a group element) into coordinates as Vector. Override if defaults are not correct.

DevNotes

• TODO Likely remove as part of serialization updates, see #590
• Used in transition period for Serialization. This function will likely be changed or deprecated entirely.

Related

getPoint

Interface function to return the variableType dimension of an InferenceVariable, extend this function for all Types<:InferenceVariable.

getLastUpdatedTimestamp(est)

getManifold(_)

Interface function to return the <:ManifoldsBase.AbstractManifold object of variableType<:InferenceVariable.

getPPE(vari)
getPPE(vari, solveKey)

Get the parametric point estimate (PPE) for a variable in the factor graph.

Notes

• Defaults on keywords solveKey and method

Related

getMeanPPE, getMaxPPE, getKDEMean, getKDEFit, getPPEs, getVariablePPEs

getPPE(v)
getPPE(v, ppekey)

Get the parametric point estimate (PPE) for a variable in the factor graph for a given solve key.

Notes

• Defaults on keywords solveKey and method

Related getPPEMean, getPPEMax, updatePPE!, mean(BeliefType)

getPPEDict(v)

Get the PPE dictionary for a variable. Recommended to use CRUD operations instead, getPPE, addPPE!, updatePPE!, deletePPE!.

getPPEMax(est)

getPPEMean(est)

getPPESuggested(est)

Get all the parametric point estimate (PPE) for a variable in the factor graph.

getPoint(, v)
getPoint(, v, basis)

Default escalzation from coordinates to a group representation point. Override if defaults are not correct. E.g. coords -> se(2) -> SE(2).

DevNotes

• TODO Likely remove as part of serialization updates, see #590
• Used in transition period for Serialization. This function will likely be changed or deprecated entirely.

Related

getCoordinates

Interface function to return the user provided identity point for this InferenceVariable manifold, extend this function for all Types<:InferenceVariable.

Notes

• Used in transition period for Serialization. This function will likely be changed or deprecated entirely.

Interface function to return the manifold point type of an InferenceVariable, extend this function for all Types<:InferenceVariable.

getSmallData(dfg, label, key)

Get the small data entry at key for variable label in dfg

getSmallData(v)

Get the small data for a variable. Note: Rather use SmallData CRUD

getSolvedCount(v)

Get the number of times a variable has been inferred – i.e. solvedCount.

Related

isSolved, setSolvedCount!

getSolverData(v)
getSolverData(v, key)

Retrieve solver data structure stored in a variable.

getSolverDataDict(v)

Get solver data dictionary for a variable. Advised to use graph CRUD operations instead.

getVariablePPE(::DFGVariable)
getVariablePPE(::VariableNodeData)

Get the Parametric Point Estimate of the given variable.

getVariablePPEDict(vari)

Return full dictionary of PPEs in a variable, recommended to rather use CRUD: getPPE,

getVariableSolverData(dfg, variablekey)
getVariableSolverData(dfg, variablekey, solvekey)

Get variable solverdata for a given solve key.

getVariableType(_)

Variable nodes variableType information holding a variety of meta data associated with the type of variable stored in that node of the factor graph.

Notes

• API Quirk in that this function returns and instance of ::T not a ::Type{<:InferenceVariable}.

DevWork

• TODO, see IncrementalInference.jl 1228

Related

getVariableType

getVariableTypeName(v)

Retrieve the soft type name symbol for a DFGVariableSummary. ie :Point2, Pose2, etc.

isInitialized(var)
isInitialized(var, key)

Returns state of variable data .initialized flag.

Notes:

• used by both factor graph variable and Bayes tree clique logic.

isMarginalized(vert)
isMarginalized(vert, solveKey)

Return ::Bool on whether this variable has been marginalized.

Notes:

• VariableNodeData default solveKey=:default

isSolved(v)

Boolean on whether the variable has been solved.

Related

getSolved, setSolved!

listPPEs(dfg, variablekey)

List all the PPE data keys in the variable.

listSmallData(dfg, label)

List all small data keys for a variable label in dfg

listVariableSolverData(dfg, variablekey)

List all the solver data keys in the variable.

mergePPEs!(destVariable, sourceVariable)

Merges and updates solver and estimate data for a variable (variable can be from another graph). Note: Makes a copy of the estimates and solver data so that there is no coupling between graphs.

mergeVariableSolverData!(destVariable, sourceVariable)

Merges and updates solver and estimate data for a variable (variable can be from another graph). If the same key is present in another collection, the value for that key will be the value it has in the last collection listed (updated). Note: Makes a copy of the estimates and solver data so that there is no coupling between graphs.

setMarginalized!(vnd, val)

Mark a variable as marginalized true or false.

setSmallData!(v, smallData)

Set the small data for a variable. This will overwrite old smallData. Note: Rather use SmallData CRUD

setSolvedCount!(v, val)

Update/set the solveCount value.

Related

getSolved, isSolved

setSolverData!(v, data)
setSolverData!(v, data, key)

Set solver data structure stored in a variable.

setTimestamp(v, ts; verbose)

Set the timestamp of a DFGVariable object returning a new DFGVariable. Note: Since the timestamp field is not mutable setTimestamp returns a new variable with the updated timestamp (note the absence of !). Use updateVariable! on the returened variable to update it in the factor graph if needed. Alternatively use setTimestamp!. See issue #315.

updatePPE!(dfg, sourceVariable; ...)
updatePPE!(dfg, sourceVariable, ppekey; warn_if_absent)

Update PPE data if it exists, otherwise add it. NOTE: Copies the PPE data.

updatePPE!(dfg, sourceVariables; ...)
updatePPE!(dfg, sourceVariables, ppekey; warn_if_absent)

Update PPE data if it exists, otherwise add it.

updatePPE!(dfg, variablekey, ppe; warn_if_absent)

Update PPE data if it exists, otherwise add it – one call per key::Symbol=:default.

Notes

• uses ppe.solveKey as solveKey.

updateSmallData!(dfg, label, pair; warn_if_absent)

Update a small data pair key=>value for variable label in dfg

updateVariableSolverData!(dfg, variablekey, vnd; ...)
updateVariableSolverData!(
    dfg,
    variablekey,
    vnd,
    useCopy;
    ...
)
updateVariableSolverData!(
    dfg,
    variablekey,
    vnd,
    useCopy,
    fields;
    warn_if_absent
)

Update variable solver data if it exists, otherwise add it.

Notes:

• useCopy=true to copy solver data and keep separate memory.
• Use fields to updated only a few VND.fields while adhering to useCopy.

Related

mergeVariableSolverData!

@defVariable StructName manifolds<:ManifoldsBase.AbstractManifold

A macro to create a new variable with name StructName and manifolds. Note that the manifolds is an object and must be a subtype of ManifoldsBase.AbstractManifold. See documentation in Manifolds.jl on making your own.

Example:

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

_getPriorType(_type)

If you know a variable is ::Type{<:Pose2} but want to find its default prior ::Type{<:PriorPose2}.

Assumptions

• The prior type will be defined in the same module as the variable type.
• Not exported per default, but can be used with knowledge of the caveats.

Example

using RoME
@assert RoME.PriorPose2 == DFG._getPriorType(Pose2)

getFactorFunction(fcd)

Return reference to the user factor in <:AbstractDFG identified by ::Symbol.

getFactorType(data)

Return user factor type from factor graph identified by label ::Symbol.

Notes

• Replaces older getfnctype.

getSolverData(f)

Retrieve solver data structure stored in a factor.

getVariableOrder(fct)

Get the variable ordering for this factor. Should be equivalent to listNeighbors unless something was deleted in the graph.

isPrior(dfg, fc)

Return ::Bool on whether given factor fc::Symbol is a prior in factor graph dfg.

printFactor(dfg, sym; kwargs...)

Display and return to console the user factor identified by tag name.

printVariable(dfg, sym; kwargs...)

Display the content of VariableNodeData to console for a given factor graph and variable tag::Symbol.

Dev Notes

• TODO split as two show macros between AMP and DFG

compareAll(Al, Bl; show, skip)

Recursively compare the all fields of T that are not in skip for objects Al and Bl.

TODO > add to func_ref.md

compareAllVariables(fgA, fgB; skip, show, skipsamples)

Compare all variables in both ::FactorGraphs A and B.

Notes

• A and B should all the same variables and factors.

Related:

compareFactorGraphs, compareSimilarVariables, compareVariable, ls

compareFactor(A, B; show, skip, skipsamples, skipcompute)

Compare that all fields are the same in a ::FactorGraph factor.

DevNotes

• TODO getSolverData(A).fnc.varValsAll / varidx are only defined downstream, so should should this function not be in IIF?

compareFactorGraphs(
    fgA,
    fgB;
    skipsamples,
    skipcompute,
    skip,
    show
)

Compare and return if two factor graph objects are the same, by comparing similar variables and factors.

Notes:

• Default items to skip with skipsamples, skipcompute.
• User defined fields to skip can be specified with skip::Vector{Symbol}.
• To enable debug messages for viewing which fields are not the same:
  • https://stackoverflow.com/questions/53548681/how-to-enable-debugging-messages-in-juno-julia-editor

Related:

compareSimilarVariables, compareSimilarFactors, compareAllVariables, ls.

compareFields(Al, Bl; show, skip)

Compare the all fields of T that are not in skip for objects Al and Bl and returns ::Bool.

TODO > add to func_ref.md

compareSimilarFactors(
    fgA,
    fgB;
    skipsamples,
    skipcompute,
    skip,
    show
)

Compare similar factors between ::FactorGraphs A and B.

Related:

compareFactorGraphs, compareSimilarVariables, compareAllVariables, ls.

compareSimilarVariables(fgA, fgB; skip, show, skipsamples)

Compare similar labels between ::FactorGraphs A and B.

Notes

• At least one variable label should exist in both A and B.

Related:

compareFactorGraphs, compareAllVariables, compareSimilarFactors, compareVariable, ls.

compareVariable(A, B; skip, show, skipsamples)

Compare that all fields are the same in a ::FactorGraph variable.

getVariableLabelNumber(vs)
getVariableLabelNumber(vs, prefix)

Small utility to return ::Int, e.g. 0 from getVariableLabelNumber(:x0)

Examples

getVariableLabelNumber(:l10)          # 10
getVariableLabelNumber(:x1)           # 1
getVariableLabelNumber(:x1_10, "x1_") # 10

DevNotes

• make prefix Regex based for longer – i.e. :apriltag578, :lm1_4

isValidLabel(id)

Returns true if the label is valid for a session, robot, or user ID.

Default non-parametric graph solution.

Standard parametric graph solution (Experimental).

sortDFG(vars; by, kwargs...)

Convenience wrapper for Base.sort. Sort variable (factor) lists in a meaningful way (by timestamp, label, etc), for example [:april;:x1_3;:x1_6;] Defaults to sorting by timestamp for variables and factors and using natural_lt for Symbols. See Base.sort for more detail.

Notes

• Not fool proof, but does better than native sort.

Example

sortDFG(ls(dfg)) sortDFG(ls(dfg), by=getLabel, lt=natural_lt)

Related

ls, lsf

getTypeFromSerializationModule(_typeString)

Get a type from the serialization module.

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.

findShortestPathDijkstra(
    dfg,
    from,
    to;
    regexVariables,
    regexFactors,
    tagsVariables,
    tagsFactors,
    typeVariables,
    typeFactors,
    solvable,
    initialized
)

Speciallized function available to only GraphsDFG at this time.

Notes

• Has option for various types of filters (increases memory usage)

Example

using IncrementalInference

# canonical example graph as example
fg = generateGraph_Kaess()

@show path = findShortestPathDijkstra(fg, :x1, :x3)
@show isVariable.(fg, path)
@show isFactor.(fg, path)

DevNotes

• TODO expand to other AbstractDFG entities.
• TODO use of filter resource consumption can be improved.

Related

findFactorsBetweenNaive, Graphs.dijkstra_shortest_paths

loadDFG!(
    dfgLoadInto,
    dst;
    overwriteDFGMetadata,
    useDeprExtract
)

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

Adds a blob to the blob store or dfg with the given entry.

Related addBlobEntry!

addBlob!(store, _, _)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:61.

addBlob!(dfg, entry, data)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:111.

addBlob!(store, entry, data)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:115.

addBlob!(store, data)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:121.

addBlob!(store, blobId, data, _)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:124.

addBlob!(store, data, _)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:128.

addBlob!(store, blobId, data)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:206.

addBlob!(store, blobId, data)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:267.

addBlob!(store, entry, linkfile)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:320.

addBlob!(store, blobId, blob, linkfile)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:324.

Delete a blob from the blob store or dfg with the given entry.

Related deleteBlobEntry!

deleteBlob!(store, _)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:69.

deleteBlob!(dfg, entry)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:142.

deleteBlob!(store, entry)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:146.

deleteBlob!(store, blobId)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:231.

deleteBlob!(store, blobId)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:282.

deleteBlob!(store, args)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:335.

deleteBlob!(store, _)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:339.

deleteBlob!(store, _)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:340.

Get the data blob for the specified blobstore or dfg.

Related getBlobEntry

getBlob(store, _)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:57.

getBlob(dfg, entry)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:85.

getBlob(store, entry)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:105.

getBlob(store, blobId)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:195.

getBlob(store, blobId)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:263.

getBlob(store, blobId)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:315.

List all ids in the blob store.

Update a blob to the blob store or dfg with the given entry. Related updateBlobEntry!

updateBlob!(store, _, _)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:65.

updateBlob!(dfg, entry, data)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:133.

updateBlob!(store, entry, data)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:137.

updateBlob!(store, blobId, data)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:219.

updateBlob!(store, blobId, data)

defined at /home/runner/work/DistributedFactorGraphs.jl/DistributedFactorGraphs.jl/src/DataBlobs/services/BlobStores.jl:275.

DevNotes

• TODO TBD update verb on data since data blobs and entries are restricted to immutable only.