Cleaned up variable elimination code in ClusterGraph
[libdai.git] / include / dai / bbp.h
index c361afe..fda1036 100644 (file)
@@ -38,6 +38,12 @@ DAI_ENUM(BBPCostFunctionBase,CFN_GIBBS_B,CFN_GIBBS_B2,CFN_GIBBS_EXP,CFN_GIBBS_B_
 /// Predefined cost functions that can be used with BBP
 class BBPCostFunction : public BBPCostFunctionBase {
     public:
+        /// Default constructor
+        BBPCostFunction() : BBPCostFunctionBase() {}
+
+        /// Construct from BBPCostFunctionBase \a x
+        BBPCostFunction( const BBPCostFunctionBase &x ) : BBPCostFunctionBase(x) {}
+
         /// Returns whether this cost function depends on having a Gibbs state
         bool needGibbsState() const;
 
@@ -65,7 +71,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;
     //@}
 
@@ -105,14 +111,14 @@ class BBP {
         /// Unnormalized factor belief adjoints
         std::vector<Prob> _adj_b_F_unnorm;
 
-        /// _T[i][_I] (see eqn. (41) in [\ref EaG09])
-        std::vector<std::vector<Prob > > _T;
-        /// _U[I][_i] (see eqn. (42) in [\ref EaG09])
-        std::vector<std::vector<Prob > > _U;
-        /// _S[i][_I][_j] (see eqn. (43) in [\ref EaG09])
-        std::vector<std::vector<std::vector<Prob > > > _S;
-        /// _R[I][_i][_J] (see eqn. (44) in [\ref EaG09])
-        std::vector<std::vector<std::vector<Prob > > > _R;
+        /// _Tmsg[i][_I] (see eqn. (41) in [\ref EaG09])
+        std::vector<std::vector<Prob > > _Tmsg;
+        /// _Umsg[I][_i] (see eqn. (42) in [\ref EaG09])
+        std::vector<std::vector<Prob > > _Umsg;
+        /// _Smsg[i][_I][_j] (see eqn. (43) in [\ref EaG09])
+        std::vector<std::vector<std::vector<Prob > > > _Smsg;
+        /// _Rmsg[I][_i][_J] (see eqn. (44) in [\ref EaG09])
+        std::vector<std::vector<std::vector<Prob > > > _Rmsg;
 
         /// Number of iterations done
         size_t _iters;
@@ -165,21 +171,21 @@ class BBP {
     /// \name Accessors/mutators
     //@{
         /// Returns reference to T value; see eqn. (41) in [\ref EaG09]
-        Prob & T(size_t i, size_t _I) { return _T[i][_I]; }
+        Prob & T(size_t i, size_t _I) { return _Tmsg[i][_I]; }
         /// Returns constant reference to T value; see eqn. (41) in [\ref EaG09]
-        const Prob & T(size_t i, size_t _I) const { return _T[i][_I]; }
+        const Prob & T(size_t i, size_t _I) const { return _Tmsg[i][_I]; }
         /// Returns reference to U value; see eqn. (42) in [\ref EaG09]
-        Prob & U(size_t I, size_t _i) { return _U[I][_i]; }
+        Prob & U(size_t I, size_t _i) { return _Umsg[I][_i]; }
         /// Returns constant reference to U value; see eqn. (42) in [\ref EaG09]
-        const Prob & U(size_t I, size_t _i) const { return _U[I][_i]; }
+        const Prob & U(size_t I, size_t _i) const { return _Umsg[I][_i]; }
         /// Returns reference to S value; see eqn. (43) in [\ref EaG09]
-        Prob & S(size_t i, size_t _I, size_t _j) { return _S[i][_I][_j]; }
+        Prob & S(size_t i, size_t _I, size_t _j) { return _Smsg[i][_I][_j]; }
         /// Returns constant reference to S value; see eqn. (43) in [\ref EaG09]
-        const Prob & S(size_t i, size_t _I, size_t _j) const { return _S[i][_I][_j]; }
+        const Prob & S(size_t i, size_t _I, size_t _j) const { return _Smsg[i][_I][_j]; }
         /// Returns reference to R value; see eqn. (44) in [\ref EaG09]
-        Prob & R(size_t I, size_t _i, size_t _J) { return _R[I][_i][_J]; }
+        Prob & R(size_t I, size_t _i, size_t _J) { return _Rmsg[I][_i][_J]; }
         /// Returns constant reference to R value; see eqn. (44) in [\ref EaG09]
-        const Prob & R(size_t I, size_t _i, size_t _J) const { return _R[I][_i][_J]; }
+        const Prob & R(size_t I, size_t _i, size_t _J) const { return _Rmsg[I][_i][_J]; }
 
         /// Returns reference to variable->factor message adjoint
         Prob& adj_n(size_t i, size_t _I) { return _adj_n[i][_I]; }
@@ -258,7 +264,10 @@ class BBP {
     public:
     /// \name Constructors/destructors
     //@{
-        /// Construct from a InfAlg \a ia and a PropertySet \a opts
+        /// 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 +336,25 @@ class BBP {
     //@}
 
     public:
-        /// Parameters of this algorithm
+        /// Parameters for BBP
         /* PROPERTIES(props,BBP) {
            /// 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]
@@ -356,12 +372,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;
@@ -369,6 +394,9 @@ class BBP {
             UpdateType updates;
 
             /// Set members from PropertySet
+            /** \throw UNKNOWN_PROPERTY if a Property key is not recognized
+             *  \throw NOT_ALL_PROPERTIES_SPECIFIED if an expected Property is missing
+             */
             void set(const PropertySet &opts);
             /// Get members into PropertySet
             PropertySet get() const;