DistributedFactorGraphs Functions Reference

DistributedFactorGraphs Module

DistributedFactorGraphs.DistributedFactorGraphsModule

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

Entities

Abstract DFG

Summary DFG

DFG Variable Nodes

DistributedFactorGraphs.DFGVariableType
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!

DistributedFactorGraphs.DFGVariableSummaryType
struct DFGVariableSummary <: AbstractDFGVariable

Summary variable structure for a DistributedFactorGraph variable.


Fields:

DistributedFactorGraphs.PackedVariableNodeDataType
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

DistributedFactorGraphs.SkeletonDFGVariableType
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!

DistributedFactorGraphs.VariableNodeDataType
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.
DistributedFactorGraphs.getEstimateFieldsMethod
getEstimateFields(_)

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

DFG Factor Nodes

DistributedFactorGraphs.DFGFactorType
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!

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

Construct a DFG factor given a label.

DistributedFactorGraphs.DFGFactorSummaryType
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

DistributedFactorGraphs.GenericFunctionNodeDataType
mutable struct GenericFunctionNodeData{T<:(Union{var"#s16251", var"#s16250", var"#s16249"} where {var"#s16251"<:AbstractPackedFactor, var"#s16250"<:AbstractFactor, var"#s16249"<:FactorOperationalMemory})}

Notes

  • S::Symbol

Designing (WIP)

  • T <: Union{FactorOperationalMemory, AbstractPackedFactor}
  • in IIF.CCW{T <: DFG.AbstractFactor}
  • in DFG.AbstractRelativeMinimize <: AbstractFactor
  • in Main.SomeFactor <: AbstractRelativeMinimize
DistributedFactorGraphs.SkeletonDFGFactorType
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

Services

Abstract DFG

DistributedFactorGraphs.buildSubgraphMethod
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:

Dev Notes

  • Bulk vs node for node: a list of labels are compiled and the sugraph is copied in bulk.
DistributedFactorGraphs.copyGraph!Function
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:

DistributedFactorGraphs.findClosestTimestampMethod
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.

DistributedFactorGraphs.findFactorsBetweenNaiveFunction
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.
DistributedFactorGraphs.findVariableNearTimestampFunction
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

DistributedFactorGraphs.getAdjacencyMatrixSymbolsMethod
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}}
DistributedFactorGraphs.getBiadjacencyMatrixMethod
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}}}
DistributedFactorGraphs.getFactorsMethod
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.

DistributedFactorGraphs.getSummaryMethod
getSummary(dfg)

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

Notes

  • Returns ::DFGSummary
DistributedFactorGraphs.getSummaryGraphMethod
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}
DistributedFactorGraphs.getVariableMethod
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.

DistributedFactorGraphs.getVariablesMethod
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).

DistributedFactorGraphs.hasTagsMethod
hasTags(dfg, sym, tags; matchAll)

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

DistributedFactorGraphs.isFactorMethod
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)

DistributedFactorGraphs.isVariableMethod
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)

DistributedFactorGraphs.listFactorsMethod
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.

DistributedFactorGraphs.listNeighborsMethod
listNeighbors(dfg, label; solvable)

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

DistributedFactorGraphs.listSolveKeysFunction
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

DistributedFactorGraphs.listVariablesFunction
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

DistributedFactorGraphs.lsMethod
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}
DistributedFactorGraphs.lsMethod
ls(dfg; ...)
ls(dfg, node; solvable)

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

DistributedFactorGraphs.lsWhoMethod
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

DistributedFactorGraphs.lsfMethod
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}
DistributedFactorGraphs.lsfWhoMethod
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

DistributedFactorGraphs.mergeGraph!Function
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:

DistributedFactorGraphs.mergeGraphVariableData!Method
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
DistributedFactorGraphs.mergeVariableData!Method
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.

DistributedFactorGraphs.toDotFileFunction
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

Common Accessors

Common Accessors to both variable and factor nodes

DistributedFactorGraphs.getSolvableMethod
getSolvable(var)

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

Related:

  • isSolveInProgress
DistributedFactorGraphs.getSolveInProgressFunction
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

DistributedFactorGraphs.isSolvableMethod
isSolvable(node)

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

  • getSolvable(@ref)
DistributedFactorGraphs.setTimestamp!Method
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

DFG Variable Accessors CRUD and SET opperations

