Skip to content

Standard Definitions of API via verbNoun structure

Jump to bottom
Johannes Terblanche edited this page Jun 12, 2025 · 5 revisions

Copyright NavAbility(TM) Contributors (2019-2025).

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

Below we define the meaning and usage of all available verbs and Nouns, enabling the user to interpolate their desired functions by following the standard structure. Adjectives are optional, and API is camelCase. 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)
lsf(::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. Once ratified, API v1.0 is intended to be an LTS specification.

verb (Action) DFG 1.0

verb Definition
add*[!] Add the value at a given key if it doesn't exist (strict add) or return Typed error if already existing
append*[!] Add to the end of collection A the elements of collection B.
build Construct a structure from inputs and available data.
calc Return a result from numerical calculations
delete*! Remove key [and data] at a given key if it exist. Return number of nodes deleted.
empty*! Remove all elements from a collection.
get Access memory for field of struct.
Return the value stored for the given key (by reference if possible) or Typed error if does not exist
generate Construct a structure from pre-defined generation logic with minimal input.
has Return ::Bool on whether given individual element exists inside the given collection object.
list
ls
lsf 		List the labels of an existing (composite) data container/object.
listvariables shorthand
listfactors shorthand
merge*[!] Construct a merged collection from the given collections. Has to be collections or fails. 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 (Julia Convention) (aka Git Accept Incoming Change). Returns number of nodes added/changed.
plot Visualize data structure
pull*[!] Asynchronous get. Returns event/future/promise.
push*[!] Asynchronous add. Will fail if exists. Returns event/future/promise.
load Load data from persistent storage (local or cloud in Blobstore/Blobentry). No default.
save Save data to persistent storage (local or cloud in Blobstore/Blobentry). No default.
set*! Set new memory location for field of struct (mutables only). Limited export. Overwrites always. Can remove children/dereference. (Strongest action. Be careful)
sync*! Set and/or merge complex data structures. Flags: Keep Current/AcceptIncoming (Can sync partial structures if given filters as input)
show
print
display 		Prints various text representations of object
solve*! Perform inference operations, either through stochastic or parametric means.
pack Serialization of object into a defined Packed structure.
unpack Deserialization of object from a defined Packed structure to original structure.
tally Calculates value of countable field (ex. number of solves completed)
union*[!] Dispatches JuliaCore union.

verb (Action) -- Reserved with no current use

verb Definition
copy
find
update*!
view
join*[!]
accumulate*[!] *Check accumulateFactorMeans
execute*!
draw *See Issue 1132
parch

Noun (Object)

Noun Definition
Agent Entity interacting with factor graph, i.e. external data provider or requester.
Belief The probabilistic belief estimate (i.e. and approximate function) of a variable; might also imply measurement process belief in certain situations.
Blobentry Part of Blobentry => Blob data pair. Reference and metadata used to retrieve Blobs/ slices of Blobs from Blobstore. Variables/factors can contain multiple entries with each entry given a unique key + meta info such as MIME, description, etc.
Blob Part of Blobentry => Blob data pair. Blob is an immutable large piece of data.
Blobstore Collection of Blobs.
Clique Node of Bayes Tree that represents a subset of variables and factors adhering to the chordal Bayes Net property.
Factor Algebraic structure (i.e. functions) that models how different variables are related to each other with a stochastic uncertainty model. 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).
Graph Factor graph object.
Label A single identifier that is unique within a collection
Metadata Storage for a couple of bytes directly in the graph. Use with caution and keep it small and simple.
Neighbors List of Variables or Factors connected to input. Variables have factor neighbors and vice versa; while 2nd tier neighbors are of the same type, etc.
Neighborhood List of neighboring variables/factors for a given depth.
Observation
Packed Internal use noun for serialization, e.g. PackedPose2Pose2.
Prior Unary factor, 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.
Points Nonparametric points used to construct a Belief.
State Fields and collections that fully describe a variable/factor. Different solves create different states within a variable, each referenced by a unique Label.
Solvable Integer value used to mark whether certain computations (verb actions) such as solve should be performed; also note this is an inequality test for all values larger than itself.
Solves Integer value indicating the number of solves that have been done on a specific state label
Tags Additional “meta-labels” helping to describe, index, group, or organize information, for example LANDMARK, or POSE.
Timestamp The best estimate of when an event occurred in real time.
Tree A symbolic refactoring of a factor graph object as cliques in an a cyclic graphical structure (also stored as nodes and edges).
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.
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).

Noun (Object) -- Open Issues

Noun Issue
PPE *See #1133
Estimate
Data *See #1121

Adjective (Special)

Adjective Definition
Type
Atomic Various multithreaded operations require atomic operations.
Parametric
Mean
Max
Suggested
Modes
Modes
Order
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.

Common Keyword-arguments

keyword Definition
graphinit Initialize variables (maybe factors too) using distributed factor graph object.
treeinit Initialize variables using Bayes/junction tree derived from distributed factor graph.
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.

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.

References

Clone this wiki locally