Removed interfaces deprecated in 0.2.6
[libdai.git] / include / dai / gibbs.h
index fa9e296..7f763f8 100644 (file)
@@ -1,21 +1,15 @@
-/*  Copyright (C) 2008  Frederik Eaton [frederik at ofb dot net]
+/*  This file is part of libDAI - http://www.libdai.org/
+ *
+ *  libDAI is licensed under the terms of the GNU General Public License version
+ *  2, or (at your option) any later version. libDAI is distributed without any
+ *  warranty. See the file COPYING for more details.
+ *
+ *  Copyright (C) 2008  Frederik Eaton  [frederik at ofb dot net]
+ */
 
-    This file is part of libDAI.
 
-    libDAI is free software; you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation; either version 2 of the License, or
-    (at your option) any later version.
-
-    libDAI is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with libDAI; if not, write to the Free Software
-    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-*/
+/// \file
+/// \brief Defines class Gibbs, which implements Gibbs sampling
 
 
 #ifndef __defined_libdai_gibbs_h
 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 periods)
+        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;
+        /// Number of iterations done (including burn-in periods)
+        size_t _iters;
+        /// Current joint state of all variables
+        _state_t _state;
+        /// Joint state with maximum probability seen so far
+        _state_t _max_state;
+        /// Highest score so far
+        Real _max_score;
+
     public:
-        /// Parameters of this inference algorithm
+        /// Parameters for Gibbs
         struct Properties {
-            /// Number of iterations
-            size_t iters;
+            /// Maximum number of iterations
+            size_t maxiter;
+
+            /// Maximum time (in seconds)
+            double maxtime;
+
+            /// Number of iterations after which a random restart is made
+            size_t restart;
+
+            /// Number of "burn-in" iterations after each (re)start (for which no statistics are gathered)
+            size_t burnin;
 
-            /// Verbosity
+            /// Verbosity (amount of output sent to stderr)
             size_t verbose;
         } props;
 
         /// Name of this inference algorithm
         static const char *Name;
 
-    protected:
-        typedef std::vector<size_t> _count_t;
-        size_t _sample_count;
-        std::vector<_count_t> _var_counts;
-        std::vector<_count_t> _factor_counts;
-
-        typedef std::vector<size_t> _state_t;
-        void update_counts(_state_t &st);
-        void randomize_state(_state_t &st);
-        Prob get_var_dist(_state_t &st, size_t i);
-        void resample_var(_state_t &st, size_t i);
-        size_t get_factor_entry(const _state_t &st, int factor);
-
     public:
-        // default constructor
-        Gibbs() : DAIAlgFG() {}
-        // copy constructor
-        Gibbs(const Gibbs & x) : DAIAlgFG(x), _sample_count(x._sample_count), _var_counts(x._var_counts), _factor_counts(x._factor_counts) {}
-        // construct Gibbs object from FactorGraph
-        Gibbs( const FactorGraph & fg, const PropertySet &opts ) : DAIAlgFG(fg) {
+        /// Default constructor
+        Gibbs() : DAIAlgFG(), _sample_count(0), _var_counts(), _factor_counts(), _iters(0), _state(), _max_state(), _max_score(-INFINITY) {}
+
+        /// Construct from FactorGraph \a fg and PropertySet \a opts
+        /** \param fg Factor graph.
+         *  \param opts Parameters @see Properties
+         */
+        Gibbs( const FactorGraph &fg, const PropertySet &opts ) : DAIAlgFG(fg), _sample_count(0), _var_counts(), _factor_counts(), _iters(0), _state(), _max_state(), _max_score(-INFINITY) {
             setProperties( opts );
             construct();
         }
-        // assignment operator
-        Gibbs & operator=(const Gibbs & x) {
-            if(this!=&x) {
-                DAIAlgFG::operator=(x);
-                _sample_count = x._sample_count;
-                _var_counts = x._var_counts;
-                _factor_counts = x._factor_counts;
-            }
-            return *this;
-        }
-        
+
+
+    /// \name General InfAlg interface
+    //@{
         virtual Gibbs* clone() const { return new Gibbs(*this); }
-        virtual Gibbs* create() const { return new Gibbs(); }
         virtual std::string identify() const { return std::string(Name) + printProperties(); }
-        virtual Factor belief( const Var &n ) const;
-        virtual Factor belief( const VarSet &ns ) const;
+        virtual Factor belief( const Var &v ) const { return beliefV( findVar( v ) ); }
+        virtual Factor belief( const VarSet &vs ) const;
+        virtual Factor beliefV( size_t i ) const;
+        virtual Factor beliefF( size_t I ) const;
         virtual std::vector<Factor> beliefs() const;
         virtual Real logZ() const { DAI_THROW(NOT_IMPLEMENTED); return 0.0; }
+        std::vector<std::size_t> findMaximum() const { return _max_state; }
         virtual void init();
         virtual void init( const VarSet &/*ns*/ ) { init(); }
-        virtual double run();
-        virtual double maxDiff() const { DAI_THROW(NOT_IMPLEMENTED); return 0.0; }
-        virtual size_t Iterations() const { return props.iters; }
-
-        Factor beliefV( size_t i ) const;
-        Factor beliefF( size_t I ) const;
-
+        virtual Real run();
+        virtual Real maxDiff() const { DAI_THROW(NOT_IMPLEMENTED); return 0.0; }
+        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;
+    //@}
+
+
+    /// \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 of all variables
+        std::vector<size_t>& state() { return _state; }
+        /// 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();
-        /// Set Props according to the PropertySet opts, where the values can be stored as std::strings or as the type of the corresponding Props member
-        void setProperties( const PropertySet &opts );
-        PropertySet getProperties() const;
-        std::string printProperties() const;
+        /// 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 );
 };
 
 
+/// Runs Gibbs sampling for \a maxiter iterations (of which \a burnin for burn-in) on FactorGraph \a fg, and returns the resulting state
+/** \relates Gibbs
+ */
+std::vector<size_t> getGibbsState( const FactorGraph &fg, size_t maxiter );
+
+
 } // end of namespace dai
 
 
+/** \example example_sprinkler_gibbs.cpp
+ *  This example shows how to use the Gibbs class.
+ */
+
+
 #endif