Implemented various heuristics for choosing a variable elimination sequence in JTree
[libdai.git] / include / dai / doc.h
index 9d6084c..9ce94ea 100644 (file)
  *
  *  \todo Document tests and utils
  *
- *  \todo Add FAQ
+ *  \todo Implement routines for UAI probabilistic inference evaluation data
  *
- *  \todo Adapt (part of the) guidelines in http://www.boost.org/development/requirements.html#Design_and_Programming
+ *  \idea Adapt (part of the) guidelines in http://www.boost.org/development/requirements.html#Design_and_Programming
  *
- *  \todo Use "gcc -MM" to generate dependencies for targets: http://make.paulandlesley.org/autodep.html
+ *  \idea Use "gcc -MM" to generate dependencies for targets: http://make.paulandlesley.org/autodep.html
  *
  *  \todo Replace VarSets by SmallSet<size_t> where appropriate, in order to minimize the use of FactorGraph::findVar().
  *
@@ -55,7 +55,7 @@
 /** \mainpage Reference manual for libDAI - A free/open source C++ library for Discrete Approximate Inference methods
  *  \author Joris Mooij
  *  \version git HEAD
- *  \date November 16, 2009 - or later
+ *  \date January 12, 2010 - or later
  *
  *  <hr size="1">
  *  \section about About libDAI
  *  The build includes a regression test, which may take a while to complete.
  *
  *  If the build was successful, you can test the example program:
- *  <pre>  example tests\alarm.fg</pre>
+ *  <pre>  examples\\example tests\\alarm.fg</pre>
  *  or the more elaborate test program:
- *  <pre>  tests\\testdai --aliases tests\aliases.conf --filename tests\alarm.fg --methods JTREE_HUGIN BP_SEQMAX</pre>
+ *  <pre>  tests\\testdai --aliases tests\\aliases.conf --filename tests\\alarm.fg --methods JTREE_HUGIN BP_SEQMAX</pre>
  *
  *
  *  <hr size="1">
  *  In libDAI, both types of graphical models are represented by a slightly more 
  *  general type of graphical model: a factor graph [\ref KFL01].
  *
+ *  An example of a Bayesian network is: 
  *  \dot
  *  digraph bayesnet {
  *    size="1,1";
  *    x2 -> x4;
  *  }
  *  \enddot
- *
+ *  The probability distribution of a Bayesian network factorizes as:
  *  \f[ P(\mathbf{x}) = \prod_{i\in\mathcal{V}} P(x_i \,|\, x_{\mathrm{pa}(i)}) \f]
  *  where \f$\mathrm{pa}(i)\f$ are the parents of node \a i in a DAG.
  *
+ *  The same probability distribution can be represented as a Markov random field:
  *  \dot
  *  graph mrf {
  *    size="1.5,1.5";
  *  }
  *  \enddot
  *
+ *  The probability distribution of a Markov random field factorizes as:
  *  \f[ P(\mathbf{x}) = \frac{1}{Z} \prod_{C\in\mathcal{C}} \psi_C(x_C) \f]
  *  where \f$ \mathcal{C} \f$ are the cliques of an undirected graph, 
  *  \f$ \psi_C(x_C) \f$ are "potentials" or "compatibility functions", and
  *  \f$ Z \f$ is the partition sum which properly normalizes the probability
  *  distribution.
  *
+ *  Finally, the same probability distribution can be represented as a factor graph:
  *  \dot
  *  graph factorgraph {
  *    size="1.8,1";
  *  }
  *  \enddot
  *
+ *  The probability distribution of a factor graph factorizes as:
  *  \f[ P(\mathbf{x}) = \frac{1}{Z} \prod_{I\in \mathcal{F}} f_I(x_I) \f]
  *  where \f$ \mathcal{F} \f$ are the factor nodes of a factor graph (a 
  *  bipartite graph consisting of variable nodes and factor nodes), 
  *  contain the variable labels of the variables on which that factor depends, 
  *  in a specific ordering. This ordering can be different from the canonical 
  *  ordering of the variables used internally in libDAI (which would be sorted 
- *  ascendingly according to the variable labels). The odering of the variables
+ *  ascendingly according to the variable labels). The ordering of the variables
  *  specifies the implicit ordering of the shared parameters: when iterating
  *  over all shared parameters, the corresponding index of the first variable
  *  changes fastest (in the inner loop), and the corresponding index of the
  *  variables) share parameters in parameter learning using EM. This convention
  *  is similar to the convention used in factor blocks in a factor graph .fg 
  *  file (see \ref fileformats-factorgraph-factor).
+ *
+ *  \section fileformats-aliases Aliases file format
+ *
+ *  An aliases file is basically a list of "macros" and the strings that they
+ *  should be substituted with.
+ *  
+ *  Each line of the aliases file can be either empty, contain a comment 
+ *  (if the first character is a '#') or contain an alias. In the latter case, 
+ *  the line should contain a colon; the part before the colon contains the 
+ *  name of the alias, the part after the colon the string that it should be 
+ *  substituted with. Any whitespace before and after the colon is ignored.
+ *
+ *  For example, the following line would define the alias \c BP_SEQFIX
+ *  as a shorthand for "BP[updates=SEQFIX,tol=1e-9,maxiter=10000,logdomain=0]":
+ *  <pre>
+ *  BP_SEQFIX:  BP[updates=SEQFIX,tol=1e-9,maxiter=10000,logdomain=0]
+ *  </pre>
+ *
+ *  Aliases files can be used to store default options for algorithms.
  */
 
 /** \page bibliography Bibliography
  *  "Divergence measures and message passing",
  *  <em>MicroSoft Research Technical Report</em> MSR-TR-2005-173,
  *  http://research.microsoft.com/en-us/um/people/minka/papers/message-passing/minka-divergence.pdf
+ *
+ *  \anchor KoF09 \ref KoF09
+ *  D. Koller and N. Friedman (2009):
+ *  <em>Probabilistic Graphical Models - Principles and Techniques</em>,
+ *  The MIT Press, Cambridge, Massachusetts, London, England.
  */