1 /* This file is part of libDAI - http://www.libdai.org/
3 * Copyright (c) 2006-2011, The libDAI authors. All rights reserved.
5 * Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.
10 * \brief Main libDAI header file. It \#includes all other libDAI headers.
12 * \todo Replace VarSets by SmallSet<size_t> where appropriate, in order to minimize the use of FactorGraph::findVar().
14 * \todo Improve SWIG interfaces and merge their build process with the main build process
18 #ifndef __defined_libdai_alldai_h
19 #define __defined_libdai_alldai_h
22 #include <dai/dai_config.h>
24 #include <dai/daialg.h>
25 #include <dai/properties.h>
26 #include <dai/exactinf.h>
27 #include <dai/evidence.h>
28 #include <dai/emalg.h>
36 #include <dai/trwbp.h>
47 #ifdef DAI_WITH_TREEEP
48 #include <dai/treeep.h>
51 #include <dai/jtree.h>
57 #include <dai/gibbs.h>
62 #ifdef DAI_WITH_DECMAP
63 #include <dai/decmap.h>
70 /// Namespace for libDAI
74 /// Returns a map that contains for each built-in inference algorithm its name and a pointer to an object of that type
75 /** \obsolete This functionality is obsolete and will be removed in future versions of libDAI
77 std::map
<std::string
, InfAlg
*>& builtinInfAlgs();
80 /// Returns a set of names of all available inference algorithms
81 /* These are the names of the algorithms that were compiled in and can be
82 * given to \ref newInfAlg and \ref newInfAlgFromString.
83 * \return A set of strings, each one corresponding with the name of an available inference algorithm.
84 * \note The set is returned by value because it will be reasonably small
85 * enough and this function is expected to be called infrequently.
87 std::set
<std::string
> builtinInfAlgNames();
90 /// Constructs a new inference algorithm.
91 /** \param name The name of the inference algorithm.
92 * \param fg The FactorGraph that the algorithm should be applied to.
93 * \param opts A PropertySet specifying the options for the algorithm.
94 * \return Returns a pointer to the new InfAlg object; it is the responsibility of the caller to delete it later.
95 * \throw UNKNOWN_DAI_ALGORITHM if the requested name is not known/compiled in.
97 InfAlg
*newInfAlg( const std::string
&name
, const FactorGraph
&fg
, const PropertySet
&opts
);
100 /// Constructs a new inference algorithm.
101 /** \param nameOpts The name and options of the inference algorithm (should be in the format "name[key1=val1,key2=val2,...,keyn=valn]").
102 * \param fg The FactorGraph that the algorithm should be applied to.
103 * \return Returns a pointer to the new InfAlg object; it is the responsibility of the caller to delete it later.
104 * \throw UNKNOWN_DAI_ALGORITHM if the requested name is not known/compiled in.
106 InfAlg
*newInfAlgFromString( const std::string
&nameOpts
, const FactorGraph
&fg
);
109 /// Constructs a new inference algorithm.
110 /** \param nameOpts The name and options of the inference algorithm (should be in the format "name[key1=val1,key2=val2,...,keyn=valn]").
111 * \param fg The FactorGraph that the algorithm should be applied to.
112 * \param aliases Maps names to strings in the format "name[key1=val1,key2=val2,...,keyn=valn]"; if not empty, alias substitution
113 * will be performed when parsing \a nameOpts by invoking parseNameProperties(const std::string &,const std::map<std::string,std::string> &)
114 * \see newInfAlgFromString(const std::string &, const FactorGraph &)
116 InfAlg
*newInfAlgFromString( const std::string
&nameOpts
, const FactorGraph
&fg
, const std::map
<std::string
,std::string
> &aliases
);
119 /// Extracts the name and property set from a string \a s in the format "name[key1=val1,key2=val2,...]" or "name"
120 std::pair
<std::string
, PropertySet
> parseNameProperties( const std::string
&s
);
123 /// Extracts the name and property set from a string \a s in the format "name[key1=val1,key2=val2,...]" or "name", performing alias substitution
124 /** Alias substitution is performed as follows: as long as name appears as a key in \a aliases,
125 * it is substituted by its value. Properties in \a s override those of the alias (in case of
126 * recursion, the "outer" properties override those of the "inner" aliases).
128 std::pair
<std::string
, PropertySet
> parseNameProperties( const std::string
&s
, const std::map
<std::string
,std::string
> &aliases
);
131 /// Reads aliases from file named \a filename
132 /** \param filename Name of the alias file
133 * \return A map that maps aliases to the strings they should be substituted with.
134 * \see \ref fileformats-aliases
136 std::map
<std::string
,std::string
> readAliasesFile( const std::string
&filename
);
139 } // end of namespace dai
142 /** \example example.cpp
143 * This example illustrates how to read a factor graph from a file and how to
144 * run several inference algorithms (junction tree, loopy belief propagation,
145 * and the max-product algorithm) on it.
149 /** \example example_imagesegmentation.cpp
150 * This example shows how one can use approximate inference in factor graphs
151 * on a simple vision task: given two images, identify smooth regions where these
152 * two images differ more than some threshold. This can be used to seperate
153 * foreground from background if one image contains the background and the other
154 * one the combination of background and foreground.
156 * \note In order to build this example, a recent version of CImg needs to be installed.
160 /** \example uai2010-aie-solver.cpp
161 * This example contains the full source code of the solver that was one of the
162 * winners (the 'libDAI2' solver) in the UAI 2010 Approximate Inference Challenge
163 * (see http://www.cs.huji.ac.il/project/UAI10/ for more information).