Added source code for one of the winning solvers of the UAI 2010 Approximate Inferenc...
[libdai.git] / include / dai / alldai.h
1 /* This file is part of libDAI - http://www.libdai.org/
2 *
3 * libDAI is licensed under the terms of the GNU General Public License version
4 * 2, or (at your option) any later version. libDAI is distributed without any
5 * warranty. See the file COPYING for more details.
6 *
7 * Copyright (C) 2006-2010 Joris Mooij [joris dot mooij at libdai dot org]
8 * Copyright (C) 2006-2007 Radboud University Nijmegen, The Netherlands
9 */
10
11
12 /** \file
13 * \brief Main libDAI header file. It \#includes all other libDAI headers.
14 *
15 * \todo Replace VarSets by SmallSet<size_t> where appropriate, in order to minimize the use of FactorGraph::findVar().
16 *
17 * \todo Improve SWIG interfaces and merge their build process with the main build process
18 */
19
20
21 #ifndef __defined_libdai_alldai_h
22 #define __defined_libdai_alldai_h
23
24
25 #include <string>
26 #include <dai/daialg.h>
27 #include <dai/properties.h>
28 #include <dai/exactinf.h>
29 #include <dai/evidence.h>
30 #include <dai/emalg.h>
31 #ifdef DAI_WITH_BP
32 #include <dai/bp.h>
33 #endif
34 #ifdef DAI_WITH_FBP
35 #include <dai/fbp.h>
36 #endif
37 #ifdef DAI_WITH_TRWBP
38 #include <dai/trwbp.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 #ifdef DAI_WITH_GIBBS
59 #include <dai/gibbs.h>
60 #endif
61 #ifdef DAI_WITH_CBP
62 #include <dai/cbp.h>
63 #endif
64 #ifdef DAI_WITH_DECMAP
65 #include <dai/decmap.h>
66 #endif
67
68
69 /// Namespace for libDAI
70 namespace dai {
71
72
73 /// Constructs a new inference algorithm.
74 /** \param name The name of the inference algorithm (should be one of the names in DAINames).
75 * \param fg The FactorGraph that the algorithm should be applied to.
76 * \param opts A PropertySet specifying the options for the algorithm.
77 * \return Returns a pointer to the new InfAlg object; it is the responsibility of the caller to delete it later.
78 * \throw UNKNOWN_DAI_ALGORITHM if the requested name is not known/compiled in.
79 */
80 InfAlg *newInfAlg( const std::string &name, const FactorGraph &fg, const PropertySet &opts );
81
82
83 /// Constructs a new inference algorithm.
84 /** \param nameOpts The name and options of the inference algorithm (should be in the format "name[key1=val1,key2=val2,...,keyn=valn]").
85 * \param fg The FactorGraph that the algorithm should be applied to.
86 * \return Returns a pointer to the new InfAlg object; it is the responsibility of the caller to delete it later.
87 * \throw UNKNOWN_DAI_ALGORITHM if the requested name is not known/compiled in.
88 */
89 InfAlg *newInfAlgFromString( const std::string &nameOpts, const FactorGraph &fg );
90
91
92 /// Constructs a new inference algorithm.
93 /** \param nameOpts The name and options of the inference algorithm (should be in the format "name[key1=val1,key2=val2,...,keyn=valn]").
94 * \param fg The FactorGraph that the algorithm should be applied to.
95 * \param aliases Maps names to strings in the format "name[key1=val1,key2=val2,...,keyn=valn]"; if not empty, alias substitution
96 * will be performed when parsing \a nameOpts by invoking parseNameProperties(const std::string &,const std::map<std::string,std::string> &)
97 * \see newInfAlgFromString(const std::string &, const FactorGraph &)
98 */
99 InfAlg *newInfAlgFromString( const std::string &nameOpts, const FactorGraph &fg, const std::map<std::string,std::string> &aliases );
100
101
102 /// Extracts the name and property set from a string \a s in the format "name[key1=val1,key2=val2,...]" or "name"
103 std::pair<std::string, PropertySet> parseNameProperties( const std::string &s );
104
105
106 /// Extracts the name and property set from a string \a s in the format "name[key1=val1,key2=val2,...]" or "name", performing alias substitution
107 /** Alias substitution is performed as follows: as long as name appears as a key in \a aliases,
108 * it is substituted by its value. Properties in \a s override those of the alias (in case of
109 * recursion, the "outer" properties override those of the "inner" aliases).
110 */
111 std::pair<std::string, PropertySet> parseNameProperties( const std::string &s, const std::map<std::string,std::string> &aliases );
112
113
114 /// Reads aliases from file named \a filename
115 /** \param filename Name of the alias file
116 * \return A map that maps aliases to the strings they should be substituted with.
117 * \see \ref fileformats-aliases
118 */
119 std::map<std::string,std::string> readAliasesFile( const std::string &filename );
120
121
122 /// Contains the names of all inference algorithms compiled into libDAI.
123 static const char* DAINames[] = {
124 ExactInf::Name,
125 #ifdef DAI_WITH_BP
126 BP::Name,
127 #endif
128 #ifdef DAI_WITH_FBP
129 FBP::Name,
130 #endif
131 #ifdef DAI_WITH_TRWBP
132 TRWBP::Name,
133 #endif
134 #ifdef DAI_WITH_MF
135 MF::Name,
136 #endif
137 #ifdef DAI_WITH_HAK
138 HAK::Name,
139 #endif
140 #ifdef DAI_WITH_LC
141 LC::Name,
142 #endif
143 #ifdef DAI_WITH_TREEEP
144 TreeEP::Name,
145 #endif
146 #ifdef DAI_WITH_JTREE
147 JTree::Name,
148 #endif
149 #ifdef DAI_WITH_MR
150 MR::Name,
151 #endif
152 #ifdef DAI_WITH_GIBBS
153 Gibbs::Name,
154 #endif
155 #ifdef DAI_WITH_CBP
156 CBP::Name,
157 #endif
158 #ifdef DAI_WITH_DECMAP
159 DecMAP::Name,
160 #endif
161 ""
162 };
163
164
165 } // end of namespace dai
166
167
168 /** \example example.cpp
169 * This example illustrates how to read a factor graph from a file and how to
170 * run several inference algorithms (junction tree, loopy belief propagation,
171 * and the max-product algorithm) on it.
172 */
173
174
175 /** \example example_imagesegmentation.cpp
176 * This example shows how one can use approximate inference in factor graphs
177 * on a simple vision task: given two images, identify smooth regions where these
178 * two images differ more than some threshold. This can be used to seperate
179 * foreground from background if one image contains the background and the other
180 * one the combination of background and foreground.
181 *
182 * \note In order to build this example, a recent version of CImg needs to be installed.
183 */
184
185
186 /** \example uai2010-aie-solver.cpp
187 * This example contains the full source code of the solver that was one of the
188 * winners (the 'libDAI2' solver) in the UAI 2010 Approximate Inference Challenge
189 * (see http://www.cs.huji.ac.il/project/UAI10/ for more information).
190 */
191
192
193 #endif