GTSAM  4.0.2
C++ library for smoothing and mapping (SAM)
Public Types | Public Member Functions | Protected Types | Protected Member Functions | Protected Attributes | List of all members
gtsam::ISAM2 Class Reference

#include <ISAM2.h>

Inheritance diagram for gtsam::ISAM2:
Inheritance graph
[legend]
Collaboration diagram for gtsam::ISAM2:
Collaboration graph
[legend]

Public Types

using This = ISAM2
 This class.
 
using Base = BayesTree< ISAM2Clique >
 The BayesTree base class.
 
using Clique = Base::Clique
 A clique.
 
using sharedClique = Base::sharedClique
 Shared pointer to a clique.
 
using Cliques = Base::Cliques
 List of Cliques.
 
typedef Clique Node
 Synonym for Clique (TODO: remove)
 
typedef sharedClique sharedNode
 Synonym for sharedClique (TODO: remove)
 
typedef ISAM2Clique ::ConditionalType ConditionalType
 
typedef std::shared_ptr< ConditionalType > sharedConditional
 
typedef ISAM2Clique ::BayesNetType BayesNetType
 
typedef std::shared_ptr< BayesNetType > sharedBayesNet
 
typedef ISAM2Clique ::FactorType FactorType
 
typedef std::shared_ptr< FactorType > sharedFactor
 
typedef ISAM2Clique ::FactorGraphType FactorGraphType
 
typedef std::shared_ptr< FactorGraphType > sharedFactorGraph
 
typedef FactorGraphType::Eliminate Eliminate
 
typedef ISAM2Clique ::EliminationTraitsType EliminationTraitsType
 
typedef ConcurrentMap< Key, sharedCliqueNodes
 
typedef FastVector< sharedCliqueRoots
 

Public Member Functions

 ISAM2 (const ISAM2Params &params)
 
 ISAM2 ()
 
virtual ~ISAM2 ()
 
virtual bool equals (const ISAM2 &other, double tol=1e-9) const
 
virtual ISAM2Result update (const NonlinearFactorGraph &newFactors=NonlinearFactorGraph(), const Values &newTheta=Values(), const FactorIndices &removeFactorIndices=FactorIndices(), const std::optional< FastMap< Key, int > > &constrainedKeys={}, const std::optional< FastList< Key > > &noRelinKeys={}, const std::optional< FastList< Key > > &extraReelimKeys={}, bool force_relinearize=false)
 
virtual ISAM2Result update (const NonlinearFactorGraph &newFactors, const Values &newTheta, const ISAM2UpdateParams &updateParams)
 
void marginalizeLeaves (const FastList< Key > &leafKeys, FactorIndices *marginalFactorsIndices=nullptr, FactorIndices *deletedFactorsIndices=nullptr)
 
template<class... OptArgs>
void marginalizeLeaves (const FastList< Key > &leafKeys, OptArgs &&... optArgs)
 
const ValuesgetLinearizationPoint () const
 Access the current linearization point.
 
bool valueExists (Key key) const
 Check whether variable with given key exists in linearization point.
 
Values calculateEstimate () const
 
template<class VALUE >
VALUE calculateEstimate (Key key) const
 
const ValuecalculateEstimate (Key key) const
 
Matrix marginalCovariance (Key key) const
 
Public members for non-typical usage
Values calculateBestEstimate () const
 
const VectorValuesgetDelta () const
 
double error (const VectorValues &x) const
 
const NonlinearFactorGraphgetFactorsUnsafe () const
 
const VariableIndexgetVariableIndex () const
 
const KeySetgetFixedVariables () const
 
const ISAM2Paramsparams () const
 
void printStats () const
 
VectorValues gradientAtZero () const
 
Standard Interface
size_t size () const
 
bool empty () const
 
const Nodesnodes () const
 
sharedClique operator[] (Key j) const
 
const Rootsroots () const
 
const sharedCliqueclique (Key j) const
 
BayesTreeCliqueData getCliqueData () const
 
size_t numCachedSeparatorMarginals () const
 
