Improved documentation of include/dai/bp_dual.h
authorJoris Mooij <joris.mooij@tuebingen.mpg.de>
Tue, 10 Nov 2009 11:03:10 +0000 (12:03 +0100)
committerJoris Mooij <joris.mooij@tuebingen.mpg.de>
Tue, 10 Nov 2009 11:03:10 +0000 (12:03 +0100)
ChangeLog
TODO
include/dai/bbp.h
include/dai/bp_dual.h
include/dai/cbp.h
include/dai/emalg.h
include/dai/evidence.h

index 7281092..7c5ae06 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
 * Introduced CCNODEBUGFLAGS in Makefile
 * Updated copyright headers
 * Added max-product functionality to JTree
-* [Charlie Vaske] EM bugfix (was using abs() instead of fabs() in 
+* [Charles Vaske] EM bugfix (was using abs() instead of fabs() in 
   determining EM termination, which caused a loss of precision).
-* [Charlie Vaske] New constructor in Permute for canonical variable ordering
-* [Charlie Vaske] New constructor in Factor that reorders variables to canonical ordering
-* [Charlie Vaske] New accessor in Properties for getting all keys
-* [Charlie Vaske] New function for getting inferred parameters
+* [Charles Vaske] New constructor in Permute for canonical variable ordering
+* [Charles Vaske] New constructor in Factor that reorders variables to canonical ordering
+* [Charles Vaske] New accessor in Properties for getting all keys
+* [Charles Vaske] New function for getting inferred parameters
 * Cleaned up error handling by introducing the DAI_THROWE macro
 * Introduced DAI_DEBASSERT macro to abbreviate a common pattern
 * Changed FactorGraph::clamp and DAIAlg::clamp interfaces (the variable to be
@@ -62,7 +62,7 @@ git ae0fc30e10be6683cbfc209dcee56f34234a6cb8
 * Added BipartiteGraph::eraseEdge
 * Removed all the virtual default constructors *::create(), as they are not used.
 * Fixed bug in MaxSpanningTree (it wrongly assumed that the tree was not empty).
-* [Charlie Vaske] Added Expectation Maximization code.
+* [Charles Vaske] Added Expectation Maximization code.
 * Added MatLab QuickStart to README.
 * MEX file dai now also returns variable and factor beliefs.
 * Cleanups and extra documentation of the code contributed by Frederik Eaton
diff --git a/TODO b/TODO
index 4140b9a..b17456b 100644 (file)
--- a/TODO
+++ b/TODO
@@ -2,7 +2,6 @@ To do for the next release (0.2.3):
 
 Improve documentation:
 
-       bp_dual.h
        bbp.h
        cbp.h
        evidence.h
index ca8b763..866193c 100644 (file)
@@ -12,6 +12,7 @@
 /// \brief Defines class BBP [\ref EaG09]
 /// \todo Fit more closely into libDAI framework
 /// \todo Improve documentation
+/// \author Frederik Eaton
 
 
 #ifndef ___defined_libdai_bbp_h
@@ -39,6 +40,8 @@ std::vector<size_t> getGibbsState( const InfAlg &ia, size_t iters );
 
 
 /// Implements BBP (Back-Belief-Propagation) [\ref EaG09]
+/** \author Frederik Eaton
+ */
 class BBP {
     protected:
     /// \name Inputs
index e205f98..e13b01a 100644 (file)
@@ -9,9 +9,9 @@
 
 
 /// \file
-/// \brief Defines class BP_dual
-/// \todo This replicates a large part of the functionality of BP; would it not be shorter to adapt BP instead?
-/// \todo Improve documentation
+/// \brief Defines class BP_dual, which is used primarily by BBP.
+/// \todo This replicates a large part of the functionality of BP; would it not be more efficient to adapt BP instead?
+/// \author Frederik Eaton
 
 
 #ifndef __defined_libdai_bp_dual_h
@@ -31,9 +31,10 @@ namespace dai {
  *  to variables and messages from variables to factors), and normalizers, given an InfAlg.
  *  These are computed from the variable and factor beliefs of the InfAlg.
  *  This class is used primarily by BBP.
+ *
+ *  \author Frederik Eaton
  */
 class BP_dual {
-
     protected:
         /// Convenience label for storing edge properties
         template<class T>
@@ -72,28 +73,28 @@ class BP_dual {
 
         /// Does all necessary preprocessing
         void init();
-        /// Allocates space for _msgs
+        /// Allocates space for \a _msgs
         void regenerateMessages();
-        /// Allocates space for _beliefs
+        /// Allocates space for \a _beliefs
         void regenerateBeliefs();
 
         /// Calculate all messages from InfAlg beliefs
         void calcMessages();
-        /// Update factor->variable message (i->I)
+        /// Update factor->variable message (\a i -> \a I)
         void calcNewM(size_t i, size_t _I);
-        /// Update variable->factor message (I->i)
+        /// Update variable->factor message (\a I -> \a i)
         void calcNewN(size_t i, size_t _I);
 
         /// Calculate all variable and factor beliefs from messages
         void calcBeliefs();
-        /// Calculate variable belief
+        /// Calculate belief of variable \a i
         void calcBeliefV(size_t i);
-        /// Calculate factor belief
+        /// Calculate belief of factor \a I
         void calcBeliefF(size_t I);
 
     public:
         /// Construct BP_dual object from (converged) InfAlg object's beliefs and factors.
-        /*  A pointer to the the InfAlg object is stored,
+        /** \warning A pointer to the the InfAlg object is stored,
          *  so the object must not be destroyed before the BP_dual is destroyed.
          */
         BP_dual( const InfAlg *ia ) : _ia(ia) { init(); }
@@ -101,31 +102,31 @@ class BP_dual {
         /// Returns the underlying FactorGraph
         const FactorGraph& fg() const { return _ia->fg(); }
 
-        /// Returns reference to factor -> var message (I->i)
+        /// Returns reference to factor->variable message (\a I -> \a i)
         Prob & msgM( size_t i, size_t _I ) { return _msgs.m[i][_I]; }
-        /// Returns constant reference to factor -> var message (I->i)
+        /// Returns constant reference to factor->variable message (\a I -> \a i)
         const Prob & msgM( size_t i, size_t _I ) const { return _msgs.m[i][_I]; }
-        /// Returns reference to var -> factor message (i->I)
+        /// Returns reference to variable -> factor message (\a i -> \a I)
         Prob & msgN( size_t i, size_t _I ) { return _msgs.n[i][_I]; }
-        /// Returns constant reference to var -> factor message (i->I)
+        /// Returns constant reference to variable -> factor message (\a i -> \a I)
         const Prob & msgN( size_t i, size_t _I ) const { return _msgs.n[i][_I]; }
-        /// Returns reference to normalizer for msgM
+        /// Returns reference to normalizer for factor->variable message (\a I -> \a i)
         Real & zM( size_t i, size_t _I ) { return _msgs.Zm[i][_I]; }
-        /// Returns constant reference to normalizer for msgM
+        /// Returns constant reference to normalizer for factor->variable message (\a I -> \a i)
         const Real & zM( size_t i, size_t _I ) const { return _msgs.Zm[i][_I]; }
-        /// Returns reference to normalizer for msgN
+        /// Returns reference to normalizer for variable -> factor message (\a i -> \a I)
         Real & zN( size_t i, size_t _I ) { return _msgs.Zn[i][_I]; }
-        /// Returns constant reference to normalizer for msgN
+        /// Returns constant reference to normalizer for variable -> factor message (\a i -> \a I)
         const Real & zN( size_t i, size_t _I ) const { return _msgs.Zn[i][_I]; }
 
-        /// Returns variable belief
+        /// Returns belief of variable \a i
         Factor beliefV( size_t i ) const { return Factor( _ia->fg().var(i), _beliefs.b1[i] ); }
-        /// Returns factor belief
+        /// Returns belief of factor \a I
         Factor beliefF( size_t I ) const { return Factor( _ia->fg().factor(I).vars(), _beliefs.b2[I] ); }
 
-        /// Returns normalizer for variable belief
+        /// Returns normalizer for belief of variable \a i
         Real beliefVZ( size_t i ) const { return _beliefs.Zb1[i]; }
-        /// Returns normalizer for factor belief
+        /// Returns normalizer for belief of factor \a I
         Real beliefFZ( size_t I ) const { return _beliefs.Zb2[I]; }
 };
 
index 7b572f6..253baf8 100644 (file)
@@ -10,6 +10,7 @@
 
 /// \file
 /// \brief Defines class CBP [\ref EaG09]
+/// \author Frederik Eaton
 /// \todo Improve documentation
 
 
@@ -40,6 +41,8 @@ std::pair<size_t, size_t> bbpFindClampVar( const InfAlg &in_bp, bool clampingVar
  *  levels (other stopping criteria are also implemented, see
  *  \a recursion property). The resulting approximate marginals are
  *  combined using logZ estimates.
+ *
+ *  \author Frederik Eaton
  */
 class CBP : public DAIAlgFG {
     private:
index 4315f5e..ec523b4 100644 (file)
@@ -27,6 +27,7 @@
 /// \brief Defines classes related to Expectation Maximization: EMAlg, ParameterEstimation, CondProbEstimation and SharedParameters
 /// \todo Describe EM file format
 /// \todo Improve documentation
+/// \author Charles Vaske
 
 
 namespace dai {
@@ -41,6 +42,8 @@ namespace dai {
  *  via the static ParameterEstimation::registerMethod function.
  *  The default registry only contains CondProbEstimation, named
  *  "ConditionalProbEstimation".
+ *
+ *  \author Charles Vaske
  */
 class ParameterEstimation {
     public:
@@ -81,6 +84,8 @@ class ParameterEstimation {
 
 
 /// Estimates the parameters of a conditional probability table, using pseudocounts.
+/** \author Charles Vaske
+ */
 class CondProbEstimation : private ParameterEstimation {
     private:
         /// Number of states of the variable of interest
@@ -137,6 +142,8 @@ class CondProbEstimation : private ParameterEstimation {
  *  class couples one or more factors (together with the specified orderings
  *  of the variables) with a ParameterEstimation object, taking care of the
  *  necessary permutations of the factor entries / parameters.
+ * 
+ *  \author Charles Vaske
  */
 class SharedParameters {
     public:
@@ -195,6 +202,8 @@ class SharedParameters {
 
 
 /// A MaximizationStep groups together several parameter estimation tasks into a single unit.
+/** \author Charles Vaske
+ */
 class MaximizationStep {
     private:
         std::vector<SharedParameters> _params;
@@ -241,6 +250,8 @@ class MaximizationStep {
  *  Having multiple and separate maximization steps allows for maximizing some
  *  parameters, performing another E step, and then maximizing separate
  *  parameters, which may result in faster convergence in some cases.
+ *
+ *  \author Charles Vaske
  */
 class EMAlg {
     private:
index c636695..aecddb6 100644 (file)
 
 
 /// \file
-/// \brief Defines classes Evidence and Observation
-/// \todo Describe tabular data file format
-/// \todo Improve documentation
+/** \brief Defines classes Evidence and Observation
+ *  \todo Describe tabular data file format
+ *  \todo Improve documentation
+ *  \author Charles Vaske
+ */
 
 
 #ifndef __defined_libdai_evidence_h
@@ -27,6 +29,8 @@ namespace dai {
 
 
 /// Stores observed values of a subset of variables
+/** \author Charles Vaske
+ */  
 class Observation {
     private:
         /// Used to store the state of some variables
@@ -50,6 +54,8 @@ class Observation {
 /// Stores multiple joint observations of sets of variables.
 /** The Evidence class stores multiple samples, where each sample is the joint
  *  observation of the states of some variables.
+ *
+ *  \author Charles Vaske
  */
 class Evidence {
     private: