Added examples example_sprinkler_gibbs and example_sprinkler_em
[libdai.git] / include / dai / doc.h
index cc51c53..b15aa7c 100644 (file)
 /** \file
  *  \brief Contains additional doxygen documentation
  *
- *  \todo Improve documentation
+ *  \todo Write a concept/notations page for the documentation,
+ *  explaining the concepts of "state" (index into a 
+ *  multi-dimensional array, e.g., one corresponding
+ *  to the Cartesian product of statespaces of variables)
+ *  and "linear index". This should make it easier to
+ *  document index.h and varset.h
  *
- *  \todo Merge README into doxygen documentation
- *  \todo Document examples, tests and utils
+ *  \todo Document tests and utils
+ *
+ *  \todo Add FAQ
  *
  *  \todo 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
- *  \todo Investigate whether switching to cmake as cross-platform build system would be a good idea.
  *
  *  \todo Replace VarSets by SmallSet<size_t> where appropriate, in order to minimize the use of FactorGraph::findVar().
  *
  *  \idea Disentangle structures. In particular, ensure that graphical properties are not
- *  entangled with probabilistic properties. For example, a FactorGraph contains several
- *  components:
+ *  entangled with probabilistic properties. For example, a FactorGraph contains several components:
  *  - a BipartiteGraph
  *  - an array of variable labels
  *  - an array of variable state space sizes
  *  - an array of pointers to factor value vectors
  *  In this way, each factor could be implemented differently, e.g., we could have
  *  some sparse factors, some noisy-OR factors, some dense factors, some arbitrary
- *  precision factors, etc.
+ *  precision factors, etcetera.
  *
- *  \idea Use Boost::uBLAS framework to deal with matrices, especially, with 2D sparse matrices.
+ *  \idea Use boost::uBLAS framework to deal with matrices, especially, with 2D sparse matrices.
  *  See http://www.boost.org/libs/numeric/ublas/doc/matrix_sparse.htm
- *  I read somewhere that boost::uBLAS concentrates more on correct implementation than on performance.
+ *  However: I read somewhere that boost::uBLAS concentrates more on correct implementation than on performance.
  *
  *  \idea Introduce naming scheme:
  *  - all Vars should be named v_..., e.g. v_i instead of i
  **/
 
 
-/** \page discussion Discussion of possible improvements
- *  \section discuss_extendedgraphs Extended factorgraphs/regiongraphs
- *
- *  A FactorGraph and a RegionGraph are often equipped with
- *  additional properties for nodes and edges. The code to initialize those
- *  is often quite similar. Maybe one could abstract this, e.g.:
- *  \code
- *  template <typename Node1Properties, typename Node2Properties, typename EdgeProperties>
- *  class ExtFactorGraph : public FactorGraph {
- *      public:
- *          std::vector<Node1Properties>              node1Props;
- *          std::vector<Node2Properties>              node2Props;
- *          std::vector<std::vector<EdgeProperties> > edgeProps;
- *         // ...
- *  }
- *  \endcode
- *
- *  Advantages:
- *  - Less code duplication.
- *  - Easier maintainability.
- *  - Easier to write new inference algorithms.
- *
- *  Disadvantages:
- *  - Cachability may be worse.
- *  - A problem is the case where there are no properties for either type of nodes or for edges.
- *    Maybe this can be solved using specializations, or using variadac template arguments?
- *    Another possible solution would be to define a "class Empty {}", and add some code
- *    that checks for the typeid, comparing it with Empty, and doing something special in that case
- *    (e.g., not allocating memory).
- *  - The main disadvantage of this approach seems to be that it leads to even more entanglement.
- *    Therefore this is probably a bad idea.
- *
- *  \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 dai::InfAlg
- *  was for functions like dai::calcMarginal. Instead, one could use a template function:
- *  \code
- *  template<typename InfAlg>
- *  Factor calcMarginal( const InfAlg &obj, const VarSet &ns, bool reInit );
- *  \endcode
- *  This would assume that the type InfAlg supports certain methods. Ideally, one would use
- *  concepts to define different classes of inference algorithms with different capabilities,
- *  for example the ability to calculate logZ, the ability to calculate marginals, the ability to
- *  calculate bounds, the ability to calculate MAP states, etc. Then, one would use traits
- *  classes in order to be able to query the capabilities of the model. For example, one would be
- *  able to query whether the inference algorithm supports calculation of logZ.  Unfortunately,
- *  this is compile-time polymorphism, whereas tests/testdai needs runtime polymorphism.
- *  Therefore this is probably a bad idea.
- */
-
-
-/** \mainpage libDAI reference manual
+/** \mainpage Reference manual for libDAI - A free/open source C++ library for Discrete Approximate Inference methods
  *  \author Joris Mooij
  *  \version git HEAD
- *  \date October 10, 2008
+ *  \date January 12, 2010 - or later
  *
+ *  <hr size="1">
  *  \section about About libDAI
- *  libDAI is a free/open source C++ library (licensed under GPLv2+) that provides
+ *  libDAI is a free/open source C++ library (licensed under GPL 2+) 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
  *  The library is targeted at researchers. To be able to use the library, a
  *  good understanding of graphical models is needed.
  *
- *  \section limitations Limitations
- *  libDAI is not intended to be a complete package for approximate inference.
- *  Instead, it should be considered as an "inference engine", providing
- *  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. The only learning method supported currently
- *  is EM for learning factor parameters.
+ *  The best way to use libDAI is by writing C++ code that invokes the library;
+ *  in addition, part of the functionality is accessibly by using the
+ *  - command line interface
+ *  - (limited) MatLab interface
+ *  - (experimental) python interface
+ *  - (experimental) octave interface.
+ *
+ *  libDAI can be used to implement novel (approximate) inference algorithms
+ *  and to easily compare the accuracy and performance with existing algorithms
+ *  that have been implemented already.
  *
  *  \section features Features
  *  Currently, libDAI supports the following (approximate) inference methods:
  *  - Exact inference by junction-tree methods;
  *  - Mean Field;
  *  - Loopy Belief Propagation [\ref KFL01];
+ *  - Fractional Belief Propagation [\ref WiH03];
  *  - Tree Expectation Propagation [\ref MiQ04];
  *  - Generalized Belief Propagation [\ref YFW05];
  *  - Double-loop GBP [\ref HAK03];
  *  - Various variants of Loop Corrected Belief Propagation
  *    [\ref MoK07, \ref MoR05];
  *  - Gibbs sampler;
- *  - Conditioned BP [\ref EaG09];
+ *  - Clamped Belief Propagation [\ref EaG09].
+ *
+ *  These inference methods can be used to calculate partition sums, marginals
+ *  over subsets of variables, and MAP states (the joint state of variables that
+ *  has maximum probability).
  *
  *  In addition, libDAI supports parameter learning of conditional probability
  *  tables by Expectation Maximization.
  *
- *  \section language Why C++?
+ *  \section limitations Limitations
+ *  libDAI is not intended to be a complete package for approximate inference.
+ *  Instead, it should be considered as an "inference engine", providing
+ *  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. The only learning method supported currently
+ *  is Expectation Maximization (or Maximum Likelihood if no data is missing)
+ *  for learning factor parameters.
+ *
+ *  \section rationale Rationale
+ *
+ *  In my opinion, the lack of open source "reference" implementations hampers
+ *  progress in research on approximate inference. Methods differ widely in terms
+ *  of quality and performance characteristics, which also depend in different
+ *  ways on various properties of the graphical models. Finding the best
+ *  approximate inference method for a particular application therefore often
+ *  requires empirical comparisons. However, implementing and debugging these
+ *  methods takes a lot of time which could otherwise be spent on research. I hope
+ *  that this code will aid researchers to be able to easily compare various
+ *  (existing as well as new) approximate inference methods, in this way
+ *  accelerating research and stimulating real-world applications of approximate
+ *  inference.
+ *
+ *  \section language Language
  *  Because libDAI is implemented in C++, it is very fast compared with
  *  implementations in MatLab (a factor 1000 faster is not uncommon).
- *  libDAI does provide a MatLab interface for easy integration with MatLab.
- */
-
-
-/** \example example.cpp
+ *  libDAI does provide a (limited) MatLab interface for easy integration with MatLab.
+ *  It also provides a command line interface and experimental python and octave 
+ *  interfaces (thanks to Patrick Pletscher).
+ *
+ *  \section compatibility Compatibility
+ *  
+ *  The code has been developed under Debian GNU/Linux with the GCC compiler suite.
+ *  libDAI compiles successfully with g++ versions 3.4, 4.1, 4.2 and 4.3.
+ *
+ *  libDAI has also been successfully compiled with MS Visual Studio 2008 under Windows
+ *  (but not all build targets are supported yet) and with Cygwin under Windows.
+ *
+ *  Finally, libDAI has been compiled successfully on MacOS X.
+ *
+ *  \section download Downloading libDAI
+ *  The libDAI sources and documentation can be downloaded from the libDAI website:
+ *  http://www.libdai.org.
+ *
+ *  \section support Mailing list
+ *  The Google group "libDAI" (http://groups.google.com/group/libdai)
+ *  can be used for getting support and discussing development issues.
  */
 
 
