include/dai/mf.h

   1 /*  This file is part of libDAI - http://www.libdai.org/
   2  *
   3  *  libDAI is licensed under the terms of the GNU General Public License version
   4  *  2, or (at your option) any later version. libDAI is distributed without any
   5  *  warranty. See the file COPYING for more details.
   6  *
   7  *  Copyright (C) 2006-2009  Joris Mooij  [joris dot mooij at libdai dot org]
   8  *  Copyright (C) 2006-2007  Radboud University Nijmegen, The Netherlands
   9  */
  10
  11
  12 /// \file
  13 /// \brief Defines class MF which implements the Mean Field algorithm
  14
  15
  16 #ifndef __defined_libdai_mf_h
  17 #define __defined_libdai_mf_h
  18
  19
  20 #include <string>
  21 #include <dai/daialg.h>
  22 #include <dai/factorgraph.h>
  23 #include <dai/properties.h>
  24
  25
  26 namespace dai {
  27
  28
  29 /// Approximate inference algorithm "Mean Field"
  30 /** The Mean Field algorithm iteratively calculates approximations of
  31  *  single variable marginals (beliefs). The update equation for
  32  *  a single belief \f$b_i\f$ is given by:
  33  *    \f[ b_i^{\mathrm{new}}(x_i) \propto \prod_{I\in N_i} \exp \left( \sum_{x_{N_I \setminus \{i\}}} \log f_I(x_I) \prod_{j \in N_I \setminus \{i\}} b_j(x_j) \right) \f]
  34  *  These update equations are performed for all variables until convergence.
  35  */
  36 class MF : public DAIAlgFG {
  37     private:
  38         /// Current approximations of single variable marginals
  39         std::vector<Factor>  _beliefs;
  40         /// Maximum difference encountered so far
  41         Real _maxdiff;
  42         /// Number of iterations needed
  43         size_t _iters;
  44
  45     public:
  46         /// Parameters for MF
  47         struct Properties {
  48             /// Verbosity (amount of output sent to stderr)
  49             size_t verbose;
  50
  51             /// Maximum number of iterations
  52             size_t maxiter;
  53
  54             /// Tolerance for convergence test
  55             Real tol;
  56
  57             /// Damping constant (0.0 means no damping, 1.0 is maximum damping)
  58             Real damping;
  59         } props;
  60
  61         /// Name of this inference algorithm
  62         static const char *Name;
  63
  64     public:
  65     /// \name Constructors/destructors
  66     //@{
  67         /// Default constructor
  68         MF() : DAIAlgFG(), _beliefs(), _maxdiff(0.0), _iters(0U), props() {}
  69
  70         /// Construct from FactorGraph \a fg and PropertySet \a opts
  71         /** \param opts Parameters @see Properties
  72          */
  73         MF( const FactorGraph &fg, const PropertySet &opts ) : DAIAlgFG(fg), _beliefs(), _maxdiff(0.0), _iters(0U), props() {
  74             setProperties( opts );
  75             construct();
  76         }
  77     //@}
  78
  79     /// \name General InfAlg interface
  80     //@{
  81         virtual MF* clone() const { return new MF(*this); }
  82         virtual std::string identify() const;
  83         virtual Factor belief( const Var &v ) const { return beliefV( findVar( v ) ); }
  84         virtual Factor belief( const VarSet &vs ) const;
  85         virtual Factor beliefV( size_t i ) const;
  86         virtual std::vector<Factor> beliefs() const;
  87         virtual Real logZ() const;
  88         virtual void init();
  89         virtual void init( const VarSet &ns );
  90         virtual Real run();
  91         virtual Real maxDiff() const { return _maxdiff; }
  92         virtual size_t Iterations() const { return _iters; }
  93         virtual void setProperties( const PropertySet &opts );
  94         virtual PropertySet getProperties() const;
  95         virtual std::string printProperties() const;
  96     //@}
  97
  98     private:
  99         /// Helper function for constructors
 100         void construct();
 101
 102         /// Calculates an updated belief of variable \a i
 103         Factor calcNewBelief( size_t i );
 104 };
 105
 106
 107 } // end of namespace dai
 108
 109
 110 #endif