f28fc6d3b4de85e880e4c0687c7e49316081927b
[libdai.git] / include / dai / alldai.h
1 /* This file is part of libDAI - http://www.libdai.org/
2 *
3 * Copyright (c) 2006-2011, The libDAI authors. All rights reserved.
4 *
5 * Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.
6 */
7
8
9 /** \file
10 * \brief Main libDAI header file. It \#includes all other libDAI headers.
11 *
12 * \todo Replace VarSets by SmallSet<size_t> where appropriate, in order to minimize the use of FactorGraph::findVar().
13 *
14 * \todo Improve SWIG interfaces and merge their build process with the main build process
15 */
16
17
18 #ifndef __defined_libdai_alldai_h
19 #define __defined_libdai_alldai_h
20
21
22 #include <string>
23 #include <dai/daialg.h>
24 #include <dai/properties.h>
25 #include <dai/exactinf.h>
26 #include <dai/evidence.h>
27 #include <dai/emalg.h>
28 #ifdef DAI_WITH_BP
29 #include <dai/bp.h>
30 #endif
31 #ifdef DAI_WITH_FBP
32 #include <dai/fbp.h>
33 #endif
34 #ifdef DAI_WITH_TRWBP
35 #include <dai/trwbp.h>
36 #endif
37 #ifdef DAI_WITH_MF
38 #include <dai/mf.h>
39 #endif
40 #ifdef DAI_WITH_HAK
41 #include <dai/hak.h>
42 #endif
43 #ifdef DAI_WITH_LC
44 #include <dai/lc.h>
45 #endif
46 #ifdef DAI_WITH_TREEEP
47 #include <dai/treeep.h>
48 #endif
49 #ifdef DAI_WITH_JTREE
50 #include <dai/jtree.h>
51 #endif
52 #ifdef DAI_WITH_MR
53 #include <dai/mr.h>
54 #endif
55 #ifdef DAI_WITH_GIBBS
56 #include <dai/gibbs.h>
57 #endif
58 #ifdef DAI_WITH_CBP
59 #include <dai/cbp.h>
60 #endif
61 #ifdef DAI_WITH_DECMAP
62 #include <dai/decmap.h>
63 #endif
64
65
66 /// Namespace for libDAI
67 namespace dai {
68
69
70 /// Returns a map that contains for each built-in inference algorithm its name and a pointer to an object of that type
71 /** \obsolete This functionality is obsolete and will be removed in future versions of libDAI
72 */
73 std::map<std::string, InfAlg *>& builtinInfAlgs();
74
75
76 /// Returns a set of names of all available inference algorithms
77 /* These are the names of the algorithms that were compiled in and can be
78 * given to \ref newInfAlg and \ref newInfAlgFromString.
79 * \return A set of strings, each one corresponding with the name of an available inference algorithm.
80 * \note The set is returned by value because it will be reasonably small
81 * enough and this function is expected to be called infrequently.
82 */
83 std::set<std::string> builtinInfAlgNames();
84
85
86 /// Constructs a new inference algorithm.
87 /** \param name The name of the inference algorithm.
88 * \param fg The FactorGraph that the algorithm should be applied to.
89 * \param opts A PropertySet specifying the options for the algorithm.
90 * \return Returns a pointer to the new InfAlg object; it is the responsibility of the caller to delete it later.
91 * \throw UNKNOWN_DAI_ALGORITHM if the requested name is not known/compiled in.
92 */
93 InfAlg *newInfAlg( const std::string &name, const FactorGraph &fg, const PropertySet &opts );
94
95
96 /// Constructs a new inference algorithm.
97 /** \param nameOpts The name and options of the inference algorithm (should be in the format "name[key1=val1,key2=val2,...,keyn=valn]").
98 * \param fg The FactorGraph that the algorithm should be applied to.
99 * \return Returns a pointer to the new InfAlg object; it is the responsibility of the caller to delete it later.
100 * \throw UNKNOWN_DAI_ALGORITHM if the requested name is not known/compiled in.
101 */
102 InfAlg *newInfAlgFromString( const std::string &nameOpts, const FactorGraph &fg );
103
104
105 /// Constructs a new inference algorithm.
106 /** \param nameOpts The name and options of the inference algorithm (should be in the format "name[key1=val1,key2=val2,...,keyn=valn]").
107 * \param fg The FactorGraph that the algorithm should be applied to.
108 * \param aliases Maps names to strings in the format "name[key1=val1,key2=val2,...,keyn=valn]"; if not empty, alias substitution
109 * will be performed when parsing \a nameOpts by invoking parseNameProperties(const std::string &,const std::map<std::string,std::string> &)
110 * \see newInfAlgFromString(const std::string &, const FactorGraph &)
111 */
112 InfAlg *newInfAlgFromString( const std::string &nameOpts, const FactorGraph &fg, const std::map<std::string,std::string> &aliases );
113
114
115 /// Extracts the name and property set from a string \a s in the format "name[key1=val1,key2=val2,...]" or "name"
116 std::pair<std::string, PropertySet> parseNameProperties( const std::string &s );
117
118
119 /// Extracts the name and property set from a string \a s in the format "name[key1=val1,key2=val2,...]" or "name", performing alias substitution
120 /** Alias substitution is performed as follows: as long as name appears as a key in \a aliases,
121 * it is substituted by its value. Properties in \a s override those of the alias (in case of
122 * recursion, the "outer" properties override those of the "inner" aliases).
123 */
124 std::pair<std::string, PropertySet> parseNameProperties( const std::string &s, const std::map<std::string,std::string> &aliases );
125
126
127 /// Reads aliases from file named \a filename
128 /** \param filename Name of the alias file
129 * \return A map that maps aliases to the strings they should be substituted with.
130 * \see \ref fileformats-aliases
131 */
132 std::map<std::string,std::string> readAliasesFile( const std::string &filename );
133
134
135 } // end of namespace dai
136
137
138 /** \example example.cpp
139 * This example illustrates how to read a factor graph from a file and how to
140 * run several inference algorithms (junction tree, loopy belief propagation,
141 * and the max-product algorithm) on it.
142 */
143
144
145 /** \example example_imagesegmentation.cpp
146 * This example shows how one can use approximate inference in factor graphs
147 * on a simple vision task: given two images, identify smooth regions where these
148 * two images differ more than some threshold. This can be used to seperate
149 * foreground from background if one image contains the background and the other
150 * one the combination of background and foreground.
151 *
152 * \note In order to build this example, a recent version of CImg needs to be installed.
153 */
154
155
156 /** \example uai2010-aie-solver.cpp
157 * This example contains the full source code of the solver that was one of the
158 * winners (the 'libDAI2' solver) in the UAI 2010 Approximate Inference Challenge
159 * (see http://www.cs.huji.ac.il/project/UAI10/ for more information).
160 */
161
162
163 #endif