Oops, correct previous partial commit.

binarybana · Oct 8, 2008 · 077347c · 077347c
1 parent 5462dc0
commit 077347c
Show file tree

Hide file tree

Showing 30 changed files with 138 additions and 64 deletions.
diff --git a/ChangeLog b/ChangeLog
@@ -1,3 +1,12 @@
+git HEAD
+--------
+* Improved documentation of include/dai/bipgraph.h
+* Moved example to examples/ and added examples/example_bipgraph.cpp
+* Cleanup of matlab interface
+* Small improvement of utils/fginfo
+* Small cleanup of BP code
+
+
 libDAI-0.2.2 (2008-09-30)
 -------------------------
 

diff --git a/Makefile b/Makefile
@@ -115,13 +115,15 @@ endif
 
 HEADERS=$(INC)/bipgraph.h $(INC)/index.h $(INC)/var.h $(INC)/factor.h $(INC)/varset.h $(INC)/smallset.h $(INC)/prob.h $(INC)/daialg.h $(INC)/properties.h $(INC)/alldai.h $(INC)/enum.h $(INC)/exceptions.h
 
-TARGETS=tests utils $(LIB)/libdai$(LE) example$(EE) testregression doc
+TARGETS=tests utils $(LIB)/libdai$(LE) testregression doc examples
 ifdef WITH_MATLAB
 TARGETS:=$(TARGETS) matlabs
 endif
 all : $(TARGETS)
 	echo -e "\a"
 
+examples : examples/example$(EE) examples/example_bipgraph$(EE)
+
 matlabs : matlab/dai$(ME) matlab/dai_readfg$(ME) matlab/dai_writefg$(ME) matlab/dai_potstrength$(ME)
 
 $(LIB)/libdai$(LE) : bipgraph$(OE) daialg$(OE) alldai$(OE) clustergraph$(OE) factorgraph$(OE) properties$(OE) regiongraph$(OE) util$(OE) weightedgraph$(OE) exceptions$(OE) $(OBJECTS)
@@ -136,15 +138,17 @@ testregression : tests/testdai
 	@echo Starting regression test...this can take a minute or so!
 	cd tests; time ./testregression; cd ..
 
