New git HEAD version
[libdai.git] / include / dai / cbp.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 Defines class CBP, which implements Conditioned Belief Propagation
11
12
13 #ifndef __defined_libdai_cbp_h
14 #define __defined_libdai_cbp_h
15
16
17 #include <dai/dai_config.h>
18 #ifdef DAI_WITH_CBP
19
20
21 #include <fstream>
22 #include <boost/shared_ptr.hpp>
23
24 #include <dai/daialg.h>
25 #include <dai/bbp.h>
26
27
28 namespace dai {
29
30
31 /// Class for CBP (Conditioned Belief Propagation) [\ref EaG09]
32 /** This approximate inference algorithm uses configurable heuristics to choose a variable
33 * \f$ x_i \f$ and a state \f$ x_i^* \f$. Inference is done with \f$ x_i \f$ "clamped" to \f$ x_i^* \f$
34 * (i.e., conditional on \f$ x_i = x_i^* \f$), and also with the negation of this condition.
35 * Clamping is done recursively up to a fixed number of levels (other stopping criteria are
36 * also implemented, see the CBP::Properties::RecurseType property). The resulting approximate
37 * marginals are combined using estimates of the partition sum.
38 *
39 * \author Frederik Eaton
40 */
41 class CBP : public DAIAlgFG {
42 private:
43 /// Variable beliefs
44 std::vector<Factor> _beliefsV;
45 /// Factor beliefs
46 std::vector<Factor> _beliefsF;
47 /// Logarithm of partition sum
48 Real _logZ;
49
50 /// Numer of iterations needed
51 size_t _iters;
52 /// Maximum difference encountered so far
53 Real _maxdiff;
54
55 /// Number of clampings at each leaf node
56 Real _sum_level;
57 /// Number of leaves of recursion tree
58 size_t _num_leaves;
59
60 /// Output stream where information about the clampings is written
61 boost::shared_ptr<std::ofstream> _clamp_ofstream;
62
63
64 public:
65 /// Default constructor
66 CBP() : DAIAlgFG(), _beliefsV(), _beliefsF(), _logZ(0.0), _iters(0), _maxdiff(0.0), _sum_level(0.0), _num_leaves(0), _clamp_ofstream() {}
67
68 /// Construct CBP object from FactorGraph \a fg and PropertySet \a opts
69 /** \param fg Factor graph.
70 * \param opts Parameters @see Properties
71 */
72 CBP( const FactorGraph &fg, const PropertySet &opts ) : DAIAlgFG(fg) {
73 props.set( opts );
74 construct();
75 }
76
77 /// \name General InfAlg interface
78 //@{
79 virtual CBP* clone() const { return new CBP(*this); }
80 virtual CBP* construct( const FactorGraph &fg, const PropertySet &opts ) const { return new CBP( fg, opts ); }
81 virtual std::string name() const { return "CBP"; }
82 virtual Factor belief( const Var &v ) const { return beliefV( findVar( v ) ); }
83 virtual Factor belief( const VarSet & ) const { DAI_THROW(NOT_IMPLEMENTED); }
84 virtual Factor beliefV( size_t i ) const { return _beliefsV[i]; }
85 virtual Factor beliefF( size_t I ) const { return _beliefsF[I]; }
86 virtual std::vector<Factor> beliefs() const { return concat(_beliefsV, _beliefsF); }
87 virtual Real logZ() const { return _logZ; }
88 virtual void init() {};
89 virtual void init( const VarSet & ) {};
90 virtual Real run();
91 virtual Real maxDiff() const { return _maxdiff; }
92 virtual size_t Iterations() const { return _iters; }
93 virtual void setMaxIter( size_t maxiter ) { props.maxiter = maxiter; }
94 virtual void setProperties( const PropertySet &opts ) { props.set( opts ); }
95 virtual PropertySet getProperties() const { return props.get(); }
96 virtual std::string printProperties() const { return props.toString(); }
97 //@}
98
99 //----------------------------------------------------------------
100
101 /// Parameters for CBP
102 /* PROPERTIES(props,CBP) {
103 /// Enumeration of possible update schedules
104 typedef BP::Properties::UpdateType UpdateType;
105 /// Enumeration of possible methods for deciding when to stop recursing
106 DAI_ENUM(RecurseType,REC_FIXED,REC_LOGZ,REC_BDIFF);
107 /// Enumeration of possible heuristics for choosing clamping variable
108 DAI_ENUM(ChooseMethodType,CHOOSE_RANDOM,CHOOSE_MAXENT,CHOOSE_BBP,CHOOSE_BP_L1,CHOOSE_BP_CFN);
109 /// Enumeration of possible clampings: variables or factors
110 DAI_ENUM(ClampType,CLAMP_VAR,CLAMP_FACTOR);
111
112 /// Verbosity (amount of output sent to stderr)
113 size_t verbose = 0;
114
115 /// Tolerance for BP convergence test
116 Real tol;
117 /// Update style for BP
118 UpdateType updates;
119 /// Maximum number of iterations for BP
120 size_t maxiter;
121
122 /// Tolerance used for controlling recursion depth (\a recurse is REC_LOGZ or REC_BDIFF)
123 Real rec_tol;
124 /// Maximum number of levels of recursion (\a recurse is REC_FIXED)
125 size_t max_levels = 10;
126 /// If choose==CHOOSE_BBP and maximum adjoint is less than this value, don't recurse
127 Real min_max_adj;
128 /// Heuristic for choosing clamping variable
129 ChooseMethodType choose;
130 /// Method for deciding when to stop recursing
131 RecurseType recursion;
132 /// Whether to clamp variables or factors
133 ClampType clamp;
134 /// Properties to pass to BBP
135 PropertySet bbp_props;
136 /// Cost function to use for BBP
137 BBPCostFunction bbp_cfn;
138 /// Random seed
139 size_t rand_seed = 0;
140
141 /// If non-empty, write clamping choices to this file
142 std::string clamp_outfile = "";
143 }
144 */
145 /* {{{ GENERATED CODE: DO NOT EDIT. Created by
146 ./scripts/regenerate-properties include/dai/cbp.h src/cbp.cpp
147 */
148 struct Properties {
149 /// Enumeration of possible update schedules
150 typedef BP::Properties::UpdateType UpdateType;
151 /// Enumeration of possible methods for deciding when to stop recursing
152 DAI_ENUM(RecurseType,REC_FIXED,REC_LOGZ,REC_BDIFF);
153 /// Enumeration of possible heuristics for choosing clamping variable
154 DAI_ENUM(ChooseMethodType,CHOOSE_RANDOM,CHOOSE_MAXENT,CHOOSE_BBP,CHOOSE_BP_L1,CHOOSE_BP_CFN);
155 /// Enumeration of possible clampings: variables or factors
156 DAI_ENUM(ClampType,CLAMP_VAR,CLAMP_FACTOR);
157 /// Verbosity (amount of output sent to stderr)
158 size_t verbose;
159 /// Tolerance for BP convergence test
160 Real tol;
161 /// Update style for BP
162 UpdateType updates;
163 /// Maximum number of iterations for BP
164 size_t maxiter;
165 /// Tolerance used for controlling recursion depth (\a recurse is REC_LOGZ or REC_BDIFF)
166 Real rec_tol;
167 /// Maximum number of levels of recursion (\a recurse is REC_FIXED)
168 size_t max_levels;
169 /// If choose==CHOOSE_BBP and maximum adjoint is less than this value, don't recurse
170 Real min_max_adj;
171 /// Heuristic for choosing clamping variable
172 ChooseMethodType choose;
173 /// Method for deciding when to stop recursing
174 RecurseType recursion;
175 /// Whether to clamp variables or factors
176 ClampType clamp;
177 /// Properties to pass to BBP
178 PropertySet bbp_props;
179 /// Cost function to use for BBP
180 BBPCostFunction bbp_cfn;
181 /// Random seed
182 size_t rand_seed;
183 /// If non-empty, write clamping choices to this file
184 std::string clamp_outfile;
185
186 /// Set members from PropertySet
187 /** \throw UNKNOWN_PROPERTY if a Property key is not recognized
188 * \throw NOT_ALL_PROPERTIES_SPECIFIED if an expected Property is missing
189 */
190 void set(const PropertySet &opts);
191 /// Get members into PropertySet
192 PropertySet get() const;
193 /// Convert to a string which can be parsed as a PropertySet
194 std::string toString() const;
195 } props;
196 /* }}} END OF GENERATED CODE */
197
198 private:
199 /// Prints beliefs, variables and partition sum, in case of a debugging build
200 void printDebugInfo();
201
202 /// Called by run(), and by itself. Implements the main algorithm.
203 /** Chooses a variable to clamp, recurses, combines the partition sum
204 * and belief estimates of the children, and returns the improved
205 * estimates in \a lz_out and \a beliefs_out to its parent.
206 */
207 void runRecurse( InfAlg *bp, Real orig_logZ, std::vector<size_t> clamped_vars_list, size_t &num_leaves,
208 size_t &choose_count, Real &sum_level, Real &lz_out, std::vector<Factor> &beliefs_out );
209
210 /// Choose the next variable to clamp.
211 /** Choose the next variable to clamp, given a converged InfAlg \a bp,
212 * and a vector of variables that are already clamped (\a
213 * clamped_vars_list). Returns the chosen variable in \a i, and
214 * the set of states in \a xis. If \a maxVarOut is non-NULL and
215 * \a props.choose == \c CHOOSE_BBP then it is used to store the
216 * adjoint of the chosen variable.
217 */
218 virtual bool chooseNextClampVar( InfAlg* bp, std::vector<size_t> &clamped_vars_list, size_t &i, std::vector<size_t> &xis, Real *maxVarOut );
219
220 /// Return the InfAlg to use at each step of the recursion.
221 /** \todo At present, CBP::getInfAlg() only returns a BP instance;
222 * it should be possible to select other inference algorithms via a property
223 */
224 InfAlg* getInfAlg();
225
226 /// Sets variable beliefs, factor beliefs and log partition sum to the specified values
227 /** \param bs should be a concatenation of the variable beliefs followed by the factor beliefs
228 * \param logZ log partition sum
229 */
230 void setBeliefs( const std::vector<Factor> &bs, Real logZ );
231
232 /// Constructor helper function
233 void construct();
234 };
235
236
237 /// Find the best variable/factor to clamp using BBP.
238 /** Takes a converged inference algorithm as input, runs Gibbs and BP_dual, creates
239 * and runs a BBP object, finds the best variable/factor (the one with the maximum
240 * factor adjoint), and returns the corresponding (index,state) pair.
241 * \param in_bp inference algorithm (compatible with BP) that should have converged;
242 * \param clampingVar if \c true, finds best variable, otherwise, finds best factor;
243 * \param bbp_props BBP parameters to use;
244 * \param cfn BBP cost function to use;
245 * \param maxVarOut maximum adjoint value (only set if not NULL).
246 * \see BBP
247 * \relates CBP
248 */
249 std::pair<size_t, size_t> BBPFindClampVar( const InfAlg &in_bp, bool clampingVar, const PropertySet &bbp_props, const BBPCostFunction &cfn, Real *maxVarOut );
250
251
252 } // end of namespace dai
253
254
255 #endif
256
257
258 #endif