Skip to content

Standard Definitions of API via verbs and set theory

Jump to bottom
Johannes Terblanche edited this page Aug 19, 2024 · 192 revisions

Copyright NavAbility Contributors (2019-2023) - Apache 2.0 License at repo root level.

Establishing The verbNoun Matrix

The DFG/Caesar SLAM API is devised from the Apollo Draper guidance computer interface method where functions follow a standardized structure:

verbNoun[Noun|Adjective][!](::NounType[,..., defaults=defaults; kwargs=defaults])

which will allow us to easily write far reaching documentation by separately defining what each of the verbs and Nouns mean, so the user can interpolate function meanings. Adjectives are optional, and API is camelCase. In fact, a shorthand is used via Julian multiple-dispatch, see below.

Exclamation [!] is optional at end of function to indicate---as is convention in Julia---that arguments might be updated by/during the function call (since pass by reference is standard in Julia).

Shorthand Naming via Multiple Dispatch

Whenever it is sensible to do so, one can use the type information of the argument to act as a Noun in the verbNoun definition, for example:

verb(::NounType, ...)

This could result in calls such as:

getBelief(::DFGVariable) # as a shorthand version of getVariableBelief

Sometimes (but not always) we can simplify to high levels of abstraction, e.g.:

list(::AbstractDFG) # or even in this particular case, akin to bash
ls(::AbstractDFG)

Since Julia is a statically typed language, it is safe to use the shortcuts of verb[Noun|Adjective*][!](::NounType...). As a general policy, the decision was made to implement the logic inside the shorthand method definition; and then also include a const alias wrapper to the more verbose full verbNoun[Noun|Adjective*][!]([::NounType|*]...) definition for when a user tries to guess the full verbNoun interface.

A few examples for graph operations is pictorially shown here in the docs.

Special Case (Internal Variables/Functions)

Underscore _verb* is a reserved convention for internal functions and variables that may not necessarily be useful to a user who is not interested in the internal developer aspects of the source code. These functions, however, still follow the general verbNoun convention as far possible.

Function argument ordering proposal

See Julia documentation on function argument ordering

Open issues at Caesar or DFG regarding the definitions here -- guidelines are that the definitions should be short, exact, and orthogonal to other verbs and Nouns as far possible. API design follows from these definitions, so they need to be accurate. Any mistakes or difficulties move to API v1.1 or even v2.0 if required. Once ratified, API v1.0 is intended to be an LTS specification.

verb (Action)

