From f7865c80b16b7bcaa53d220e3d8a849917197c38 Mon Sep 17 00:00:00 2001 From: Nick Barrash Date: Mon, 23 Jan 2012 19:54:45 +0000 Subject: [PATCH] added comment groupings to inference --- gtsam/inference/BayesNet.h | 137 +++++++++++--------- gtsam/inference/BayesTree.h | 113 ++++++++-------- gtsam/inference/BayesTreeCliqueBase.h | 93 ++++++++----- gtsam/inference/ClusterTree.h | 54 +++++--- gtsam/inference/Conditional.h | 61 ++++++--- gtsam/inference/EliminationTree.h | 39 ++++-- gtsam/inference/Factor.h | 75 +++++++---- gtsam/inference/FactorGraph.h | 42 +++++- gtsam/inference/GenericMultifrontalSolver.h | 10 ++ gtsam/inference/GenericSequentialSolver.h | 14 ++ gtsam/inference/ISAM.h | 16 ++- gtsam/inference/IndexConditional.h | 19 +++ gtsam/inference/IndexFactor.h | 36 +++-- gtsam/inference/JunctionTree.h | 25 +++- gtsam/inference/Permutation.h | 62 ++++++--- gtsam/inference/SymbolicFactorGraph.h | 42 ++++-- gtsam/inference/VariableIndex.h | 54 ++++++-- gtsam/inference/VariableSlots.h | 11 ++ 18 files changed, 626 insertions(+), 277 deletions(-) diff --git a/gtsam/inference/BayesNet.h b/gtsam/inference/BayesNet.h index 672d9a4e8..684e28ae0 100644 --- a/gtsam/inference/BayesNet.h +++ b/gtsam/inference/BayesNet.h @@ -38,6 +38,7 @@ namespace gtsam { * * todo: Symbolic using Index is a misnomer. * todo: how to handle Bayes nets with an optimize function? Currently using global functions. + * \nosubgrouping */ template class BayesNet { @@ -67,18 +68,52 @@ protected: public: + /// @name Standard Constructors + /// @{ + /** Default constructor as an empty BayesNet */ BayesNet() {}; /** BayesNet with 1 conditional */ BayesNet(const sharedConditional& conditional) { push_back(conditional); } + /// @} + /// @name Testable + /// @{ + /** print */ void print(const std::string& s = "") const; /** check equality */ bool equals(const BayesNet& other, double tol = 1e-9) const; + /// @} + /// @name Standard Interface + /// @{ + + /** size is the number of nodes */ + size_t size() const { + return conditionals_.size(); + } + + /** return keys in reverse topological sort order, i.e., elimination order */ + FastList ordering() const; + + /** SLOW O(n) random access to Conditional by key */ + sharedConditional operator[](Index key) const; + + /** return last node in ordering */ + boost::shared_ptr front() const { return conditionals_.front(); } + + /** return last node in ordering */ + boost::shared_ptr back() const { return conditionals_.back(); } + + /** return iterators. FD: breaks encapsulation? */ + const_iterator begin() const {return conditionals_.begin();} /// ordering() const; - - /** SLOW O(n) random access to Conditional by key */ - sharedConditional operator[](Index key) const; - - /** return last node in ordering */ - sharedConditional& front() { return conditionals_.front(); } - - /** return last node in ordering */ - boost::shared_ptr front() const { return conditionals_.front(); } - - /** return last node in ordering */ - sharedConditional& back() { return conditionals_.back(); } - - /** return last node in ordering */ - boost::shared_ptr back() const { return conditionals_.back(); } - - /** return iterators. FD: breaks encapsulation? */ - const_iterator begin() const {return conditionals_.begin();} - const_iterator end() const {return conditionals_.end();} - const_reverse_iterator rbegin() const {return conditionals_.rbegin();} - const_reverse_iterator rend() const {return conditionals_.rend();} - iterator begin() {return conditionals_.begin();} - iterator end() {return conditionals_.end();} - reverse_iterator rbegin() {return conditionals_.rbegin();} - reverse_iterator rend() {return conditionals_.rend();} + iterator begin() {return conditionals_.begin();} /// > class BayesTree { @@ -128,12 +129,19 @@ namespace gtsam { public: + /// @name Standard Constructors + /// @{ + /** Create an empty Bayes Tree */ BayesTree(); /** Create a Bayes Tree from a Bayes Net */ BayesTree(const BayesNet& bayesNet); + /// @} + /// @name Advanced Constructors + /// @{ + /** * Create a Bayes Tree from a Bayes Net and some subtrees. The Bayes net corresponds to the * new root clique and the subtrees are connected to the root clique. @@ -143,53 +151,19 @@ namespace gtsam { /** Destructor */ virtual ~BayesTree() {} - /** - * Constructing Bayes trees - */ - - /** Insert a new conditional - * This function only applies for Symbolic case with IndexCondtional, - * We make it static so that it won't be compiled in GaussianConditional case. - * */ - static void insert(BayesTree& bayesTree, const sharedConditional& conditional); - - /** - * Insert a new clique corresponding to the given Bayes net. - * It is the caller's responsibility to decide whether the given Bayes net is a valid clique, - * i.e. all the variables (frontal and separator) are connected - */ - sharedClique insert(const sharedConditional& clique, - std::list& children, bool isRootClique = false); - - /** - * Hang a new subtree off of the existing tree. This finds the appropriate - * parent clique for the subtree (which may be the root), and updates the - * nodes index with the new cliques in the subtree. None of the frontal - * variables in the subtree may appear in the separators of the existing - * BayesTree. - */ - void insert(const sharedClique& subtree); - - /** - * Querying Bayes trees - */ + /// @} + /// @name Testable + /// @{ /** check equality */ bool equals(const BayesTree& other, double tol = 1e-9) const; - void cloneTo(shared_ptr& newTree) const { - cloneTo(newTree, root(), sharedClique()); - } + /** print */ + void print(const std::string& s = "") const; - private: - /** deep copy from another tree */ - void cloneTo(shared_ptr& newTree, const sharedClique& subtree, const sharedClique& parent) const { - sharedClique newClique(subtree->clone()); - newTree->addClique(newClique, parent); - BOOST_FOREACH(const sharedClique& childClique, subtree->children()) { - cloneTo(newTree, childClique, newClique); - } - } + /// @} + /// @name Standard Interface + /// @{ public: @@ -214,9 +188,6 @@ namespace gtsam { /** return root clique */ const sharedClique& root() const { return root_; } - /** Access the root clique (non-const version) */ - sharedClique& root() { return root_; } - /** find the clique to which key belongs */ sharedClique operator[](Index key) const { return nodes_.at(key); @@ -245,15 +216,15 @@ namespace gtsam { * Read only with side effects */ - /** print */ - void print(const std::string& s = "") const; - /** saves the Tree to a text file in GraphViz format */ void saveGraph(const std::string& s) const; - /** - * Altering Bayes trees - */ + /// @} + /// @name Advanced Interface + /// @{ + + /** Access the root clique (non-const version) */ + sharedClique& root() { return root_; } /** Remove all nodes */ void clear(); @@ -271,7 +242,45 @@ namespace gtsam { template void removeTop(const CONTAINER& keys, BayesNet& bn, Cliques& orphans); + /** + * Hang a new subtree off of the existing tree. This finds the appropriate + * parent clique for the subtree (which may be the root), and updates the + * nodes index with the new cliques in the subtree. None of the frontal + * variables in the subtree may appear in the separators of the existing + * BayesTree. + */ + void insert(const sharedClique& subtree); + + /** Insert a new conditional + * This function only applies for Symbolic case with IndexCondtional, + * We make it static so that it won't be compiled in GaussianConditional case. + * */ + static void insert(BayesTree& bayesTree, const sharedConditional& conditional); + + /** + * Insert a new clique corresponding to the given Bayes net. + * It is the caller's responsibility to decide whether the given Bayes net is a valid clique, + * i.e. all the variables (frontal and separator) are connected + */ + sharedClique insert(const sharedConditional& clique, + std::list& children, bool isRootClique = false); + + ///TODO: comment + void cloneTo(shared_ptr& newTree) const { + cloneTo(newTree, root(), sharedClique()); + } + private: + + /** deep copy from another tree */ + void cloneTo(shared_ptr& newTree, const sharedClique& subtree, const sharedClique& parent) const { + sharedClique newClique(subtree->clone()); + newTree->addClique(newClique, parent); + BOOST_FOREACH(const sharedClique& childClique, subtree->children()) { + cloneTo(newTree, childClique, newClique); + } + } + /** Serialization function */ friend class boost::serialization::access; template @@ -280,6 +289,8 @@ namespace gtsam { ar & BOOST_SERIALIZATION_NVP(root_); } + /// @} + }; // BayesTree diff --git a/gtsam/inference/BayesTreeCliqueBase.h b/gtsam/inference/BayesTreeCliqueBase.h index 75bf86449..08427bae4 100644 --- a/gtsam/inference/BayesTreeCliqueBase.h +++ b/gtsam/inference/BayesTreeCliqueBase.h @@ -41,6 +41,7 @@ namespace gtsam { * * @tparam DERIVED The derived clique type. * @tparam CONDITIONAL The conditional type. + * \nosubgrouping */ template struct BayesTreeCliqueBase { @@ -58,7 +59,9 @@ namespace gtsam { typedef typename FactorGraph::Eliminate Eliminate; protected: - void assertInvariants() const; + + /// @name Standard Constructors + /// @{ /** Default constructor */ BayesTreeCliqueBase() {} @@ -69,11 +72,57 @@ namespace gtsam { /** Construct from an elimination result, which is a pair */ BayesTreeCliqueBase(const std::pair >& result); + /// @} + public: sharedConditional conditional_; derived_weak_ptr parent_; std::list children_; + /// @name Testable + /// @{ + + /** check equality */ + bool equals(const This& other, double tol=1e-9) const { + return (!conditional_ && !other.conditional()) || + conditional_->equals(*other.conditional(), tol); + } + + /** print this node */ + void print(const std::string& s = "") const; + + /** print this node and entire subtree below it */ + void printTree(const std::string& indent="") const; + + /// @} + /// @name Standard Interface + /// @{ + + /** Access the conditional */ + const sharedConditional& conditional() const { return conditional_; } + + /** is this the root of a Bayes tree ? */ + inline bool isRoot() const { return parent_.expired(); } + + /** The size of subtree rooted at this clique, i.e., nr of Cliques */ + size_t treeSize() const; + + /** The arrow operator accesses the conditional */ + const ConditionalType* operator->() const { return conditional_.get(); } + + ///TODO: comment + const std::list& children() const { return children_; } + + /// @} + /// @name Advanced Interface + /// @{ + + /** The arrow operator accesses the conditional */ + ConditionalType* operator->() { return conditional_.get(); } + + /** return the const reference of children */ + std::list& children() { return children_; } + /** Construct shared_ptr from a conditional, leaving parent and child pointers uninitialized */ static derived_ptr Create(const sharedConditional& conditional) { return boost::make_shared(conditional); } @@ -82,34 +131,10 @@ namespace gtsam { * types, such as ISAM2Clique, the factor part is kept as a cached factor. * @param An elimination result, which is a pair */ - static derived_ptr Create(const std::pair >& result) { return boost::make_shared(result); } + static derived_ptr Create(const std::pair >& result) { return boost::make_shared(result); } - derived_ptr clone() const { return Create(sharedConditional(new ConditionalType(*conditional_))); } - - /** print this node */ - void print(const std::string& s = "") const; - - /** The arrow operator accesses the conditional */ - const ConditionalType* operator->() const { return conditional_.get(); } - - /** The arrow operator accesses the conditional */ - ConditionalType* operator->() { return conditional_.get(); } - - /** Access the conditional */ - const sharedConditional& conditional() const { return conditional_; } - - /** is this the root of a Bayes tree ? */ - inline bool isRoot() const { return parent_.expired(); } - - /** return the const reference of children */ - std::list& children() { return children_; } - const std::list& children() const { return children_; } - - /** The size of subtree rooted at this clique, i.e., nr of Cliques */ - size_t treeSize() const; - - /** print this node and entire subtree below it */ - void printTree(const std::string& indent="") const; + ///TODO: comment + derived_ptr clone() const { return Create(sharedConditional(new ConditionalType(*conditional_))); } /** Permute the variables in the whole subtree rooted at this clique */ void permuteWithInverse(const Permutation& inversePermutation); @@ -131,13 +156,13 @@ namespace gtsam { /** return the joint P(C1,C2), where C1==this. TODO: not a method? */ FactorGraph joint(derived_ptr C2, derived_ptr root, Eliminate function); - bool equals(const This& other, double tol=1e-9) const { - return (!conditional_ && !other.conditional()) || - conditional_->equals(*other.conditional(), tol); - } - friend class BayesTree; + protected: + + ///TODO: comment + void assertInvariants() const; + private: /** Serialization function */ friend class boost::serialization::access; @@ -148,6 +173,8 @@ namespace gtsam { ar & BOOST_SERIALIZATION_NVP(children_); } + /// @} + }; // \struct Clique template diff --git a/gtsam/inference/ClusterTree.h b/gtsam/inference/ClusterTree.h index d72c0fcdf..7544587c1 100644 --- a/gtsam/inference/ClusterTree.h +++ b/gtsam/inference/ClusterTree.h @@ -33,6 +33,7 @@ namespace gtsam { * A cluster-tree is associated with a factor graph and is defined as in Koller-Friedman: * each node k represents a subset C_k \sub X, and the tree is family preserving, in that * each factor f_i is associated with a single cluster and scope(f_i) \sub C_k. + * \nosubgrouping */ template class ClusterTree { @@ -56,57 +57,78 @@ namespace gtsam { public: - // Construct empty clique + /// Construct empty clique Cluster() {} - /* Create a node with a single frontal variable */ + /** Create a node with a single frontal variable */ template Cluster(const FG& fg, Index key, Iterator firstSeparator, Iterator lastSeparator); - /* Create a node with several frontal variables */ + /** Create a node with several frontal variables */ template Cluster(const FG& fg, FRONTALIT firstFrontal, FRONTALIT lastFrontal, SEPARATORIT firstSeparator, SEPARATORIT lastSeparator); - /* Create a node with several frontal variables */ + /** Create a node with several frontal variables */ template Cluster(FRONTALIT firstFrontal, FRONTALIT lastFrontal, SEPARATORIT firstSeparator, SEPARATORIT lastSeparator); - // print the object + /// print void print(const std::string& indent) const; + + /// print the enire tree void printTree(const std::string& indent) const; - // check equality + /// check equality bool equals(const Cluster& other) const; - // get or set the parent - weak_ptr& parent() { return parent_; } - - // get a reference to the children + /// get a reference to the children const std::list& children() const { return children_; } - // add a child + /// add a child void addChild(shared_ptr child); + + /// get or set the parent + weak_ptr& parent() { return parent_; } + }; - // typedef for shared pointers to clusters + /// @name Advanced Interface + /// @{ + + /// typedef for shared pointers to clusters typedef typename Cluster::shared_ptr sharedCluster; - // Root cluster + /// Root cluster sharedCluster root_; public: - // constructor of empty tree + + /// @} + /// @name Standard Constructors + /// @{ + + /// constructor of empty tree ClusterTree() {} - // return the root cluster + /// @} + /// @name Standard Interface + /// @{ + + /// return the root cluster sharedCluster root() const { return root_; } - // print the object + /// @} + /// @name Testable + /// @{ + + /// print the object void print(const std::string& str="") const; /** check equality */ bool equals(const ClusterTree& other, double tol = 1e-9) const; + /// @} + }; // ClusterTree } // namespace gtsam diff --git a/gtsam/inference/Conditional.h b/gtsam/inference/Conditional.h index 1d6d07303..2fa5f691d 100644 --- a/gtsam/inference/Conditional.h +++ b/gtsam/inference/Conditional.h @@ -36,6 +36,7 @@ namespace gtsam { * Derived classes *must* redefine the Factor and shared_ptr typedefs to refer * to the associated factor type and shared_ptr type of the derived class. See * IndexConditional and GaussianConditional for examples. + * \nosubgrouping */ template class Conditional: public gtsam::Factor { @@ -87,6 +88,9 @@ public: /** View of the separator keys (call parents()) */ typedef boost::iterator_range Parents; + /// @name Standard Constructors + /// @{ + /** Empty Constructor to make serialization possible */ Conditional() : nrFrontals_(0) { assertInvariants(); } @@ -102,6 +106,10 @@ public: /** Three parents */ Conditional(Key key, Key parent1, Key parent2, Key parent3) : FactorType(key, parent1, parent2, parent3), nrFrontals_(1) { assertInvariants(); } + /// @} + /// @name Advanced Constructors + /// @{ + /** Constructor from a frontal variable and a vector of parents */ Conditional(Key key, const std::vector& parents) : FactorType(MakeKeys(key, parents.begin(), parents.end())), nrFrontals_(1) { @@ -114,11 +122,22 @@ public: assertInvariants(); } + /// @} + /// @name Testable + /// @{ + + /** print */ + void print(const std::string& s = "Conditional") const; + /** check equality */ template bool equals(const DERIVED& c, double tol = 1e-9) const { return nrFrontals_ == c.nrFrontals_ && FactorType::equals(c, tol); } + /// @} + /// @name Standard Interface + /// @{ + /** return the number of frontals */ size_t nrFrontals() const { return nrFrontals_; } @@ -129,20 +148,6 @@ public: Key firstFrontalKey() const { assert(nrFrontals_>0); return FactorType::front(); } Key lastFrontalKey() const { assert(nrFrontals_>0); return *(endFrontals()-1); } - /** Iterators over frontal and parent variables. */ - const_iterator beginFrontals() const { return FactorType::begin(); } - const_iterator endFrontals() const { return FactorType::begin()+nrFrontals_; } - const_iterator beginParents() const { return FactorType::begin()+nrFrontals_; } - const_iterator endParents() const { return FactorType::end(); } - - /** Mutable iterators and accessors */ - iterator beginFrontals() { return FactorType::begin(); } - iterator endFrontals() { return FactorType::begin()+nrFrontals_; } - iterator beginParents() { return FactorType::begin()+nrFrontals_; } - iterator endParents() { return FactorType::end(); } - boost::iterator_range frontals() { return boost::make_iterator_range(beginFrontals(), endFrontals()); } - boost::iterator_range parents() { return boost::make_iterator_range(beginParents(), endParents()); } - /** return a view of the frontal keys */ Frontals frontals() const { return boost::make_iterator_range(beginFrontals(), endFrontals()); } @@ -151,8 +156,29 @@ public: Parents parents() const { return boost::make_iterator_range(beginParents(), endParents()); } - /** print */ - void print(const std::string& s = "Conditional") const; + /** Iterators over frontal and parent variables. */ + const_iterator beginFrontals() const { return FactorType::begin(); } /// frontals() { + return boost::make_iterator_range(beginFrontals(), endFrontals()); } + + ///TODO: comment + boost::iterator_range parents() { + return boost::make_iterator_range(beginParents(), endParents()); } private: /** Serialization function */ @@ -162,6 +188,9 @@ private: ar & BOOST_SERIALIZATION_BASE_OBJECT_NVP(Base); ar & BOOST_SERIALIZATION_NVP(nrFrontals_); } + + /// @} + }; diff --git a/gtsam/inference/EliminationTree.h b/gtsam/inference/EliminationTree.h index 76db131ed..4d0ccce56 100644 --- a/gtsam/inference/EliminationTree.h +++ b/gtsam/inference/EliminationTree.h @@ -32,6 +32,7 @@ namespace gtsam { * * This structure is examined even more closely in a JunctionTree, which * additionally identifies cliques in the chordal Bayes net. + * \nosubgrouping */ template class EliminationTree { @@ -59,14 +60,15 @@ private: Factors factors_; ///< factors associated with root SubTrees subTrees_; ///< sub-trees + /// @name Standard Constructors + /// @{ + /** default constructor, private, as you should use Create below */ EliminationTree(Index key = 0) : key_(key) {} - /** add a factor, for Create use only */ - void add(const sharedFactor& factor) { factors_.push_back(factor); } - - /** add a subtree, for Create use only */ - void add(const shared_ptr& child) { subTrees_.push_back(child); } + /// @} + /// @name Advanced Interface + /// @{ /** * Static internal function to build a vector of parent pointers using the @@ -74,6 +76,12 @@ private: */ static std::vector ComputeParents(const VariableIndex& structure); + /** add a factor, for Create use only */ + void add(const sharedFactor& factor) { factors_.push_back(factor); } + + /** add a subtree, for Create use only */ + void add(const shared_ptr& child) { subTrees_.push_back(child); } + /** * Recursive routine that eliminates the factors arranged in an elimination tree * @param Conditionals is a vector of shared pointers that will be modified in place @@ -106,11 +114,9 @@ public: template static shared_ptr Create(const FactorGraph& factorGraph); - /** Print the tree to cout */ - void print(const std::string& name = "EliminationTree: ") const; - - /** Test whether the tree is equal to another */ - bool equals(const EliminationTree& other, double tol = 1e-9) const; + /// @} + /// @name Standard Interface + /// @{ /** Eliminate the factors to a Bayes Net * @param function The function to use to eliminate, see the namespace functions @@ -118,6 +124,19 @@ public: * @return The BayesNet resulting from elimination */ typename BayesNet::shared_ptr eliminate(Eliminate function) const; + + /// @} + /// @name Testable + /// @{ + + /** Print the tree to cout */ + void print(const std::string& name = "EliminationTree: ") const; + + /** Test whether the tree is equal to another */ + bool equals(const EliminationTree& other, double tol = 1e-9) const; + + /// @} + }; diff --git a/gtsam/inference/Factor.h b/gtsam/inference/Factor.h index 7a6cf4d7f..5a0b1e333 100644 --- a/gtsam/inference/Factor.h +++ b/gtsam/inference/Factor.h @@ -48,6 +48,7 @@ template class Conditional; * This class is \bold{not} virtual for performance reasons - derived symbolic classes, * IndexFactor and IndexConditional, need to be created and destroyed quickly * during symbolic elimination. GaussianFactor and NonlinearFactor are virtual. + * \nosubgrouping */ template class Factor { @@ -88,16 +89,15 @@ protected: public: + /// @name Standard Constructors + /// @{ + /** Copy constructor */ Factor(const This& f); /** Construct from conditional, calls ConditionalType::toFactor() */ Factor(const ConditionalType& c); - /** Constructor from a collection of keys */ - template Factor(KEYITERATOR beginKey, KEYITERATOR endKey) : - keys_(beginKey, endKey) { assertInvariants(); } - /** Default constructor for I/O */ Factor() {} @@ -117,6 +117,10 @@ public: Factor(Key key1, Key key2, Key key3, Key key4) : keys_(4) { keys_[0] = key1; keys_[1] = key2; keys_[2] = key3; keys_[3] = key4; assertInvariants(); } + /// @} + /// @name Advanced Constructors + /// @{ + /** Construct n-way factor */ Factor(const std::set& keys) { BOOST_FOREACH(const Key& key, keys) keys_.push_back(key); @@ -128,6 +132,12 @@ public: assertInvariants(); } + /** Constructor from a collection of keys */ + template Factor(KEYITERATOR beginKey, KEYITERATOR endKey) : + keys_(beginKey, endKey) { assertInvariants(); } + + /// @} + #ifdef TRACK_ELIMINATE /** * eliminate the first variable involved in this factor @@ -143,40 +153,54 @@ public: typename BayesNet::shared_ptr eliminate(size_t nrFrontals = 1); #endif - /** iterators */ - const_iterator begin() const { return keys_.begin(); } - const_iterator end() const { return keys_.end(); } + /// @name Standard Interface + /// @{ - /** mutable iterators */ - iterator begin() { return keys_.begin(); } - iterator end() { return keys_.end(); } - - /** First key*/ + /// First key Key front() const { return keys_.front(); } - /** Last key */ + /// Last key Key back() const { return keys_.back(); } - /** find */ + /// find const_iterator find(Key key) const { return std::find(begin(), end(), key); } - /** print */ - void print(const std::string& s = "Factor") const; - - /** check equality */ - bool equals(const This& other, double tol = 1e-9) const; - - /** - * @return keys involved in this factor - */ - std::vector& keys() { return keys_; } + ///TODO: comment const std::vector& keys() const { return keys_; } + /** iterators */ + const_iterator begin() const { return keys_.begin(); } ///TODO: comment + const_iterator end() const { return keys_.end(); } ///TODO: comment + /** * @return the number of variables involved in this factor */ size_t size() const { return keys_.size(); } + /// @} + /// @name Testable + /// @{ + + /// print + void print(const std::string& s = "Factor") const; + + /// check equality + bool equals(const This& other, double tol = 1e-9) const; + + /// @} + /// @name Advanced Interface + /// @{ + + /** + * @return keys involved in this factor + */ + std::vector& keys() { return keys_; } + + /** mutable iterators */ + iterator begin() { return keys_.begin(); } ///TODO: comment + iterator end() { return keys_.end(); } ///TODO: comment + + private: /** Serialization function */ @@ -185,6 +209,9 @@ private: void serialize(Archive & ar, const unsigned int version) { ar & BOOST_SERIALIZATION_NVP(keys_); } + + /// @} + }; } diff --git a/gtsam/inference/FactorGraph.h b/gtsam/inference/FactorGraph.h index 0ea0eecc9..5c66eb57e 100644 --- a/gtsam/inference/FactorGraph.h +++ b/gtsam/inference/FactorGraph.h @@ -37,8 +37,7 @@ template class BayesTree; /** * A factor graph is a bipartite graph with factor nodes connected to variable nodes. * In this class, however, only factor nodes are kept around. - * - * Templated on the type of factors and values structure. + * \nosubgrouping */ template class FactorGraph { @@ -69,9 +68,16 @@ template class BayesTree; /** ------------------ Creating Factor Graphs ---------------------------- */ + /// @name Standard Constructors + /// @{ + /** Default constructor */ FactorGraph() {} + /// @} + /// @name Advanced Constructor + /// @{ + /** convert from Bayes net */ template FactorGraph(const BayesNet& bayesNet); @@ -107,7 +113,9 @@ template class BayesTree; template void push_back(const std::vector >& factors); - /** ------------------ Querying Factor Graphs ---------------------------- */ + /// @} + /// @name Testable + /// @{ /** print out graph */ void print(const std::string& s = "FactorGraph") const; @@ -115,13 +123,15 @@ template class BayesTree; /** Check equality */ bool equals(const FactorGraph& fg, double tol = 1e-9) const; + /// @} + /// @name Standard Interface + /// @{ + + /** ------------------ Querying Factor Graphs ---------------------------- */ + /** const cast to the underlying vector of factors */ operator const std::vector&() const { return factors_; } - /** STL begin and end, so we can use BOOST_FOREACH */ - const_iterator begin() const { return factors_.begin();} - const_iterator end() const { return factors_.end(); } - /** Get a specific factor by index */ const sharedFactor operator[](size_t i) const { assert(i class BayesTree; return ret; } + /// @} + /// @name Advanced Interface + /// @{ + + /** STL begin and end, so we can use BOOST_FOREACH */ + const_iterator begin() const { return factors_.begin();} + const_iterator end() const { return factors_.end(); } + /** ----------------- Modifying Factor Graphs ---------------------------- */ /** STL begin and end, so we can use BOOST_FOREACH */ iterator begin() { return factors_.begin();} iterator end() { return factors_.end(); } + /// @} + /// @name Standard Interface + /// @{ + /** * Reserve space for the specified number of factors if you know in * advance how many there will be (works like std::vector::reserve). @@ -195,6 +217,10 @@ template class BayesTree; /** replace a factor by index */ void replace(size_t index, sharedFactor factor); + /// @} + /// @name Advanced Interface + /// @{ + private: /** Serialization function */ @@ -205,6 +231,8 @@ template class BayesTree; } }; // FactorGraph + /// @} + /** Create a combined joint factor (new style for EliminationTree). */ template typename DERIVED::shared_ptr Combine(const FactorGraph& factors, diff --git a/gtsam/inference/GenericMultifrontalSolver.h b/gtsam/inference/GenericMultifrontalSolver.h index 2375ff08c..4900a5a16 100644 --- a/gtsam/inference/GenericMultifrontalSolver.h +++ b/gtsam/inference/GenericMultifrontalSolver.h @@ -36,6 +36,7 @@ namespace gtsam { * JUNCTIONTREE annoyingly, you also have to supply a compatible JT type * i.e., one templated on a factor graph with the same factors * TODO: figure why this is so and possibly fix it + * \nosubgrouping */ template class GenericMultifrontalSolver { @@ -53,6 +54,9 @@ namespace gtsam { typedef typename FactorGraph::shared_ptr sharedGraph; typedef typename FactorGraph::Eliminate Eliminate; + /// @name Standard Constructors + /// @{ + /** * Construct the solver for a factor graph. This builds the junction * tree, which does the symbolic elimination, identifies the cliques, @@ -68,6 +72,10 @@ namespace gtsam { GenericMultifrontalSolver(const sharedGraph& factorGraph, const VariableIndex::shared_ptr& variableIndex); + /// @} + /// @name Standard Interface + /// @{ + /** * Replace the factor graph with a new one having the same structure. The * This function can be used if the numerical part of the factors changes, @@ -97,6 +105,8 @@ namespace gtsam { typename FACTOR::shared_ptr marginalFactor(Index j, Eliminate function) const; + /// @} + }; } // gtsam diff --git a/gtsam/inference/GenericSequentialSolver.h b/gtsam/inference/GenericSequentialSolver.h index d9c593b25..5486b3280 100644 --- a/gtsam/inference/GenericSequentialSolver.h +++ b/gtsam/inference/GenericSequentialSolver.h @@ -43,6 +43,7 @@ namespace gtsam { * However, sequential variable elimination is easier to understand so this is a good * starting point to learn about these algorithms and our implementation. * Additionally, the first step of MFQR is symbolic sequential elimination. + * \nosubgrouping */ template class GenericSequentialSolver { @@ -73,6 +74,9 @@ namespace gtsam { public: + /// @name Standard Constructors + /// @{ + /** * Construct the solver for a factor graph. This builds the elimination * tree, which already does some of the work of elimination. @@ -88,12 +92,20 @@ namespace gtsam { const sharedFactorGraph& factorGraph, const boost::shared_ptr& variableIndex); + /// @} + /// @name Testable + /// @{ + /** Print to cout */ void print(const std::string& name = "GenericSequentialSolver: ") const; /** Test whether is equal to another */ bool equals(const GenericSequentialSolver& other, double tol = 1e-9) const; + /// @} + /// @name Standard Interface + /// @{ + /** * Replace the factor graph with a new one having the same structure. The * This function can be used if the numerical part of the factors changes, @@ -120,6 +132,8 @@ namespace gtsam { */ typename FACTOR::shared_ptr marginalFactor(Index j, Eliminate function) const; + /// @} + }; // GenericSequentialSolver } // namespace gtsam diff --git a/gtsam/inference/ISAM.h b/gtsam/inference/ISAM.h index 052f85615..a4ef047e5 100644 --- a/gtsam/inference/ISAM.h +++ b/gtsam/inference/ISAM.h @@ -25,6 +25,7 @@ namespace gtsam { /** * A Bayes tree with an update methods that implements the iSAM algorithm. * Given a set of new factors, it re-eliminates the invalidated part of the tree. + * \nosubgrouping */ template class ISAM: public BayesTree { @@ -35,6 +36,9 @@ namespace gtsam { public: + /// @name Standard Constructors + /// @{ + /** Create an empty Bayes Tree */ ISAM(); @@ -43,6 +47,10 @@ namespace gtsam { Base(bayesTree) { } + /// @} + /// @name Advanced Interface Interface + /// @{ + /** * update the Bayes tree with a set of new factors, typically derived from measurements * @param newFactors is a factor graph that contains the new factors @@ -51,16 +59,16 @@ namespace gtsam { template void update(const FG& newFactors, typename FG::Eliminate function); - /** advanced interface */ - - typedef typename BayesTree::sharedClique sharedClique; - typedef typename BayesTree::Cliques Cliques; + typedef typename BayesTree::sharedClique sharedClique; ///::Cliques Cliques; /// void update_internal(const FG& newFactors, Cliques& orphans, typename FG::Eliminate function); + /// @} + }; }/// namespace gtsam diff --git a/gtsam/inference/IndexConditional.h b/gtsam/inference/IndexConditional.h index 6e0a700a0..c1cbbdaac 100644 --- a/gtsam/inference/IndexConditional.h +++ b/gtsam/inference/IndexConditional.h @@ -31,6 +31,7 @@ namespace gtsam { * * It derives from Conditional with a key type of Index, which is an * unsigned integer. + * \nosubgrouping */ class IndexConditional : public Conditional { @@ -46,6 +47,9 @@ namespace gtsam { typedef IndexFactor FactorType; typedef boost::shared_ptr shared_ptr; + /// @name Standard Constructors + /// @{ + /** Empty Constructor to make serialization possible */ IndexConditional() { assertInvariants(); } @@ -61,6 +65,10 @@ namespace gtsam { /** Three parents */ IndexConditional(Index j, Index parent1, Index parent2, Index parent3) : Base(j, parent1, parent2, parent3) { assertInvariants(); } + /// @} + /// @name Advanced Constructors + /// @{ + /** Constructor from a frontal variable and a vector of parents */ IndexConditional(Index j, const std::vector& parents) : Base(j, parents) { assertInvariants(); @@ -72,6 +80,10 @@ namespace gtsam { assertInvariants(); } + /// @} + /// @name Standard Interface + /// @{ + /** Named constructor directly returning a shared pointer */ template static shared_ptr FromKeys(const KEYS& keys, size_t nrFrontals) { @@ -86,6 +98,10 @@ namespace gtsam { return IndexFactor::shared_ptr(new IndexFactor(*this)); } + /// @} + /// @name Advanced Interface + /// @{ + /** Permute the variables when only separator variables need to be permuted. * Returns true if any reordered variables appeared in the separator and * false if not. @@ -105,6 +121,9 @@ namespace gtsam { void serialize(Archive & ar, const unsigned int version) { ar & BOOST_SERIALIZATION_BASE_OBJECT_NVP(Base); } + + /// @} + }; } diff --git a/gtsam/inference/IndexFactor.h b/gtsam/inference/IndexFactor.h index 2bea9998f..9b2d39727 100644 --- a/gtsam/inference/IndexFactor.h +++ b/gtsam/inference/IndexFactor.h @@ -32,14 +32,20 @@ namespace gtsam { * elimination by JunctionTree. * * It derives from Factor with a key type of Index, an unsigned integer. + * \nosubgrouping */ class IndexFactor: public Factor { protected: - // Internal function for checking class invariants (unique keys for this factor) + /// @name Advanced Interface + /// @{ + + /// Internal function for checking class invariants (unique keys for this factor) void assertInvariants() const; + /// @} + public: typedef IndexFactor This; @@ -51,6 +57,9 @@ namespace gtsam { /** Overriding the shared_ptr typedef */ typedef boost::shared_ptr shared_ptr; + /// @name Standard Interface + /// @{ + /** Copy constructor */ IndexFactor(const This& f) : Base(f) { @@ -60,13 +69,6 @@ namespace gtsam { /** Construct from derived type */ IndexFactor(const IndexConditional& c); - /** Constructor from a collection of keys */ - template IndexFactor(KeyIterator beginKey, - KeyIterator endKey) : - Base(beginKey, endKey) { - assertInvariants(); - } - /** Default constructor for I/O */ IndexFactor() { assertInvariants(); @@ -96,6 +98,10 @@ namespace gtsam { assertInvariants(); } + /// @} + /// @name Advanced Constructors + /// @{ + /** Construct n-way factor */ IndexFactor(const std::set& js) : Base(js) { @@ -108,6 +114,15 @@ namespace gtsam { assertInvariants(); } + /** Constructor from a collection of keys */ + template IndexFactor(KeyIterator beginKey, + KeyIterator endKey) : + Base(beginKey, endKey) { + assertInvariants(); + } + + /// @} + #ifdef TRACK_ELIMINATE /** * eliminate the first variable involved in this factor @@ -120,6 +135,9 @@ namespace gtsam { 1); #endif + /// @name Advanced Interface + /// @{ + /** * Permutes the factor, but for efficiency requires the permutation * to already be inverted. @@ -137,6 +155,8 @@ namespace gtsam { ar & BOOST_SERIALIZATION_BASE_OBJECT_NVP(Base); } + /// @} + }; // IndexFactor } diff --git a/gtsam/inference/JunctionTree.h b/gtsam/inference/JunctionTree.h index c4d8aaa2c..33a9aa5e4 100644 --- a/gtsam/inference/JunctionTree.h +++ b/gtsam/inference/JunctionTree.h @@ -48,6 +48,7 @@ namespace gtsam { * * * \ingroup Multifrontal + * \nosubgrouping */ template::Clique> class JunctionTree: public ClusterTree { @@ -68,23 +69,33 @@ namespace gtsam { typedef gtsam::BayesTree SymbolicBayesTree; private: - // distribute the factors along the cluster tree + + /// @name Advanced Interface + /// @{ + + /// distribute the factors along the cluster tree sharedClique distributeFactors(const FG& fg, const SymbolicBayesTree::sharedClique& clique); - // distribute the factors along the cluster tree + /// distribute the factors along the cluster tree sharedClique distributeFactors(const FG& fg, const std::vector >& targets, const SymbolicBayesTree::sharedClique& clique); - // recursive elimination function + /// recursive elimination function std::pair eliminateOneClique(typename FG::Eliminate function, const boost::shared_ptr& clique) const; - // internal constructor + /// internal constructor void construct(const FG& fg, const VariableIndex& variableIndex); + /// @} + public: + + /// @name Standard Constructors + /// @{ + /** Default constructor */ JunctionTree() {} @@ -104,6 +115,10 @@ namespace gtsam { */ JunctionTree(const FG& fg, const VariableIndex& variableIndex); + /// @} + /// @name Standard Interface + /// @{ + /** Eliminate the factors in the subgraphs to produce a BayesTree. * @param function The function used to eliminate, see the namespace functions * in GaussianFactorGraph.h @@ -111,6 +126,8 @@ namespace gtsam { */ typename BTClique::shared_ptr eliminate(typename FG::Eliminate function) const; + /// @} + }; // JunctionTree } // namespace gtsam diff --git a/gtsam/inference/Permutation.h b/gtsam/inference/Permutation.h index b2d9c2d11..5cbd8e187 100644 --- a/gtsam/inference/Permutation.h +++ b/gtsam/inference/Permutation.h @@ -42,6 +42,7 @@ class Inference; * arguments supplied through the square-bracket [] operator through the * permutation. Note that this helper class stores a reference to the original * container. + * \nosubgrouping */ class Permutation { protected: @@ -52,6 +53,9 @@ public: typedef std::vector::const_iterator const_iterator; typedef std::vector::iterator iterator; + /// @name Standard Constructors + /// @{ + /** * Create an empty permutation. This cannot do anything, but you can later * assign to it. @@ -64,12 +68,26 @@ public: */ Permutation(Index nVars) : rangeIndices_(nVars) {} + /// @} + /// @name Testable + /// @{ + + /** Print */ + void print(const std::string& str = "Permutation: ") const; + + /** Check equality */ + bool equals(const Permutation& rhs, double tol=0.0) const { return rangeIndices_ == rhs.rangeIndices_; } + + + /// @} + /// @name Standard Interface + /// @{ + /** * Permute the given variable, i.e. determine it's new index after the * permutation. */ Index operator[](Index variable) const { check(variable); return rangeIndices_[variable]; } - Index& operator[](Index variable) { check(variable); return rangeIndices_[variable]; } /** * The number of variables in the range of this permutation, i.e. the output @@ -104,29 +122,12 @@ public: */ static Permutation PushToBack(const std::vector& toBack, size_t size, bool filterDuplicates = false); - iterator begin() { return rangeIndices_.begin(); } - const_iterator begin() const { return rangeIndices_.begin(); } - iterator end() { return rangeIndices_.end(); } - const_iterator end() const { return rangeIndices_.end(); } - - /** Print for debugging */ - void print(const std::string& str = "Permutation: ") const; - - /** Equals */ - bool equals(const Permutation& rhs, double tol=0.0) const { return rangeIndices_ == rhs.rangeIndices_; } /** * Permute the permutation, p1.permute(p2)[i] is equivalent to p1[p2[i]]. */ Permutation::shared_ptr permute(const Permutation& permutation) const; - /** - * A partial permutation, reorders the variables selected by selector through - * partialPermutation. selector and partialPermutation should have the same - * size, this is checked if NDEBUG is not defined. - */ - Permutation::shared_ptr partialPermutation(const Permutation& selector, const Permutation& partialPermutation) const; - /** * Return the inverse permutation. This is only possible if this is a non- * reducing permutation, that is, (*this)[i] < this->size() for all i SymbolicBayesNet; typedef EliminationTree SymbolicEliminationTree; - /** Symbolic IndexFactor Graph */ + /** Symbolic IndexFactor Graph + * \nosubgrouping + */ class SymbolicFactorGraph: public FactorGraph { public: + /// @name Standard Constructors + /// @{ + /** Construct empty factor graph */ SymbolicFactorGraph() { } @@ -42,6 +47,26 @@ namespace gtsam { /** Construct from a BayesNet */ SymbolicFactorGraph(const BayesNet& bayesNet); + /** + * Construct from a factor graph of any type + */ + template + SymbolicFactorGraph(const FactorGraph& fg); + + /// @} + /// @name Standard Interface + /// @{ + + /** + * Return the set of variables involved in the factors (computes a set + * union). + */ + FastSet keys() const; + + /// @} + /// @name Advanced Interface + /// @{ + /** Push back unary factor */ void push_factor(Index key); @@ -54,17 +79,6 @@ namespace gtsam { /** Push back 4-way factor */ void push_factor(Index key1, Index key2, Index key3, Index key4); - /** - * Construct from a factor graph of any type - */ - template - SymbolicFactorGraph(const FactorGraph& fg); - - /** - * Return the set of variables involved in the factors (computes a set - * union). - */ - FastSet keys() const; }; /** Create a combined joint factor (new style for EliminationTree). */ @@ -80,7 +94,9 @@ namespace gtsam { std::pair, boost::shared_ptr > EliminateSymbolic(const FactorGraph&, size_t nrFrontals = 1); - /* Template function implementation */ + /// @} + + /** Template function implementation */ template SymbolicFactorGraph::SymbolicFactorGraph(const FactorGraph& fg) { for (size_t i = 0; i < fg.size(); i++) { diff --git a/gtsam/inference/VariableIndex.h b/gtsam/inference/VariableIndex.h index a7d6f9ba8..982bff247 100644 --- a/gtsam/inference/VariableIndex.h +++ b/gtsam/inference/VariableIndex.h @@ -35,6 +35,7 @@ class Inference; * from a factor graph prior to elimination, and stores the list of factors * that involve each variable. This information is stored as a vector of * lists of factor indices. + * \nosubgrouping */ class VariableIndex { public: @@ -51,6 +52,10 @@ protected: size_t nEntries_; // Sum of involved variable counts of each factor. public: + + /// @name Standard Constructors + /// @{ + /** Default constructor, creates an empty VariableIndex */ VariableIndex() : index_(indexUnpermuted_), nFactors_(0), nEntries_(0) {} @@ -67,6 +72,10 @@ public: */ template VariableIndex(const FactorGraph& factorGraph); + /// @} + /// @name Standard Interface + /// @{ + /** * The number of variable entries. This is one greater than the variable * with the highest index. @@ -82,15 +91,24 @@ public: /** Access a list of factors by variable */ const Factors& operator[](Index variable) const { checkVar(variable); return index_[variable]; } + /// @} + /// @name Testable + /// @{ + + /** Test for equality (for unit tests and debug assertions). */ + bool equals(const VariableIndex& other, double tol=0.0) const; + + /** Print the variable index (for unit tests and debugging). */ + void print(const std::string& str = "VariableIndex: ") const; + + + /// @} + /// @name Advanced Interface + /// @{ + /** Access a list of factors by variable */ Factors& operator[](Index variable) { checkVar(variable); return index_[variable]; } - /** - * Apply a variable permutation. Does not rearrange data, just permutes - * future lookups by variable. - */ - void permute(const Permutation& permutation); - /** * Augment the variable index with new factors. This can be used when * solving problems incrementally. @@ -105,22 +123,30 @@ public: */ template void remove(const CONTAINER& indices, const FactorGraph& factors); - /** Test for equality (for unit tests and debug assertions). */ - bool equals(const VariableIndex& other, double tol=0.0) const; - /** Print the variable index (for unit tests and debugging). */ - void print(const std::string& str = "VariableIndex: ") const; + /** + * Apply a variable permutation. Does not rearrange data, just permutes + * future lookups by variable. + */ + void permute(const Permutation& permutation); protected: + Factor_iterator factorsBegin(Index variable) { checkVar(variable); return index_[variable].begin(); } /// void fill(const FactorGraph& factorGraph); - Factor_iterator factorsBegin(Index variable) { checkVar(variable); return index_[variable].begin(); } - Factor_const_iterator factorsBegin(Index variable) const { checkVar(variable); return index_[variable].begin(); } - Factor_iterator factorsEnd(Index variable) { checkVar(variable); return index_[variable].end(); } - Factor_const_iterator factorsEnd(Index variable) const { checkVar(variable); return index_[variable].end(); } + /// @} }; /* ************************************************************************* */ diff --git a/gtsam/inference/VariableSlots.h b/gtsam/inference/VariableSlots.h index 996560179..551993db4 100644 --- a/gtsam/inference/VariableSlots.h +++ b/gtsam/inference/VariableSlots.h @@ -52,6 +52,7 @@ namespace gtsam { * further sorted so that the column-block position of the first structural * non-zero increases monotonically through the rows. This additional process * is not performed by this class. + * \nosubgrouping */ class VariableSlots : public FastMap > { @@ -60,6 +61,9 @@ public: typedef FastMap > Base; + /// @name Standard Constructors + /// @{ + /** * Constructor from a set of factors to be combined. Sorts the variables * and keeps track of which variable from each factor ends up in each slot @@ -68,11 +72,18 @@ public: template VariableSlots(const FG& factorGraph); + /// @} + /// @name Testable + /// @{ + /** print */ void print(const std::string& str = "VariableSlots: ") const; /** equals */ bool equals(const VariableSlots& rhs, double tol = 0.0) const; + + /// @} + }; /* ************************************************************************* */