sharedConditional marginalFactor (Key j, const Eliminate &function=EliminationTraitsType::DefaultEliminate) const
 
sharedFactorGraph joint (Key j1, Key j2, const Eliminate &function=EliminationTraitsType::DefaultEliminate) const
 
sharedBayesNet jointBayesNet (Key j1, Key j2, const Eliminate &function=EliminationTraitsType::DefaultEliminate) const
 
Graph Display
void dot (std::ostream &os, const KeyFormatter &keyFormatter=DefaultKeyFormatter) const
 Output to graphviz format, stream version.
 
std::string dot (const KeyFormatter &keyFormatter=DefaultKeyFormatter) const
 Output to graphviz format string.
 
void saveGraph (const std::string &filename, const KeyFormatter &keyFormatter=DefaultKeyFormatter) const
 output to file with graphviz format.
 

Protected Types

typedef std::shared_ptr< Thisshared_ptr
 

Protected Member Functions

void recalculate (const ISAM2UpdateParams &updateParams, const KeySet &relinKeys, ISAM2Result *result)
 Remove marked top and either recalculate in batch or incrementally.
 
void recalculateBatch (const ISAM2UpdateParams &updateParams, KeySet *affectedKeysSet, ISAM2Result *result)
 
GaussianFactorGraph relinearizeAffectedFactors (const ISAM2UpdateParams &updateParams, const FastList< Key > &affectedKeys, const KeySet &relinKeys)
 
void recalculateIncremental (const ISAM2UpdateParams &updateParams, const KeySet &relinKeys, const FastList< Key > &affectedKeys, KeySet *affectedKeysSet, Cliques *orphans, ISAM2Result *result)
 Perform an incremental update of the factor graph to return a new Bayes Tree with affected keys. More...
 
void addVariables (const Values &newTheta, ISAM2Result::DetailedResults *detail=0)
 
void removeVariables (const KeySet &unusedKeys)
 
void updateDelta (bool forceFullSolve=false) const
 

Protected Attributes

Values theta_
 
VariableIndex variableIndex_
 
VectorValues delta_
 
VectorValues deltaNewton_
 
VectorValues RgProd_
 
KeySet deltaReplacedMask_
 
NonlinearFactorGraph nonlinearFactors_
 
GaussianFactorGraph linearFactors_
 
ISAM2Params params_
 
std::optional< double > doglegDelta_
 
KeySet fixedVariables_
 
int update_count_
 
Nodes nodes_
 
Roots roots_
 

Testable

void print (const std::string &s="", const KeyFormatter &keyFormatter=DefaultKeyFormatter) const
 
bool equals (const This &other, double tol=1e-9) const
 

Advanced Interface

Key findParentClique (const CONTAINER &parents) const
 
void clear ()
 
void deleteCachedShortcuts ()
 
void removePath (sharedClique clique, BayesNetType *bn, Cliques *orphans)
 
void removeTop (const KeyVector &keys, BayesNetType *bn, Cliques *orphans)
 
Cliques removeSubtree (const sharedClique &subtree)
 
void insertRoot (const sharedClique &subtree)
 
void addClique (const sharedClique &clique, const sharedClique &parent_clique=sharedClique())
 
void addFactorsToGraph (FactorGraph< FactorType > *graph) const
 
void getCliqueData (sharedClique clique, BayesTreeCliqueData *stats) const
 
void dot (std::ostream &s, sharedClique clique, const KeyFormatter &keyFormatter, int parentnum=0) const
 
void removeClique (sharedClique clique)
 
void fillNodesIndex (const sharedClique &subtree)
 

Detailed Description

Implementation of the full ISAM2 algorithm for incremental nonlinear optimization.

The typical cycle of using this class to create an instance by providing ISAM2Params to the constructor, then add measurements and variables as they arrive using the update() method. At any time, calculateEstimate() may be called to obtain the current estimate of all variables.

Member Typedef Documentation

◆ Nodes

Map from keys to Clique

◆ Roots

Root cliques

Constructor & Destructor Documentation

◆ ISAM2() [1/2]

gtsam::ISAM2::ISAM2 ( const ISAM2Params params)
explicit