verb Definition
add*[!] Create new data to an existing data structure, similar to push.
add the value at a given key if it doesn't exist (strict add)
append*[!] Add to the end of collection A the elements of collection B.
push*[!] Reserved. (Similar to add, but other distributed cases likely)
set*! set new memory location for field of struct (mutables).
update*! Update data at a given key if it exists, else add
merge*[!] Construct a merged collection from the given collections. 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). 🔴 Does this create a third collection? DF, think it depends on use of [!]. Yes, [!] follows the standard julia style guide to overwrite the first collection.
union*[!] Combine distinct data from two or more collections/containers/graph of the same (or similar) types into one collection/container/graph of the particular but most similar type.
join*[!] Join two or more of the same type T objects (regardless of value) together and return new memory result of the same type T.
clone Reserved, no immediate use defined.
duplicate Reserved, like to be used for shorttape, longtape duplication roles.
copy Create a shallow copy of an object: the outer structure is copied, but not all internal values.
deepcopy Create a deep copy of an object: everything is copied recursively, resulting in a fully independent object.
view Reserved. e.g. viewSubgraph. Like getindex, but returns a view into the parent instead of making a copy.
🔴 DF, this is similar to a shallow copy, but maybe the verb can be used to emulate a shallow copy for DB cases that can only do deepcopy. Also, CloudDFG object is already a view? Or, getSubgraphSummary (i.e. DataLevel0) is needed by the caller rather than a view.
🔴 Functions such as getSummary, getDuplicatedEmptyDFG, getAdjacencyMatrix does not fit in 100% with existing definition of get as it does not access, but rather create/build. Do we maybe just use it as summaryDFG, adjacencyMatrix and duplicateEmptyDFG/copyEmptyDFG/emptyDFG, update get definition, use build from above, or a new verb such as construct/make/create.
JT-I like the constructor like approach of summaryDFG.
DF - I'd still push for using the correct (possibly new) verb. Do build / calc / generate / empty and copy verbs not already partially fit some of these cases?
Missing Nouns such as Summary.
build Build a structure from readily available data, likely involving symbolic operations and little numerical calculations.
generate Generate a structure, likely not using (or requiring) too much other data; and likely does not require any persisted state beyond the generation logic itself.
similar Duplicate or similar object (likely Adjective Empty), to be used in the same was as Julia base similar.
load Load data from persistent storage, likely into some specialized data format.
get accessor to get memory for field of struct.
Return the value stored for the given key (by reference if possible)
find perform calculations to find something.
has similar to exist.
exist return ::Bool on whether an individual element exists inside the given collection object.
list / ls / lsf List the labels of an existing (composite) data container/object in an intelligent way.
is Open ended logic test returning ::Bool based on the Noun and arguments.
show Abstract show interface if no better description of visualization is available.
🔴 I would suggest: https://docs.julialang.org/en/v1/manual/types/#man-custom-pretty-printing-1
print print to console.
describe more verbose description of a Noun or object, likely associated with output stream, default console.
length Return the number of elements in the collection
empty*! Remove all elements from a collection
delete*! remove key [and data] at a given key if it exist, return data
accumulate*[!] Perform numerical computations from available data which tend to accumulate values a chain of some kind, likely used in helper functions to simplify or improve user experience with PPE results.
calc Perform calculations from readily available information, and usually smaller lighter numerical computations.
solve*! Perform inference operations, either through stochastic or parametric means.
execute*! Perform specified task, likely a point of no return.
plot 2D plots stacked together, such as top down XY, etc.
draw 3D drawing / visualization, may include abstract visualization of graph topology.
unconditional Not subject to any conditions.
pack Serialization of object into a defined Packed structure.
parch 🔴 Parching refers to drying/hollowing out the object to reduce its memory size to the bare minimum.
stash 🔴 Storing data somewhere and in a format that the user understands, and likely pertains particularly to serialization of large factors where data blobs are stashed outside the persisted graph itself.
preamble 🔴 Action that occurs just once during create/make/build/generate steps.

Also possible (Using Base/Core Convention)

Proposal getindex/setindex! and iterators, I like the syntax
getindex Retrieve the value(s) stored at the given key or index within a collection. The syntax a[i,j,...] is converted by the compiler to getindex(a, i, j, ...).
setindex! Store the given value at the given key or index within a collection. The syntax a[i,j,...] = x is converted by the compiler to (setindex!(a, x, i, j, ...); x).
iterators The use of iterators and broadcasting

Noun (Object)

