include/dai/alldai.h

   1 /*  Copyright (C) 2006-2008  Joris Mooij  [joris dot mooij at tuebingen dot mpg dot de]
   2     Radboud University Nijmegen, The Netherlands /
   3     Max Planck Institute for Biological Cybernetics, Germany
   4
   5     This file is part of libDAI.
   6
   7     libDAI is free software; you can redistribute it and/or modify
   8     it under the terms of the GNU General Public License as published by
   9     the Free Software Foundation; either version 2 of the License, or
  10     (at your option) any later version.
  11
  12     libDAI is distributed in the hope that it will be useful,
  13     but WITHOUT ANY WARRANTY; without even the implied warranty of
  14     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15     GNU General Public License for more details.
  16
  17     You should have received a copy of the GNU General Public License
  18     along with libDAI; if not, write to the Free Software
  19     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  20 */
  21
  22
  23 /// \file
  24 /// \brief Main libDAI header file
  25 /// \todo Improve documentation
  26
  27
  28 #ifndef __defined_libdai_alldai_h
  29 #define __defined_libdai_alldai_h
  30
  31
  32 #include <string>
  33 #include <dai/daialg.h>
  34 #include <dai/properties.h>
  35 #include <dai/exactinf.h>
  36 #ifdef DAI_WITH_BP
  37     #include <dai/bp.h>
  38 #endif
  39 #ifdef DAI_WITH_MF
  40     #include <dai/mf.h>
  41 #endif
  42 #ifdef DAI_WITH_HAK
  43     #include <dai/hak.h>
  44 #endif
  45 #ifdef DAI_WITH_LC
  46     #include <dai/lc.h>
  47 #endif
  48 #ifdef DAI_WITH_TREEEP
  49     #include <dai/treeep.h>
  50 #endif
  51 #ifdef DAI_WITH_JTREE
  52     #include <dai/jtree.h>
  53 #endif
  54 #ifdef DAI_WITH_MR
  55     #include <dai/mr.h>
  56 #endif
  57
  58
  59 /// Namespace for libDAI
  60 namespace dai {
  61
  62
  63 /// Constructs a new approximate inference algorithm.
  64 /** \param name The name of the approximate inference algorithm (should be one of the names in DAINames).
  65  *  \param fg The FactorGraph that the algorithm should be applied to.
  66  *  \param opts A PropertySet specifying the options for the algorithm.
  67  *  \return Returns a pointer to the new InfAlg object; it is the responsibility of the caller to delete it later.
  68  */
  69 InfAlg *newInfAlg( const std::string &name, const FactorGraph &fg, const PropertySet &opts );
  70
  71
  72 /// Contains the names of all approximate inference algorithms compiled into libDAI.
  73 static const char* DAINames[] = {
  74     ExactInf::Name,
  75 #ifdef DAI_WITH_BP
  76     BP::Name,
  77 #endif
  78 #ifdef DAI_WITH_MF
  79     MF::Name,
  80 #endif
  81 #ifdef DAI_WITH_HAK
  82     HAK::Name,
  83 #endif
  84 #ifdef DAI_WITH_LC
  85     LC::Name,
  86 #endif
  87 #ifdef DAI_WITH_TREEEP
  88     TreeEP::Name,
  89 #endif
  90 #ifdef DAI_WITH_JTREE
  91     JTree::Name,
  92 #endif
  93 #ifdef DAI_WITH_MR
  94     MR::Name,
  95 #endif
  96     ""
  97 };
  98
  99
 100 } // end of namespace dai
 101
 102
 103 /** \mainpage libDAI reference manual
 104  *  \author Joris Mooij
 105  *  \version git HEAD
 106  *  \date October 8, 2008
 107  *
 108  *  \section about About libDAI
 109  *  libDAI is a free/open source C++ library (licensed under GPL) that provides
 110  *  implementations of various (approximate) inference methods for discrete
 111  *  graphical models. libDAI supports arbitrary factor graphs with discrete
 112  *  variables; this includes discrete Markov Random Fields and Bayesian
 113  *  Networks.
 114  *
 115  *  The library is targeted at researchers; to be able to use the library, a
 116  *  good understanding of graphical models is needed.
 117  *
 118  *  \section limitations Limitations
 119  *  libDAI is not intended to be a complete package for approximate inference.
 120  *  Instead, it should be considered as an "inference engine", providing
 121  *  various inference methods. In particular, it contains no GUI, currently
 122  *  only supports its own file format for input and output (although support
 123  *  for standard file formats may be added later), and provides very limited
 124  *  visualization functionalities.
 125  *
 126  *  \section features Features
 127  *  Currently, libDAI supports the following (approximate) inference methods:
 128  *  - Exact inference by brute force enumeration;
 129  *  - Exact inference by junction-tree methods;
 130  *  - Mean Field;
 131  *  - Loopy Belief Propagation [\ref KFL01];
 132  *  - Tree Expectation Propagation [\ref MiQ04];
 133  *  - Generalized Belief Propagation [\ref YFW05];
 134  *  - Double-loop GBP [\ref HAK03];
 135  *  - Various variants of Loop Corrected Belief Propagation
 136  *    [\ref MoK07, \ref MoR05].
 137  *
 138  *  \section language Why C++?
 139  *  Because libDAI is implemented in C++, it is very fast compared with
 140  *  implementations in MatLab (a factor 1000 faster is not uncommon).
 141  *  libDAI does provide a MatLab interface for easy integration with MatLab.
 142  *
 143  *  \section quickstart Quick start
 144  *  An example program illustrating basic usage of libDAI is given in examples/example.cpp.
 145  */
 146
 147 /// \example example.cpp
 148
 149 /** \page Bibliography
 150  *  \section Bibliograpy
 151  *  \anchor KFL01 \ref KFL01
 152  *  F. R. Kschischang and B. J. Frey and H.-A. Loeliger (2001):
 153  *  "Factor Graphs and the Sum-Product Algorithm",
 154  *  <em>IEEE Transactions on Information Theory</em> 47(2):498-519.
 155  *  http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?arnumber=910572
 156  *
 157  *  \anchor MiQ04 \ref MiQ04
 158  *  T. Minka and Y. Qi (2004):
 159  *  "Tree-structured Approximations by Expectation Propagation",
 160  *  <em>Advances in Neural Information Processing Systems</em> (NIPS) 16.
 161  *  http://books.nips.cc/papers/files/nips16/NIPS2003_AA25.pdf
 162  *
 163  *  \anchor MoR05 \ref MoR05
 164  *  A. Montanari and T. Rizzo (2005):
 165  *  "How to Compute Loop Corrections to the Bethe Approximation",
 166  *  <em>Journal of Statistical Mechanics: Theory and Experiment</em>
 167  *  2005(10)-P10011.
 168  *  http://stacks.iop.org/1742-5468/2005/P10011
 169  *
 170  *  \anchor YFW05 \ref YFW05
 171  *  J. S. Yedidia and W. T. Freeman and Y. Weiss (2005):
 172  *  "Constructing Free-Energy Approximations and Generalized Belief Propagation Algorithms",
 173  *  <em>IEEE Transactions on Information Theory</em>
 174  *  51(7):2282-2312.
 175  *  http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?arnumber=1459044
 176  *
 177  *  \anchor HAK03 \ref HAK03
 178  *  T. Heskes and C. A. Albers and H. J. Kappen (2003):
 179  *  "Approximate Inference and Constrained Optimization",
 180  *  <em>Proceedings of the 19th Annual Conference on Uncertainty in Artificial Intelligence (UAI-03)</em> pp. 313-320.
 181  *  http://www.snn.ru.nl/reports/Heskes.uai2003.ps.gz
 182  *
 183  *  \anchor MoK07 \ref MoK07
 184  *  J. M. Mooij and H. J. Kappen (2007):
 185  *  "Loop Corrections for Approximate Inference on Factor Graphs",
 186  *  <em>Journal of Machine Learning Research</em> 8:1113-1143.
 187  *  http://www.jmlr.org/papers/volume8/mooij07a/mooij07a.pdf
 188  *
 189  *  \anchor MoK07b \ref MoK07b
 190  *  J. M. Mooij and H. J. Kappen (2007):
 191  *  "Sufficient Conditions for Convergence of the Sum-Product Algorithm",
 192  *  <em>IEEE Transactions on Information Theory</em> 53(12):4422-4437.
 193  *  http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?arnumber=4385778
 194  */
 195
 196
 197 #endif