Create an empty ISAM2 instance

◆ ISAM2() [2/2]

gtsam::ISAM2::ISAM2 ( )

Create an empty ISAM2 instance using the default set of parameters (see ISAM2Params)

◆ ~ISAM2()

virtual gtsam::ISAM2::~ISAM2 ( )
inlinevirtual

default virtual destructor

Member Function Documentation

◆ addClique()

void gtsam::BayesTree< ISAM2Clique >::addClique ( const sharedClique clique,
const sharedClique parent_clique = sharedClique() 
)
inherited

add a clique (top down)

◆ addFactorsToGraph()

void gtsam::BayesTree< ISAM2Clique >::addFactorsToGraph ( FactorGraph< FactorType > *  graph) const
inherited

Add all cliques in this BayesTree to the specified factor graph

◆ addVariables()

void gtsam::ISAM2::addVariables ( const Values newTheta,
ISAM2Result::DetailedResults detail = 0 
)
protected

Add new variables to the ISAM2 system.

Parameters
newThetaInitial values for new variables
variableStatusoptional detailed result structure

◆ calculateBestEstimate()

Values gtsam::ISAM2::calculateBestEstimate ( ) const

Compute an estimate using a complete delta computed by a full back-substitution.

◆ calculateEstimate() [1/3]

Values gtsam::ISAM2::calculateEstimate ( ) const

Compute an estimate from the incomplete linear delta computed during the last update. This delta is incomplete because it was not updated below wildfire_threshold. If only a single variable is needed, it is faster to call calculateEstimate(const KEY&).

◆ calculateEstimate() [2/3]

template<class VALUE >
VALUE gtsam::ISAM2::calculateEstimate ( Key  key) const
inline

Compute an estimate for a single variable using its incomplete linear delta computed during the last update. This is faster than calling the no-argument version of calculateEstimate, which operates on all variables.

Parameters
key
Returns

◆ calculateEstimate() [3/3]

const Value& gtsam::ISAM2::calculateEstimate ( Key  key) const

Compute an estimate for a single variable using its incomplete linear delta computed during the last update. This is faster than calling the no-argument version of calculateEstimate, which operates on all variables. This is a non-templated version that returns a Value base class for use with the MATLAB wrapper.

Parameters
key
Returns

◆ clear()

void gtsam::BayesTree< ISAM2Clique >::clear ( )
inherited

Remove all nodes

◆ clique()

const sharedClique& gtsam::BayesTree< ISAM2Clique >::clique ( Key  j) const
inlineinherited

alternate syntax for matlab: find the clique that contains the variable with Key j

◆ deleteCachedShortcuts()

void gtsam::BayesTree< ISAM2Clique >::deleteCachedShortcuts ( )
inherited

Clear all shortcut caches - use before timing on marginal calculation to avoid residual cache data

◆ dot()

void gtsam::BayesTree< ISAM2Clique >::dot ( std::ostream &  s,
sharedClique  clique,
const KeyFormatter keyFormatter,
int  parentnum = 0 
) const
protectedinherited

private helper method for saving the Tree to a text file in GraphViz format

◆ empty()

bool gtsam::BayesTree< ISAM2Clique >::empty ( ) const
inlineinherited

Check if there are any cliques in the tree

◆ equals() [1/2]

virtual bool gtsam::ISAM2::equals ( const ISAM2 other,
double  tol = 1e-9 
) const
virtual

Compare equality

◆ equals() [2/2]

bool gtsam::BayesTree< ISAM2Clique >::equals ( const This other,
double  tol = 1e-9 
) const
protectedinherited

check equality

◆ error()

double gtsam::ISAM2::error ( const VectorValues x) const

Compute the linear error

◆ fillNodesIndex()

void gtsam::BayesTree< ISAM2Clique >::fillNodesIndex ( const sharedClique subtree)
protectedinherited

Fill the nodes index for a subtree

◆ findParentClique()

Key gtsam::BayesTree< ISAM2Clique >::findParentClique ( const CONTAINER &  parents) const
inherited

Find parent clique of a conditional. It will look at all parents and return the one with the lowest index in the ordering.