Noun Definition
Label A single identifier that is unique within each user, robot, and session combination -- but not necessarily unique across session, robots, or users.
Variable A group of free dimensions representing the parameters or decision values that must be assigned during inference, and are only defined by their connected factors (dependence) and the mixed-manifold domain over which the values can exist; the values should be assumed as parameters that are used to produce an approximate function which represents the estimated belief (probability density/distribution).
Factor Algebraic structure (i.e. functions) that models how different variables are related to each other, along with a stochastic uncertainty model, through connectedness in the factor graph. Factors can also depend on internal parameters which can be solved iteratively through a separate “inverse” inference process. Factors can be n-ary (implying only relative data) or a prior (see Prior).
Node More abstract definition to represent either DFG.Factor or DFG.Variable.
Timestamp The best estimate of when an event occurred in real time.
Tags Additional “meta-labels” helping to describe, index, group, or organize information, for example LANDMARK, or POSE.
Initialized Whether a data element has numerical values which are ready to be used by either calc or solve actions.
Marginalized Whether a component should be used or treated as marginalized (i.e. frozen) for solve actions.
Marginal The belief over specific dimensions only.
Belief The probabilistic belief estimate (i.e. and approximate function) of a variable; might also imply measurement process belief is certain situations.
Estimate DO NOT USE. See Belief; note that Estimate does in no way refer to PPE. For parametric estimates see PPE exclusively.
Points Nonparametric points used to construct a Belief.
Solved Whether a component contains numerical values following a successful solve action.
Solvable Integer value used to mark whether certain computations (verb actions) such as solve can be performed; also note this is used as inequality test for all values larger than 0, or 1, etc.
SolveCount Integer value indicating the number of solves that have been done on a specific solve key
Tree A symbolic refactoring of a factor graph object as cliques in an a cyclic graphical structure (also stored as nodes and edges).
Clique A node in the tree representing a subset of variables and factors from the factor graph, adhering to the chordal Bayes net property.
🔴 Cliq will be deprecated in favor of Clique.
Graph Generally referring to a factor graph object, likely a DistributedFactorGraph.jl container type.
PPE Parametric Point Estimates, a product derived from the full marginal estimate of some variable.
Statistics/Stats Higher level abstraction of stochastic values, including variables or factors, likely used for analysis or verification purposes.
Neighbors Variables have factor neighbors andnvisa versa; while 2nd tier neighbors are of the same type, etc.
Prior/Priors Unary factors, that is with only a single variable edge — Algebraic significance is these factors are the only allowable way to introduce so called absolute data about a variable.
varType <: InferenceVariable Variables also have type information which helps describe the manifolds and domains on which the variable exist. Softtypes are not always stringently enforced.
Session A unique name for each sequence of variables and factors (along with metadata) that constitute one session/run of a robot or device.
Robot The unique identifier for each robot or device used.
User A unique identifier for each user.
Data Concept for a Entry=>Blob pair data store that is weakly connected to the actual factor graph object -- i.e. separate store that can be synchronized at user convenience.
Entry Part of an Entry => Blob data pair. Multiple Entrys can be maintained for each Node in the graph as a unique key + meta info such as MIME, description, etc.
Blob Part of an Entry => Blob data pair, where Blob representes an immutable piece of data described by and retrieved from any store by whomever/whatever has the Entry record and authorized + bandwidth access.
Smalldata 🔴 Pollutes the graph, but a convenient way to store a couple of bytes directly in the graph. Use this with caution and keep it small and simple. See JuliaRobotics/DistributedFactorGraphs.jl#509
BigData 🔴 Discontinued, use Data Noun instead.
Summary 🔴 ?
Cache 🔴 Designated operational memory that is likely used during computation or data retrieval, and likely relates to enhancing performance. Cache will likely be copied/duplicated for multi-threading situations without the user being aware that has happened. Cache is likely to have a defined scope which is defined by the solver code such that both performance and code versatility is achieved.
Packed 🔴 Usually a defined type which also acts as a contraction for data interchange, e.g. PackedPose2Pose2.

Adjective (Special)

Adjective Definition
Type
Atomic Various multithreaded operations require atomic operations.
Parametric
Mean
Max
Suggested
Modes

Common Keyword-arguments

keyword Definition
tags Metadata representing tags that help annotate a Noun object.
graphinit Initialize variables (maybe factors too) using distributed factor graph object.
treeinit Initialize variables using Bayes/junction tree derived from distributed factor graph.
solvable 🔴 Integer value used to mark whether certain computations (verb actions) such as solve can be performed; also note this is used as inequality test for all values larger than 0, or 1, etc.
solveKey 🔴 Super-solves key, defaults to mmISAM :default, WIP :parametric
mimeType Format in which data is stored similar to Internet use of mime definitions, most likely relates to Data (aka BigData blobs) -- e.g. image/raw/rgb/672x376.

Deprecation of Struct Fields

Has moved here: http://github.com/JuliaRobotics/IncrementalInference.jl/wiki/Coding-Templates#deprecate-struct-field

Notes:

  • getSofttype returns Symbol, other drivers return full type -- 🔴 DF, this is obsolete and should be dropped in favor of just the getSofttype<:InferenceVariable as hydrated object -- see DFG#237.

Usage Example

Guess we should compile a more standard language here -- something that is consistent and user guesses should be right as frequently as possible. Perhaps functions are aways verbNoun[Special]:

  • getVariable, getVariableIds, getLabel(<:AbstractVariable)
  • getMarginalBelief(<:AbstractDFG, ::Symbol)
    • RESOLVE getMarginalPPE(...) vs getVariablePPE, but both probably fine too.
  • isInitialized!, findVariableNearTimestamp, findFactorNearTimestamp
    • RESOLVE isVariableSolving(..) vs isSolveInProgress(..)
    • I think that's my fault - generally we have used is prefix for boolean operators in Java. That is leading to confusion, it's just best to switch to getVariableSolving.

Can define standard verbs and nouns and populate the matrix between them as where sensible.

Additional Requirements

References

Clone this wiki locally