-/** \page quickstart Quick start
- *  An example program illustrating basic usage of libDAI is given in examples/example.cpp.
+/** \page license License
+ *  <hr size="1">
+ *  \section license-license License
+ *
+ *  libDAI is free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation; either version 2 of the License, or
+ *  (at your option) any later version.
+ *
+ *  libDAI is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  <hr size="1">
+ *  \section license-gpl GNU General Public License version 2
+ * 
+ *  \verbinclude COPYING
  */
 
 
-/** \page bibliography Bibliography
- *  \anchor KFL01 \ref KFL01
- *  F. R. Kschischang and B. J. Frey and H.-A. Loeliger (2001):
- *  "Factor Graphs and the Sum-Product Algorithm",
- *  <em>IEEE Transactions on Information Theory</em> 47(2):498-519.
- *  http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?arnumber=910572
+/** \page citations Citing libDAI
+ *  <hr size="1">
+ *  \section citations-citations Citing libDAI
  *
- *  \anchor MiQ04 \ref MiQ04
- *  T. Minka and Y. Qi (2004):
- *  "Tree-structured Approximations by Expectation Propagation",
- *  <em>Advances in Neural Information Processing Systems</em> (NIPS) 16.
- *  http://books.nips.cc/papers/files/nips16/NIPS2003_AA25.pdf
+ *  If you write a scientific paper describing research that made substantive use
+ *  of this program, please:
+ *    - mention the fashion in which this software was
+ *      used, including the version number, with a citation to the literature, 
+ *      to allow replication; 
+ *    - mention this software in the Acknowledgements section. 
  *
- *  \anchor MoR05 \ref MoR05
- *  A. Montanari and T. Rizzo (2005):
- *  "How to Compute Loop Corrections to the Bethe Approximation",
- *  <em>Journal of Statistical Mechanics: Theory and Experiment</em>
- *  2005(10)-P10011.
- *  http://stacks.iop.org/1742-5468/2005/P10011
+ *  An appropriate citation would be:\n
+ *  J. M. Mooij (2009) "libDAI 0.2.3: A free/open source C++ library for Discrete 
+ *  Approximate Inference", http://www.libdai.org
  *
- *  \anchor YFW05 \ref YFW05
- *  J. S. Yedidia and W. T. Freeman and Y. Weiss (2005):
- *  "Constructing Free-Energy Approximations and Generalized Belief Propagation Algorithms",
- *  <em>IEEE Transactions on Information Theory</em>
- *  51(7):2282-2312.
- *  http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?arnumber=1459044
- *
- *  \anchor HAK03 \ref HAK03
- *  T. Heskes and C. A. Albers and H. J. Kappen (2003):
- *  "Approximate Inference and Constrained Optimization",
- *  <em>Proceedings of the 19th Annual Conference on Uncertainty in Artificial Intelligence (UAI-03)</em> pp. 313-320.
- *  http://www.snn.ru.nl/reports/Heskes.uai2003.ps.gz
- *
- *  \anchor MoK07 \ref MoK07
- *  J. M. Mooij and H. J. Kappen (2007):
- *  "Loop Corrections for Approximate Inference on Factor Graphs",
- *  <em>Journal of Machine Learning Research</em> 8:1113-1143.
- *  http://www.jmlr.org/papers/volume8/mooij07a/mooij07a.pdf
- *
- *  \anchor MoK07b \ref MoK07b
- *  J. M. Mooij and H. J. Kappen (2007):
- *  "Sufficient Conditions for Convergence of the Sum-Product Algorithm",
- *  <em>IEEE Transactions on Information Theory</em> 53(12):4422-4437.
- *  http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?arnumber=4385778
+ *  Moreover, as a personal note, I would appreciate it if you would email
+ *  (citations of) papers referencing this work to joris dot mooij at libdai dot org.
+ */
+
+
+/** \page authors Authors
+ *  \section authors-authors People who contributed to libDAI
  *
- *  \anchor EaG09 \ref EaG09
- *  F. Eaton and Z. Ghahramani (2009):
- *  "Choosing a Variable to Clamp",
- *  <em>Proceedings of the Twelfth International Conference on Artificial Intelligence and Statistics (AISTATS 2009)</em> 5:145-152
- *  http://jmlr.csail.mit.edu/proceedings/papers/v5/eaton09a/eaton09a.pdf
+ *  \verbinclude AUTHORS
+ */
+
+
+/** \page build Building libDAI
+ *  <hr size="1">
+ *  \section build-unix Building libDAI under UNIX variants (Linux / Cygwin / Mac OS X)
+ *
+ *  You need:
+ *    - a recent version of gcc (at least version 3.4)
+ *    - GNU make
+ *    - doxygen
+ *    - graphviz
+ *    - recent boost C++ libraries (at least version 1.34, or 1.37 for cygwin;
+ *      version 1.37 shipped with Ubuntu 9.04 is known not to work)
+ * 
+ *  On Debian/Ubuntu, you can easily install all these packages with a single command:
+ *  <pre>  apt-get install g++ make doxygen graphviz libboost-dev libboost-graph-dev libboost-program-options-dev</pre>
+ *  (root permissions needed).
+ *
+ *  On Mac OS X (10.4 is known to work), these packages can be installed easily via MacPorts.
+ *  If MacPorts is not already installed, install it according to the instructions at http://www.macports.org/.
+ *  Then, a simple 
+ *    <pre>  sudo port install gmake boost doxygen graphviz</pre>
+ *  should be enough to install everything that is needed.
+ *  
+ *  On Cygwin, the prebuilt Cygwin package boost-1.33.1-x is known not to work.
+ *  You can however obtain the latest boost version (you need at least 1.37.0)
+ *  from http://www.boost.org/ and compile/install it with:
+ *
+ *  <pre>  ./configure
+ *  make
+ *  make install
+ *  </pre>
  *
- *  \anchor StW99 \ref StW99
- *  A. Steger and N. C. Wormald (1999):
- *  "Generating Random Regular Graphs Quickly",
- *  <em>Combinatorics, Probability and Computing</em> Vol 8, Issue 4, pp. 377-396
- *  http://www.math.uwaterloo.ca/~nwormald/papers/randgen.pdf
+ *  To build the libDAI source, first copy a template Makefile.* to Makefile.conf
+ *  (for example, copy Makefile.LINUX to Makefile.conf if you use GNU/Linux). 
+ *  Then, edit the Makefile.conf template to adapt it to your local setup.
+ *  Especially directories may differ from system to system. Finally, run
+ *  <pre>  make</pre>
+ *  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>  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>
+ *
+ *
+ *  <hr size="1">
+ *  \section build-windows Building libDAI under Windows
+ *
+ *  You need:
+ *  - A recent version of MicroSoft Visual Studio (2008 works)
+ *  - recent boost C++ libraries (version 1.34 or higher)
+ *  - GNU make (can be obtained from http://gnuwin32.sourceforge.net)
+ *
+ *  For the regression test, you need:
+ *  - GNU diff, GNU sed (can be obtained from http://gnuwin32.sourceforge.net)
+ *
+ *  To build the source, copy Makefile.WINDOWS to Makefile.conf. Then, edit 
+ *  Makefile.conf to adapt it to your local setup. Finally, run (from the command line)
+ *  <pre>  make</pre>
+ *  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>  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>
+ *
+ *
+ *  <hr size="1">
+ *  \section build-matlab Building the libDAI MatLab interface
+ *
+ *  You need:
+ *  - MatLab
+ *  - The platform-dependent requirements described above
+ *
+ *  First, you need to build the libDAI source as described above for your
+ *  platform. By default, the MatLab interface is disabled, so before compiling the
+ *  source, you have to enable it in the Makefile.conf by setting
+ *  <pre>  WITH_MATLAB=true</pre>
+ *  Also, you have to configure the MatLab-specific parts of
+ *  Makefile.conf to match your system (in particular, the Makefile variables ME,
+ *  MATLABDIR and MEX). The MEX file extension depends on your platform; for a
+ *  64-bit linux x86_64 system this would be "ME=.mexa64", for a 32-bit linux x86
+ *  system "ME=.mexglx". If you are unsure about your MEX file
+ *  extension: it needs to be the same as what the MatLab command "mexext" returns.
+ *  The required MEX files are built by issuing
+ *  <pre>  make</pre>
+ *  from the command line. The MatLab interface is much less powerful than using
+ *  libDAI from C++. There are two reasons for this: (i) it is boring to write MEX
+ *  files; (ii) the large performance penalty paid when large data structures (like
+ *  factor graphs) have to be converted between their native C++ data structure to
+ *  something that MatLab understands.
+ *
+ *  A simple example of how to use the MatLab interface is the following (entered
+ *  at the MatLab prompt), which performs exact inference by the junction tree
+ *  algorithm and approximate inference by belief propagation on the ALARM network:
+ *  <pre>  cd path_to_libdai/matlab
+ *  [psi] = dai_readfg ('../examples/alarm.fg');
+ *  [logZ,q,md,qv,qf] = dai (psi, 'JTREE', '[updates=HUGIN,verbose=0]')
+ *  [logZ,q,md,qv,qf] = dai (psi, 'BP', '[updates=SEQMAX,tol=1e-9,maxiter=10000,logdomain=0]')</pre>
+ *  where "path_to_libdai" has to be replaced with the directory in which libDAI
+ *  was installed. For other algorithms and some default parameters, see the file
+ *  tests/aliases.conf.
+ *
+ *  <hr size="1">
+ *  \section build-doxygen Building the documentation
+ *
+ *  Install doxygen, graphviz and a TeX distribution and use
+ *  <pre>  make doc</pre>
+ *  to build the documentation. If the documentation is not clear enough, feel free 
+ *  to send me an email (or even better, to improve the documentation and send a patch!).
+ *  The documentation can also be browsed online at http://www.libdai.org.
+ */
+
+
+/** \page changelog Change Log
+ *  \verbinclude ChangeLog
+ */
+
+
+/** \page inference Graphical models and approximate inference
+ *
+ *  \section inference-graphicalmodels Graphical models
+ *
+ *  Commonly used graphical models are Bayesian networks and Markov random fields.
+ *  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";
+ *    x0 [label="0"];
+ *    x1 [label="1"];
+ *    x2 [label="2"];
+ *    x3 [label="3"];
+ *    x4 [label="4"];
+ *    x0 -> x1;
+ *    x0 -> x2;
+ *    x1 -> x3;
+ *    x1 -> x4;
+ *    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";
+ *    x0 [label="0"];
+ *    x1 [label="1"];
+ *    x2 [label="2"];
+ *    x3 [label="3"];
+ *    x4 [label="4"];
+ *    x0 -- x1;
+ *    x0 -- x2;
+ *    x1 -- x2;
+ *    x1 -- x3;
+ *    x1 -- x4;
+ *    x2 -- x4;
+ *  }
+ *  \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";
+ *    x0 [label="0"];
+ *    x1 [label="1"];
+ *    x2 [label="2"];
+ *    x3 [label="3"];
+ *    x4 [label="4"];
+ *    f01 [shape="box",label=""];
+ *    f02 [shape="box",label=""];
+ *    f13 [shape="box",label=""];
+ *    f124 [shape="box",label=""];
+ *    x0 -- f01;
+ *    x1 -- f01;
+ *    x0 -- f02;
+ *    x2 -- f02;
+ *    x1 -- f13;
+ *    x3 -- f13;
+ *    x1 -- f124;
+ *    x2 -- f124;
+ *    x4 -- f124;
+ *  }
+ *  \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), 
+ *  \f$ f_I(x_I) \f$ are the factors, and \f$ Z \f$ is the partition sum
+ *  which properly normalizes the probability distribution.
+ *
+ *  Looking at the expressions for the joint probability distributions,
+ *  it is obvious that Bayesian networks and Markov random fields can 
+ *  both be easily represented as factor graphs. Factor graphs most
+ *  naturally express the factorization structure of a probability
+ *  distribution, and hence are a convenient representation for approximate
+ *  inference algorithms, which all try to exploit this factorization.
+ *  This is why libDAI uses a factor graph as representation of a 
+ *  graphical model, implemented in the dai::FactorGraph class.
+ *
+ *  \section inference-inference Inference tasks
+ *
+ *  Given a factor graph, specified by the variable nodes \f$\{x_i\}_{i\in\mathcal{V}}\f$
+ *  the factor nodes \f$ \mathcal{F} \f$, the graph structure, and the factors
+ *  \f$\{f_I(x_I)\}_{I\in\mathcal{F}}\f$, the following tasks are important:
+ *
+ *  - Calculating the partition sum:
+ *    \f[ Z = \sum_{\mathbf{x}_{\mathcal{V}}} \prod_{I \in \mathcal{F}} f_I(x_I) \f]
+ *  - Calculating the marginal distribution of a subset of variables
+ *    \f$\{x_i\}_{i\in A}\f$: 
+ *    \f[ P(\mathbf{x}_{A}) = \frac{1}{Z} \sum_{\mathbf{x}_{\mathcal{V}\setminus A}} \prod_{I \in \mathcal{F}} f_I(x_I) \f]
+ *  - Calculating the MAP state which has the maximum probability mass:
+ *    \f[ \mathrm{argmax}_{\mathbf{x}}\,\prod_{I\in\mathcal{F}} f_I(x_I) \f]
+ *
+ *  libDAI offers several inference algorithms, which solve (a subset of) these tasks either 
+ *  approximately or exactly, for factor graphs with discrete variables. The following
+ *  algorithms are implemented:
+ *  
+ *  Exact inference:
+ *  - Brute force enumeration: dai::ExactInf
+ *  - Junction-tree method: dai::JTree
+ *
+ *  Approximate inference:
+ *  - Mean Field: dai::MF
+ *  - (Loopy) Belief Propagation: dai::BP [\ref KFL01]
+ *  - Tree Expectation Propagation: dai::TreeEP [\ref MiQ04]
+ *  - Generalized Belief Propagation: dai::HAK [\ref YFW05]
+ *  - Double-loop GBP: dai::HAK [\ref HAK03]
+ *  - Loop Corrected Belief Propagation: dai::MR [\ref MoR05] and dai::LC [\ref MoK07]
+ *  - Gibbs sampling: dai::Gibbs
+ *  - Clamped Belief Propagation: dai::CBP [\ref EaG09]
+ *
+ *  Not all inference tasks are implemented by each method: calculating MAP states
+ *  is only possible with dai::JTree and dai::BP, calculating partition sums is
+ *  not possible with dai::MR, dai::LC and dai::Gibbs.
+ *
+ *  \section inference-learning Parameter learning
  *
- *  \anchor EMK06 \ref EMK06
- *  G. Elidan and I. McGraw and D. Koller (2006):
- *  "Residual Belief Propagation: Informed Scheduling for Asynchronous Message Passing",
- *  <em>Proceedings of the 22nd Annual Conference on Uncertainty in Artificial Intelligence (UAI-06)</em>
- *  http://uai.sis.pitt.edu/papers/06/UAI2006_0091.pdf
+ *  In addition, libDAI supports parameter learning of conditional probability
+ *  tables by Expectation Maximization (or Maximum Likelihood, if there is no
+ *  missing data). This is implemented in dai::EMAlg.
+ *  
  */
 
 
  *  to specify which variables occur in the factor, what their respective
  *  cardinalities (i.e., number of possible values) are, and a table listing all
  *  the values of that factor for all possible configurations of these variables.