◆ getCliqueData() [1/2]

BayesTreeCliqueData gtsam::BayesTree< ISAM2Clique >::getCliqueData ( ) const
inherited

Gather data on all cliques

◆ getCliqueData() [2/2]

void gtsam::BayesTree< ISAM2Clique >::getCliqueData ( sharedClique  clique,
BayesTreeCliqueData stats 
) const
protectedinherited

Gather data on a single clique

◆ getDelta()

const VectorValues& gtsam::ISAM2::getDelta ( ) const

Access the current delta, computed during the last call to update

◆ getFactorsUnsafe()

const NonlinearFactorGraph& gtsam::ISAM2::getFactorsUnsafe ( ) const
inline

Access the set of nonlinear factors

◆ getFixedVariables()

const KeySet& gtsam::ISAM2::getFixedVariables ( ) const
inline

Access the nonlinear variable index

◆ getVariableIndex()

const VariableIndex& gtsam::ISAM2::getVariableIndex ( ) const
inline

Access the nonlinear variable index

◆ gradientAtZero()

VectorValues gtsam::ISAM2::gradientAtZero ( ) const

Compute the gradient of the energy function, \( \nabla_{x=0} \left\Vert \Sigma^{-1} R x - d \right\Vert^2 \), centered around zero. The gradient about zero is \( -R^T d \). See also gradient(const GaussianBayesNet&, const VectorValues&).

Returns
A VectorValues storing the gradient.

◆ insertRoot()

void gtsam::BayesTree< ISAM2Clique >::insertRoot ( const sharedClique subtree)
inherited

Insert a new subtree with known parent clique. This function does not check that the specified parent is the correct parent. This function updates all of the internal data structures associated with adding a subtree, such as populating the nodes index.

◆ joint()

BayesTree< ISAM2Clique >::sharedFactorGraph gtsam::BayesTree< ISAM2Clique >::joint ( Key  j1,
Key  j2,
const Eliminate &  function = EliminationTraitsType::DefaultEliminate 
) const
inherited

return joint on two variables Limitation: can only calculate joint if cliques are disjoint or one of them is root

◆ jointBayesNet()

BayesTree< ISAM2Clique >::sharedBayesNet gtsam::BayesTree< ISAM2Clique >::jointBayesNet ( Key  j1,
Key  j2,
const Eliminate &  function = EliminationTraitsType::DefaultEliminate 
) const
inherited

return joint on two variables as a BayesNet Limitation: can only calculate joint if cliques are disjoint or one of them is root

◆ marginalCovariance()

Matrix gtsam::ISAM2::marginalCovariance ( Key  key) const

Return marginal on any variable as a covariance matrix

◆ marginalFactor()

BayesTree< ISAM2Clique >::sharedConditional gtsam::BayesTree< ISAM2Clique >::marginalFactor ( Key  j,
const Eliminate &  function = EliminationTraitsType::DefaultEliminate 
) const
inherited

Return marginal on any variable. Note that this actually returns a conditional, for which a solution may be directly obtained by calling .solve() on the returned object. Alternatively, it may be directly used as its factor base class. For example, for Gaussian systems, this returns a GaussianConditional, which inherits from JacobianFactor and GaussianFactor.

◆ marginalizeLeaves() [1/2]

void gtsam::ISAM2::marginalizeLeaves ( const FastList< Key > &  leafKeys,
FactorIndices marginalFactorsIndices = nullptr,
FactorIndices deletedFactorsIndices = nullptr 
)

Marginalize out variables listed in leafKeys. These keys must be leaves in the BayesTree. Throws MarginalizeNonleafException if non-leaves are requested to be marginalized. Marginalization leaves a linear approximation of the marginal in the system, and the linearization points of any variables involved in this linear marginal become fixed. The set fixed variables will include any key involved with the marginalized variables in the original factors, and possibly additional ones due to fill-in.

If provided, 'marginalFactorsIndices' will be augmented with the factor graph indices of the marginal factors added during the 'marginalizeLeaves' call

