aGrUM 3.3.2
a C++ library for (probabilistic) graphical models
graphicalModelInference.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
49#ifndef GUM_GRAPHICALMODELINFERENCE_H
50#define GUM_GRAPHICALMODELINFERENCE_H
51
52
53#include <exception>
54#include <functional>
55
56#include <agrum/agrum.h>
57
60
61namespace gum {
62
106
107 template < GUM_Numeric GUM_SCALAR >
109 public:
130 enum class StateOfInference { OutdatedStructure, OutdatedTensors, ReadyForInference, Done };
131
132
133 // ############################################################################
135 // ############################################################################
137
139
142
144
152
154 virtual ~GraphicalModelInference();
155
157
158
159 // ############################################################################
161 // ############################################################################
163
165
167 virtual const GraphicalModel& model() const final;
168
170 virtual const NodeProperty< Size >& domainSizes() const final;
171
173 virtual bool isInferenceReady() const noexcept final;
175 virtual bool isInferenceOutdatedStructure() const noexcept final;
177 virtual bool isInferenceOutdatedTensors() const noexcept final;
179
184 virtual bool isInferenceDone() const noexcept final;
185
186
188 virtual void prepareInference() final;
189
191
196 virtual void makeInference() final;
197
199 virtual void clear();
200
202 virtual StateOfInference state() const noexcept final;
204
205
206 // ############################################################################
208 // ############################################################################
210
212
217 virtual void addEvidence(NodeId id, const Idx val) final;
218
220
225 virtual void addEvidence(std::string_view nodeName, const Idx val) final;
226
228
233 virtual void addEvidence(NodeId id, std::string_view label) final;
234
236
241 virtual void addEvidence(std::string_view nodeName, std::string_view label) final;
242
244
251 virtual void addEvidence(NodeId id, const std::vector< GUM_SCALAR >& vals) final;
252
254
261 virtual void addEvidence(std::string_view nodeName,
262 const std::vector< GUM_SCALAR >& vals) final;
263
265
273 virtual void addEvidence(const Tensor< GUM_SCALAR >& pot) final;
274
276
284 virtual void addEvidence(Tensor< GUM_SCALAR >&& pot) final;
285
287
295 virtual void addSetOfEvidence(const Set< const Tensor< GUM_SCALAR >* >& potset) final;
296
298
306 virtual void addListOfEvidence(const List< const Tensor< GUM_SCALAR >* >& potlist) final;
307
309
314 virtual void chgEvidence(NodeId id, const Idx val) final;
315
317
322 virtual void chgEvidence(std::string_view nodeName, const Idx val) final;
323
325
330 virtual void chgEvidence(NodeId id, std::string_view label) final;
331
333
338 virtual void chgEvidence(std::string_view nodeName, std::string_view label) final;
339
341
348 virtual void chgEvidence(NodeId id, const std::vector< GUM_SCALAR >& vals) final;
349
351
358 virtual void chgEvidence(std::string_view nodeName,
359 const std::vector< GUM_SCALAR >& vals) final;
360
362
370 virtual void chgEvidence(const Tensor< GUM_SCALAR >& pot) final;
371
373 virtual void eraseAllEvidence() final;
374
376 virtual void eraseEvidence(NodeId id) final;
377
379 virtual void eraseEvidence(std::string_view nodeName) final;
380
382 virtual bool hasEvidence() const final;
383
385 virtual bool hasEvidence(NodeId id) const final;
386
388 virtual bool hasHardEvidence(NodeId id) const final;
389
391 virtual bool hasSoftEvidence(NodeId id) const final;
393
394 virtual bool hasEvidence(std::string_view nodeName) const final;
395
397 virtual bool hasHardEvidence(std::string_view nodeName) const final;
398
400 virtual bool hasSoftEvidence(std::string_view nodeName) const final;
401
403 virtual Size nbrEvidence() const final;
404
406 virtual Size nbrHardEvidence() const final;
407
409 virtual Size nbrSoftEvidence() const final;
410
412 const NodeProperty< const Tensor< GUM_SCALAR >* >& evidence() const;
413
415 const NodeSet& softEvidenceNodes() const;
416
418 const NodeSet& hardEvidenceNodes() const;
419
421 const NodeProperty< Idx >& hardEvidence() const;
422
424
425
426 protected:
432 virtual std::function< void() > stateRestorer_();
433
435
442 public:
444 ~StateGuard_() noexcept(false);
445
446 StateGuard_(const StateGuard_&) = delete;
448
449 private:
450 std::function< void() > _restore_;
451
454 };
455
457 virtual void onStateChanged_() = 0;
458
460 virtual void onEvidenceAdded_(const NodeId id, bool isHardEvidence) = 0;
461
463 virtual void onEvidenceErased_(const NodeId id, bool isHardEvidence) = 0;
464
466 virtual void onAllEvidenceErased_(bool contains_hard_evidence) = 0;
467
476 virtual void onEvidenceChanged_(const NodeId id, bool hasChangedSoftHard) = 0;
477
479 virtual void onModelChanged_(const GraphicalModel* model) = 0;
480
482
485 virtual void updateOutdatedStructure_() = 0;
486
488
491 virtual void updateOutdatedTensors_() = 0;
492
494
495 virtual void makeInference_() = 0;
496
498
518
529
530
531 private:
534
536 const GraphicalModel* _model_{nullptr};
537
540
543
546
549
552
553
555 Tensor< GUM_SCALAR > _createHardEvidence_(NodeId id, Idx val) const;
556
558 bool _isHardEvidence_(const Tensor< GUM_SCALAR >& pot, Idx& val) const;
559
562
563 protected:
567 virtual void setState_(const StateOfInference state) final;
568
569 void setModel_(const GraphicalModel* model);
570
573
574 bool hasNoModel_() const;
575 };
576} // namespace gum
577
579
580
581#endif // GUM_GRAPHICALMODELINFERENCE_H
StateGuard_(const StateGuard_ &)=delete
StateGuard_ & operator=(const StateGuard_ &)=delete
StateGuard_(GraphicalModelInference< GUM_SCALAR > &inference)
int _uncaught_exceptions_
number of uncaught exceptions when the guard was created
<agrum/base/graphicalModels/graphicalModel.h>
GraphicalModelInference()
default constructor with a null model (useful for virtual inheritance)
virtual void prepareInference() final
prepare the internal inference structures for the next inference
void _computeDomainSizes_()
computes the domain sizes of the random variables
const NodeSet & softEvidenceNodes() const
returns the set of nodes with soft evidence
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 onAllEvidenceErased_(bool contains_hard_evidence)=0
fired before all the evidence are erased
virtual void onStateChanged_()=0
fired when the stage is changed
const NodeProperty< const Tensor< GUM_SCALAR > * > & evidence() const
returns the set of evidence
virtual StateOfInference state() const noexcept final
returns the state of the inference engine
virtual void onEvidenceChanged_(const NodeId id, bool hasChangedSoftHard)=0
fired after an evidence is changed, in particular when its status (soft/hard) changes
virtual bool isInferenceReady() const noexcept final
returns whether the inference object is in a ready state
virtual bool hasEvidence() const final
indicates whether some node(s) have received evidence
GraphicalModelInference(const GraphicalModel *model)
default constructor
virtual void setState_(const StateOfInference state) final
set the state of the inference engine and call the notification onStateChanged_ when necessary (i....
NodeProperty< const Tensor< GUM_SCALAR > * > _evidence_
the set of evidence entered into the network
virtual bool hasHardEvidence(NodeId id) const final
indicates whether node id has received a hard evidence
virtual void onModelChanged_(const GraphicalModel *model)=0
fired after a new Bayes net has been assigned to the engine
void setModel_(const GraphicalModel *model)
bool _isHardEvidence_(const Tensor< GUM_SCALAR > &pot, Idx &val) const
checks whether a tensor corresponds to a hard evidence or not
NodeSet _soft_evidence_nodes_
the set of nodes that received soft evidence
StateOfInference _state_
the current state of the inference (outdated/ready/done)
NodeProperty< Size > _domain_sizes_
the domain sizes of the random variables
const NodeProperty< Idx > & hardEvidence() const
indicate for each node with hard evidence which value it took
virtual const NodeProperty< Size > & domainSizes() const final
get the domain sizes of the random variables of the model
virtual void eraseEvidence(NodeId id) final
removed the evidence, if any, corresponding to node id
void setModelDuringConstruction_(const GraphicalModel *model)
assigns a model during the inference engine construction
void setOutdatedTensorsState_()
puts the inference into an OutdatedTensors state if it is not already in an OutdatedStructure state
const NodeSet & hardEvidenceNodes() const
returns the set of nodes with hard evidence
virtual void updateOutdatedTensors_()=0
prepares inference when the latter is in OutdatedTensors state
virtual void onEvidenceAdded_(const NodeId id, bool isHardEvidence)=0
fired after a new evidence is inserted
virtual bool isInferenceOutdatedTensors() const noexcept final
returns whether the inference object is in a OutdatedTensor state
virtual bool hasSoftEvidence(NodeId id) const final
indicates whether node id has received a soft evidence
virtual void makeInference_()=0
called when the inference has to be performed effectively
virtual Size nbrEvidence() const final
returns the number of evidence entered into the Bayesian network
virtual Size nbrSoftEvidence() const final
returns the number of soft evidence entered into the Bayesian network
virtual void addListOfEvidence(const List< const Tensor< GUM_SCALAR > * > &potlist) final
adds a new list of evidence
virtual void updateOutdatedStructure_()=0
prepares inference when the latter is in OutdatedStructure state
virtual std::function< void() > stateRestorer_()
Returns a function restoring the current state of the inference engine.
virtual Size nbrHardEvidence() const final
returns the number of hard evidence entered into the Bayesian network
virtual void eraseAllEvidence() final
removes all the evidence entered into the network
StateOfInference
current state of the inference
Tensor< GUM_SCALAR > _createHardEvidence_(NodeId id, Idx val) const
create the internal structure for a hard evidence
void setOutdatedStructureState_()
put the inference into an outdated model structure state
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
NodeSet _hard_evidence_nodes_
the set of nodes that received hard evidence
const GraphicalModel * _model_
the Bayes net on which we perform inferences
NodeProperty< Idx > _hard_evidence_
assign to each node with a hard evidence the index of its observed value
virtual void addSetOfEvidence(const Set< const Tensor< GUM_SCALAR > * > &potset) final
adds a new set of evidence
virtual void clear()
clears all the data structures allocated for the last inference
virtual void onEvidenceErased_(const NodeId id, bool isHardEvidence)=0
fired before an evidence is removed
virtual bool isInferenceOutdatedStructure() const noexcept final
returns whether the inference object is in a OutdatedStructure state
virtual const GraphicalModel & model() const final
Returns a constant reference over the IBayesNet referenced by this class.
Virtual base class for probabilistic graphical models.
Generic doubly linked lists.
Definition list.h:378
Representation of a set.
Definition set.h:129
aGrUM's Tensor is a multi-dimensional array with tensor operators.
Definition tensor.h:85
Implementation of the non pure virtual methods of class GraphicalModelInference.
Class representing probabilistic DAG model.
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.
HashTable< NodeId, VAL > NodeProperty
Property on graph elements.
Set< NodeId > NodeSet
Some typdefs and define for shortcuts ...
gum is the global namespace for all aGrUM entities
Definition agrum.h:46
STL namespace.
Header of the Tensor class.