+ *
  *  A .fg file is not much more than that. It starts with a line containing the
  *  number of factors in that graph, followed by an empty line. Then all factors
- *  are specified, one block for each factor, where the blocks are seperated by
- *  empty lines. Each variable occurring in the factor graph has a unique
- *  identifier, its index (which should be a nonnegative integer). Comment lines
- *  start with #.
- *
- *  Each block starts with a line containing the number of variables in that
- *  factor. The second line contains the indices of these variables, seperated by
- *  spaces (indices are nonnegative integers and to avoid confusion, it is
- *  suggested to start counting at 0). The third line contains the number of
- *  possible values of each of these variables, also seperated by spaces. Note that
- *  there is some redundancy here, since if a variable appears in more than one
- *  factor, the cardinality of that variable appears several times in the .fg file.
- *  The fourth line contains the number of nonzero entries in the factor table.
- *  The rest of the lines contain these nonzero entries; each entry consists of a
- *  table index, followed by white-space, followed by the value corresponding to
- *  that table index. The most difficult part is getting the indexing right. The
- *  convention that is used is that the left-most variables cycle through their
- *  values the fastest (similar to MATLAB indexing of multidimensional arrays). An
- *  example block describing one factor is:
+ *  are specified, using one block for each factor, where the blocks are seperated 
+ *  by empty lines. Each variable occurring in the factor graph has a unique
+ *  identifier, its label (which should be a nonnegative integer). Comment lines
+ *  which start with # are ignored.
+ *
+ *  \subsection fileformats-factorgraph-factor Factor block format
+ *
+ *  Each block describing a factor starts with a line containing the number of 
+ *  variables in that factor. The second line contains the labels of these 
+ *  variables, seperated by spaces (labels are nonnegative integers and to avoid 
+ *  confusion, it is suggested to start counting at 0). The third line contains 
+ *  the number of possible values of each of these variables, also seperated by 
+ *  spaces. Note that there is some redundancy here, since if a variable appears 
+ *  in more than one factor, the cardinality of that variable appears several 
+ *  times in the .fg file; obviously, these cardinalities should be consistent.
+ *  The fourth line contains the number of nonzero entries 
+ *  in the factor table. The rest of the lines contain these nonzero entries; 
+ *  each line consists of a table index, followed by white-space, followed by the 
+ *  value corresponding to that table index. The most difficult part is getting 
+ *  the indexing right. The convention that is used is that the left-most 
+ *  variables cycle through their values the fastest (similar to MatLab indexing 
+ *  of multidimensional arrays). 
+ *
+ *  \subsubsection fileformats-factorgraph-factor-example Example
+ *
+ *  An example block describing one factor is:
  *
  *  <pre>
  *  3
  *
  *  \section fileformats-evidence Evidence (.tab) file format
  *
