Improved documentation of bipgraph.h and added example_bipgraph.cpp
[libdai.git] / src / hak.cpp
index 5a5a19b..e1a33d3 100644 (file)
@@ -1,6 +1,7 @@
-/*  Copyright (C) 2006-2008  Joris Mooij  [j dot mooij at science dot ru dot nl]
-    Radboud University Nijmegen, The Netherlands
-    
+/*  Copyright (C) 2006-2008  Joris Mooij  [joris dot mooij at tuebingen dot mpg dot de]
+    Radboud University Nijmegen, The Netherlands /
+    Max Planck Institute for Biological Cybernetics, Germany
+
     This file is part of libDAI.
 
     libDAI is free software; you can redistribute it and/or modify
@@ -22,7 +23,6 @@
 #include <map>
 #include <dai/hak.h>
 #include <dai/util.h>
-#include <dai/diffs.h>
 #include <dai/exceptions.h>
 
 
@@ -35,30 +35,54 @@ using namespace std;
 const char *HAK::Name = "HAK";
 
 
-bool HAK::checkProperties() {
-    if( !HasProperty("tol") )
-        return false;
-    if (!HasProperty("maxiter") )
-        return false;
-    if (!HasProperty("verbose") )
-        return false;
-    if( !HasProperty("doubleloop") )
-        return false;
-    if( !HasProperty("clusters") )
-        return false;
+void HAK::setProperties( const PropertySet &opts ) {
+    assert( opts.hasKey("tol") );
+    assert( opts.hasKey("maxiter") );
+    assert( opts.hasKey("verbose") );
+    assert( opts.hasKey("doubleloop") );
+    assert( opts.hasKey("clusters") );
     
-    ConvertPropertyTo<double>("tol");
-    ConvertPropertyTo<size_t>("maxiter");
-    ConvertPropertyTo<size_t>("verbose");
-    ConvertPropertyTo<bool>("doubleloop");
-    ConvertPropertyTo<ClustersType>("clusters");
-
-    if( HasProperty("loopdepth") )
-        ConvertPropertyTo<size_t>("loopdepth");
-    else if( Clusters() == ClustersType::LOOP )
-        return false;
-
-    return true;
+    props.tol = opts.getStringAs<double>("tol");
+    props.maxiter = opts.getStringAs<size_t>("maxiter");
+    props.verbose = opts.getStringAs<size_t>("verbose");
+    props.doubleloop = opts.getStringAs<bool>("doubleloop");
+    props.clusters = opts.getStringAs<Properties::ClustersType>("clusters");
+
+    if( opts.hasKey("loopdepth") )
+        props.loopdepth = opts.getStringAs<size_t>("loopdepth");
+    else
+        assert( props.clusters != Properties::ClustersType::LOOP );
+    if( opts.hasKey("damping") )
+        props.damping = opts.getStringAs<double>("damping");
+    else
+        props.damping = 0.0;
+}
+
+
+PropertySet HAK::getProperties() const {
+    PropertySet opts;
+    opts.Set( "tol", props.tol );
+    opts.Set( "maxiter", props.maxiter );
+    opts.Set( "verbose", props.verbose );
+    opts.Set( "doubleloop", props.doubleloop );
+    opts.Set( "clusters", props.clusters );
+    opts.Set( "loopdepth", props.loopdepth );
+    opts.Set( "damping", props.damping );
+    return opts;
+}
+
+
+string HAK::printProperties() const {
+    stringstream s( stringstream::out );
+    s << "[";
+    s << "tol=" << props.tol << ",";
+    s << "maxiter=" << props.maxiter << ",";
+    s << "verbose=" << props.verbose << ",";
+    s << "doubleloop=" << props.doubleloop << ",";
+    s << "clusters=" << props.clusters << ",";
+    s << "loopdepth=" << props.loopdepth << ",";
+    s << "damping=" << props.damping << "]";
+    return s.str();
 }
 
 
@@ -93,8 +117,8 @@ void HAK::constructMessages() {
 }
 
 
-HAK::HAK(const RegionGraph & rg, const Properties &opts) : DAIAlgRG(rg, opts) {
-    assert( checkProperties() );
+HAK::HAK( const RegionGraph &rg, const PropertySet &opts ) : DAIAlgRG(rg), _Qa(), _Qb(), _muab(), _muba(), _maxdiff(0.0), _iters(0U), props() {
+    setProperties( opts );
 
     constructMessages();
 }
@@ -103,7 +127,7 @@ HAK::HAK(const RegionGraph & rg, const Properties &opts) : DAIAlgRG(rg, opts) {
 void HAK::findLoopClusters( const FactorGraph & fg, std::set<VarSet> &allcl, VarSet newcl, const Var & root, size_t length, VarSet vars ) {
     for( VarSet::const_iterator in = vars.begin(); in != vars.end(); in++ ) {
         VarSet ind = fg.delta( fg.findVar( *in ) );
-        if( (newcl.size()) >= 2 && (ind >> root) ) {
+        if( (newcl.size()) >= 2 && ind.contains( root ) ) {
             allcl.insert( newcl | *in );
         }
         else if( length > 1 )
@@ -112,27 +136,27 @@ void HAK::findLoopClusters( const FactorGraph & fg, std::set<VarSet> &allcl, Var
 }
 
 
-HAK::HAK(const FactorGraph & fg, const Properties &opts) : DAIAlgRG(opts) {
-    assert( checkProperties() );
+HAK::HAK(const FactorGraph & fg, const PropertySet &opts) : DAIAlgRG(), _Qa(), _Qb(), _muab(), _muba(), _maxdiff(0.0), _iters(0U), props() {
+    setProperties( opts );
 
     vector<VarSet> cl;
-    if( Clusters() == ClustersType::MIN ) {
+    if( props.clusters == Properties::ClustersType::MIN ) {
         cl = fg.Cliques();
-    } else if( Clusters() == ClustersType::DELTA ) {
+    } else if( props.clusters == Properties::ClustersType::DELTA ) {
         for( size_t i = 0; i < fg.nrVars(); i++ )
             cl.push_back(fg.Delta(i)); 
-    } else if( Clusters() == ClustersType::LOOP ) {
+    } else if( props.clusters == Properties::ClustersType::LOOP ) {
         cl = fg.Cliques();
         set<VarSet> scl;
         for( size_t i0 = 0; i0 < fg.nrVars(); i0++ ) {
             VarSet i0d = fg.delta(i0);
-            if( LoopDepth() > 1 )
-                findLoopClusters( fg, scl, fg.var(i0), fg.var(i0), LoopDepth() - 1, fg.delta(i0) );
+            if( props.loopdepth > 1 )
+                findLoopClusters( fg, scl, fg.var(i0), fg.var(i0), props.loopdepth - 1, fg.delta(i0) );
         }
         for( set<VarSet>::const_iterator c = scl.begin(); c != scl.end(); c++ )
             cl.push_back(*c);
-        if( Verbose() >= 3 ) {
-            cout << "HAK uses the following clusters: " << endl;
+        if( props.verbose >= 3 ) {
+            cout << Name << " uses the following clusters: " << endl;
             for( vector<VarSet>::const_iterator cli = cl.begin(); cli != cl.end(); cli++ )
                 cout << *cli << endl;
         }
@@ -143,15 +167,13 @@ HAK::HAK(const FactorGraph & fg, const Properties &opts) : DAIAlgRG(opts) {
     RegionGraph::operator=(rg);
     constructMessages();
 
-    if( Verbose() >= 3 )
-        cout << "HAK regiongraph: " << *this << endl;
+    if( props.verbose >= 3 )
+        cout << Name << " regiongraph: " << *this << endl;
 }
 
 
 string HAK::identify() const { 
-    stringstream result (stringstream::out);
-    result << Name << GetProperties();
-    return result.str();
+    return string(Name) + printProperties();
 }
 
 
@@ -165,16 +187,14 @@ void HAK::init( const VarSet &ns ) {
             _Qb[beta].fill( 1.0 );
             foreach( const Neighbor &alpha, nbIR(beta) ) {
                 size_t _beta = alpha.dual;
-                muab( alpha, _beta ).fill( 1.0 / IR(beta).states() );
-                muba( alpha, _beta ).fill( 1.0 / IR(beta).states() );
+                muab( alpha, _beta ).fill( 1.0 );
+                muba( alpha, _beta ).fill( 1.0 );
             }
         }
 }
 
 
 void HAK::init() {
-    assert( checkProperties() );
-
     for( vector<Factor>::iterator alpha = _Qa.begin(); alpha != _Qa.end(); alpha++ )
         alpha->fill( 1.0 / alpha->states() );
 
@@ -191,9 +211,9 @@ void HAK::init() {
 
 
 double HAK::doGBP() {
-    if( Verbose() >= 1 )
+    if( props.verbose >= 1 )
         cout << "Starting " << identify() << "...";
-    if( Verbose() >= 3)
+    if( props.verbose >= 3)
         cout << endl;
 
     double tic = toc();
@@ -211,14 +231,24 @@ double HAK::doGBP() {
     // Differences in single node beliefs
     Diffs diffs(nrVars(), 1.0);
 
-    size_t iter = 0;
     // do several passes over the network until maximum number of iterations has
     // been reached or until the maximum belief difference is smaller than tolerance
-    for( iter = 0; iter < MaxIter() && diffs.maxDiff() > Tol(); iter++ ) {
+    for( _iters = 0; _iters < props.maxiter && diffs.maxDiff() > props.tol; _iters++ ) {
         for( size_t beta = 0; beta < nrIRs(); beta++ ) {
             foreach( const Neighbor &alpha, nbIR(beta) ) {
                 size_t _beta = alpha.dual;
                 muab( alpha, _beta ) = _Qa[alpha].marginal(IR(beta)).divided_by( muba(alpha,_beta) );
+                /* TODO: INVESTIGATE THIS PROBLEM
+                 *
+                 * In some cases, the muab's can have very large entries because the muba's have very
+                 * small entries. This may cause NANs later on (e.g., multiplying large quantities may
+                 * result in +inf; normalization then tries to calculate inf / inf which is NAN). 
+                 * A fix of this problem would consist in normalizing the messages muab.
+                 * However, it is not obvious whether this is a real solution, because it has a
+                 * negative performance impact and the NAN's seem to be a symptom of a fundamental
+                 * numerical unstability.
+                 */
+                 muab(alpha,_beta).normalize(); 
             }
 
             Factor Qb_new;
