Improved documentation of include/dai/gibbs.h

diff --git a/TODO b/TODO
index 8aa3f10..4140b9a 100644 (file)
--- a/TODO
+++ b/TODO
@@ -2,7 +2,6 @@ To do for the next release (0.2.3):
 
 Improve documentation:
 
-       gibbs.h
        bp_dual.h
        bbp.h
        cbp.h

diff --git a/include/dai/gibbs.h b/include/dai/gibbs.h
index 8c08990..c4166a6 100644 (file)
--- a/include/dai/gibbs.h
+++ b/include/dai/gibbs.h
@@ -9,8 +9,7 @@
 
 
 /// \file
-/// \brief Defines class Gibbs
-/// \todo Improve documentation
+/// \brief Defines class Gibbs, which implements Gibbs sampling
 
 
 #ifndef __defined_libdai_gibbs_h
@@ -26,22 +25,32 @@ namespace dai {
 
 
 /// Approximate inference algorithm "Gibbs sampling"
+/** \author Frederik Eaton
+ */
 class Gibbs : public DAIAlgFG {
     private:
+        /// Type used to store the counts of various states
         typedef std::vector<size_t> _count_t;
+        /// Type used to store the joint state of all variables
         typedef std::vector<size_t> _state_t;
-
+        /// Number of samples counted so far (excluding burn-in)
         size_t _sample_count;
+        /// State counts for each variable
         std::vector<_count_t> _var_counts;
+        /// State counts for each factor
         std::vector<_count_t> _factor_counts;
+        /// Current joint state of all variables
         _state_t _state;
 
     public:
         /// Parameters of this inference algorithm
         struct Properties {
-            /// Number of iterations
+            /// Total number of iterations
             size_t iters;
 
+            /// Number of "burn-in" iterations
+            size_t burnin;
+
             /// Verbosity
             size_t verbose;
         } props;
@@ -53,7 +62,7 @@ class Gibbs : public DAIAlgFG {
         /// Default constructor
         Gibbs() : DAIAlgFG(), _sample_count(0), _var_counts(), _factor_counts(), _state() {}
 
-        /// Construct from FactorGraph fg and PropertySet opts
+        /// Construct from FactorGraph \a fg and PropertySet \a opts
         Gibbs( const FactorGraph &fg, const PropertySet &opts ) : DAIAlgFG(fg), _sample_count(0), _var_counts(), _factor_counts(), _state() {
             setProperties( opts );
             construct();
@@ -83,22 +92,27 @@ class Gibbs : public DAIAlgFG {
 
     /// \name Additional interface specific for Gibbs
     //@{
+        /// Draw the current joint state of all variables from a uniform random distribution
         void randomizeState();
-        /// Return reference to current state vector
+        /// Return reference to current state of all variables
         std::vector<size_t>& state() { return _state; }
-
-        /// Return const reference to current state vector
+        /// Return constant reference to current state of all variables
         const std::vector<size_t>& state() const { return _state; }
     //@}
 
     private:
+        /// Helper function for constructors
+        void construct();
+        /// Updates all counts (_sample_count, _var_counts, _factor_counts) based on current state
         void updateCounts();
+        /// Calculate conditional distribution of variable \a i, given the current state
         Prob getVarDist( size_t i );
+        /// Draw state of variable \a i randomly from its conditional distribution and update the current state
         void resampleVar( size_t i );
+        /// Calculates linear index into factor \a I corresponding to the current state
         size_t getFactorEntry( size_t I );
+        /// Calculates the differences between linear indices into factor \a I corresponding with a state change of variable \a i
         size_t getFactorEntryDiff( size_t I, size_t i );
-
-        void construct();
 };
 
 

diff --git a/include/dai/util.h b/include/dai/util.h
index 3e02d41..de16e11 100644 (file)
--- a/include/dai/util.h
+++ b/include/dai/util.h
@@ -137,7 +137,7 @@ Real rnd_stdnormal();
 int rnd_int( int min, int max );
 
 /// Returns a random integer in the half-open interval [0, \a n)
-inline int rnd( int n) {
+inline int rnd( int n ) {
     return rnd_int( 0, n-1 );
 }
 

diff --git a/src/gibbs.cpp b/src/gibbs.cpp
index 3f4c547..5655448 100644 (file)
--- a/src/gibbs.cpp
+++ b/src/gibbs.cpp
@@ -31,6 +31,11 @@ void Gibbs::setProperties( const PropertySet &opts ) {
     DAI_ASSERT( opts.hasKey("iters") );
     props.iters = opts.getStringAs<size_t>("iters");
 
+    if( opts.hasKey("burnin") )
+        props.burnin = opts.getStringAs<size_t>("burnin");
+    else
+        props.burnin = 0;
+
     if( opts.hasKey("verbose") )
         props.verbose = opts.getStringAs<size_t>("verbose");
     else
@@ -41,6 +46,7 @@ void Gibbs::setProperties( const PropertySet &opts ) {
 PropertySet Gibbs::getProperties() const {
     PropertySet opts;
     opts.Set( "iters", props.iters );
+    opts.Set( "burnin", props.burnin );
     opts.Set( "verbose", props.verbose );
     return opts;
 }
@@ -50,6 +56,7 @@ string Gibbs::printProperties() const {
     stringstream s( stringstream::out );
     s << "[";
     s << "iters=" << props.iters << ",";
+    s << "burnin=" << props.burnin << ",";
     s << "verbose=" << props.verbose << "]";
     return s.str();
 }
@@ -74,11 +81,13 @@ void Gibbs::construct() {
 
 
 void Gibbs::updateCounts() {
-    for( size_t i = 0; i < nrVars(); i++ )
-        _var_counts[i][_state[i]]++;
-    for( size_t I = 0; I < nrFactors(); I++ )
-        _factor_counts[I][getFactorEntry(I)]++;
     _sample_count++;
+    if( _sample_count > props.burnin ) {
+        for( size_t i = 0; i < nrVars(); i++ )
+            _var_counts[i][_state[i]]++;
+        for( size_t I = 0; I < nrFactors(); I++ )
+            _factor_counts[I][getFactorEntry(I)]++;
+    }
 }
 
 
@@ -137,14 +146,13 @@ Prob Gibbs::getVarDist( size_t i ) {
 
 
 inline void Gibbs::resampleVar( size_t i ) {
-    // draw randomly from conditional distribution and update _state
     _state[i] = getVarDist(i).draw();
 }
 
 
 void Gibbs::randomizeState() {
     for( size_t i = 0; i < nrVars(); i++ )
-        _state[i] = rnd_int( 0, var(i).states() - 1 );
+        _state[i] = rnd( var(i).states() );
 }
 
 

diff --git a/tests/aliases.conf b/tests/aliases.conf
index 2f9b582..0c4d526 100644 (file)
--- a/tests/aliases.conf
+++ b/tests/aliases.conf
@@ -97,16 +97,16 @@ LCBP:                           LCBP_FULLCAVin_SEQRND
 
 # --- GIBBS -------------------
 
-GIBBS:                          GIBBS[iters=1000,verbose=0]
-GIBBS_1e1:                      GIBBS[iters=10]
-GIBBS_1e2:                      GIBBS[iters=100]
-GIBBS_1e3:                      GIBBS[iters=1000]
-GIBBS_1e4:                      GIBBS[iters=10000]
-GIBBS_1e5:                      GIBBS[iters=100000]
-GIBBS_1e6:                      GIBBS[iters=1000000]
-GIBBS_1e7:                      GIBBS[iters=10000000]
-GIBBS_1e8:                      GIBBS[iters=100000000]
-GIBBS_1e9:                      GIBBS[iters=1000000000]
+GIBBS:                          GIBBS[iters=1000,burnin=100,verbose=0]
+GIBBS_1e1:                      GIBBS[iters=10,burnin=1,verbose=0]
+GIBBS_1e2:                      GIBBS[iters=100,burnin=10,verbose=0]
+GIBBS_1e3:                      GIBBS[iters=1000,burnin=100,verbose=0]
+GIBBS_1e4:                      GIBBS[iters=10000,burnin=1000,verbose=0]
+GIBBS_1e5:                      GIBBS[iters=100000,burnin=10000,verbose=0]
+GIBBS_1e6:                      GIBBS[iters=1000000,burnin=100000,verbose=0]
+GIBBS_1e7:                      GIBBS[iters=10000000,burnin=100000,verbose=0]
+GIBBS_1e8:                      GIBBS[iters=100000000,burnin=100000,verbose=0]
+GIBBS_1e9:                      GIBBS[iters=1000000000,burnin=100000,verbose=0]
 
 # --- CBP ---------------------