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