bd0a8e0d6179615ee8de0c522f7eb1b192ecd857

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-2009 Joris Mooij [joris dot mooij at libdai dot org]

8 * Copyright (C) 2006-2007 Radboud University Nijmegen, The Netherlands

9 */

12 /// \file

13 /// \brief Defines abstract base class InfAlg, its descendant DAIAlg<>, the specializations DAIAlgFG and DAIAlgRG and some generic inference methods.

16 #ifndef __defined_libdai_daialg_h

17 #define __defined_libdai_daialg_h

20 #include <string>

21 #include <iostream>

22 #include <vector>

23 #include <dai/factorgraph.h>

24 #include <dai/regiongraph.h>

30 /// InfAlg is an abstract base class, defining the common interface of all inference algorithms in libDAI.

31 /** \todo General marginalization functions like calcMarginal() now copy a complete InfAlg object. Instead,

32 * it would make more sense that they construct a new object without copying the FactorGraph or RegionGraph.

33 * Or they can simply be made methods of the general InfAlg class.

34 * \idea Use a PropertySet as output of an InfAlg, instead of functions like maxDiff() and Iterations().

35 */

38 /// \name Constructors/destructors

39 //@{

40 /// Virtual destructor (needed because this class contains virtual functions)

43 /// Returns a pointer to a new, cloned copy of \c *this (i.e., virtual copy constructor)

45 //@}

47 /// \name Queries

48 //@{

49 /// Identifies itself for logging purposes

52 /// Returns reference to underlying FactorGraph.

55 /// Returns constant reference to underlying FactorGraph.

57 //@}

59 /// \name Inference interface

60 //@{

61 /// Initializes all data structures of the approximate inference algorithm.

62 /** \note This method should be called at least once before run() is called.

63 */

66 /// Initializes all data structures corresponding to some set of variables.

67 /** This method can be used to do a partial initialization after a part of the factor graph has changed.

68 * Instead of initializing all data structures, it only initializes those involving the variables in \a vs.

69 */

72 /// Runs the approximate inference algorithm.

73 /** \note Before run() is called the first time, init() should have been called.

74 */

77 /// Returns the (approximate) marginal probability distribution of a variable.

78 /** \note Before this method is called, run() should have been called.

79 */

82 /// Returns the (approximate) marginal probability distribution of a set of variables.

83 /** \note Before this method is called, run() should have been called.

84 */

87 /// Returns the (approximate) marginal probability distribution of the variable with index \a i.

88 /** For some approximate inference algorithms, using beliefV() is preferred to belief() for performance reasons.

89 * \note Before this method is called, run() should have been called.

90 */

93 /// Returns the (approximate) marginal probability distribution of the variables on which factor \a I depends.

94 /** For some approximate inference algorithms, using beliefF() is preferred to belief() for performance reasons.

95 * \note Before this method is called, run() should have been called.

96 */

99 /// Returns all beliefs (approximate marginal probability distributions) calculated by the algorithm.

100 /** \note Before this method is called, run() should have been called.

101 */

104 /// Returns the logarithm of the (approximated) partition sum (normalizing constant of the factor graph).

105 /** \note Before this method is called, run() should have been called.

106 * \throw NOT_IMPLEMENTED if not implemented/supported

107 */

110 /// Returns maximum difference between single variable beliefs in the last iteration.

111 /** \throw NOT_IMPLEMENTED if not implemented/supported

112 */

115 /// Returns number of iterations done (one iteration passes over the complete factorgraph).

116 /** \throw NOT_IMPLEMENTED if not implemented/supported

117 */

119 //@}

121 /// \name Changing the factor graph

122 //@{

123 /// Clamp variable with index \a i to value \a x (i.e. multiply with a Kronecker delta \f$\delta_{x_i, x}\f$)

124 /** If \a backup == \c true, make a backup of all factors that are changed.

125 */

128 // OBSOLETE

129 /// Only for backwards compatibility (to be removed soon)

132 /// Sets all factors interacting with variable with index \a i to one.

133 /** If \a backup == \c true, make a backup of all factors that are changed.

134 */

136 //@}

138 /// \name Backup/restore mechanism for factors

