Several changes by Giuseppe Passino
[libdai.git] / include / dai / factorgraph.h
1 /* Copyright (C) 2006-2008 Joris Mooij [joris dot mooij at tuebingen dot mpg dot de]
2 Radboud University Nijmegen, The Netherlands /
3 Max Planck Institute for Biological Cybernetics, Germany
4
5 This file is part of libDAI.
6
7 libDAI is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 2 of the License, or
10 (at your option) any later version.
11
12 libDAI is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
16
17 You should have received a copy of the GNU General Public License
18 along with libDAI; if not, write to the Free Software
19 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
20 */
21
22
23 /// \file
24 /// \brief Defines the FactorGraph class
25
26
27 #ifndef __defined_libdai_factorgraph_h
28 #define __defined_libdai_factorgraph_h
29
30
31 #include <iostream>
32 #include <map>
33 #include <dai/bipgraph.h>
34 #include <dai/factor.h>
35
36
37 namespace dai {
38
39
40 /// Represents a factor graph.
41 /** Both Bayesian Networks and Markov random fields can be represented in a
42 * unifying representation, called <em>factor graph</em> [\ref KFL01],
43 * implemented in libDAI by the FactorGraph class.
44 *
45 * Consider a probability distribution over \f$N\f$ discrete random variables
46 * \f$x_0,x_1,\dots,x_N\f$ that factorizes as a product of factors, each of
47 * which depends on some subset of the variables:
48 * \f[
49 * P(x_0,x_1,\dots,x_N) = \frac{1}{Z} \prod_{I=0}^M f_I(x_I), \qquad
50 * Z = \sum_{x_0}\dots\sum_{x_N} \prod_{I=0}^M f_I(X_I).
51 * \f]
52 * Each factor \f$f_I\f$ is a function from an associated subset
53 * of variables \f$X_I \subset \{x_0,x_1,\dots,x_N\}\f$ to the nonnegative
54 * real numbers.
55 *
56 * For a Bayesian network, each factor corresponds to a (conditional)
57 * probability table, whereas for a Markov random field, each factor
58 * corresponds to a maximal clique of the undirected graph.
59 *
60 * Factor graphs explicitly express the factorization structure of the
61 * corresponding probability distribution.
62 */
63 class FactorGraph {
64 public:
65 /// Stores the neighborhood structure
66 BipartiteGraph G;
67
68 /// Shorthand for BipartiteGraph::Neighbor
69 typedef BipartiteGraph::Neighbor Neighbor;
70
71 /// Shorthand for BipartiteGraph::Neighbors
72 typedef BipartiteGraph::Neighbors Neighbors;
73
74 /// Shorthand for BipartiteGraph::Edge
75 typedef BipartiteGraph::Edge Edge;
76
77 /// Iterator over factors
78 typedef std::vector<Factor>::iterator iterator;
79
80 /// Const iterator over factors
81 typedef std::vector<Factor>::const_iterator const_iterator;
82
83
84 private:
85 std::vector<Var> _vars;
86 std::vector<Factor> _factors;
87 std::map<size_t,Factor> _backup;
88
89 public:
90 /// Default constructor
91 FactorGraph() : G(), _vars(), _factors(), _backup() {}
92
93 /// Copy constructor
94 FactorGraph(const FactorGraph & x) : G(x.G), _vars(x._vars), _factors(x._factors), _backup(x._backup) {}
95
96 /// Assignment operator
97 FactorGraph & operator=(const FactorGraph & x) {
98 if( this != &x ) {
99 G = x.G;
100 _vars = x._vars;
101 _factors = x._factors;
102 _backup = x._backup;
103 }
104 return *this;
105 }
106
107 /// Constructs a FactorGraph from a vector of factors
108 FactorGraph(const std::vector<Factor> &P);
109
110 /// Constructs a FactorGraph from given factor and variable iterators
111 /** \tparam FactorInputIterator Iterator with value_type Factor
112 * \tparam VarInputIterator Iterator with value_type Var
113 * \pre Assumes that the set of variables in [var_begin,var_end) is the union of the variables in the factors in [fact_begin, fact_end)
114 */
115 template<typename FactorInputIterator, typename VarInputIterator>
116 FactorGraph(FactorInputIterator fact_begin, FactorInputIterator fact_end, VarInputIterator var_begin, VarInputIterator var_end, size_t nr_fact_hint = 0, size_t nr_var_hint = 0 );
117
118 /// Destructor
119 virtual ~FactorGraph() {}
120
121 /// Clone *this (virtual copy constructor)
122 virtual FactorGraph* clone() const { return new FactorGraph(); }
123
124 /// Create (virtual default constructor)
125 virtual FactorGraph* create() const { return new FactorGraph(*this); }
126
127 /// Returns const reference to i'th variable
128 const Var & var(size_t i) const { return _vars[i]; }
129 /// Returns const reference to all factors
130 const std::vector<Var> & vars() const { return _vars; }
131 /// Returns reference to I'th factor
132 Factor & factor(size_t I) { return _factors[I]; }
133 /// Returns const reference to I'th factor
134 const Factor & factor(size_t I) const { return _factors[I]; }
135 /// Returns const reference to all factors
136 const std::vector<Factor> & factors() const { return _factors; }
137 /// Returns iterator pointing to first factor
138 iterator begin() { return _factors.begin(); }
139 /// Returns const iterator pointing to first factor
140 const_iterator begin() const { return _factors.begin(); }
141 /// Returns iterator pointing beyond last factor
142 iterator end() { return _factors.end(); }
143 /// Returns const iterator pointing beyond last factor
144 const_iterator end() const { return _factors.end(); }
145
146 /// Returns number of variables
147 size_t nrVars() const { return vars().size(); }
148 /// Returns number of factors
149 size_t nrFactors() const { return factors().size(); }
150 /// Calculates number of edges
151 size_t nrEdges() const { return G.nrEdges(); }
152
153 /// Provides read access to neighbors of variable
154 const Neighbors & nbV( size_t i ) const { return G.nb1(i); }
155 /// Provides full access to neighbors of variable
156 Neighbors & nbV( size_t i ) { return G.nb1(i); }
157 /// Provides read access to neighbors of factor
158 const Neighbors & nbF( size_t I ) const { return G.nb2(I); }
159 /// Provides full access to neighbors of factor
160 Neighbors & nbF( size_t I ) { return G.nb2(I); }
161 /// Provides read access to neighbor of variable
162 const Neighbor & nbV( size_t i, size_t _I ) const { return G.nb1(i)[_I]; }
163 /// Provides full access to neighbor of variable
164 Neighbor & nbV( size_t i, size_t _I ) { return G.nb1(i)[_I]; }
165 /// Provides read access to neighbor of factor
166 const Neighbor & nbF( size_t I, size_t _i ) const { return G.nb2(I)[_i]; }
167 /// Provides full access to neighbor of factor
168 Neighbor & nbF( size_t I, size_t _i ) { return G.nb2(I)[_i]; }
169
170 /// Returns the index of a particular variable
171 size_t findVar( const Var & n ) const {
172 size_t i = find( vars().begin(), vars().end(), n ) - vars().begin();
173 assert( i != nrVars() );
174 return i;
175 }
176
177 /// Returns a set of indexes corresponding to a set of variables
178 std::set<size_t> findVars( VarSet &ns ) const {
179 std::set<size_t> indexes;
180 for( VarSet::const_iterator n = ns.begin(); n != ns.end(); n++ )
181 indexes.insert( findVar( *n ) );
182 return indexes;
183 }
184
185 /// Returns index of the first factor that depends on the variables
186 size_t findFactor(const VarSet &ns) const {
187 size_t I;
188 for( I = 0; I < nrFactors(); I++ )
189 if( factor(I).vars() == ns )
190 break;
191 assert( I != nrFactors() );
192 return I;
193 }
194
195 /// Return all variables that occur in a factor involving the i'th variable, itself included
196 VarSet Delta( unsigned i ) const;
197
198 /// Return all variables that occur in a factor involving some variable in ns, ns itself included
199 VarSet Delta( const VarSet &ns ) const;
200
201 /// Return all variables that occur in a factor involving the i'th variable, n itself excluded
202 VarSet delta( unsigned i ) const;
203
204 /// Return all variables that occur in a factor involving some variable in ns, ns itself excluded
205 VarSet delta( const VarSet & ns ) const {
206 return Delta( ns ) / ns;
207 }
208
209 /// Set the content of the I'th factor and make a backup of its old content if backup == true
210 virtual void setFactor( size_t I, const Factor &newFactor, bool backup = false ) {
211 assert( newFactor.vars() == factor(I).vars() );
212 if( backup )
213 backupFactor( I );
214 _factors[I] = newFactor;
215 }
216
217 /// Set the contents of all factors as specified by facs and make a backup of the old contents if backup == true
218 virtual void setFactors( const std::map<size_t, Factor> & facs, bool backup = false ) {
219 for( std::map<size_t, Factor>::const_iterator fac = facs.begin(); fac != facs.end(); fac++ ) {
220 if( backup )
221 backupFactor( fac->first );
222 setFactor( fac->first, fac->second );
223 }
224 }
225
226 /// Clamp variable n to value i (i.e. multiply with a Kronecker delta \f$\delta_{x_n, i}\f$);
227 /// If backup == true, make a backup of all factors that are changed
228 virtual void clamp( const Var & n, size_t i, bool backup = false );
229
230 /// Set all factors interacting with the i'th variable 1
231 virtual void makeCavity( unsigned i, bool backup = false );
232
233 /// Backup the factors specified by indices in facs
234 virtual void backupFactors( const std::set<size_t> & facs );
235
236 /// Restore all factors to the backup copies
237 virtual void restoreFactors();
238
239 /// Returns true if the FactorGraph is connected
240 bool isConnected() const { return G.isConnected(); }
241
242 /// Returns true if the FactorGraph is a tree
243 bool isTree() const { return G.isTree(); }
244
245 /// Returns true if each factor depends on at most two variables
246 bool isPairwise() const;
247
248 /// Returns true if each variable has only two possible values
249 bool isBinary() const;
250
251 /// Reads a FactorGraph from a file
252 void ReadFromFile(const char *filename);
253
254 /// Writes a FactorGraph to a file
255 void WriteToFile(const char *filename) const;
256
257 /// Writes a FactorGraph to a GraphViz .dot file
258 void printDot( std::ostream& os ) const;
259
260 /// Returns the cliques in this FactorGraph
261 std::vector<VarSet> Cliques() const;
262
263 /// Clamp variable v_i to value state (i.e. multiply with a Kronecker delta \f$\delta_{x_{v_i},x}\f$);
264 /** This version changes the factor graph structure and thus returns a newly constructed FactorGraph
265 * and keeps the current one constant, contrary to clamp()
266 */
267 FactorGraph clamped( const Var & v_i, size_t x ) const;
268
269 /// Returns a copy of *this, where all factors that are subsumed by some larger factor are merged with the larger factors.
270 FactorGraph maximalFactors() const;
271
272 /// Makes a backup of the I'th Factor
273 void restoreFactor( size_t I );
274
275 /// Restores the I'th Factor from the backup (it should be backed up first)
276 void backupFactor( size_t I );
277
278 /// Makes a backup of all factors connected to a set of variables
279 void backupFactors( const VarSet &ns );
280 /// Restores all factors connected to a set of variables from their backups
281 void restoreFactors( const VarSet &ns );
282
283 // Friends
284 friend std::ostream& operator << (std::ostream& os, const FactorGraph& fg);
285 friend std::istream& operator >> (std::istream& is, FactorGraph& fg);
286
287 private:
288 /// Part of constructors (creates edges, neighbors and adjacency matrix)
289 void constructGraph( size_t nrEdges );
290 };
291
292
293 template<typename FactorInputIterator, typename VarInputIterator>
294 FactorGraph::FactorGraph(FactorInputIterator fact_begin, FactorInputIterator fact_end, VarInputIterator var_begin, VarInputIterator var_end, size_t nr_fact_hint, size_t nr_var_hint ) : G(), _backup() {
295 // add factors
296 size_t nrEdges = 0;
297 _factors.reserve( nr_fact_hint );
298 for( FactorInputIterator p2 = fact_begin; p2 != fact_end; ++p2 ) {
299 _factors.push_back( *p2 );
300 nrEdges += p2->vars().size();
301 }
302
303 // add variables
304 _vars.reserve( nr_var_hint );
305 for( VarInputIterator p1 = var_begin; p1 != var_end; ++p1 )
306 _vars.push_back( *p1 );
307
308 // create graph structure
309 constructGraph( nrEdges );
310 }
311
312
313 } // end of namespace dai
314
315
316 #endif