- *  This page describes the .tab fileformat used in libDAI to store "evidence",
+ *  This section describes the .tab fileformat used in libDAI to store "evidence",
  *  i.e., a data set consisting of multiple samples, where each sample is the 
  *  observed joint state of some variables.
  *
- *  A .tab file is a tabular data file, consisting of a header line followed by
- *  one line for each data sample. Each line should have the same number of columns,
+ *  A .tab file is a tabular data file, consisting of a header line, followed by
+ *  an empty line, followed by the data points, with one line for each data point.
+ *  Each line (apart from the empty one) should have the same number of columns,
  *  where columns are separated by one tab character. Each column corresponds to 
  *  a variable. The header line consists of the variable labels (corresponding to 
- *  Var::label()). The other lines are observed joint states of the variables, i.e.,
+ *  dai::Var::label()). The other lines are observed joint states of the variables, i.e.,
  *  each line corresponds to a joint observation of the variables, and each column
  *  of a line contains the state of the variable associated with that column.
  *  Missing data is handled simply by having two consecutive tab characters, 
  *  without any characters in between.
  *
- *  \par  Example:
+ *  \subsection fileformats-evidence-example Example
  *
  *  <pre>
  *  1       3       2
+ *
  *  0       0       1
  *  1       0       1
  *  1               1
  *  file is useless. Furthermore, one also needs a corresponding .tab file
  *  containing the data used for parameter learning.
  *
