GitHub

DistributedFactorGraphs Functions

Abstract DFG

DistributedFactorGraphs.buildSubgraph — Method
buildSubgraph(, dfg, variableFactorLabels; ...)
buildSubgraph(
    ,
    dfg,
    variableFactorLabels,
    distance;
    solvable,
    graphLabel,
    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.
source
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:

source
DistributedFactorGraphs.findClosestTimestamp — Method
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.

source
DistributedFactorGraphs.findFactorsBetweenNaive — Function
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.
source
DistributedFactorGraphs.findShortestPathDijkstra — Function

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

source
DistributedFactorGraphs.findVariableNearTimestamp — Function
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

source
DistributedFactorGraphs.getAdjacencyMatrixSymbols — Method
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}}
source
DistributedFactorGraphs.getBiadjacencyMatrix — Method
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}}}
source
DistributedFactorGraphs.getFactors — Method
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.

source
DistributedFactorGraphs.getSummaryGraph — Method
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, VariableSummary, FactorSummary}
source
DistributedFactorGraphs.getVariable — Method
getVariable(dfg, label, solveKey)

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

source
DistributedFactorGraphs.getVariables — Method
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).

source
DistributedFactorGraphs.isFactor — Method
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 FactorCompute)

source
DistributedFactorGraphs.isVariable — Method
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 VariableCompute)

source
DistributedFactorGraphs.listFactors — Function
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.

source
DistributedFactorGraphs.listSolveKeys — Function
listSolveKeys(variable::VariableCompute) -> Set{Symbol}
listSolveKeys(
    variable::VariableCompute,
    filterSolveKeys::Union{Nothing, Regex}
) -> Set{Symbol}
listSolveKeys(
    variable::VariableCompute,
    filterSolveKeys::Union{Nothing, Regex},
    skeys
) -> Any

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

Related

listSolveKeys, getSolverDataDict, listVariables

source
DistributedFactorGraphs.listVariables — Function
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

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

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

source
DistributedFactorGraphs.lsWho — Method
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

source
DistributedFactorGraphs.lsf — Method
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}
source
DistributedFactorGraphs.lsf — Method
lsf(dfg; ...)
lsf(dfg, _)

Lists the factors of a specific type in the factor graph. Example, list all the Point2Point2 factors in the factor graph dfg: lsfWho(dfg, :Point2Point2)

Notes

  • Return Vector{Symbol}
source
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:

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

source
DistributedFactorGraphs.toDotFile — Function
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
source

Common Accessors

Common Accessors to both variable and factor nodes

DistributedFactorGraphs.getSolvable — Method
getSolvable(var)

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

Related:

  • isSolveInProgress
source
DistributedFactorGraphs.getSolveInProgress — Function
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

source
DistributedFactorGraphs.isSolvable — Method
isSolvable(node)

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

  • getSolvable(@ref)
source

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.

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

source
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.
source
DistributedFactorGraphs.getCoordinates — Method
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

source
DistributedFactorGraphs.getPPE — Function
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

source
DistributedFactorGraphs.getPoint — Method
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

source
DistributedFactorGraphs.getPointIdentity — Function

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.
source
DistributedFactorGraphs.getVariableType — Method
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

source
DistributedFactorGraphs.isInitialized — Function
isInitialized(var)
isInitialized(var, key)

Returns state of variable data .initialized flag.

Notes:

  • used by both factor graph variable and Bayes tree clique logic.
source
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.

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

source
DistributedFactorGraphs.setTimestamp — Method
setTimestamp(v, ts; verbose)

Set the timestamp of a VariableCompute object returning a new VariableCompute. 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.

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

source
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.
source
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!

source
DistributedFactorGraphs.@defVariable — Macro
@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])
source

DFG Factor Accessors CRUD and SET opperations

DistributedFactorGraphs._getPriorType — Method
_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)
source

Printing

DistributedFactorGraphs.printVariable — Method
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
source

Compare Utilities

DistributedFactorGraphs.compareAllVariables — Method
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

source
DistributedFactorGraphs.compareFactor — Method
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?
source
DistributedFactorGraphs.compareFactorGraphs — Method
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.

source
DistributedFactorGraphs.compareSimilarFactors — Method
compareSimilarFactors(
    fgA,
    fgB;
    skipsamples,
    skipcompute,
    skip,
    show
)

Compare similar factors between ::FactorGraphs A and B.

Related:

compareFactorGraphs, compareSimilarVariables, compareAllVariables, ls.

source
DistributedFactorGraphs.compareSimilarVariables — Method
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.

source

Common Functions

DistributedFactorGraphs.getVariableLabelNumber — Function
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
source
DistributedFactorGraphs.sortDFG — Method
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

source

Serialization