If provided, 'deletedFactorsIndices' will be augmented with the factor graph indices of any factor that was removed during the 'marginalizeLeaves' call

◆ marginalizeLeaves() [2/2]

template<class... OptArgs>
void gtsam::ISAM2::marginalizeLeaves ( const FastList< Key > &  leafKeys,
OptArgs &&...  optArgs 
)
inline

An overload of marginalizeLeaves that takes references to vectors instead of pointers to vectors and passes it to the pointer version of the function.

◆ nodes()

const Nodes& gtsam::BayesTree< ISAM2Clique >::nodes ( ) const
inlineinherited

Return nodes. Each node is a clique of variables obtained after elimination.

◆ numCachedSeparatorMarginals()

size_t gtsam::BayesTree< ISAM2Clique >::numCachedSeparatorMarginals ( ) const
inherited

Collect number of cliques with cached separator marginals

◆ operator[]()

sharedClique gtsam::BayesTree< ISAM2Clique >::operator[] ( Key  j) const
inlineinherited

Access node by variable

◆ print()

void gtsam::BayesTree< ISAM2Clique >::print ( const std::string &  s = "",
const KeyFormatter keyFormatter = DefaultKeyFormatter 
) const
inherited

print

◆ printStats()

void gtsam::ISAM2::printStats ( ) const
inline

prints out clique statistics

◆ recalculateIncremental()

void gtsam::ISAM2::recalculateIncremental ( const ISAM2UpdateParams updateParams,
const KeySet relinKeys,
const FastList< Key > &  affectedKeys,
KeySet affectedKeysSet,
Cliques orphans,
ISAM2Result result 
)
protected

Perform an incremental update of the factor graph to return a new Bayes Tree with affected keys.

Parameters
updateParamsParameters for the ISAM2 update.
relinKeysKeys of variables to relinearize.
affectedKeysThe set of keys which are affected in the update.
affectedKeysSet[output] Affected and contaminated keys.
orphans[output] List of orphanes cliques after elimination.
result[output] The result of the incremental update step.

◆ removeClique()

void gtsam::BayesTree< ISAM2Clique >::removeClique ( sharedClique  clique)
protectedinherited

remove a clique: warning, can result in a forest

◆ removePath()

void gtsam::BayesTree< ISAM2Clique >::removePath ( sharedClique  clique,
BayesNetType *  bn,
Cliques orphans 
)
inherited

Remove path from clique to root and return that path as factors plus a list of orphaned subtree roots. Used in removeTop below.

◆ removeSubtree()

BayesTree< ISAM2Clique >::Cliques gtsam::BayesTree< ISAM2Clique >::removeSubtree ( const sharedClique subtree)
inherited

Remove the requested subtree.

◆ removeTop()

void gtsam::BayesTree< ISAM2Clique >::removeTop ( const KeyVector keys,
BayesNetType *  bn,
Cliques orphans 
)
inherited

Given a list of indices, turn "contaminated" part of the tree back into a factor graph. Factors and orphans are added to the in/out arguments.

◆ removeVariables()

void gtsam::ISAM2::removeVariables ( const KeySet unusedKeys)
protected

Remove variables from the ISAM2 system.

◆ roots()

const Roots& gtsam::BayesTree< ISAM2Clique >::roots ( ) const
inlineinherited

return root cliques

◆ size()

size_t gtsam::BayesTree< ISAM2Clique >::size ( ) const
inherited

number of cliques

◆ update() [1/2]

virtual ISAM2Result gtsam::ISAM2::update ( const NonlinearFactorGraph newFactors = NonlinearFactorGraph(),
const Values newTheta = Values(),
const FactorIndices removeFactorIndices = FactorIndices(),
const std::optional< FastMap< Key, int > > &  constrainedKeys = {},
const std::optional< FastList< Key > > &  noRelinKeys = {},
const std::optional< FastList< Key > > &  extraReelimKeys = {},
bool  force_relinearize = false 
)
virtual

Add new factors, updating the solution and relinearizing as needed.

Optionally, this function remove existing factors from the system to enable behaviors such as swapping existing factors with new ones.

