Improved documentation...

... of examples/example.cpp, examples/example_bipgraph.cpp,
include/dai/prob.h, include/dai/smallset.h, include/dai/var.h,
include/dai/varset.h

Some small additional changes:
- Replaced TProb<T>::log0() by TProb<T>::log(true)
  and TProb<T>::takeLog0() by TProb<T>::takeLog(true)
- Replaced TFactor<T>::log0() by TFactor<T>::log(true)
- Removed TProb<T>::hasNonPositives()
- Added examples/example_varset.cpp
- Renamed smallSet<T> to SmallSet<T>
- Changed operator<< for Var and VarSet

Makefile

@@ -122,7 +122,7 @@ endif
 all : $(TARGETS)
 	echo -e "\a"
 
-examples : examples/example$(EE) examples/example_bipgraph$(EE)
+examples : examples/example$(EE) examples/example_bipgraph$(EE) examples/example_varset$(EE)
 
 matlabs : matlab/dai$(ME) matlab/dai_readfg$(ME) matlab/dai_writefg$(ME) matlab/dai_potstrength$(ME)
 
@@ -146,7 +146,7 @@ doc : $(INC)/*.h $(SRC)/*.cpp examples/*.cpp doxygen.conf
 clean :
 	-rm *$(OE)
 	-rm matlab/*$(ME)
-	-rm examples/example$(EE) examples/example_bipgraph$(EE)
+	-rm examples/example$(EE) examples/example_bipgraph$(EE) examples/example_varset$(EE)
 	-rm tests/testdai$(EE)
 	-rm utils/fg2dot$(EE) utils/createfg$(EE) utils/fginfo$(EE)
 	-rm -R doc

Makefile.shared

@@ -83,6 +83,9 @@ examples/example$(EE) : examples/example.cpp $(HEADERS) $(LIB)/libdai$(LE)
 examples/example_bipgraph$(EE) : examples/example_bipgraph.cpp $(HEADERS) $(LIB)/libdai$(LE)
 	$(CC) $(CCFLAGS) $(CCO)examples/example_bipgraph$(EE) examples/example_bipgraph.cpp $(LIBS)
 
+examples/example_varset$(EE) : examples/example_varset.cpp $(HEADERS) $(LIB)/libdai$(LE)
+	$(CC) $(CCFLAGS) $(CCO)examples/example_varset$(EE) examples/example_varset.cpp $(LIBS)
+
 
 # TESTS
 ########

Makefile.win

@@ -123,7 +123,7 @@ TARGETS = $(TARGETS) matlabs
 !ENDIF
 all : $(TARGETS)
 
-examples : examples/example$(EE) examples/example_bipgraph$(EE)
+examples : examples/example$(EE) examples/example_bipgraph$(EE) examples/example_varset$(EE)
 
 matlabs : matlab/dai$(ME) matlab/dai_readfg$(ME) matlab/dai_writefg$(ME) matlab/dai_potstrength$(ME)
 

examples/example.cpp

@@ -21,7 +21,7 @@
 
 
 #include <iostream>
-#include <dai/alldai.h>
+#include <dai/alldai.h>  // Include main libDAI header file
 
 
 using namespace dai;
@@ -35,43 +35,64 @@ int main( int argc, char *argv[] ) {
         cout << "Belief Propagation and JunctionTree on it." << endl << endl;
         return 1;
     } else {
+        // Read FactorGraph from the file specified by the first command line argument
         FactorGraph fg;
         fg.ReadFromFile(argv[1]);
 
+        // Set some constants
         size_t  maxiter = 10000;
         double  tol = 1e-9;
         size_t  verb = 1;
 
+        // Store the constants in a PropertySet object
         PropertySet opts;
-        opts.Set("maxiter",maxiter);
-        opts.Set("tol",tol);
-        opts.Set("verbose",verb);
+        opts.Set("maxiter",maxiter);  // Maximum number of iterations
+        opts.Set("tol",tol);          // Tolerance for convergence
+        opts.Set("verbose",verb);     // Verbosity (amount of output generated)
 
+        // Construct a JTree (junction tree) object from the FactorGraph fg
+        // using the parameters specified by opts and an additional property
+        // that specifies the type of updates the JTree algorithm should perform
         JTree jt( fg, opts("updates",string("HUGIN")) );
+        // Initialize junction tree algoritm
         jt.init();
+        // Run junction tree algorithm
         jt.run();
 
+        // Construct a BP (belief propagation) object from the FactorGraph fg
+        // using the parameters specified by opts and two additional properties,
+        // specifying the type of updates the BP algorithm should perform and
+        // whether they should be done in the real or in the logdomain
         BP bp(fg, opts("updates",string("SEQFIX"))("logdomain",false));
+        // Initialize belief propagation algorithm
         bp.init();
+        // Run belief propagation algorithm
         bp.run();
 
-        cout << "Exact single node marginals:" << endl;
-        for( size_t i = 0; i < fg.nrVars(); i++ )
-            cout << jt.belief(fg.var(i)) << endl;
+        // Report single-variable marginals for fg, calculated by the junction tree algorithm
+        cout << "Exact single-variable marginals:" << endl;
+        for( size_t i = 0; i < fg.nrVars(); i++ ) // iterate over all variables in fg
+            cout << jt.belief(fg.var(i)) << endl; // display the "belief" of jt for that variable
 
-        cout << "Approximate (loopy belief propagation) single node marginals:" << endl;
-        for( size_t i = 0; i < fg.nrVars(); i++ )
-            cout << bp.belief(fg.var(i)) << endl;
+        // Report single-variable marginals for fg, calculated by the belief propagation algorithm
+        cout << "Approximate (loopy belief propagation) single-variable marginals:" << endl;
+        for( size_t i = 0; i < fg.nrVars(); i++ ) // iterate over all variables in fg
+            cout << bp.belief(fg.var(i)) << endl; // display the belief of bp for that variable
 
+        // Report factor marginals for fg, calculated by the junction tree algorithm
         cout << "Exact factor marginals:" << endl;
-        for( size_t I = 0; I < fg.nrFactors(); I++ )
-            cout << jt.belief(fg.factor(I).vars()) << endl;
+        for( size_t I = 0; I < fg.nrFactors(); I++ ) // iterate over all factors in fg
+            cout << jt.belief(fg.factor(I).vars()) << endl;  // display the "belief" of jt for the variables in that factor
 
+        // Report factor marginals for fg, calculated by the belief propagation algorithm
         cout << "Approximate (loopy belief propagation) factor marginals:" << endl;
-        for( size_t I = 0; I < fg.nrFactors(); I++ )
-            cout << bp.belief(fg.factor(I).vars()) << "=" << bp.beliefF(I) << endl;
+        for( size_t I = 0; I < fg.nrFactors(); I++ ) // iterate over all factors in fg
+            cout << bp.belief(fg.factor(I).vars()) << endl; // display the belief of bp for the variables in that factor
 
+        // Report log partition sum (normalizing constant) of fg, calculated by the junction tree algorithm
         cout << "Exact log partition sum: " << jt.logZ() << endl;
+
+        // Report log partition sum of fg, approximated by the belief propagation algorithm
         cout << "Approximate (loopy belief propagation) log partition sum: " << bp.logZ() << endl;
     }
 

examples/example_bipgraph.cpp

@@ -4,30 +4,37 @@ using namespace std;
 using namespace dai;
 
 int main() {
+    // Create a list of edges
     vector<BipartiteGraph::Edge> edges;
     edges.reserve( 5 );
     edges.push_back( BipartiteGraph::Edge(0, 0) );
     edges.push_back( BipartiteGraph::Edge(1, 0) );
     edges.push_back( BipartiteGraph::Edge(2, 0) );
     edges.push_back( BipartiteGraph::Edge(1, 1) );
     edges.push_back( BipartiteGraph::Edge(2, 1) );
+
+    // Create a bipartite graph with 3 nodes of type 1,
+    // 2 nodes of type 2 and edge list edges.
     BipartiteGraph G( 3, 2, edges.begin(), edges.end() );
 
+    // Display some information about G
     cout << "G has " << G.nr1() << " nodes of type 1, " << G.nr2() << " nodes of type 2 and " << G.nrEdges() << " edges." << endl << endl;
 
+    // Iterate over all nodes n1 of type 1
     for( size_t n1 = 0; n1 < G.nr1(); n1++ ) {
         cout << "Node " << n1 << " of type 1 has " << G.nb1(n1).size() << " neighbors:" << endl;
+        // Iterate over all neighbors n2 of n1
         foreach( const BipartiteGraph::Neighbor &n2, G.nb1(n1) ) {
-            size_t _n2 = n2.iter;
-            size_t _n1 = n2.dual;
-            cout << "  the " << n2.iter << "'th neighbor is node " << n2 << " of type 2" << endl;
+            // The n2.iter'th neighbor of n1 is n2:
+            assert( G.nb1(n1)[n2.iter] == n2 );
+
+            // The n2.dual'th neighbor of n2 is n1:
+            assert( G.nb2(n2)[n2.dual] == n1 );
 
-            // The _n2'th neighbor of n1 is n2:
-            assert( G.nb1(n1)[_n2] == n2 );
-            // The _n1'th neighbor of n2 is n1:
-            assert( G.nb2(n2)[_n1] == n1 );
             // n2 can be used as an abbreviation of n2.node:
             assert( static_cast<size_t>(n2) == n2.node );
+
+            cout << "  the " << n2.iter << "'th neighbor is node " << n2 << " of type 2" << endl;
         }
         cout << endl;
     }

examples/example_varset.cpp

@@ -0,0 +1,52 @@
+#include <dai/varset.h>
+#include <iostream>
+
+using namespace std;
+using namespace dai;
+
+int main() {
+    Var x0(0, 2);   // Define binary variable x0 (with label 0)
+    Var x1(1, 3);   // Define ternary variable x1 (with label 1)
+
+    // Define set X = {x0, x1}
+    VarSet X; // empty
+    X |= x1;  // X = {x1}
+    X |= x0;  // X = {x1, x0}
+    cout << "X = " << X << endl << endl; // Note that the elements of X are ordered according to their labels
+
+    // Output some information about x0, x1 and X
+    cout << "Var " << x0 << " has " << x0.states() << " states (possible values)." << endl;
+    cout << "Var " << x1 << " has " << x1.states() << " states." << endl << endl;
+    cout << "VarSet " << X << " has " << X.nrStates() << " states (joint assignments of its variables)." << endl << endl;
+
+    cout << "States of VarSets correspond to states of their constituent Vars:" << endl;
+    cout << "  state of x0:   state of x1:   state of X:" << endl;
+    for( size_t s1 = 0; s1 < x1.states(); s1++ ) // for all states s1 of x1
+        for( size_t s0 = 0; s0 < x0.states(); s0++ ) { // for all states s0 of x0
+            // store s0 and s1 in a map "states"
+            map<Var,size_t> states;
+            states[x0] = s0;
+            states[x1] = s1;
+
+            // output states of x0, x1 and corresponding state of X
+            cout << "    " << s0 << "              " << s1 << "              " << X.calcState(states) << endl;
+
+            // VarSet::calcStates is the inverse of VarSet::calcState
+            assert( X.calcStates(X.calcState(states)) == states );
+        }
+
+    cout << endl << "And vice versa:" << endl;
+    cout << "  state of x0:   state of x1:   state of X:" << endl;
+    for( size_t S = 0; S < X.nrStates(); S++ ) { // for all (joint) states of X
+        // calculate states of x0 and x1 corresponding to state S of X
+        map<Var,size_t> states = X.calcStates(S);
+
+        // output state of X and corresponding states of x0, x1
+        cout << "    " << states[x0] << "              " << states[x1] << "              " << S << endl;
+
+        // VarSet::calcState is the inverse of VarSet::calcStates
+        assert( X.calcState(X.calcStates(S)) == S );
+    }
+
+	return 0;
+}

examples/example_varset.out

@@ -0,0 +1,24 @@
+X = {x0,x1}
+
+Var x0 has 2 states (possible values).
+Var x1 has 3 states.
+
+VarSet {x0,x1} has 6 states (joint assignments of its variables).
+
+States of VarSets correspond to states of their constituent Vars:
+  state of x0:   state of x1:   state of X:
+    0              0              0
+    1              0              1
+    0              1              2
+    1              1              3
+    0              2              4
+    1              2              5
+
+And vice versa:
+  state of x0:   state of x1:   state of X:
+    0              0              0
+    1              0              1
+    0              1              2
+    1              1              3
+    0              2              4
+    1              2              5

include/dai/alldai.h

@@ -23,7 +23,6 @@
 /// \file
 /// \brief Main libDAI header file
 /// \todo Improve documentation
-/// \todo Improve documentation of examples/example
 
 
 #ifndef __defined_libdai_alldai_h

include/dai/bipgraph.h

@@ -22,7 +22,6 @@
 
 /// \file
 /// \brief Defines BipartiteGraph class
-/// \todo Improve documentation of examples_bipgraph
 
 
 #ifndef __defined_libdai_bipgraph_h

include/dai/factor.h

@@ -246,11 +246,13 @@ template <typename T> class TFactor {
             return *this;
         }
 
-        /// Returns inverse of *this
-        TFactor<T> inverse() const { 
+        /// Returns inverse of *this.
+        /** If zero == true, uses 1 / 0 == 0; otherwise 1 / 0 == Inf.
+         */
+        TFactor<T> inverse(bool zero=true) const { 
             TFactor<T> inv; 
             inv._vs = _vs; 
-            inv._p = _p.inverse(true);  // FIXME
+            inv._p = _p.inverse(zero);
             return inv; 
         }
 
@@ -290,21 +292,15 @@ template <typename T> class TFactor {
         }
 
         /// Returns logarithm of *this
-        TFactor<T> log() const {
+        /** If zero==true, uses log(0)==0; otherwise, log(0)=-Inf.
+         */
+        TFactor<T> log(bool zero=false) const {
             TFactor<T> l; 
             l._vs = _vs; 
-            l._p = _p.log(); 
+            l._p = _p.log(zero); 
             return l; 
         }
 
-        /// Returns logarithm of *this (defining log(0)=0)
-        TFactor<T> log0() const {
-            TFactor<T> l0; 
-            l0._vs = _vs; 
-            l0._p = _p.log0(); 
-            return l0; 
-        }
-
         /// Normalizes *this Factor
         T normalize( typename Prob::NormType norm = Prob::NORMPROB ) { return _p.normalize( norm ); }