@@ -227,30 +257,51 @@ double HAK::doGBP() {
                 Qb_new *= muab(alpha,_beta) ^ (1 / (nbIR(beta).size() + IR(beta).c()));
             }
 
-            Qb_new.normalize( _normtype );
+            Qb_new.normalize();
             if( Qb_new.hasNaNs() ) {
-                cout << "HAK::doGBP:  Qb_new has NaNs!" << endl;
+                // TODO: WHAT TO DO IN THIS CASE?
+                cout << Name << "::doGBP:  Qb_new has NaNs!" << endl;
                 return 1.0;
             }
-//          _Qb[beta] = Qb_new.makeZero(1e-100);    // damping?
-            _Qb[beta] = Qb_new;
+            /* TODO: WHAT IS THE PURPOSE OF THE FOLLOWING CODE?
+             *
+             *   _Qb[beta] = Qb_new.makeZero(1e-100);
+             */
+
+            if( props.doubleloop || props.damping == 0.0 )
+                _Qb[beta] = Qb_new; // no damping for double loop
+            else
+                _Qb[beta] = (Qb_new^(1.0 - props.damping)) * (_Qb[beta]^props.damping);
 
             foreach( const Neighbor &alpha, nbIR(beta) ) {
                 size_t _beta = alpha.dual;
-
                 muba(alpha,_beta) = _Qb[beta].divided_by( muab(alpha,_beta) );
 
+                /* TODO: INVESTIGATE WHETHER THIS HACK (INVENTED BY KEES) TO PREVENT NANS MAKES SENSE 
+                 *
+                 *   muba(beta,*alpha).makePositive(1e-100);
+                 *
+                 */
+
                 Factor Qa_new = OR(alpha);
                 foreach( const Neighbor &gamma, nbOR(alpha) )
                     Qa_new *= muba(alpha,gamma.iter);
                 Qa_new ^= (1.0 / OR(alpha).c());
-                Qa_new.normalize( _normtype );
+                Qa_new.normalize();
                 if( Qa_new.hasNaNs() ) {
-                    cout << "HAK::doGBP:  Qa_new has NaNs!" << endl;
+                    cout << Name << "::doGBP:  Qa_new has NaNs!" << endl;
                     return 1.0;
                 }
-//              _Qa[alpha] = Qa_new.makeZero(1e-100); // damping?
-                _Qa[alpha] = Qa_new;
+                /* TODO: WHAT IS THE PURPOSE OF THE FOLLOWING CODE?
+                 *
+                 *   _Qb[beta] = Qb_new.makeZero(1e-100);
+                 */
+
+                if( props.doubleloop || props.damping == 0.0 )
+                    _Qa[alpha] = Qa_new; // no damping for double loop
+                else
+                    // FIXME: GEOMETRIC DAMPING IS SLOW!
+                _Qa[alpha] = (Qa_new^(1.0 - props.damping)) * (_Qa[alpha]^props.damping);
             }
         }
 
@@ -261,21 +312,22 @@ double HAK::doGBP() {
             old_beliefs[i] = new_belief;
         }
 
-        if( Verbose() >= 3 )
-            cout << "HAK::doGBP:  maxdiff " << diffs.maxDiff() << " after " << iter+1 << " passes" << endl;
+        if( props.verbose >= 3 )
+            cout << Name << "::doGBP:  maxdiff " << diffs.maxDiff() << " after " << _iters+1 << " passes" << endl;
     }
 
-    updateMaxDiff( diffs.maxDiff() );
+    if( diffs.maxDiff() > _maxdiff )
+        _maxdiff = diffs.maxDiff();
 
-    if( Verbose() >= 1 ) {
-        if( diffs.maxDiff() > Tol() ) {
-            if( Verbose() == 1 )
+    if( props.verbose >= 1 ) {
+        if( diffs.maxDiff() > props.tol ) {
+            if( props.verbose == 1 )
                 cout << endl;
-            cout << "HAK::doGBP:  WARNING: not converged within " << MaxIter() << " passes (" << toc() - tic << " clocks)...final maxdiff:" << diffs.maxDiff() << endl;
+            cout << Name << "::doGBP:  WARNING: not converged within " << props.maxiter << " passes (" << toc() - tic << " seconds)...final maxdiff:" << diffs.maxDiff() << endl;
         } else {
-            if( Verbose() >= 2 )
-                cout << "HAK::doGBP:  ";
-            cout << "converged in " << iter << " passes (" << toc() - tic << " clocks)." << endl;
+            if( props.verbose >= 2 )
+                cout << Name << "::doGBP:  ";
+            cout << "converged in " << _iters << " passes (" << toc() - tic << " seconds)." << endl;
         }
     }
 
@@ -284,9 +336,9 @@ double HAK::doGBP() {
 
 
 double HAK::doDoubleLoop() {
-    if( Verbose() >= 1 )
+    if( props.verbose >= 1 )
         cout << "Starting " << identify() << "...";
-    if( Verbose() >= 3)
+    if( props.verbose >= 3)
         cout << endl;
 
     double tic = toc();
@@ -311,16 +363,17 @@ double HAK::doDoubleLoop() {
     // Differences in single node beliefs
     Diffs diffs(nrVars(), 1.0);
 
-    size_t  outer_maxiter   = MaxIter();
-    double  outer_tol       = Tol();
-    size_t  outer_verbose   = Verbose();
-    double  org_maxdiff     = MaxDiff();
+    size_t outer_maxiter   = props.maxiter;
+    double outer_tol       = props.tol;
+    size_t outer_verbose   = props.verbose;
+    double org_maxdiff     = _maxdiff;
 
     // Set parameters for inner loop
-    MaxIter( 5 );
-    Verbose( outer_verbose ? outer_verbose - 1 : 0 );
+    props.maxiter = 5;
+    props.verbose = outer_verbose ? outer_verbose - 1 : 0;
 
     size_t outer_iter = 0;
+    size_t total_iter = 0;
     for( outer_iter = 0; outer_iter < outer_maxiter && diffs.maxDiff() > outer_tol; outer_iter++ ) {
         // Calculate new outer regions
         for( size_t alpha = 0; alpha < nrORs(); alpha++ ) {
@@ -340,16 +393,20 @@ double HAK::doDoubleLoop() {
             old_beliefs[i] = new_belief;
         }
 
-        if( Verbose() >= 3 )
-            cout << "HAK::doDoubleLoop:  maxdiff " << diffs.maxDiff() << " after " << outer_iter+1 << " passes" << endl;
+        total_iter += Iterations();
+
+        if( props.verbose >= 3 )
+            cout << Name << "::doDoubleLoop:  maxdiff " << diffs.maxDiff() << " after " << total_iter << " passes" << endl;
     }
 
     // restore _maxiter, _verbose and _maxdiff
-    MaxIter( outer_maxiter );
-    Verbose( outer_verbose );
-    MaxDiff( org_maxdiff );
+    props.maxiter = outer_maxiter;
+    props.verbose = outer_verbose;
+    _maxdiff = org_maxdiff;
 
-    updateMaxDiff( diffs.maxDiff() );
+    _iters = total_iter;
+    if( diffs.maxDiff() > _maxdiff )
+        _maxdiff = diffs.maxDiff();
 
     // Restore original outer regions
     ORs = org_ORs;
@@ -358,15 +415,15 @@ double HAK::doDoubleLoop() {
     for( size_t beta = 0; beta < nrIRs(); ++beta )
         IR(beta).c() = org_IR_cs[beta];
 
-    if( Verbose() >= 1 ) {
-        if( diffs.maxDiff() > Tol() ) {
-            if( Verbose() == 1 )
+    if( props.verbose >= 1 ) {
+        if( diffs.maxDiff() > props.tol ) {
+            if( props.verbose == 1 )
                 cout << endl;
-                cout << "HAK::doDoubleLoop:  WARNING: not converged within " << outer_maxiter << " passes (" << toc() - tic << " clocks)...final maxdiff:" << diffs.maxDiff() << endl;
+                cout << Name << "::doDoubleLoop:  WARNING: not converged within " << outer_maxiter << " passes (" << toc() - tic << " seconds)...final maxdiff:" << diffs.maxDiff() << endl;
             } else {
-                if( Verbose() >= 3 )
-                    cout << "HAK::doDoubleLoop:  ";
-                cout << "converged in " << outer_iter << " passes (" << toc() - tic << " clocks)." << endl;
+                if( props.verbose >= 3 )
+                    cout << Name << "::doDoubleLoop:  ";
+                cout << "converged in " << total_iter << " passes (" << toc() - tic << " seconds)." << endl;
             }
         }
 
@@ -375,7 +432,7 @@ double HAK::doDoubleLoop() {
 
 
 double HAK::run() {
-    if( DoubleLoop() )
+    if( props.doubleloop )
         return doDoubleLoop();
     else
         return doGBP();
@@ -415,12 +472,12 @@ vector<Factor> HAK::beliefs() const {
 }
 
 
-Complex HAK::logZ() const {
-    Complex sum = 0.0;
+Real HAK::logZ() const {
+    Real sum = 0.0;
     for( size_t beta = 0; beta < nrIRs(); beta++ )
-        sum += Complex(IR(beta).c()) * Qb(beta).entropy();
+        sum += IR(beta).c() * Qb(beta).entropy();
     for( size_t alpha = 0; alpha < nrORs(); alpha++ ) {
-        sum += Complex(OR(alpha).c()) * Qa(alpha).entropy();
+        sum += OR(alpha).c() * Qa(alpha).entropy();
         sum += (OR(alpha).log0() * Qa(alpha)).totalSum();
     }
     return sum;