Fixed example_imagesegmentation by adding InfAlg::setMaxIter(size_t)
[libdai.git] / include / dai / hak.h
index d4c395c..99927f8 100644 (file)
@@ -4,13 +4,17 @@
  *  2, or (at your option) any later version. libDAI is distributed without any
  *  warranty. See the file COPYING for more details.
  *
- *  Copyright (C) 2006-2009  Joris Mooij  [joris dot mooij at libdai dot org]
+ *  Copyright (C) 2006-2010  Joris Mooij  [joris dot mooij at libdai dot org]
  *  Copyright (C) 2006-2007  Radboud University Nijmegen, The Netherlands
  */
 
 
 /// \file
 /// \brief Defines class HAK, which implements a variant of Generalized Belief Propagation.
+/// \idea Implement more general region graphs and corresponding Generalized Belief Propagation updates as described in [\ref YFW05].
+/// \todo Use ClusterGraph instead of a vector<VarSet> for speed.
+/// \todo Optimize this code for large factor graphs.
+/// \todo Implement GBP parent-child  algorithm.
 
 
 #ifndef __defined_libdai_hak_h
@@ -28,8 +32,6 @@ namespace dai {
 
 
 /// Approximate inference algorithm: implementation of single-loop ("Generalized Belief Propagation") and double-loop algorithms by Heskes, Albers and Kappen [\ref HAK03]
-/** \todo Optimize HAK with precalculated indices, similarly to BP.
- */
 class HAK : public DAIAlgRG {
     private:
         /// Outer region beliefs
@@ -46,24 +48,33 @@ class HAK : public DAIAlgRG {
         size_t _iters;
 
     public:
-        /// Parameters of this inference algorithm
+        /// Parameters for HAK
         struct Properties {
             /// Enumeration of possible cluster choices
-            DAI_ENUM(ClustersType,MIN,DELTA,LOOP);
+            /** The following cluster choices are defined:
+             *   - MIN minimal clusters, i.e., one outer region for each maximal factor
+             *   - DELTA one outer region for each variable and its Markov blanket
+             *   - LOOP one cluster for each loop of length at most \a Properties::loopdepth, and in addition one cluster for each maximal factor
+             *   - BETHE Bethe approximation (one outer region for each maximal factor, inner regions are single variables)
+             */
+            DAI_ENUM(ClustersType,MIN,BETHE,DELTA,LOOP);
 
             /// Enumeration of possible message initializations
             DAI_ENUM(InitType,UNIFORM,RANDOM);
 
-            /// Verbosity
+            /// Verbosity (amount of output sent to stderr)
             size_t verbose;
 
             /// Maximum number of iterations
             size_t maxiter;
 
-            /// Tolerance
+            /// Maximum time (in seconds)
+            double maxtime;
+
+            /// Tolerance for convergence test
             Real tol;
 
-            /// Damping constant
+            /// Damping constant (0.0 means no damping, 1.0 is maximum damping)
             Real damping;
 
             /// How to choose the outer regions
@@ -89,10 +100,8 @@ class HAK : public DAIAlgRG {
         HAK() : DAIAlgRG(), _Qa(), _Qb(), _muab(), _muba(), _maxdiff(0.0), _iters(0U), props() {}
 
         /// Construct from FactorGraph \a fg and PropertySet \a opts
-        /** The clusters are chosen according to \a opts["clusters"]:
-         *  - MIN minimal clusters, i.e., one outer region for each maximal factor
-         *  - DELTA one outer region for each variable and its Markov blanket
-         *  - LOOP one cluster for each loop of length at most \a opts["loopdepth"], and in addition one cluster for each maximal factor of \a fg
+        /** \param fg Factor graph.
+         *  \param opts Parameters @see Properties
          */
         HAK( const FactorGraph &fg, const PropertySet &opts );
 
@@ -105,7 +114,6 @@ class HAK : public DAIAlgRG {
     //@{
         virtual HAK* clone() const { return new HAK(*this); }
         virtual std::string identify() const;
-        virtual Factor belief( const Var &v ) const;
         virtual Factor belief( const VarSet &vs ) const;
         virtual std::vector<Factor> beliefs() const;
         virtual Real logZ() const;
@@ -114,6 +122,7 @@ class HAK : public DAIAlgRG {
         virtual Real run();
         virtual Real maxDiff() const { return _maxdiff; }
         virtual size_t Iterations() const { return _iters; }
+        virtual void setMaxIter( size_t maxiter ) { props.maxiter = maxiter; }
         virtual void setProperties( const PropertySet &opts );
         virtual PropertySet getProperties() const;
         virtual std::string printProperties() const;