- *  An .em file starts with a line specifying the number of maximization steps.
- *  Then, for each maximization step, its description follows in the format
- *  described in the next section.
+ *  An .em file starts with a line specifying the number of maximization steps,
+ *  followed by an empty line. Then, each maximization step is described in a
+ *  block, which should satisfy the format described in the next subsection.
  *
- *  \subsection fileformats-emalg-maximizationstep Maximization Step section in EM file
+ *  \subsection fileformats-emalg-maximizationstep Maximization Step block format
  *
- *  A maximization step section of an .em file starts with a single line
- *  describing the number of shared parameters sections that will follow.
- *  Then, precisely that number of shared parameters sections follow, 
- *  where each of those sections follows the format described in the next
- *  subsection.
+ *  A maximization step block of an .em file starts with a single line
+ *  describing the number of shared parameters blocks that will follow.
+ *  Then, each shared parameters block follows, in the format described in
+ *  the next subsection.
  *
- *  \subsection fileformats-sharedparameters Shared parameters section in EM file
+ *  \subsection fileformats-emalg-sharedparameters Shared parameters block format
  *
- *  A shared parameters section of an .em file starts with a single line
+ *  A shared parameters block of an .em file starts with a single line
  *  consisting of the name of a ParameterEstimation subclass
  *  and its parameters in the format of a PropertySet. For example:
- *
- *  <pre>
- *  ConditionalProbEstimation [target_dim=2,total_dim=4,pseudo_count=1]
- *  </pre>
- *
+ *  <pre>  CondProbEstimation [target_dim=2,total_dim=4,pseudo_count=1]</pre>
  *  The next line contains the number of factors that share their parameters.
  *  Then, each of these factors is specified on separate lines (possibly 
  *  seperated by empty lines), where each line consists of several fields
  *  seperated by a space or a tab character. The first field contains 
- *  the index of the factor in the factor graph. The 
- *  following fields specify the ordering of the variables on which that
- *  factor depends, i.e., they form a permutation of the labels of the
- *  variables belonging to that factor. The permutation corresponds to the
- *  mapping from the ordering of the variables that is used in the 
- *  SharedParameters object to the canonical ordering of the variables
- *  (i.e., sorted ascendingly according to their labels) which is used in
- *  the internal representation of the Factor object.
+ *  the index of the factor in the factor graph. The following fields should
+ *  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 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
+ *  last variable changes slowest (in the outer loop). By choosing the right
+ *  ordering, it is possible to let different factors (depending on different
+ *  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).
  */
 