Add new measurements, and optionally new variables, to the current system. This runs a full step of the ISAM2 algorithm, relinearizing and updating the solution as needed, according to the wildfire and relinearize thresholds.

Parameters
newFactorsThe new factors to be added to the system
newThetaInitialization points for new variables to be added to the system. You must include here all new variables occuring in newFactors (which were not already in the system). There must not be any variables here that do not occur in newFactors, and additionally, variables that were already in the system must not be included here.
removeFactorIndicesIndices of factors to remove from system
force_relinearizeRelinearize any variables whose delta magnitude is sufficiently large (Params::relinearizeThreshold), regardless of the relinearization interval (Params::relinearizeSkip).
constrainedKeysis an optional map of keys to group labels, such that a variable can be constrained to a particular grouping in the BayesTree
noRelinKeysis an optional set of nonlinear keys that iSAM2 will hold at a constant linearization point, regardless of the size of the linear delta
extraReelimKeysis an optional set of nonlinear keys that iSAM2 will re-eliminate, regardless of the size of the linear delta. This allows the provided keys to be reordered.
Returns
An ISAM2Result struct containing information about the update

◆ update() [2/2]

virtual ISAM2Result gtsam::ISAM2::update ( const NonlinearFactorGraph newFactors,
const Values newTheta,
const ISAM2UpdateParams updateParams 
)
virtual

Add new factors, updating the solution and relinearizing as needed.

Alternative signature of update() (see its documentation above), with all additional parameters in one structure. This form makes easier to keep future API/ABI compatibility if parameters change.

Parameters
newFactorsThe new factors to be added to the system
newThetaInitialization points for new variables to be added to the system. You must include here all new variables occuring in newFactors (which were not already in the system). There must not be any variables here that do not occur in newFactors, and additionally, variables that were already in the system must not be included here.
updateParamsAdditional parameters to control relinearization, constrained keys, etc.
Returns
An ISAM2Result struct containing information about the update
Note
No default parameters to avoid ambiguous call errors.

Member Data Documentation

◆ delta_

VectorValues gtsam::ISAM2::delta_
mutableprotected

The linear delta from the last linear solution, an update to the estimate in theta

This is mutable because it is a "cached" variable - it is not updated until either requested with getDelta() or calculateEstimate(), or needed during update() to evaluate whether to relinearize variables.

◆ deltaReplacedMask_

KeySet gtsam::ISAM2::deltaReplacedMask_
mutableprotected

A cumulative mask for the variables that were replaced and have not yet been updated in the linear solution delta_, this is only used internally, delta will always be updated if necessary when requested with getDelta() or calculateEstimate().

This is mutable because it is used internally to not update delta_ until it is needed.

◆ doglegDelta_

std::optional<double> gtsam::ISAM2::doglegDelta_
mutableprotected

The current Dogleg Delta (trust region radius)

◆ fixedVariables_

KeySet gtsam::ISAM2::fixedVariables_
protected

Set of variables that are involved with linear factors from marginalized variables and thus cannot have their linearization points changed.

◆ linearFactors_

GaussianFactorGraph gtsam::ISAM2::linearFactors_
mutableprotected

The current linear factors, which are only updated as needed

◆ nodes_

Nodes gtsam::BayesTree< ISAM2Clique >::nodes_
protectedinherited

Map from indices to Clique

◆ nonlinearFactors_

NonlinearFactorGraph gtsam::ISAM2::nonlinearFactors_
protected

All original nonlinear factors are stored here to use during relinearization

◆ params_

ISAM2Params gtsam::ISAM2::params_
protected

The current parameters

◆ roots_

Roots gtsam::BayesTree< ISAM2Clique >::roots_
protectedinherited

Root cliques

◆ theta_

Values gtsam::ISAM2::theta_
protected

The current linearization point

◆ update_count_

int gtsam::ISAM2::update_count_
protected

Counter incremented every update(), used to determine periodic relinearization

◆ variableIndex_

VariableIndex gtsam::ISAM2::variableIndex_
protected

VariableIndex lets us look up factors by involved variable and keeps track of dimensions


The documentation for this class was generated from the following file: