Some documentation improvements
[libdai.git] / include / dai / bp_dual.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) 2009 Frederik Eaton [frederik at ofb dot net]
8 */
9
10
11 /// \file
12 /// \brief Defines class BP_dual, which is used primarily by BBP.
13 /// \idea BP_dual replicates a large part of the functionality of BP; would it not be more efficient to adapt BP instead?
14 /// \author Frederik Eaton
15
16
17 #ifndef __defined_libdai_bp_dual_h
18 #define __defined_libdai_bp_dual_h
19
20
21 #include <dai/daialg.h>
22 #include <dai/factorgraph.h>
23 #include <dai/enum.h>
24
25
26 namespace dai {
27
28
29 /// Calculates both types of BP messages and their normalizers from an InfAlg.
30 /** BP_dual calculates "dual" versions of BP messages (both messages from factors
31 * to variables and messages from variables to factors), and normalizers, given an InfAlg.
32 * These are computed from the variable and factor beliefs of the InfAlg.
33 * This class is used primarily by BBP.
34 *
35 * \author Frederik Eaton
36 */
37 class BP_dual {
38 protected:
39 /// Convenience label for storing edge properties
40 template<class T>
41 struct _edges_t : public std::vector<std::vector<T> > {};
42
43 /// Groups together the data structures for storing the two types of messages and their normalizers
44 struct messages {
45 /// Unnormalized variable->factor messages
46 _edges_t<Prob> n;
47 /// Normalizers of variable->factor messages
48 _edges_t<Real> Zn;
49 /// Unnormalized Factor->variable messages
50 _edges_t<Prob> m;
51 /// Normalizers of factor->variable messages
52 _edges_t<Real> Zm;
53 };
54 /// Stores all messages
55 messages _msgs;
56
57 /// Groups together the data structures for storing the two types of beliefs and their normalizers
58 struct beliefs {
59 /// Unnormalized variable beliefs
60 std::vector<Prob> b1;
61 /// Normalizers of variable beliefs
62 std::vector<Real> Zb1;
63 /// Unnormalized factor beliefs
64 std::vector<Prob> b2;
65 /// Normalizers of factor beliefs
66 std::vector<Real> Zb2;
67 };
68 /// Stores all beliefs
69 beliefs _beliefs;
70
71 /// Pointer to the InfAlg object
72 const InfAlg *_ia;
73
74 /// Does all necessary preprocessing
75 void init();
76 /// Allocates space for \a _msgs
77 void regenerateMessages();
78 /// Allocates space for \a _beliefs
79 void regenerateBeliefs();
80
81 /// Calculate all messages from InfAlg beliefs
82 void calcMessages();
83 /// Update factor->variable message (\a i -> \a I)
84 void calcNewM(size_t i, size_t _I);
85 /// Update variable->factor message (\a I -> \a i)
86 void calcNewN(size_t i, size_t _I);
87
88 /// Calculate all variable and factor beliefs from messages
89 void calcBeliefs();
90 /// Calculate belief of variable \a i
91 void calcBeliefV(size_t i);
92 /// Calculate belief of factor \a I
93 void calcBeliefF(size_t I);
94
95 public:
96 /// Construct BP_dual object from (converged) InfAlg object's beliefs and factors.
97 /** \warning A pointer to the the InfAlg object is stored,
98 * so the object must not be destroyed before the BP_dual is destroyed.
99 */
100 BP_dual( const InfAlg *ia ) : _ia(ia) { init(); }
101
102 /// Returns the underlying FactorGraph
103 const FactorGraph& fg() const { return _ia->fg(); }
104
105 /// Returns reference to factor->variable message (\a I -> \a i)
106 Prob & msgM( size_t i, size_t _I ) { return _msgs.m[i][_I]; }
107 /// Returns constant reference to factor->variable message (\a I -> \a i)
108 const Prob & msgM( size_t i, size_t _I ) const { return _msgs.m[i][_I]; }
109 /// Returns reference to variable -> factor message (\a i -> \a I)
110 Prob & msgN( size_t i, size_t _I ) { return _msgs.n[i][_I]; }
111 /// Returns constant reference to variable -> factor message (\a i -> \a I)
112 const Prob & msgN( size_t i, size_t _I ) const { return _msgs.n[i][_I]; }
113 /// Returns reference to normalizer for factor->variable message (\a I -> \a i)
114 Real & zM( size_t i, size_t _I ) { return _msgs.Zm[i][_I]; }
115 /// Returns constant reference to normalizer for factor->variable message (\a I -> \a i)
116 const Real & zM( size_t i, size_t _I ) const { return _msgs.Zm[i][_I]; }
117 /// Returns reference to normalizer for variable -> factor message (\a i -> \a I)
118 Real & zN( size_t i, size_t _I ) { return _msgs.Zn[i][_I]; }
119 /// Returns constant reference to normalizer for variable -> factor message (\a i -> \a I)
120 const Real & zN( size_t i, size_t _I ) const { return _msgs.Zn[i][_I]; }
121
122 /// Returns belief of variable \a i
123 Factor beliefV( size_t i ) const { return Factor( _ia->fg().var(i), _beliefs.b1[i] ); }
124 /// Returns belief of factor \a I
125 Factor beliefF( size_t I ) const { return Factor( _ia->fg().factor(I).vars(), _beliefs.b2[I] ); }
126
127 /// Returns normalizer for belief of variable \a i
128 Real beliefVZ( size_t i ) const { return _beliefs.Zb1[i]; }
129 /// Returns normalizer for belief of factor \a I
130 Real beliefFZ( size_t I ) const { return _beliefs.Zb2[I]; }
131 };
132
133
134 } // end of namespace dai
135
136
137 #endif