-/** \page license License
-
-<b>libDAI is licensed under the GNU General Public License version 2, or
-(at your option) any later version. The complete license text is
-included below.</b>
-
-\htmlonly
-<pre>
-                   GNU GENERAL PUBLIC LICENSE
-                      Version 2, June 1991
-
- Copyright (C) 1989, 1991 Free Software Foundation, Inc.
-                       51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-                           Preamble
-
-  The licenses for most software are designed to take away your
-freedom to share and change it.  By contrast, the GNU General Public
-License is intended to guarantee your freedom to share and change free
-software--to make sure the software is free for all its users.  This
-General Public License applies to most of the Free Software
-Foundation's software and to any other program whose authors commit to
-using it.  (Some other Free Software Foundation software is covered by
-the GNU Library General Public License instead.)  You can apply it to
-your programs, too.
-
-  When we speak of free software, we are referring to freedom, not
-price.  Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-this service if you wish), that you receive source code or can get it
-if you want it, that you can change the software or use pieces of it
-in new free programs; and that you know you can do these things.
-
-  To protect your rights, we need to make restrictions that forbid
-anyone to deny you these rights or to ask you to surrender the rights.
-These restrictions translate to certain responsibilities for you if you
-distribute copies of the software, or if you modify it.
-
-  For example, if you distribute copies of such a program, whether
-gratis or for a fee, you must give the recipients all the rights that
-you have.  You must make sure that they, too, receive or can get the
-source code.  And you must show them these terms so they know their
-rights.
-
-  We protect your rights with two steps: (1) copyright the software, and
-(2) offer you this license which gives you legal permission to copy,
-distribute and/or modify the software.
-
-  Also, for each author's protection and ours, we want to make certain
-that everyone understands that there is no warranty for this free
-software.  If the software is modified by someone else and passed on, we
-want its recipients to know that what they have is not the original, so
-that any problems introduced by others will not reflect on the original
-authors' reputations.
-
-  Finally, any free program is threatened constantly by software
-patents.  We wish to avoid the danger that redistributors of a free
-program will individually obtain patent licenses, in effect making the
-program proprietary.  To prevent this, we have made it clear that any
-patent must be licensed for everyone's free use or not licensed at all.
-
-  The precise terms and conditions for copying, distribution and
-modification follow.
-
-                   GNU GENERAL PUBLIC LICENSE
-   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
-  0. This License applies to any program or other work which contains
-a notice placed by the copyright holder saying it may be distributed
-under the terms of this General Public License.  The "Program", below,
-refers to any such program or work, and a "work based on the Program"
-means either the Program or any derivative work under copyright law:
-that is to say, a work containing the Program or a portion of it,
-either verbatim or with modifications and/or translated into another
-language.  (Hereinafter, translation is included without limitation in
-the term "modification".)  Each licensee is addressed as "you".
-
-Activities other than copying, distribution and modification are not
-covered by this License; they are outside its scope.  The act of
-running the Program is not restricted, and the output from the Program
-is covered only if its contents constitute a work based on the
-Program (independent of having been made by running the Program).
-Whether that is true depends on what the Program does.
-
-  1. You may copy and distribute verbatim copies of the Program's
-source code as you receive it, in any medium, provided that you
-conspicuously and appropriately publish on each copy an appropriate
-copyright notice and disclaimer of warranty; keep intact all the
-notices that refer to this License and to the absence of any warranty;
-and give any other recipients of the Program a copy of this License
-along with the Program.
-
-You may charge a fee for the physical act of transferring a copy, and
-you may at your option offer warranty protection in exchange for a fee.
-
-  2. You may modify your copy or copies of the Program or any portion
-of it, thus forming a work based on the Program, and copy and
-distribute such modifications or work under the terms of Section 1
-above, provided that you also meet all of these conditions:
-
-    a) You must cause the modified files to carry prominent notices
-    stating that you changed the files and the date of any change.
-
-    b) You must cause any work that you distribute or publish, that in
-    whole or in part contains or is derived from the Program or any
-    part thereof, to be licensed as a whole at no charge to all third
-    parties under the terms of this License.
-
-    c) If the modified program normally reads commands interactively
-    when run, you must cause it, when started running for such
-    interactive use in the most ordinary way, to print or display an
-    announcement including an appropriate copyright notice and a
-    notice that there is no warranty (or else, saying that you provide
-    a warranty) and that users may redistribute the program under
-    these conditions, and telling the user how to view a copy of this
-    License.  (Exception: if the Program itself is interactive but
-    does not normally print such an announcement, your work based on
-    the Program is not required to print an announcement.)
-
-These requirements apply to the modified work as a whole.  If
-identifiable sections of that work are not derived from the Program,
-and can be reasonably considered independent and separate works in
-themselves, then this License, and its terms, do not apply to those
-sections when you distribute them as separate works.  But when you
-distribute the same sections as part of a whole which is a work based
-on the Program, the distribution of the whole must be on the terms of
-this License, whose permissions for other licensees extend to the
-entire whole, and thus to each and every part regardless of who wrote it.
-
-Thus, it is not the intent of this section to claim rights or contest
-your rights to work written entirely by you; rather, the intent is to
-exercise the right to control the distribution of derivative or
-collective works based on the Program.
-
-In addition, mere aggregation of another work not based on the Program
-with the Program (or with a work based on the Program) on a volume of
-a storage or distribution medium does not bring the other work under
-the scope of this License.
-
-  3. You may copy and distribute the Program (or a work based on it,
-under Section 2) in object code or executable form under the terms of
-Sections 1 and 2 above provided that you also do one of the following:
-
-    a) Accompany it with the complete corresponding machine-readable
-    source code, which must be distributed under the terms of Sections
-    1 and 2 above on a medium customarily used for software interchange; or,
-
-    b) Accompany it with a written offer, valid for at least three
-    years, to give any third party, for a charge no more than your
-    cost of physically performing source distribution, a complete
-    machine-readable copy of the corresponding source code, to be
-    distributed under the terms of Sections 1 and 2 above on a medium
-    customarily used for software interchange; or,
-
-    c) Accompany it with the information you received as to the offer
-    to distribute corresponding source code.  (This alternative is
-    allowed only for noncommercial distribution and only if you
-    received the program in object code or executable form with such
-    an offer, in accord with Subsection b above.)
-
-The source code for a work means the preferred form of the work for
-making modifications to it.  For an executable work, complete source
-code means all the source code for all modules it contains, plus any
-associated interface definition files, plus the scripts used to
-control compilation and installation of the executable.  However, as a
-special exception, the source code distributed need not include
-anything that is normally distributed (in either source or binary
-form) with the major components (compiler, kernel, and so on) of the
-operating system on which the executable runs, unless that component
-itself accompanies the executable.
-
-If distribution of executable or object code is made by offering
-access to copy from a designated place, then offering equivalent
-access to copy the source code from the same place counts as
-distribution of the source code, even though third parties are not
-compelled to copy the source along with the object code.
-
-  4. You may not copy, modify, sublicense, or distribute the Program
-except as expressly provided under this License.  Any attempt
-otherwise to copy, modify, sublicense or distribute the Program is
-void, and will automatically terminate your rights under this License.
-However, parties who have received copies, or rights, from you under
-this License will not have their licenses terminated so long as such
-parties remain in full compliance.
-
-  5. You are not required to accept this License, since you have not
-signed it.  However, nothing else grants you permission to modify or
-distribute the Program or its derivative works.  These actions are
-prohibited by law if you do not accept this License.  Therefore, by
-modifying or distributing the Program (or any work based on the
-Program), you indicate your acceptance of this License to do so, and
-all its terms and conditions for copying, distributing or modifying
-the Program or works based on it.
-
-  6. Each time you redistribute the Program (or any work based on the
-Program), the recipient automatically receives a license from the
-original licensor to copy, distribute or modify the Program subject to
-these terms and conditions.  You may not impose any further
-restrictions on the recipients' exercise of the rights granted herein.
-You are not responsible for enforcing compliance by third parties to
-this License.
-
-  7. If, as a consequence of a court judgment or allegation of patent
-infringement or for any other reason (not limited to patent issues),
-conditions are imposed on you (whether by court order, agreement or
-otherwise) that contradict the conditions of this License, they do not
-excuse you from the conditions of this License.  If you cannot
-distribute so as to satisfy simultaneously your obligations under this
-License and any other pertinent obligations, then as a consequence you
-may not distribute the Program at all.  For example, if a patent
-license would not permit royalty-free redistribution of the Program by
-all those who receive copies directly or indirectly through you, then
-the only way you could satisfy both it and this License would be to
-refrain entirely from distribution of the Program.
-
-If any portion of this section is held invalid or unenforceable under
-any particular circumstance, the balance of the section is intended to
-apply and the section as a whole is intended to apply in other
-circumstances.
-
-It is not the purpose of this section to induce you to infringe any
-patents or other property right claims or to contest validity of any
-such claims; this section has the sole purpose of protecting the
-integrity of the free software distribution system, which is
-implemented by public license practices.  Many people have made
-generous contributions to the wide range of software distributed
-through that system in reliance on consistent application of that
-system; it is up to the author/donor to decide if he or she is willing
-to distribute software through any other system and a licensee cannot
-impose that choice.
-
-This section is intended to make thoroughly clear what is believed to
-be a consequence of the rest of this License.
-
-  8. If the distribution and/or use of the Program is restricted in
-certain countries either by patents or by copyrighted interfaces, the
-original copyright holder who places the Program under this License
-may add an explicit geographical distribution limitation excluding
-those countries, so that distribution is permitted only in or among
-countries not thus excluded.  In such case, this License incorporates
-the limitation as if written in the body of this License.
-
-  9. The Free Software Foundation may publish revised and/or new versions
-of the General Public License from time to time.  Such new versions will
-be similar in spirit to the present version, but may differ in detail to
-address new problems or concerns.
-
-Each version is given a distinguishing version number.  If the Program
-specifies a version number of this License which applies to it and "any
-later version", you have the option of following the terms and conditions
-either of that version or of any later version published by the Free
-Software Foundation.  If the Program does not specify a version number of
-this License, you may choose any version ever published by the Free Software
-Foundation.
-
-  10. If you wish to incorporate parts of the Program into other free
-programs whose distribution conditions are different, write to the author
-to ask for permission.  For software which is copyrighted by the Free
-Software Foundation, write to the Free Software Foundation; we sometimes
-make exceptions for this.  Our decision will be guided by the two goals
-of preserving the free status of all derivatives of our free software and
-of promoting the sharing and reuse of software generally.
-
-                           NO WARRANTY
-
-  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
-FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
-OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
-PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
-OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
-TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
-PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
-REPAIR OR CORRECTION.
-
-  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
-WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
-REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
-INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
-OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
-TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
-YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
-PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
-POSSIBILITY OF SUCH DAMAGES.
-
-                    END OF TERMS AND CONDITIONS
-
-           How to Apply These Terms to Your New Programs
-
-  If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these terms.
-
-  To do so, attach the following notices to the program.  It is safest
-to attach them to the start of each source file to most effectively
-convey the exclusion of warranty; and each file should have at least
-the "copyright" line and a pointer to where the full notice is found.
-
-    &lt;one line to give the program's name and a brief idea of what it does.&gt;
-    Copyright (C) &lt;year&gt;  &lt;name of author&gt;
-
-    This program is free software; you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation; either version 2 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with this program; if not, write to the Free Software
-    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-
-
-Also add information on how to contact you by electronic and paper mail.
-
-If the program is interactive, make it output a short notice like this
-when it starts in an interactive mode:
-
-    Gnomovision version 69, Copyright (C) year name of author
-    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
-    This is free software, and you are welcome to redistribute it
-    under certain conditions; type `show c' for details.
-
-The hypothetical commands `show w' and `show c' should show the appropriate
-parts of the General Public License.  Of course, the commands you use may
-be called something other than `show w' and `show c'; they could even be
-mouse-clicks or menu items--whatever suits your program.
-
-You should also get your employer (if you work as a programmer) or your
-school, if any, to sign a "copyright disclaimer" for the program, if
-necessary.  Here is a sample; alter the names:
-
-  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
-  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+/** \page bibliography Bibliography
+ *  \anchor KFL01 \ref KFL01
+ *  F. R. Kschischang and B. J. Frey and H.-A. Loeliger (2001):
+ *  "Factor Graphs and the Sum-Product Algorithm",
+ *  <em>IEEE Transactions on Information Theory</em> 47(2):498-519.
+ *  http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?arnumber=910572
+ *
+ *  \anchor MiQ04 \ref MiQ04
+ *  T. Minka and Y. Qi (2004):
+ *  "Tree-structured Approximations by Expectation Propagation",
+ *  <em>Advances in Neural Information Processing Systems</em> (NIPS) 16.
+ *  http://books.nips.cc/papers/files/nips16/NIPS2003_AA25.pdf
+ *
+ *  \anchor MoR05 \ref MoR05
+ *  A. Montanari and T. Rizzo (2005):
+ *  "How to Compute Loop Corrections to the Bethe Approximation",
+ *  <em>Journal of Statistical Mechanics: Theory and Experiment</em>
+ *  2005(10)-P10011.
+ *  http://stacks.iop.org/1742-5468/2005/P10011
+ *
+ *  \anchor YFW05 \ref YFW05
+ *  J. S. Yedidia and W. T. Freeman and Y. Weiss (2005):
+ *  "Constructing Free-Energy Approximations and Generalized Belief Propagation Algorithms",
+ *  <em>IEEE Transactions on Information Theory</em>
+ *  51(7):2282-2312.
+ *  http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?arnumber=1459044
+ *
+ *  \anchor HAK03 \ref HAK03
+ *  T. Heskes and C. A. Albers and H. J. Kappen (2003):
+ *  "Approximate Inference and Constrained Optimization",
+ *  <em>Proceedings of the 19th Annual Conference on Uncertainty in Artificial Intelligence (UAI-03)</em> pp. 313-320.
+ *  http://www.snn.ru.nl/reports/Heskes.uai2003.ps.gz
+ *
+ *  \anchor MoK07 \ref MoK07
+ *  J. M. Mooij and H. J. Kappen (2007):
+ *  "Loop Corrections for Approximate Inference on Factor Graphs",
+ *  <em>Journal of Machine Learning Research</em> 8:1113-1143.
+ *  http://www.jmlr.org/papers/volume8/mooij07a/mooij07a.pdf
+ *
+ *  \anchor MoK07b \ref MoK07b
+ *  J. M. Mooij and H. J. Kappen (2007):
+ *  "Sufficient Conditions for Convergence of the Sum-Product Algorithm",
+ *  <em>IEEE Transactions on Information Theory</em> 53(12):4422-4437.
+ *  http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?arnumber=4385778
+ *
+ *  \anchor EaG09 \ref EaG09
+ *  F. Eaton and Z. Ghahramani (2009):
+ *  "Choosing a Variable to Clamp",
+ *  <em>Proceedings of the Twelfth International Conference on Artificial Intelligence and Statistics (AISTATS 2009)</em> 5:145-152
+ *  http://jmlr.csail.mit.edu/proceedings/papers/v5/eaton09a/eaton09a.pdf
+ *
+ *  \anchor StW99 \ref StW99
+ *  A. Steger and N. C. Wormald (1999):
+ *  "Generating Random Regular Graphs Quickly",
+ *  <em>Combinatorics, Probability and Computing</em> Vol 8, Issue 4, pp. 377-396
+ *  http://www.math.uwaterloo.ca/~nwormald/papers/randgen.pdf
+ *
+ *  \anchor EMK06 \ref EMK06
+ *  G. Elidan and I. McGraw and D. Koller (2006):
+ *  "Residual Belief Propagation: Informed Scheduling for Asynchronous Message Passing",
+ *  <em>Proceedings of the 22nd Annual Conference on Uncertainty in Artificial Intelligence (UAI-06)</em>
+ *  http://uai.sis.pitt.edu/papers/06/UAI2006_0091.pdf
+ *
+ *  \anchor WiH03 \ref WiH03
+ *  W. Wiegerinck and T. Heskes (2003):
+ *  "Fractional Belief Propagation",
+ *  <em>Advances in Neural Information Processing Systems</em> (NIPS) 15, pp. 438-445.
+ *  http://books.nips.cc/papers/files/nips15/LT16.pdf
+ *
+ *  \anchor Min05 \ref Min05
+ *  T. Minka (2005):
+ *  "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
+ */
 
