Some documentation improvements
authorJoris Mooij <joris.mooij@tuebingen.mpg.de>
Sun, 15 Nov 2009 18:10:39 +0000 (19:10 +0100)
committerJoris Mooij <joris.mooij@tuebingen.mpg.de>
Sun, 15 Nov 2009 18:10:39 +0000 (19:10 +0100)
13 files changed:
README
TODO
include/dai/bbp.h
include/dai/bp.h
include/dai/cbp.h
include/dai/exactinf.h
include/dai/gibbs.h
include/dai/hak.h
include/dai/jtree.h
include/dai/lc.h
include/dai/mf.h
include/dai/mr.h
include/dai/treeep.h

diff --git a/README b/README
index 0ea97a6..f5e28fd 100644 (file)
--- a/README
+++ b/README
@@ -2,8 +2,8 @@ libDAI  -  A free/open source C++ library for Discrete Approximate Inference
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Version:  git commit 76cf77837c617f54202590125c7a566ae443d0ab
-Date:     Thu Nov 12 10:52:51 2009 +0100
+Version:  git commit 7982eafde7cecc6ee4105461337667980203e4d2
+Date:     Thu Nov 12 16:36:54 2009 +0100
 See also: http://www.libdai.org
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
diff --git a/TODO b/TODO
index e5f0c9c..105d4b5 100644 (file)
--- a/TODO
+++ b/TODO
@@ -1,7 +1,5 @@
 To do for the next release (0.2.3):
 