DistributedFactorGraphs.addPPE!Function
addPPE!(dfg, sourceVariable)
addPPE!(dfg, sourceVariable, ppekey)

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

DistributedFactorGraphs.addVariableSolverData!Function
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.

DistributedFactorGraphs.cloneSolveKey!Method
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.
DistributedFactorGraphs.getCoordinatesMethod
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

DistributedFactorGraphs.getDimensionFunction

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

DistributedFactorGraphs.getPPEFunction
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

DistributedFactorGraphs.getPointMethod
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

DistributedFactorGraphs.getPointIdentityFunction

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.
DistributedFactorGraphs.getPointTypeFunction

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

DistributedFactorGraphs.getVariableTypeMethod
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

DistributedFactorGraphs.isInitializedFunction
isInitialized(var)
isInitialized(var, key)

Returns state of variable data .initialized flag.

Notes:

  • used by both factor graph variable and Bayes tree clique logic.
DistributedFactorGraphs.isMarginalizedFunction
isMarginalized(vert)
isMarginalized(vert, solveKey)

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

Notes:

  • VariableNodeData default solveKey=:default
DistributedFactorGraphs.mergePPEs!Method
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.

DistributedFactorGraphs.mergeVariableSolverData!Method
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.

DistributedFactorGraphs.setTimestampMethod
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.

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

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

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

Update PPE data if it exists, otherwise add it.

DistributedFactorGraphs.updatePPE!Method
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.
DistributedFactorGraphs.updateVariableSolverData!Function
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!

DistributedFactorGraphs.@defVariableMacro
@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])

DFG Factor Accessors CRUD and SET opperations

DistributedFactorGraphs._getPriorTypeMethod
_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)

Printing

DistributedFactorGraphs.printVariableMethod
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

Compare Utilities

DistributedFactorGraphs.compareAllMethod
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

DistributedFactorGraphs.compareAllVariablesMethod
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

DistributedFactorGraphs.compareFactorMethod
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?
DistributedFactorGraphs.compareFactorGraphsMethod
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.

DistributedFactorGraphs.compareFieldsMethod
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

DistributedFactorGraphs.compareSimilarFactorsMethod
compareSimilarFactors(
    fgA,
    fgB;
    skipsamples,
    skipcompute,
    skip,
    show
)

Compare similar factors between ::FactorGraphs A and B.

Related:

compareFactorGraphs, compareSimilarVariables, compareAllVariables, ls.

DistributedFactorGraphs.compareSimilarVariablesMethod
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.

Common Functions

DistributedFactorGraphs.getVariableLabelNumberFunction
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
DistributedFactorGraphs.sortDFGMethod
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

Serialization

DFG Plots [GraphPlot.jl]

Modules = [DFGPlots]

Drivers

GraphsDFGs

DistributedFactorGraphs.findShortestPathDijkstraMethod
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

FileDFG

DistributedFactorGraphs.loadDFG!Method
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

DistributedFactorGraphs.saveDFGMethod
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")

Data Entries and Blobs

DistributedFactorGraphs.addBlob!Function

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

Related addBlobEntry!

addBlob!(store, _, _)
addBlob!(dfg, entry, data)
addBlob!(store, entry, data)
addBlob!(store, data)
addBlob!(store, blobId, data, _)
addBlob!(store, data, _)
addBlob!(store, blobId, data)
addBlob!(store, blobId, data)
addBlob!(store, entry, linkfile)
addBlob!(store, blobId, blob, linkfile)
DistributedFactorGraphs.deleteBlob!Function

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

Related deleteBlobEntry!

deleteBlob!(store, _)
deleteBlob!(dfg, entry)
deleteBlob!(store, entry)
deleteBlob!(store, blobId)
deleteBlob!(store, blobId)
deleteBlob!(store, args)
deleteBlob!(store, _)
deleteBlob!(store, _)
DistributedFactorGraphs.getBlobFunction

Get the data blob for the specified blobstore or dfg.

Related getBlobEntry

getBlob(store, _)
getBlob(dfg, entry)
getBlob(store, entry)
getBlob(store, blobId)
getBlob(store, blobId)
getBlob(store, blobId)
DistributedFactorGraphs.updateBlob!Function

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

updateBlob!(store, _, _)
updateBlob!(dfg, entry, data)
updateBlob!(store, entry, data)
updateBlob!(store, blobId, data)
updateBlob!(store, blobId, data)

DevNotes

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