Significant improvement of documentation
[libdai.git] / include / dai / regiongraph.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 classes Region, FRegion and RegionGraph
25
26
27 #ifndef __defined_libdai_regiongraph_h
28 #define __defined_libdai_regiongraph_h
29
30
31 #include <iostream>
32 #include <dai/bipgraph.h>
33 #include <dai/factorgraph.h>
34 #include <dai/weightedgraph.h>
35
36
37 namespace dai {
38
39
40 /// A Region is a set of variables with a counting number
41 class Region : public VarSet {
42 private:
43 /// Counting number
44 double _c;
45
46 public:
47 /// Default constructor
48 Region() : VarSet(), _c(1.0) {}
49
50 /// Construct Region from a VarSet and a counting number
51 Region(const VarSet & x, double c) : VarSet(x), _c(c) {}
52
53 /// Copy constructor
54 Region(const Region & x) : VarSet(x), _c(x._c) {}
55
56 /// Assignment operator
57 Region & operator=(const Region & x) {
58 if( this != &x ) {
59 VarSet::operator=(x);
60 _c = x._c;
61 }
62 return *this;
63 }
64
65 /// Provide read access to counting number
66 const double & c() const { return _c; }
67 /// Provide full access to counting number
68 double & c() { return _c; }
69 };
70
71
72 /// A FRegion is a factor with a counting number
73 class FRegion : public Factor {
74 private:
75 /// Counting number
76 double _c;
77
78 public:
79 /// Default constructor
80 FRegion() : Factor(), _c(1.0) {}
81
82 /// Constructs FRegion from a Factor and a counting number
83 FRegion( const Factor & x, double c ) : Factor(x), _c(c) {}
84
85 /// Copy constructor
86 FRegion( const FRegion & x ) : Factor(x), _c(x._c) {}
87
88 /// Assignment operator
89 FRegion & operator=(const FRegion & x) {
90 if( this != &x ) {
91 Factor::operator=(x);
92 _c = x._c;
93 }
94 return *this;
95 }
96
97 /// Provide read access to counting number
98 const double & c() const { return _c; }
99 /// Provide full access to counting number
100 double & c() { return _c; }
101 };
102
103
104 /// A RegionGraph is a bipartite graph consisting of outer regions (type FRegion) and inner regions (type Region)
105 class RegionGraph : public FactorGraph {
106 public:
107 /// Stores the neighborhood structure
108 BipartiteGraph G;
109
110 /// The outer regions (corresponding to nodes of type 1)
111 std::vector<FRegion> ORs;
112
113 /// The inner regions (corresponding to nodes of type 2)
114 std::vector<Region> IRs;
115
116 /// Stores for each factor index the index of the outer region it belongs to
117 std::vector<size_t> fac2OR;
118
119
120 public:
121 /// Default constructor
122 RegionGraph() : FactorGraph(), G(), ORs(), IRs(), fac2OR() {}
123
124 /// Constructs a RegionGraph from a FactorGraph
125 RegionGraph( const FactorGraph &fg ) : FactorGraph(fg), G(), ORs(), IRs(), fac2OR() {}
126
127 /// Constructs a RegionGraph from a FactorGraph, a vector of outer regions, a vector of inner regions and a vector of edges
128 RegionGraph( const FactorGraph &fg, const std::vector<Region> &ors, const std::vector<Region> &irs, const std::vector<std::pair<size_t,size_t> > &edges );
129
130 /// Constructs a RegionGraph from a FactorGraph and a vector of outer VarSets (CVM style)
131 RegionGraph( const FactorGraph &fg, const std::vector<VarSet> &cl );
132
133 /// Copy constructor
134 RegionGraph( const RegionGraph &x ) : FactorGraph(x), G(x.G), ORs(x.ORs), IRs(x.IRs), fac2OR(x.fac2OR) {}
135
136 /// Assignment operator
137 RegionGraph & operator=( const RegionGraph &x ) {
138 if( this != &x ) {
139 FactorGraph::operator=( x );
140 G = x.G;
141 ORs = x.ORs;
142 IRs = x.IRs;
143 fac2OR = x.fac2OR;
144 }
145 return *this;
146 }
147
148 /// Clone *this (virtual copy constructor)
149 virtual RegionGraph* clone() const { return new RegionGraph(*this); }
150
151 /// Create (virtual default constructor)
152 virtual RegionGraph* create() const { return new RegionGraph(); }
153
154 /// Set the content of the I'th factor and make a backup of its old content if backup == true
155 virtual void setFactor( size_t I, const Factor &newFactor, bool backup = false ) {
156 FactorGraph::setFactor( I, newFactor, backup );
157 RecomputeOR( I );
158 }
159
160 /// Set the contents of all factors as specified by facs and make a backup of the old contents if backup == true
161 virtual void setFactors( const std::map<size_t, Factor> & facs, bool backup = false ) {
162 FactorGraph::setFactors( facs, backup );
163 VarSet ns;
164 for( std::map<size_t, Factor>::const_iterator fac = facs.begin(); fac != facs.end(); fac++ )
165 ns |= fac->second.vars();
166 RecomputeORs( ns );
167 }
168
169
170 /// Provides read access to outer region
171 const FRegion & OR(size_t alpha) const { return ORs[alpha]; }
172 /// Provides access to outer region
173 FRegion & OR(size_t alpha) { return ORs[alpha]; }
174
175 /// Provides read access to inner region
176 const Region & IR(size_t beta) const { return IRs[beta]; }
177 /// Provides access to inner region
178 Region & IR(size_t beta) { return IRs[beta]; }
179
180 /// Returns number of outer regions
181 size_t nrORs() const { return ORs.size(); }
182 /// Returns number of inner regions
183 size_t nrIRs() const { return IRs.size(); }
184
185
186 /// Provides read access to neighbors of outer region
187 const Neighbors & nbOR( size_t alpha ) const { return G.nb1(alpha); }
188 /// Provides full access to neighbors of outer region
189 Neighbors & nbOR( size_t alpha ) { return G.nb1(alpha); }
190
191 /// Provides read access to neighbors of inner region
192 const Neighbors & nbIR( size_t beta ) const { return G.nb2(beta); }
193 /// Provides full access to neighbors of inner region
194 Neighbors & nbIR( size_t beta ) { return G.nb2(beta); }
195
196
197 /// Calculates counting numbers of inner regions based upon counting numbers of outer regions
198 void Calc_Counting_Numbers();
199 /// Check whether the counting numbers are valid
200 bool Check_Counting_Numbers();
201
202 /// Recompute all outer regions
203 void RecomputeORs();
204
205 /// Recompute all outer regions involving the variables in ns
206 void RecomputeORs( const VarSet & ns );
207
208 /// Recompute all outer regions involving factor I
209 void RecomputeOR( size_t I );
210
211 // Friends
212 friend std::ostream & operator << ( std::ostream & os, const RegionGraph & rg );
213 };
214
215
216 } // end of namespace dai
217
218
219 #endif