-Improve documentation of all .props structs.
-
 Write a concept/notations page for the documentation,
 explaining the concepts of "state" (index into a 
 multi-dimensional array, e.g., one corresponding
index 59ba043..efddc6c 100644 (file)
@@ -65,7 +65,7 @@ class BBP {
         BP_dual _bp_dual;
         /// Pointer to the factor graph
         const FactorGraph *_fg;
-        /// Pointer to the approximate inference algorithm
+        /// Pointer to the approximate inference algorithm (currently, only BP objects are supported)
         const InfAlg *_ia;
     //@}
 
@@ -259,6 +259,9 @@ class BBP {
     /// \name Constructors/destructors
     //@{
         /// Construct BBP object from a InfAlg \a ia and a PropertySet \a opts
+        /** \param ia should be a BP object or something compatible
+         *  \param opts Parameters @see Properties
+         */
         BBP( const InfAlg *ia, const PropertySet &opts ) : _bp_dual(ia), _fg(&(ia->fg())), _ia(ia) {
             props.set(opts);
         }
@@ -327,18 +330,24 @@ class BBP {
     //@}
 
     public:
-        /// Parameters of this algorithm
+        /// Parameters for BBP
         /* PROPERTIES(props,BBP) {
-           /// Enumeration of possible update schedules
+           /// \brief Enumeration of possible update schedules
+           /// - SEQ_FIX fixed sequential updates
+           /// - SEQ_MAX maximum residual updates (inspired by [\ref EMK06])
+           /// - SEQ_BP_REV schedule used by BP, but reversed
+           /// - SEQ_BP_FWD schedule used by BP
+           /// - PAR parallel updates
            DAI_ENUM(UpdateType,SEQ_FIX,SEQ_MAX,SEQ_BP_REV,SEQ_BP_FWD,PAR);
 
-           /// Verbosity
+           /// Verbosity (amount of output sent to stderr)
            size_t verbose;
 
            /// Maximum number of iterations
            size_t maxiter;
 
-           /// Tolerance (not used for updates = SEQ_BP_REV, SEQ_BP_FWD)
+           /// Tolerance for convergence test
+           /// \note Not used for updates = SEQ_BP_REV, SEQ_BP_FWD
            Real tol;
 
            /// Damping constant (0 for none); damping = 1 - lambda where lambda is the damping constant used in [\ref EaG09]
@@ -356,12 +365,21 @@ class BBP {
 */
         struct Properties {
             /// Enumeration of possible update schedules
+            /** The following update schedules are defined:
+             *  - SEQ_FIX fixed sequential updates
+             *  - SEQ_MAX maximum residual updates (inspired by [\ref EMK06])
+             *  - SEQ_BP_REV schedule used by BP, but reversed
+             *  - SEQ_BP_FWD schedule used by BP
+             *  - PAR parallel updates
+             */
             DAI_ENUM(UpdateType,SEQ_FIX,SEQ_MAX,SEQ_BP_REV,SEQ_BP_FWD,PAR);
-            /// Verbosity
+            /// Verbosity (amount of output sent to stderr)
             size_t verbose;
             /// Maximum number of iterations
             size_t maxiter;
-            /// Tolerance (not used for updates = SEQ_BP_REV, SEQ_BP_FWD)
+            /// Tolerance for convergence test
+            /** \note Not used for updates = SEQ_BP_REV, SEQ_BP_FWD
+             */
             Real tol;
             /// Damping constant (0 for none); damping = 1 - lambda where lambda is the damping constant used in [\ref EaG09]
             Real damping;
index 536164f..ea872e5 100644 (file)
@@ -50,12 +50,6 @@ namespace dai {
  *  The logarithm of the partition sum is calculated by:
  *    \f[ \log Z = \sum_i (1 - |N_i|) \sum_{x_i} b_i(x_i) \log b_i(x_i) - \sum_I \sum_{x_I} b_I(x_I) \log \frac{b_I(x_I)}{f_I(x_I)} \f]
  *
- *  There are several predefined update schedules:
- *    - PARALL parallel updates
- *    - SEQFIX sequential updates using a fixed sequence
- *    - SEQRND sequential updates using a random sequence
- *    - SEQMAX maximum-residual updates [\ref EMK06]
- *
  *  For the max-product algorithm, a heuristic way of finding the MAP state (the 
  *  joint configuration of all variables which has maximum probability) is provided
  *  by the findMaximum() method, which can be called after convergence.
@@ -95,15 +89,25 @@ class BP : public DAIAlgFG {
         std::vector<std::pair<std::size_t, std::size_t> > _sentMessages;
 
     public:
-        /// Parameters of this inference algorithm
+        /// Parameters for BP
         struct Properties {
             /// Enumeration of possible update schedules
+            /** The following update schedules have been defined:
+             *  - PARALL parallel updates
+             *  - SEQFIX sequential updates using a fixed sequence
+             *  - SEQRND sequential updates using a random sequence
+             *  - SEQMAX maximum-residual updates [\ref EMK06]
+             */
             DAI_ENUM(UpdateType,SEQFIX,SEQRND,SEQMAX,PARALL);
 
             /// Enumeration of inference variants
+            /** There are two inference variants:
+             *  - SUMPROD Sum-Product
+             *  - MAXPROD Max-Product (equivalent to Min-Sum)
+             */
             DAI_ENUM(InfType,SUMPROD,MAXPROD);
 
-            /// Verbosity
+            /// Verbosity (amount of output sent to stderr)
             size_t verbose;
 
             /// Maximum number of iterations
@@ -121,7 +125,7 @@ class BP : public DAIAlgFG {
             /// Message update schedule
             UpdateType updates;
 
-            /// Type of inference: sum-product or max-product?
+            /// Inference variant
             InfType inference;
         } props;
 
@@ -138,6 +142,8 @@ class BP : public DAIAlgFG {
         BP() : DAIAlgFG(), _edges(), _edge2lut(), _lut(), _maxdiff(0.0), _iters(0U), _sentMessages(), props(), recordSentMessages(false) {}
 
         /// Construct from FactorGraph \a fg and PropertySet \a opts
+        /** \param opts Parameters @see Properties
+         */
         BP( const FactorGraph & fg, const PropertySet &opts ) : DAIAlgFG(fg), _edges(), _maxdiff(0.0), _iters(0U), _sentMessages(), props(), recordSentMessages(false) {
             setProperties( opts );
             construct();
index 6f252f8..8caf058 100644 (file)
@@ -61,6 +61,8 @@ class CBP : public DAIAlgFG {
 
     public:
         /// Construct CBP object from FactorGraph \a fg and PropertySet \a opts
+        /** \param opts Parameters @see Properties
+         */
         CBP( const FactorGraph &fg, const PropertySet &opts ) : DAIAlgFG(fg) {
             props.set( opts );
             construct();
@@ -91,7 +93,7 @@ class CBP : public DAIAlgFG {
 
         //----------------------------------------------------------------
 
-        /// Parameters of this inference algorithm
+        /// Parameters for CBP
         /* PROPERTIES(props,CBP) {
             /// Enumeration of possible update schedules
             typedef BP::Properties::UpdateType UpdateType;
@@ -102,17 +104,17 @@ class CBP : public DAIAlgFG {
             /// Enumeration of possible clampings: variables or factors
             DAI_ENUM(ClampType,CLAMP_VAR,CLAMP_FACTOR);
 
-            /// Verbosity
+            /// Verbosity (amount of output sent to stderr)
             size_t verbose = 0;
 
-            /// Tolerance to use in BP
+            /// Tolerance for BP convergence test
             Real tol;
             /// Update style for BP
             UpdateType updates;
             /// Maximum number of iterations for BP
             size_t maxiter;
 
-            /// Tolerance to use for controlling recursion depth (\a recurse is REC_LOGZ or REC_BDIFF)
+            /// Tolerance used for controlling recursion depth (\a recurse is REC_LOGZ or REC_BDIFF)
             Real rec_tol;
             /// Maximum number of levels of recursion (\a recurse is REC_FIXED)
             size_t max_levels = 10;
@@ -147,15 +149,15 @@ class CBP : public DAIAlgFG {
             DAI_ENUM(ChooseMethodType,CHOOSE_RANDOM,CHOOSE_MAXENT,CHOOSE_BBP,CHOOSE_BP_L1,CHOOSE_BP_CFN);
             /// Enumeration of possible clampings: variables or factors
             DAI_ENUM(ClampType,CLAMP_VAR,CLAMP_FACTOR);
-            /// Verbosity
+            /// Verbosity (amount of output sent to stderr)
             size_t verbose;
-            /// Tolerance to use in BP
+            /// Tolerance for BP convergence test
             Real tol;
             /// Update style for BP
             UpdateType updates;
             /// Maximum number of iterations for BP
             size_t maxiter;
-            /// Tolerance to use for controlling recursion depth (\a recurse is REC_LOGZ or REC_BDIFF)
+            /// Tolerance used for controlling recursion depth (\a recurse is REC_LOGZ or REC_BDIFF)
             Real rec_tol;
             /// Maximum number of levels of recursion (\a recurse is REC_FIXED)
             size_t max_levels;
index ed1512f..5a1f0bf 100644 (file)
@@ -34,9 +34,9 @@ namespace dai {
  */
 class ExactInf : public DAIAlgFG {
     public:
-        /// Parameters of this inference algorithm
+        /// Parameters for ExactInf
         struct Properties {
-            /// Verbosity
+            /// Verbosity (amount of output sent to stderr)
             size_t verbose;
         } props;
 
@@ -58,6 +58,8 @@ class ExactInf : public DAIAlgFG {
         ExactInf() : DAIAlgFG(), props(), _beliefsV(), _beliefsF(), _logZ(0) {}
 
         /// Construct from FactorGraph \a fg and PropertySet \a opts
+        /** \param opts Parameters @see Properties
+         */
         ExactInf( const FactorGraph &fg, const PropertySet &opts ) : DAIAlgFG(fg), props(), _beliefsV(), _beliefsF(), _logZ() {
             setProperties( opts );
             construct();
index 451941e..fbc5f62 100644 (file)
@@ -43,7 +43,7 @@ class Gibbs : public DAIAlgFG {
         _state_t _state;
 
     public:
-        /// Parameters of this inference algorithm
+        /// Parameters for Gibbs
         struct Properties {
             /// Total number of iterations
             size_t iters;
@@ -51,7 +51,7 @@ class Gibbs : public DAIAlgFG {
             /// Number of "burn-in" iterations
             size_t burnin;
 
-            /// Verbosity
+            /// Verbosity (amount of output sent to stderr)
             size_t verbose;
         } props;
 
@@ -63,6 +63,8 @@ class Gibbs : public DAIAlgFG {
         Gibbs() : DAIAlgFG(), _sample_count(0), _var_counts(), _factor_counts(), _state() {}
 
         /// Construct from FactorGraph \a fg and PropertySet \a opts
+        /** \param opts Parameters @see Properties
+         */
         Gibbs( const FactorGraph &fg, const PropertySet &opts ) : DAIAlgFG(fg), _sample_count(0), _var_counts(), _factor_counts(), _state() {
             setProperties( opts );
             construct();
index 0a00b9b..fee0386 100644 (file)
@@ -46,24 +46,29 @@ class HAK : public DAIAlgRG {
         size_t _iters;
 
     public:
-        /// Parameters of this inference algorithm
+        /// Parameters for HAK
         struct Properties {
             /// Enumeration of possible cluster choices
+            /** 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
+             */
             DAI_ENUM(ClustersType,MIN,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
+            /// 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 +94,7 @@ 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 opts Parameters @see Properties
          */
         HAK( const FactorGraph &fg, const PropertySet &opts );
 
index b92d3e5..6a0e55c 100644 (file)
@@ -59,21 +59,29 @@ class JTree : public DAIAlgRG {
         /// Inner region beliefs
         std::vector<Factor> Qb;
 
-        /// Parameters of this inference algorithm
+        /// Parameters for JTree
         struct Properties {
             /// Enumeration of possible JTree updates
+            /** There are two types of updates:
+             *  - HUGIN similar to those in HUGIN
+             *  - SHSH Shafer-Shenoy type
+             */
             DAI_ENUM(UpdateType,HUGIN,SHSH);
 
             /// Enumeration of inference variants
+            /** There are two inference variants:
+             *  - SUMPROD Sum-Product
+             *  - MAXPROD Max-Product (equivalent to Min-Sum)
+             */
             DAI_ENUM(InfType,SUMPROD,MAXPROD);
 
-            /// Verbosity
+            /// Verbosity (amount of output sent to stderr)
             size_t verbose;
 
-            /// Type of updates: HUGIN or Shafer-Shenoy
+            /// Type of updates
             UpdateType updates;
 
-            /// Type of inference: sum-product or max-product
+            /// Type of inference
             InfType inference;
         } props;
 
@@ -88,7 +96,7 @@ class JTree : public DAIAlgRG {
 
         /// Construct from FactorGraph \a fg and PropertySet \a opts
         /** \param fg factor graph (which has to be connected);
-         *  \param opts parameters;
+         ** \param opts Parameters @see Properties
          *  \param automatic if \c true, construct the junction tree automatically, using the MinFill heuristic.
          *  \throw FACTORGRAPH_NOT_CONNECTED if \a fg is not connected
          */
index c62c625..1c817c9 100644 (file)
@@ -45,7 +45,7 @@ class LC : public DAIAlgFG {
         size_t _iters;
 
     public:
-        /// Parameters of this inference algorithm
+        /// Parameters for LC
         struct Properties {
             /// Enumeration of possible ways to initialize the cavities
             /** The following initialization methods are defined:
@@ -63,19 +63,19 @@ class LC : public DAIAlgFG {
              */
             DAI_ENUM(UpdateType,SEQFIX,SEQRND);
 
-            /// Verbosity
+            /// Verbosity (amount of output sent to stderr)
             size_t verbose;
 
             /// Maximum number of iterations
             size_t maxiter;
 
-            /// Tolerance
+            /// Tolerance for convergence test
             Real tol;
 
             /// Complete or partial reinitialization of cavity graphs?
             bool reinit;
 
-            /// Damping constant
+            /// Damping constant (0.0 means no damping, 1.0 is maximum damping)
             Real damping;
 
             /// How to initialize the cavities
@@ -99,7 +99,7 @@ class LC : public DAIAlgFG {
         LC() : DAIAlgFG(), _pancakes(), _cavitydists(), _phis(), _beliefs(), _maxdiff(), _iters(), props() {}
 
         /// Construct from FactorGraph \a fg and PropertySet \a opts
-        /** \see Properties
+        /** \param opts Parameters @see Properties
          */
         LC( const FactorGraph &fg, const PropertySet &opts );
 
index dd8cb87..9218579 100644 (file)
@@ -43,18 +43,18 @@ class MF : public DAIAlgFG {
         size_t _iters;
 
     public:
-        /// Parameters of this inference algorithm
+        /// Parameters for MF
         struct Properties {
-            /// Verbosity
+            /// Verbosity (amount of output sent to stderr)
             size_t verbose;
 
             /// Maximum number of iterations
             size_t maxiter;
 
-            /// Tolerance
+            /// Tolerance for convergence test
             Real tol;
 
-            /// Damping constant
+            /// Damping constant (0.0 means no damping, 1.0 is maximum damping)
             Real damping;
         } props;
 
@@ -68,6 +68,8 @@ class MF : public DAIAlgFG {
         MF() : DAIAlgFG(), _beliefs(), _maxdiff(0.0), _iters(0U), props() {}
 
         /// Construct from FactorGraph \a fg and PropertySet \a opts
+        /** \param opts Parameters @see Properties
+         */
         MF( const FactorGraph &fg, const PropertySet &opts ) : DAIAlgFG(fg), _beliefs(), _maxdiff(0.0), _iters(0U), props() {
             setProperties( opts );
             construct();
index 10e7201..3c25b8f 100644 (file)
@@ -66,7 +66,7 @@ class MR : public DAIAlgFG {
         size_t _iters;
 
     public:
-        /// Parameters of this inference algorithm
+        /// Parameters for MR
         struct Properties {
             /// Enumeration of different types of update equations
             /** The possible update equations are:
@@ -83,10 +83,10 @@ class MR : public DAIAlgFG {
              */
             DAI_ENUM(InitType,RESPPROP,CLAMPING,EXACT);
 
-            /// Verbosity
+            /// Verbosity (amount of output sent to stderr)
             size_t verbose;
 
-            /// Tolerance
+            /// Tolerance for convergence test
             Real tol;
 
             /// Update equations
@@ -104,7 +104,8 @@ class MR : public DAIAlgFG {
         MR() : DAIAlgFG(), supported(), con(), nb(), tJ(), theta(), M(), kindex(), cors(), N(), Mag(), _maxdiff(), _iters(), props() {}
 
         /// Construct from FactorGraph \a fg and PropertySet \a opts
-        /** \note This implementation only deals with binary variables and pairwise interactions.
+        /** \param opts Parameters @see Properties
+         *  \note This implementation only deals with binary variables and pairwise interactions.
          *  \throw NOT_IMPLEMENTED if \a fg has factors depending on three or more variables or has variables with more than two possible states.
          */
         MR( const FactorGraph &fg, const PropertySet &opts );
index 6499a18..5a3e1ac 100644 (file)
@@ -43,7 +43,7 @@ class TreeEP : public JTree {
         size_t                _iters;
 
     public:
-        /// Parameters of this inference algorithm
+        /// Parameters for TreeEP
         struct Properties {
             /// Enumeration of possible choices for the tree
             /** The two possibilities are:
@@ -54,13 +54,13 @@ class TreeEP : public JTree {
              */
             DAI_ENUM(TypeType,ORG,ALT);
 
-            /// Verbosity
+            /// Verbosity (amount of output sent to stderr)
             size_t verbose;
 
             /// Maximum number of iterations
             size_t maxiter;
 
-            /// Tolerance
+            /// Tolerance for convergence test
             Real tol;
 
             /// How to choose the tree
@@ -143,7 +143,8 @@ class TreeEP : public JTree {
         }
 
         /// Construct from FactorGraph \a fg and PropertySet \a opts
-        /** \note The factor graph has to be connected.
+        /** \param opts Parameters @see Properties
+         *  \note The factor graph has to be connected.
          *  \throw FACTORGRAPH_NOT_CONNECTED if \a fg is not connected
          */
         TreeEP( const FactorGraph &fg, const PropertySet &opts );