aGrUM 3.3.2
a C++ library for (probabilistic) graphical models
jointTargetedMRFInference_tpl.h
Go to the documentation of this file.
1/****************************************************************************
2 * This file is part of the aGrUM/pyAgrum library. *
3 * *
4 * Copyright (c) 2005-2026 by *
5 * - Pierre-Henri WUILLEMIN(_at_LIP6) *
6 * - Christophe GONZALES(_at_AMU) *
7 * *
8 * The aGrUM/pyAgrum library is free software; you can redistribute it *
9 * and/or modify it under the terms of either : *
10 * *
11 * - the GNU Lesser General Public License as published by *
12 * the Free Software Foundation, either version 3 of the License, *
13 * or (at your option) any later version, *
14 * - the MIT license (MIT), *
15 * - or both in dual license, as here. *
16 * *
17 * (see https://agrum.gitlab.io/articles/dual-licenses-lgplv3mit.html) *
18 * *
19 * This aGrUM/pyAgrum library is distributed in the hope that it will be *
20 * useful, but WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, *
21 * INCLUDING BUT NOT LIMITED TO THE WARRANTIES MERCHANTABILITY or FITNESS *
22 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE *
23 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER *
24 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, *
25 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR *
26 * OTHER DEALINGS IN THE SOFTWARE. *
27 * *
28 * See LICENCES for more details. *
29 * *
30 * SPDX-FileCopyrightText: Copyright 2005-2026 *
31 * - Pierre-Henri WUILLEMIN(_at_LIP6) *
32 * - Christophe GONZALES(_at_AMU) *
33 * SPDX-License-Identifier: LGPL-3.0-or-later OR MIT *
34 * *
35 * Contact : info_at_agrum_dot_org *
36 * homepage : http://agrum.gitlab.io *
37 * gitlab : https://gitlab.com/agrumery/agrum *
38 * *
39 ****************************************************************************/
40
41#pragma once
42
43
52
53namespace gum {
54
55
56 // Default Constructor
57 template < GUM_Numeric GUM_SCALAR >
60 // assign a MRF if this has not been done before (due to virtual inheritance)
62 GUM_CONSTRUCTOR(JointTargetedMRFInference);
63 }
64
65 // Destructor
66 template < GUM_Numeric GUM_SCALAR >
70
71 // assigns a new MRF to the inference engine
72 template < GUM_Numeric GUM_SCALAR >
78
79 // ##############################################################################
80 // Targets
81 // ##############################################################################
82
83 // return true if target is a nodeset target.
84 template < GUM_Numeric GUM_SCALAR >
86 if (this->hasNoModel_())
88 "No Markov net has been assigned to the "
89 "inference algorithm");
90
91 const auto& gra = this->MRF().internalGraph();
92 for (const auto var: vars) {
93 if (!gra.exists(var)) {
94 GUM_ERROR(UndefinedElement, var << " is not a NodeId in the Markov random field")
95 }
96 }
97
98 return _joint_targets_.contains(vars);
99 }
100
101 // Clear all previously defined single targets
102 template < GUM_Numeric GUM_SCALAR >
106
107 // Clear all previously defined targets (single targets and sets of targets)
108 template < GUM_Numeric GUM_SCALAR >
110 if (_joint_targets_.size() > 0) {
111 // we already are in target mode. So no this->setTargetedMode_(); is needed
113 _joint_targets_.clear();
115 }
116 }
117
118 // Clear all previously defined targets (single and joint targets)
119 template < GUM_Numeric GUM_SCALAR >
124
125 // Add a set of nodes as a new target
126 template < GUM_Numeric GUM_SCALAR >
128 // check if the nodes in the target belong to the Markov random field
129 if (this->hasNoModel_())
131 "No Markov net has been assigned to the "
132 "inference algorithm");
133
134 const auto& dag = this->MRF().internalGraph();
135 for (const auto node: joint_target) {
136 if (!dag.exists(node)) {
138 "at least one one in " << joint_target << " does not belong to the mn");
139 }
140 }
141
142 if (isExactJointComputable_(joint_target)) return;
143 if (!superForJointComputable_(joint_target).empty()) return;
144
145 // check if joint_target is a subset of an already existing target
146 for (const auto& target: _joint_targets_) {
147 if (target.isStrictSupersetOf(joint_target)) return;
148 }
149
150 // check if joint_target is not a superset of an already existing target
151 // in this case, we need to remove old existing target
152 for (auto iter = _joint_targets_.beginSafe(); iter != _joint_targets_.endSafe(); ++iter) {
153 if (iter->isStrictSubsetOf(joint_target)) eraseJointTarget(*iter);
154 }
155
156 this->setTargetedMode_(); // does nothing if already in targeted mode
157 _joint_targets_.insert(joint_target);
158 onJointTargetAdded_(joint_target);
160 }
161
162 // removes an existing set target
163 template < GUM_Numeric GUM_SCALAR >
165 // check if the nodes in the target belong to the Markov random field
166 if (this->hasNoModel_())
168 "No Markov net has been assigned to the "
169 "inference algorithm");
170
171 const auto& dag = this->MRF().internalGraph();
172 for (const auto node: joint_target) {
173 if (!dag.exists(node)) {
175 "at least one one in " << joint_target << " does not belong to the mn");
176 }
177 }
178
179 // check that the joint_target set does not contain the new target
180 if (_joint_targets_.contains(joint_target)) {
181 // note that we have to be in target mode when we are here
182 // so, no this->setTargetedMode_(); is necessary
183 onJointTargetErased_(joint_target);
184 _joint_targets_.erase(joint_target);
186 }
187 }
188
190 template < GUM_Numeric GUM_SCALAR >
194
196 template < GUM_Numeric GUM_SCALAR >
200
201 // ##############################################################################
202 // Inference
203 // ##############################################################################
204
205 // Compute the posterior of a nodeset.
206 template < GUM_Numeric GUM_SCALAR >
207 const Tensor< GUM_SCALAR >&
209 NodeSet real_nodes;
210 for (const auto& node: nodes) {
211 if (!this->hasHardEvidence(node)) { real_nodes.insert(node); }
212 }
213 // try to get the smallest set of targets that contains "nodes"
214 bool found_exact_target = false;
215 NodeSet super_target;
216
217 if (isExactJointComputable_(real_nodes)) {
218 found_exact_target = true;
219 } else {
220 super_target = superForJointComputable_(real_nodes);
221 if (super_target.empty()) {
223 "No joint target containing " << real_nodes << " could be found among "
224 << _joint_targets_);
225 }
226 }
227
228 if (!this->isInferenceDone()) { this->makeInference(); }
229
230 // the superset may be real_nodes itself (e.g. the scope of a factor)
231 if (found_exact_target || (super_target == real_nodes)) return jointPosterior_(real_nodes);
232 else { return jointPosterior_(real_nodes, super_target); }
233 }
234
235 // Compute the posterior of a node
236 template < GUM_Numeric GUM_SCALAR >
239 else return jointPosterior(NodeSet{node});
240 }
241
242 // Compute the posterior of a node
243 template < GUM_Numeric GUM_SCALAR >
244 const Tensor< GUM_SCALAR >&
246 return posterior(this->MRF().idFromName(nodeName));
247 }
248
249 // ##############################################################################
250 // Entropy
251 // ##############################################################################
252
253 template < GUM_Numeric GUM_SCALAR >
254 Tensor< GUM_SCALAR >
256 const NodeSet& evs) {
257 if (!(evs * targets).empty()) {
259 "Targets (" << targets << ") can not intersect evs (" << evs << ").");
260 }
261 auto condset = this->MRF().minimalCondSet(targets, evs);
262
263 // the targets and the evidence of the user are restored when leaving
264 const typename GraphicalModelInference< GUM_SCALAR >::StateGuard_ guard(*this);
265 this->eraseAllTargets();
266 this->eraseAllEvidence();
267
268 Instantiation iTarget;
269 Tensor< GUM_SCALAR > res;
270 for (const auto& target: targets) {
271 res.add(this->MRF().variable(target));
272 iTarget.add(this->MRF().variable(target));
273 }
274 this->addJointTarget(targets);
275
276 for (const auto& n: condset) {
277 res.add(this->MRF().variable(n));
278 this->addEvidence(n, 0);
279 }
280
281 Instantiation inst(res);
282 for (inst.setFirstOut(iTarget); !inst.end(); inst.incOut(iTarget)) {
283 // inferring
284 for (const auto& n: condset)
285 this->chgEvidence(n, inst.val(this->MRF().variable(n)));
286 this->makeInference();
287 // populate res
288 for (inst.setFirstIn(iTarget); !inst.end(); inst.incIn(iTarget)) {
289 res.set(inst, this->jointPosterior(targets)[inst]);
290 }
291 inst.setFirstIn(iTarget); // remove inst.end() flag
292 }
293
294 return res;
295 }
296
297 template < GUM_Numeric GUM_SCALAR >
299 const std::vector< std::string >& targets,
300 const std::vector< std::string >& evs) {
301 const auto& mn = this->MRF();
302 return evidenceJointImpact(mn.nodeset(targets), mn.nodeset(evs));
303 }
304
305 template < GUM_Numeric GUM_SCALAR >
306 GUM_SCALAR
308 const auto& mn = this->MRF();
309 const Size siz = targets.size();
310 if (siz <= 1) {
312 "jointMutualInformation needs at least 2 variables (targets=" << targets << ")");
313 }
314
315 // the targets and the evidence of the user are restored when leaving
316 const typename GraphicalModelInference< GUM_SCALAR >::StateGuard_ guard(*this);
317 this->eraseAllTargets();
318 this->eraseAllEvidence();
319 this->addJointTarget(targets);
320 this->makeInference();
321 const auto po = this->jointPosterior(targets);
322
323 gum::Instantiation caracteristic;
324 gum::Instantiation variables;
325 for (const auto nod: targets) {
326 const auto& var = mn.variable(nod);
327 auto pv = new gum::RangeVariable(var.name(), "", 0, 1);
328 caracteristic.add(*pv);
329 variables.add(var);
330 }
331
333
334 const GUM_SCALAR start = (siz % 2 == 0) ? GUM_SCALAR(-1.0) : GUM_SCALAR(1.0);
335 GUM_SCALAR sign;
336 GUM_SCALAR res = GUM_SCALAR(0.0);
337
338 caracteristic.setFirst();
339 for (caracteristic.inc(); !caracteristic.end(); caracteristic.inc()) {
340 sov.clear();
341 sign = start;
342 for (Idx i = 0; i < caracteristic.nbrDim(); i++) {
343 if (caracteristic.val(i) == 1) {
344 sign = -sign;
345 sov.insert(&variables.variable(i));
346 }
347 }
348 res += sign * po.sumIn(sov).entropy();
349 }
350
351 for (Idx i = 0; i < caracteristic.nbrDim(); i++) {
352 delete &caracteristic.variable(i);
353 }
354
355 return res;
356 }
357
358 template < GUM_Numeric GUM_SCALAR >
360 const std::vector< std::string >& targets) {
361 return jointMutualInformation(this->MRF().nodeset(targets));
362 }
363
364 template < GUM_Numeric GUM_SCALAR >
366 if (_joint_targets_.contains(vars)) return true;
367
368 return false;
369 }
370
371 template < GUM_Numeric GUM_SCALAR >
373 for (const auto& target: _joint_targets_)
374 if (vars.isSubsetOrEqual(target)) return target;
375
376 for (const auto& factor: this->MRF().factors()) {
377 if (vars.isSubsetOrEqual(factor.first)) return factor.first;
378 }
379
380 return NodeSet();
381 }
382
383 template < GUM_Numeric GUM_SCALAR >
385 return [this,
387 joints = _joint_targets_]() {
389 marginal();
390 for (const auto& joint: joints)
391 addJointTarget(joint);
392 };
393 }
394
395} /* namespace gum */
restores the state of the inference engine (see stateRestorer_) when destroyed
virtual void chgEvidence(NodeId id, const Idx val) final
change the value of an already existing hard evidence
virtual bool isInferenceDone() const noexcept final
returns whether the inference object is in a InferenceDone state
virtual void setState_(const StateOfInference state) final
set the state of the inference engine and call the notification onStateChanged_ when necessary (i....
virtual bool hasHardEvidence(NodeId id) const final
indicates whether node id has received a hard evidence
virtual void eraseAllEvidence() final
removes all the evidence entered into the network
virtual void makeInference() final
perform the heavy computations needed to compute the targets' posteriors
virtual void addEvidence(NodeId id, const Idx val) final
adds a new hard evidence on node id
Virtual base class for probabilistic graphical models.
Class representing the minimal interface for Markov random field.
Class for assigning/browsing values to tuples of discrete variables.
bool end() const
Returns true if the Instantiation reached the end.
void inc()
Operator increment.
void incOut(const Instantiation &i)
Operator increment for the variables not in i.
void setFirstIn(const Instantiation &i)
Assign the first values in the Instantiation for the variables in i.
void add(const DiscreteVariable &v) final
Adds a new variable in the Instantiation.
void incIn(const Instantiation &i)
Operator increment for the variables in i.
Idx val(Idx i) const
Returns the current value of the variable at position i.
void setFirst()
Assign the first values to the tuple of the Instantiation.
void setFirstOut(const Instantiation &i)
Assign the first values in the Instantiation for the variables not in i.
const DiscreteVariable & variable(Idx i) const final
Returns the variable at position i in the tuple.
Idx nbrDim() const final
Returns the number of variables in the Instantiation.
Exception: at least one argument passed to a function is not what was expected.
virtual void eraseJointTarget(const NodeSet &joint_target) final
removes an existing joint target
GUM_SCALAR jointMutualInformation(const NodeSet &targets)
Mutual information between targets.
virtual const Set< NodeSet > & jointTargets() const noexcept final
returns the list of joint targets
virtual Size nbrJointTargets() const noexcept final
returns the number of joint targets
std::function< void() > stateRestorer_() override
returns a function restoring the current marginal and joint targets and evidence
Set< NodeSet > _joint_targets_
the set of joint targets
void eraseAllTargets() final
Clear all previously defined targets (marginal and joint targets).
virtual const Tensor< GUM_SCALAR > & jointPosterior(const NodeSet &nodes) final
Compute the joint posterior of a set of nodes.
virtual void addJointTarget(const NodeSet &joint_target) final
Add a set of nodes as a new joint target. As a collateral effect, every node is added as a marginal t...
virtual void onJointTargetErased_(const NodeSet &set)=0
fired before a joint target is removed
virtual void eraseAllJointTargets() final
Clear all previously defined joint targets.
const Tensor< GUM_SCALAR > & posterior(NodeId node) final
Computes and returns the posterior of a node.
virtual const Tensor< GUM_SCALAR > & jointPosterior_(const NodeSet &set)=0
asks derived classes for the joint posterior of a declared target set
virtual void onAllJointTargetsErased_()=0
fired before a all the joint targets are removed
virtual void onJointTargetAdded_(const NodeSet &set)=0
fired after a new joint target is inserted
virtual bool isExactJointComputable_(const NodeSet &vars)
check if the vars form a possible computable joint (can be redefined by subclass)
Tensor< GUM_SCALAR > evidenceJointImpact(const NodeSet &targets, const NodeSet &evs)
Create a gum::Tensor for P(joint targets|evs) (for all instantiation of targets and evs).
JointTargetedMRFInference(const IMarkovRandomField< GUM_SCALAR > *mn)
default constructor
virtual NodeSet superForJointComputable_(const NodeSet &vars)
virtual void eraseAllMarginalTargets() final
Clear all the previously defined marginal targets.
virtual bool isJointTarget(const NodeSet &vars) const final
return true if target is a joint target.
void onModelChanged_(const GraphicalModel *mn) override
fired after a new Markov net has been assigned to the engine
void _setMRFDuringConstruction_(const IMarkovRandomField< GUM_SCALAR > *mn)
assigns a MRF during the inference engine construction
virtual const IMarkovRandomField< GUM_SCALAR > & MRF() const final
Returns a constant reference over the IMarkovRandomField referenced by this class.
virtual const NodeSet & targets() const noexcept final
returns the list of marginal targets
void onModelChanged_(const GraphicalModel *mn) override
fired after a new Markov net has been assigned to the engine
virtual void eraseAllTargets()
Clear all previously defined targets.
MarginalTargetedMRFInference(const IMarkovRandomField< GUM_SCALAR > *mn)
default constructor
std::function< void() > stateRestorer_() override
returns a function restoring the current marginal targets and evidence
virtual bool isTarget(NodeId node) const final
return true if variable is a (marginal) target
virtual const Tensor< GUM_SCALAR > & posterior(NodeId node)
Computes and returns the posterior of a node.
Exception : a pointer or a reference on a nullptr (0) object.
Defines a discrete random variable over an integer interval.
Representation of a set.
Definition set.h:129
bool isSubsetOrEqual(const Set< Key > &s) const
Definition set_tpl.h:488
void clear()
Removes all the elements, if any, from the set.
Definition set_tpl.h:315
bool empty() const noexcept
Indicates whether the set is the empty set.
Definition set_tpl.h:613
void insert(const Key &k)
Inserts a new element into the set.
Definition set_tpl.h:510
Size size() const noexcept
Returns the number of elements in the set.
Definition set_tpl.h:607
Exception : a looked-for element could not be found.
#define GUM_ERROR(type, msg)
Definition exceptions.h:76
std::size_t Size
In aGrUM, hashed values are unsigned long int.
Definition types.h:74
Size Idx
Type for indexes.
Definition types.h:79
Size NodeId
Type for node ids.
Set< NodeId > NodeSet
Some typdefs and define for shortcuts ...
Class encapsulating computations of notions from Information Theory.
This file contains the abstract inference class definition for computing (incrementally) joint poster...
gum is the global namespace for all aGrUM entities
Definition agrum.h:46
Set< const DiscreteVariable * > VariableSet
Header of gumRangeVariable.