-  &lt;signature of Ty Coon&gt;, 1 April 1989
-  Ty Coon, President of Vice
 
-This General Public License does not permit incorporating your program into
-proprietary programs.  If your program is a subroutine library, you may
-consider it more useful to permit linking proprietary applications with the
-library.  If this is what you want to do, use the GNU Library General
-Public License instead of this License.</pre>
-\endhtmlonly
-  */
+/** \page discussion Ideas not worth exploring
+ *  \section discuss_extendedgraphs Extended factorgraphs/regiongraphs
+ *
+ *  A FactorGraph and a RegionGraph are often equipped with
+ *  additional properties for nodes and edges. The code to initialize those
+ *  is often quite similar. Maybe one could abstract this, e.g.:
+ *  \code
+ *  template <typename Node1Properties, typename Node2Properties, typename EdgeProperties>
+ *  class ExtFactorGraph : public FactorGraph {
+ *      public:
+ *          std::vector<Node1Properties>              node1Props;
+ *          std::vector<Node2Properties>              node2Props;
+ *          std::vector<std::vector<EdgeProperties> > edgeProps;
+ *         // ...
+ *  }
+ *  \endcode
+ *
+ *  Advantages:
+ *  - Less code duplication.
+ *  - Easier maintainability.
+ *  - Easier to write new inference algorithms.
+ *
+ *  Disadvantages:
+ *  - Cachability may be worse.
+ *  - A problem is the case where there are no properties for either type of nodes or for edges.
+ *    Maybe this can be solved using specializations, or using variadac template arguments?
+ *    Another possible solution would be to define a "class Empty {}", and add some code
+ *    that checks for the typeid, comparing it with Empty, and doing something special in that case
+ *    (e.g., not allocating memory).
+ *  - The main disadvantage of this approach seems to be that it leads to even more entanglement.
+ *    Therefore this is probably a bad idea.
+ *
+ *  \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 dai::InfAlg
+ *  was for functions like dai::calcMarginal. Instead, one could use a template function:
+ *  \code
+ *  template<typename InfAlg>
+ *  Factor calcMarginal( const InfAlg &obj, const VarSet &ns, bool reInit );
+ *  \endcode
+ *  This would assume that the type InfAlg supports certain methods. Ideally, one would use
+ *  concepts to define different classes of inference algorithms with different capabilities,
+ *  for example the ability to calculate logZ, the ability to calculate marginals, the ability to
+ *  calculate bounds, the ability to calculate MAP states, etc. Then, one would use traits
+ *  classes in order to be able to query the capabilities of the model. For example, one would be
+ *  able to query whether the inference algorithm supports calculation of logZ.  Unfortunately,
+ *  this is compile-time polymorphism, whereas tests/testdai needs runtime polymorphism.
+ *  Therefore this is probably a bad idea.
+ */