139 //@{

140 /// Make a backup copy of factor \a I

142 /// Make backup copies of all factors involving the variables in \a vs

145 /// Restore factor \a I from its backup copy

147 /// Restore the factors involving the variables in \a vs from their backup copies

149 //@}

150 };

153 /// Combines the abstract base class InfAlg with a graphical model (e.g., a FactorGraph or RegionGraph).

154 /** Inference algorithms in libDAI directly inherit from a DAIAlg, currently either

155 * from a DAIAlg<FactorGraph> or from a DAIAlg<RegionGraph>.

156 *

157 * \tparam GRM Should be castable to FactorGraph

158 * \todo A DAIAlg should not inherit from a FactorGraph or RegionGraph, but should

159 * store a reference to the graphical model object. This prevents needless copying

160 * of (possibly large) data structures. Disadvantage: the caller must not change

161 * the graphical model between calls to the inference algorithm (maybe a smart_ptr

162 * or some locking mechanism would help here?).

163 */

167 /// \name Constructors/destructors

168 //@{

169 /// Default constructor

172 /// Construct from GRM

174 //@}

176 /// \name Queries

177 //@{

178 /// Returns reference to underlying FactorGraph.

181 /// Returns constant reference to underlying FactorGraph.

183 //@}

185 /// \name Changing the factor graph

186 //@{

187 /// Clamp variable with index \a i to value \a x (i.e. multiply with a Kronecker delta \f$\delta_{x_i, x}\f$)

188 /** If \a backup == \c true, make a backup of all factors that are changed.

189 */

192 // OBSOLETE

193 /// Only for backwards compatibility (to be removed soon)

196 std::cerr << "Warning: this DAIAlg<...>::clamp(const Var&,...) interface is obsolete!" << std::endl;

197 }

199 /// Sets all factors interacting with variable with index \a i to one.

200 /** If \a backup == \c true, make a backup of all factors that are changed.

201 */

203 //@}

205 /// \name Backup/restore mechanism for factors

206 //@{

207 /// Make a backup copy of factor \a I

209 /// Make backup copies of all factors involving the variables in \a vs

212 /// Restore factor \a I from its backup copy

214 /// Restore the factors involving the variables in \a vs from their backup copies

216 //@}

217 };

220 /// Base class for inference algorithms that operate on a FactorGraph

223 /// Base class for inference algorithms that operate on a RegionGraph

227 /// Calculates the marginal probability distribution for \a vs using inference algorithm \a obj.

228 /** calcMarginal() works by clamping all variables in \a vs and calculating the partition sum for each clamped state.

229 * Therefore, it can be used in combination with any inference algorithm that can calculate/approximate partition sums.

230 * \param obj instance of inference algorithm to be used

231 * \param vs variables for which the marginal should be calculated

232 * \param reInit should be set to \c true if at least one of the possible clamped states would be invalid (leading to a factor graph with zero partition sum).

233 */

236 /// Calculates beliefs for all pairs of variables in \a vs using inference algorithm \a obj.

237 /** calcPairBeliefs() works by

238 * - clamping single variables in \a vs and calculating the partition sum and the single variable beliefs for each clamped state, if \a accurate == \c false;

239 * - clamping pairs of variables in \a vs and calculating the partition sum for each clamped state, if \a accurate == \c true.

240 *

241 * Therefore, it can be used in combination with any inference algorithm that can calculate/approximate partition sums (and single variable beliefs, if

242 * \a accurate == \c true).

243 * \param obj instance of inference algorithm to be used

244 * \param vs variables for which the pair beliefs should be calculated

245 * \param reInit should be set to \c true if at least one of the possible clamped states would be invalid (leading to a factor graph with zero partition sum).

246 * \param accurate if \c true, uses a slower but more accurate approximation algorithm

247 */

248 std::vector<Factor> calcPairBeliefs( const InfAlg& obj, const VarSet& vs, bool reInit, bool accurate=false );

250 // OBSOLETE

251 /// Only for backwards compatibility (to be removed soon)

254 // OBSOLETE

255 /// Only for backwards compatibility (to be removed soon)

262 #endif