Small documentation improvements
authorJoris Mooij <joris.mooij@tuebingen.mpg.de>
Tue, 8 Sep 2009 07:52:09 +0000 (09:52 +0200)
committerJoris Mooij <joris.mooij@tuebingen.mpg.de>
Tue, 8 Sep 2009 07:52:09 +0000 (09:52 +0200)
doxygen.conf
include/dai/bbp.h
include/dai/doc.h
include/dai/factor.h
include/dai/factorgraph.h
include/dai/properties.h
src/bbp.cpp
src/factorgraph.cpp
src/properties.cpp
src/util.cpp

index 59bd5a2..00e1c70 100644 (file)
@@ -313,7 +313,7 @@ EXTRACT_STATIC         = YES
 # defined locally in source files will be included in the documentation. 
 # If set to NO only classes defined in header files are included.
 
-EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_CLASSES  = NO
 
 # This flag is only useful for Objective-C code. When set to YES local 
 # methods, which are defined in the implementation section but not in 
index 2973471..736ffcd 100644 (file)
@@ -343,6 +343,10 @@ Real getCostFn( const InfAlg &fg, bbp_cfn_t cfn_type, const std::vector<size_t>
 
 /// Function to test the validity of adjoints computed by BBP given a state for each variable using numerical derivatives.
 /** Factors containing a variable are multiplied by psi_1 adjustments to verify accuracy of _adj_psi_V.
+ *  \param bp BP object.
+ *  \param state Global state of all variables.
+ *  \param bbp_props BBP Properties.
+ *  \param cfn Cost function to be used.
  *  \param h controls size of perturbation.
  */
 double numericBBPTest( const InfAlg &bp, const std::vector<size_t> *state, const PropertySet &bbp_props, bbp_cfn_t cfn, double h );
index e7f9071..1e5686b 100644 (file)
@@ -93,7 +93,7 @@
  *
  *  \section discuss_templates Polymorphism by template parameterization
  *  Instead of polymorphism by inheritance, use polymorphism by template parameterization. 
- *  For example, the real reason for introducing the complicated inheritance scheme of InfAlg
+ *  For example, the real reason for introducing the complicated inheritance scheme of dai::InfAlg
  *  was for functions like dai::calcMarginal. Instead, one could use a template function:
  *  \code
  *  template<typename InfAlg>
  *  \date October 10, 2008
  *
  *  \section about About libDAI
- *  libDAI is a free/open source C++ library (licensed under GPL) that provides
+ *  libDAI is a free/open source C++ library (licensed under GPLv2+) that provides
  *  implementations of various (approximate) inference methods for discrete 
  *  graphical models. libDAI supports arbitrary factor graphs with discrete 
  *  variables; this includes discrete Markov Random Fields and Bayesian 
  *  Networks.
  *
- *  The library is targeted at researchers; to be able to use the library, a 
+ *  The library is targeted at researchers. To be able to use the library, a 
  *  good understanding of graphical models is needed. 
  *
  *  \section limitations Limitations
  *  various inference methods. In particular, it contains no GUI, currently 
  *  only supports its own file format for input and output (although support 
  *  for standard file formats may be added later), and provides very limited
- *  visualization functionalities.
+ *  visualization functionalities. The only learning method supported currently
+ *  is EM for learning factor parameters.
  *
  *  \section features Features
  *  Currently, libDAI supports the following (approximate) inference methods:
index c116f4c..695813b 100644 (file)
@@ -43,8 +43,9 @@
 namespace dai {
 
 
-/// Function object similar to std::divides(), but different in that dividing by zero results in zero
+// Function object similar to std::divides(), but different in that dividing by zero results in zero
 template<typename T> struct divides0 : public std::binary_function<T, T, T> {
+    // Returns (j == 0 ? 0 : (i/j))
     T operator()(const T& i, const T& j) const {
         if( j == (T)0 )
             return (T)0;
index fc88e4d..4e53ae4 100644 (file)
@@ -289,9 +289,10 @@ class FactorGraph {
         /// Restores all factors connected to a set of variables from their backups
         void restoreFactors( const VarSet &ns );
 
-        // Friends
-        friend std::ostream& operator << (std::ostream& os, const FactorGraph& fg);
-        friend std::istream& operator >> (std::istream& is, FactorGraph& fg);
+        /// Writes a FactorGraph to an output stream
+        friend std::ostream& operator<< (std::ostream &os, const FactorGraph &fg );
+        /// Reads a FactorGraph from an input stream
+        friend std::istream& operator>> (std::istream &is, FactorGraph &fg );
 
         // OBSOLETE
         /// @name Backwards compatibility layer (to be removed soon)
index 47e43cb..efdd789 100644 (file)
@@ -159,8 +159,10 @@ class PropertySet : private std::map<PropertyKey, PropertyValue> {
             return res;
         }
 
-        // Friends
+        /// Writes a PropertySet object to an output stream
         friend std::ostream& operator<< (std::ostream & os, const PropertySet & ps);
+
+        /// Reads a PropertySet object from an input stream, storing values as strings
         friend std::istream& operator>> (std::istream& is, PropertySet & ps);
 };
 
index 1f0161c..15e3672 100644 (file)
@@ -31,6 +31,7 @@ namespace dai {
 using namespace std;
 
 
+/// Convenience typedef
 typedef BipartiteGraph::Neighbor Neighbor;
 
 
@@ -57,6 +58,7 @@ std::vector<size_t> getGibbsState( const InfAlg &ia, size_t iters ) {
 }
 
 
+/// Returns the entry of the I'th factor corresponding to a global state
 size_t getFactorEntryForState( const FactorGraph &fg, size_t I, const vector<size_t> &state ) {
     size_t f_entry = 0;
     for( int _j = fg.nbF(I).size() - 1; _j >= 0; _j-- ) {
index 263b186..b41e577 100644 (file)
@@ -84,7 +84,7 @@ void FactorGraph::constructGraph( size_t nrEdges ) {
 
 
 /// Writes a FactorGraph to an output stream
-ostream& operator << (ostream& os, const FactorGraph& fg) {
+std::ostream& operator<< ( std::ostream &os, const FactorGraph &fg ) {
     os << fg.nrFactors() << endl;
 
     for( size_t I = 0; I < fg.nrFactors(); I++ ) {
@@ -111,7 +111,7 @@ ostream& operator << (ostream& os, const FactorGraph& fg) {
 
 
 /// Reads a FactorGraph from an input stream
-istream& operator >> (istream& is, FactorGraph& fg) {
+std::istream& operator>> ( std::istream& is, FactorGraph &fg ) {
     long verbose = 0;
 
     vector<Factor> facs;
index d035076..1629b84 100644 (file)
@@ -60,7 +60,7 @@ std::ostream& operator<< (std::ostream & os, const PropertySet & ps) {
 
 
 /// Reads a PropertySet object from an input stream, storing values as strings
-std::istream& operator >> (std::istream& is, PropertySet & ps) {
+std::istream& operator>> (std::istream& is, PropertySet & ps) {
     ps = PropertySet();
 
     std::string s;
index b5e1d34..f679a6a 100644 (file)
@@ -73,19 +73,22 @@ double toc() {
 #endif
 }
 
-// This is a typedef for a random number generator.
-// Try boost::mt19937 or boost::ecuyer1988 instead of boost::minstd_rand
-typedef boost::minstd_rand _rnd_gen_type;
+/// Type of global random number generator
+typedef boost::minstd_rand _rnd_gen_type;  // Try boost::mt19937 or boost::ecuyer1988 instead of boost::minstd_rand
 
+/// Global random number generator
 _rnd_gen_type _rnd_gen(42U);
 
-// Define a uniform random number distribution which produces
-// values between 0 and 1 (0 inclusive, 1 exclusive).
+/// Uniform distribution with values between 0 and 1 (0 inclusive, 1 exclusive).
 boost::uniform_real<> _uni_dist(0,1);
+
+/// Global uniform random random number 
 boost::variate_generator<_rnd_gen_type&, boost::uniform_real<> > _uni_rnd(_rnd_gen, _uni_dist);
 
-// Define a normal distribution with mean 0 and standard deviation 1.
+/// Normal distribution with mean 0 and standard deviation 1.
 boost::normal_distribution<> _normal_dist;
+
+/// Global random number generator with standard normal distribution
 boost::variate_generator<_rnd_gen_type&, boost::normal_distribution<> > _normal_rnd(_rnd_gen, _normal_dist);
 
 
@@ -105,10 +108,7 @@ int rnd_int( int min, int max ) {
     return (int)floor(_uni_rnd() * (max + 1 - min) + min);
 }
 
-void tokenizeString(const std::string& s,
-                    std::vector<std::string>& outTokens,
-                    const std::string& delim)
-{
+void tokenizeString(const std::string& s, std::vector<std::string>& outTokens, const std::string& delim) {
     size_t start = 0;
     while (start < s.size()) {
         size_t end = s.find_first_of(delim, start);