-doc : $(INC)/*.h $(SRC)/*.cpp doxygen.conf
+doc : $(INC)/*.h $(SRC)/*.cpp examples/*.cpp doxygen.conf
 	-mkdir -p doc
 	doxygen doxygen.conf
 
 .PHONY : clean
 clean :
 	-rm *$(OE)
 	-rm matlab/*$(ME)
-	-rm example$(EE) tests/testdai$(EE) utils/fg2dot$(EE) utils/createfg$(EE) utils/fginfo$(EE)
+	-rm examples/example$(EE) examples/example_bipgraph$(EE)
+	-rm tests/testdai$(EE)
+	-rm utils/fg2dot$(EE) utils/createfg$(EE) utils/fginfo$(EE)
 	-rm -R doc
 	-rm -R lib
 

diff --git a/Makefile.shared b/Makefile.shared
@@ -74,11 +74,14 @@ alldai$(OE) : $(SRC)/alldai.cpp $(HEADERS)
 	$(CC) $(CCFLAGS) -c $(SRC)/alldai.cpp
 
 
-# EXAMPLE
-##########
+# EXAMPLES
+###########
 
-example$(EE) : example.cpp $(HEADERS) $(LIB)/libdai$(LE)
-	$(CC) $(CCFLAGS) $(CCO)example$(EE) example.cpp $(LIBS)
+examples/example$(EE) : examples/example.cpp $(HEADERS) $(LIB)/libdai$(LE)
+	$(CC) $(CCFLAGS) $(CCO)examples/example$(EE) examples/example.cpp $(LIBS)
+
+examples/example_bipgraph$(EE) : examples/example_bipgraph.cpp $(HEADERS) $(LIB)/libdai$(LE)
+	$(CC) $(CCFLAGS) $(CCO)examples/example_bipgraph$(EE) examples/example_bipgraph.cpp $(LIBS)
 
 
 # TESTS

diff --git a/Makefile.win b/Makefile.win
@@ -115,14 +115,16 @@ MEXFLAGS=$(MEXFLAGS) /DSMALLMEM
 
 HEADERS=$(INC)/bipgraph.h $(INC)/index.h $(INC)/var.h $(INC)/factor.h $(INC)/varset.h $(INC)/smallset.h $(INC)/prob.h $(INC)/daialg.h $(INC)/properties.h $(INC)/alldai.h $(INC)/enum.h $(INC)/exceptions.h
 
-TARGETS=tests utils $(LIB)/libdai$(LE) example$(EE)
+TARGETS=tests utils $(LIB)/libdai$(LE) examples
 # testregression disabled, it uses diff
-# doc disabled, it uses doxygen
+# doc disabled, it uses doxygen, graphviz and latex
 !IFDEF WITH_MATLAB
 TARGETS = $(TARGETS) matlabs
 !ENDIF
 all : $(TARGETS)
 
+examples : examples/example$(EE) examples/example_bipgraph$(EE)
+
 matlabs : matlab/dai$(ME) matlab/dai_readfg$(ME) matlab/dai_writefg$(ME) matlab/dai_potstrength$(ME)
 
 $(LIB)/libdai$(LE) : bipgraph$(OE) daialg$(OE) alldai$(OE) clustergraph$(OE) factorgraph$(OE) properties$(OE) regiongraph$(OE) util$(OE) weightedgraph$(OE) exceptions$(OE) $(OBJECTS)
@@ -133,13 +135,13 @@ tests : tests/testdai$(EE)
 utils : utils/createfg$(EE) utils/fg2dot$(EE) utils/fginfo$(EE)
 
 testregression : tests/testdai$(EE)
-	echo Testing...this can take a while...
+	echo Starting regression test...this can take a minute or so!
 	cd tests; time ./testregression; cd ..
 
-doc : $(INC)/*.h $(SRC)/*.cpp doxygen.conf
+doc : $(INC)/*.h $(SRC)/*.cpp examples/*.cpp doxygen.conf
 	doxygen doxygen.conf
 
 clean :
-	del *$(OE) *.ilk *.pdb *$(EE) matlab\*$(ME) tests\testdai$(EE) tests\*.pdb tests\*.ilk utils\*$(EE) utils\*.pdb utils\*.ilk $(LIB)\libdai$(LE)
+	del *$(OE) *.ilk *.pdb *$(EE) matlab\*$(ME) examples\*$(EE) tests\testdai$(EE) tests\*.pdb tests\*.ilk utils\*$(EE) utils\*.pdb utils\*.ilk $(LIB)\libdai$(LE)
 
 !INCLUDE Makefile.shared
diff --git a/doxygen.conf b/doxygen.conf
@@ -571,7 +571,7 @@ EXCLUDE_SYMBOLS        =
 # directories that contain example code fragments that are included (see 
 # the \include command).
 
-EXAMPLE_PATH           = 
+EXAMPLE_PATH           = examples
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the 
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 

diff --git a/include/dai/alldai.h b/include/dai/alldai.h
@@ -22,6 +22,8 @@
 
 /// \file
 /// \brief Main libDAI header file
+/// \todo Improve documentation
+/// \todo Improve documentation of examples/example
 
 
 #ifndef __defined_libdai_alldai_h
@@ -101,8 +103,8 @@ static const char* DAINames[] = {
 
 /** \mainpage libDAI reference manual
  *  \author Joris Mooij
- *  \version 0.2.2
- *  \date 30 September 2008
+ *  \version git HEAD
+ *  \date October 8, 2008
  *
  *  \section about About libDAI
  *  libDAI is a free/open source C++ library (licensed under GPL) that provides
@@ -139,8 +141,11 @@ static const char* DAINames[] = {
  *  implementations in MatLab (a factor 1000 faster is not uncommon).
  *  libDAI does provide a MatLab interface for easy integration with MatLab. 
  *
+ *  \section quickstart Quick start
+ *  An example program illustrating basic usage of libDAI is given in examples/example.cpp.
  */
 
+/// \example example.cpp
 
 /** \page Bibliography
  *  \section Bibliograpy

diff --git a/include/dai/bipgraph.h b/include/dai/bipgraph.h
@@ -22,6 +22,7 @@
 
 /// \file
 /// \brief Defines BipartiteGraph class
+/// \todo Improve documentation of examples_bipgraph
 
 
 #ifndef __defined_libdai_bipgraph_h
@@ -40,32 +41,29 @@ namespace dai {
 
 /// Represents the neighborhood structure of nodes in a bipartite graph.
 /** A bipartite graph has two types of nodes: type 1 and type 2. Edges can occur only between
- *  nodes of different type. Nodes are indexed by an unsigned integer, edges are indexed as
- *  a pair of unsigned integers, where the pair (a,b) means the b'th neighbor of the a'th node.
+ *  nodes of different type. Nodes are indexed by an unsigned integer. If there are nr1()
+ *  nodes of type 1 and nr2() nodes of type 2, the nodes of type 1 are numbered 
+ *  0,1,2,...,nr1()-1 and the nodes of type 2 are numbered 0,1,2,...,nr2()-1. An edge
+ *  between node \a n1 of type 1 and node \a n2 of type 2 is represented by a BipartiteGraph::Edge(\a n1,\a n2).
  *
- *  The BipartiteGraph stores for each node of type 1 a vector of Neighbor structures, where
- *  each Neighbor corresponds to a neighboring node of type 2. In addition, each node of type 2
- *  stores a vector of Neighbor structures describing its neighboring nodes of type 1.
+ *  A BipartiteGraph is implemented as a sparse adjacency list, i.e., it stores for each node a list of
+ *  its neighboring nodes. In particular, it stores for each node of type 1 a vector of Neighbor structures
+ *  (accessible by the nb1() method) describing the neighboring nodes of type 2; similarly, for each node 
+ *  of type 2 it stores a vector of Neighbor structures (accessibly by the nb2() method) describing the 
+ *  neighboring nodes of type 1. 
+ *  Thus, each node has an associated variable of type BipartiteGraph::Neighbors, which is a vector of
+ *  Neighbor structures, describing its neighboring nodes of the other type.
  */
 class BipartiteGraph {
     public:
         /// Describes a neighboring node of some other node in a BipartiteGraph.
-        /** Iterating over all neighbors of the n1'th node of type 1 can be done in the following way:
-         *  \code
-         *      size_t n1 = ...;
-         *      foreach( const BipartiteGraph::Neighbor &n2, nb1(n1) ) {
-         *          size_t _n2 = n2.iter;
-         *          size_t _n1 = n2.dual;
-         *          std::cout << "The " << _n2 << "'th neighbor of the " << n1 << "'th node of type 1 is: the " << n2 << "'th node of type 2" << endl;
-         *
-         *          // The _n2'th neighbor of n1 is n2:
-         *          assert( nb1(n1)[_n2] == n2 );
-         *          // The _n1'th neighbor of n2 is n1:
-         *          assert( nb2(n2)[_n1] == n1 );
-         *          // n2 can be used as an abbreviation of n2.node:
-         *          assert( static_cast<size_t>(n2) == n2.node );
-         *      }
-         *  \endcode
+        /** A Neighbor structure has three members: \a iter, \a node and \a dual. The \a 
+         *  node member is the most important member: it contains the index of the neighboring node. The \a iter 
+         *  member is useful for iterating over neighbors, and contains the index of this Neighbor entry in the
+         *  corresponding BipartiteGraph::Neighbors variable. The \a dual member is useful to find the dual Neighbor 
+         *  element: a pair of neighboring nodes can be either specified as a node of type 1 and a neighbor of type 
+         *  2, or as a node of type 2 and a neighbor of type 1; the \a dual member contains the index of the dual 
+         *  Neighbor element (see the example for another explanation of the dual member).
          */
         struct Neighbor {
             /// Corresponds to the index of this Neighbor entry in the vector of neighbors
@@ -77,17 +75,17 @@ class BipartiteGraph {
 
             /// Default constructor
             Neighbor() {}
-            /// Constructor that sets the Neighbor members accordingly to the parameters
+            /// Constructor that sets the Neighbor members according to the parameters
             Neighbor( size_t iter, size_t node, size_t dual ) : iter(iter), node(node), dual(dual) {}
 
-            /// Cast to size_t returns member node
+            /// Cast to size_t returns node member
             operator size_t () const { return node; }
         };
 
         /// Describes the neighbors of some node.
         typedef std::vector<Neighbor> Neighbors;
 
-        /// Used as index of an edge: an Edge(a,b) corresponds to the edge between the a'th node and its b'th neighbor (it depends on the context whether the first node (with index a) is of type 1 or of type 2).
+        /// Represents an edge: an Edge(\a n1,\a n2) corresponds to the edge between node \a n1 of type 1 and node \a n2 of type 2.
         typedef std::pair<size_t,size_t> Edge;
 
     private:
@@ -104,13 +102,13 @@ class BipartiteGraph {
         };
 
     public:
-        /// Default constructor
+        /// Default constructor (creates an empty bipartite graph)
         BipartiteGraph() : _nb1(), _nb2() {}
 
-        /// Copy constructor
+        /// Copy constructor (constructs a bipartite graph containing a copy of \c x)
         BipartiteGraph( const BipartiteGraph & x ) : _nb1(x._nb1), _nb2(x._nb2) {}
 
-        /// Assignment operator
+        /// Assignment operator (makes \c *this equal to \c x)
         BipartiteGraph & operator=( const BipartiteGraph & x ) {
             if( this != &x ) {
                 _nb1 = x._nb1;
@@ -119,24 +117,24 @@ class BipartiteGraph {
             return *this;
         }
 
-        /// Constructs BipartiteGraph from a range of edges. 
-        /** \tparam EdgeInputIterator Iterator with value_type Edge.
+        /// Constructs BipartiteGraph from a range of edges.
+        /** \tparam EdgeInputIterator Iterator that iterates over instances of BipartiteGraph::Edge.
          *  \param nr1 The number of nodes of type 1.
          *  \param nr2 The number of nodes of type 2. 
-         *  \param begin Points to the first Edge.
-         *  \param end Points just beyond the last Edge.
+         *  \param begin Points to the first edge.
+         *  \param end Points just beyond the last edge.
          */
         template<typename EdgeInputIterator>
         BipartiteGraph( size_t nr1, size_t nr2, EdgeInputIterator begin, EdgeInputIterator end ) : _nb1( nr1 ), _nb2( nr2 ) {
             construct( nr1, nr2, begin, end );
         }
 
-        /// (Re)constructs BipartiteGraph from a range of edges. 
-        /** \tparam EdgeInputIterator Iterator with value_type Edge.
+        /// (Re)constructs BipartiteGraph from a range of edges.
+        /** \tparam EdgeInputIterator Iterator that iterates over instances of BipartiteGraph::Edge.
          *  \param nr1 The number of nodes of type 1.
          *  \param nr2 The number of nodes of type 2. 
-         *  \param begin Points to the first Edge.
-         *  \param end Points just beyond the last Edge.
+         *  \param begin Points to the first edge.
+         *  \param end Points just beyond the last edge.
          */
         template<typename EdgeInputIterator>
         void construct( size_t nr1, size_t nr2, EdgeInputIterator begin, EdgeInputIterator end );
@@ -210,7 +208,7 @@ class BipartiteGraph {
         /// Returns number of nodes of type 2
         size_t nr2() const { return _nb2.size(); }
 
-        /// Calculates the number of edges, using O(nr1()) time
+        /// Calculates the number of edges, time complexity: O(nr1())
         size_t nrEdges() const {
             size_t sum = 0;
             for( size_t i1 = 0; i1 < nr1(); i1++ )
@@ -224,11 +222,10 @@ class BipartiteGraph {
         /// Adds a node of type 2 without neighbors.
         void add2() { _nb2.push_back( Neighbors() ); }
 
-        /// Adds a node of type 1, with neighbors specified by a range of indices of nodes of type 2.
-        /** \tparam NodeInputIterator Iterator with value_type size_t, corresponding to
-         *  the indices of nodes of type 2 that should become neighbors of the added node.
-         *  \param begin Points to the index of the first neighbor.
-         *  \param end Points just beyond the index of the last neighbor.
+        /// Adds a node of type 1, with neighbors specified by a range of nodes of type 2.
+        /** \tparam NodeInputIterator Iterator that iterates over instances of size_t.
+         *  \param begin Points to the first index of the nodes of type 2 that should become neighbors of the added node.
+         *  \param end Points just beyond the last index of the nodes of type 2 that should become neighbors of the added node.
          *  \param sizeHint For improved efficiency, the size of the range may be specified by sizeHint.
          */
         template <typename NodeInputIterator>
@@ -246,11 +243,10 @@ class BipartiteGraph {
             _nb1.push_back( nbs1new );
         }
 
-        /// Adds a node of type 2, with neighbors specified by a range of indices of nodes of type 1.
-        /** \tparam NodeInputIterator Iterator with value_type size_t, corresponding to
-         *  the indices of nodes of type 1 that should become neighbors of the added node.
-         *  \param begin Points to the index of the first neighbor.
-         *  \param end Points just beyond the index of the last neighbor.
+        /// Adds a node of type 2, with neighbors specified by a range of nodes of type 1.
+        /** \tparam NodeInputIterator Iterator that iterates over instances of size_t.
+         *  \param begin Points to the first index of the nodes of type 1 that should become neighbors of the added node.
+         *  \param end Points just beyond the last index of the nodes of type 1 that should become neighbors of the added node.
          *  \param sizeHint For improved efficiency, the size of the range may be specified by sizeHint.
          */
         template <typename NodeInputIterator>
@@ -311,9 +307,6 @@ class BipartiteGraph {
         bool isConnected() const;
 
         /// Returns true if the graph is a tree, i.e., if it is singly connected and connected.
-        /** This is equivalent to whether for each pair of nodes in the graph, there exists
-         *  a unique path in the graph that starts at the first and ends at the second node.
-         */
         bool isTree() const;
 
         /// Writes this BipartiteGraph to an output stream in GraphViz .dot syntax
@@ -345,4 +338,39 @@ void BipartiteGraph::construct( size_t nr1, size_t nr2, EdgeInputIterator begin,
 } // end of namespace dai
 
 
+/** \example example_bipgraph.cpp
+ *  This example deals with the following bipartite graph:
+ *  \dot
+ *  graph example {
+ *    ordering=out;
+ *    subgraph cluster_type1 {
+ *      node[shape=circle,width=0.4,fixedsize=true,style=filled];
+ *      12 [label="2"];
+ *      11 [label="1"];
+ *      10 [label="0"];
+ *    }
+ *    subgraph cluster_type2 {
+ *      node[shape=polygon,regular=true,sides=4,width=0.4,fixedsize=true,style=filled];
+ *      21 [label="1"];
+ *      20 [label="0"];
+ *    }
+ *    10 -- 20;
+ *    11 -- 20;
+ *    12 -- 20;
+ *    11 -- 21;
+ *    12 -- 21;
+ *  }
+ *  \enddot
+ *  It has three nodes of type 1 (drawn as circles) and two nodes of type 2 (drawn as rectangles). 
+ *  Node 0 of type 1 has only one neighbor (node 0 of type 2), but node 0 of type 2 has three neighbors (nodes 0,1,2 of type 1).
+ *  The example code shows how to construct a BipartiteGraph object representing this bipartite graph and
+ *  how to iterate over nodes and their neighbors.
+ *
+ *  \section Output
+ *  \verbinclude examples/example_bipgraph.out
+ *
+ *  \section Source
+ */
+
+
 #endif
diff --git a/include/dai/bp.h b/include/dai/bp.h
@@ -22,6 +22,7 @@
 
 /// \file
 /// \brief Defines class BP
+/// \todo Improve documentation
 
 
 #ifndef __defined_libdai_bp_h

diff --git a/include/dai/clustergraph.h b/include/dai/clustergraph.h
@@ -22,6 +22,7 @@
 
 /// \file
 /// \brief Defines class ClusterGraph
+/// \todo Improve documentation
 
 
 #ifndef __defined_libdai_clustergraph_h

diff --git a/include/dai/daialg.h b/include/dai/daialg.h
@@ -22,6 +22,7 @@
 
 /// \file
 /// \brief Defines abstract base class InfAlg, its descendants DAIAlg<T>, the specializations DAIAlgFG and DAIAlgRG and some generic inference methods.
+/// \todo Improve documentation
 
 
 #ifndef __defined_libdai_daialg_h

diff --git a/include/dai/enum.h b/include/dai/enum.h
@@ -22,6 +22,7 @@
 
 /// \file
 /// \brief Defines the DAI_ENUM macro
+/// \todo Improve documentation
 
 
 #ifndef __defined_libdai_enum_h