aGrUM 3.3.2
a C++ library for (probabilistic) graphical models
approximationScheme.cpp
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
53
54#include <cstdint>
55
58
59namespace gum {
60
62 ApproximationScheme(Configuration::instance().typed< bool >("approximation", "verbosity")) {}
63
67 max_iter_(static_cast< Size >(1)), enabled_max_iter_(true), burn_in_(static_cast< Size >(0)),
68 period_size_(static_cast< Size >(1)), verbosity_(verbosity) {
69 // the verbosity is the argument, the other parameters come from the configuration
70 setFromConfiguration_("approximation", true, false);
71 // the timeout is read (and checked) but stays disabled until the user asks for it
73
74 // after the reading of the configuration, which may throw: the destructor is not called if the
75 // constructor throws, so that GUM_CONSTRUCTOR would unbalance the counters of the debug mode
76 GUM_CONSTRUCTOR(ApproximationScheme);
77 }
78
80 const std::string& key) {
81 const auto value = Configuration::instance().typed< std::int64_t >(section, key);
82 if (value < 0) {
84 "The key " << section << "." << key
85 << " of the configuration must not be negative.")
86 }
87 return static_cast< Size >(value);
88 }
89
90 void ApproximationScheme::setFromConfiguration_(const std::string& section,
91 bool withMaxTime,
92 bool withVerbosity) {
93 const auto& conf = Configuration::instance();
94
95 setEpsilon(conf.typed< double >(section, "epsilon"));
96 setMinEpsilonRate(conf.typed< double >(section, "minEpsilonRate"));
97 setMaxIter(sizeFromConfiguration_(section, "maxIter"));
98 setPeriodSize(sizeFromConfiguration_(section, "periodSize"));
99 if (withVerbosity) setVerbosity(conf.typed< bool >(section, "verbosity"));
100 if (withMaxTime) setMaxTime(conf.typed< double >(section, "maxTime"));
101 // only some sections have a burn-in (approximation, gibbs, gibbsKL)
102 if (conf.has(section, "burnIn")) burn_in_ = sizeFromConfiguration_(section, "burnIn");
103 }
104
106
108 // For coherence, we fix the time used in the method
109
110 double timer_step = timer_.step();
111
112 if (enabled_max_time_) {
113 if (timer_step > max_time_) {
115 return false;
116 }
117 }
118
119 if (!startOfPeriod()) { return true; }
120
122 GUM_ERROR(
124 "state of the approximation scheme is not correct : " << messageApproximationScheme());
125 }
126
127 if (verbosity()) { history_.push_back(error); }
128
129 if (enabled_max_iter_) {
130 if (current_step_ >= max_iter_) {
132 return false;
133 }
134 }
135
137 current_epsilon_ = error; // eps rate isEnabled needs it so affectation was
138 // moved from eps isEnabled below
139
140 if (enabled_eps_) {
141 if (current_epsilon_ <= eps_) {
143 return false;
144 }
145 }
146
147 if (last_epsilon_ >= 0.) {
148 if (current_epsilon_ > .0) {
149 // ! current_epsilon_ can be 0. AND epsilon
150 // isEnabled can be disabled !
152 }
153 // limit with current eps ---> 0 is | 1 - ( last_eps / 0 ) | --->
154 // infinity the else means a return false if we isEnabled the rate below,
155 // as we would have returned false if epsilon isEnabled was enabled
156 else {
158 }
159
163 return false;
164 }
165 }
166 }
167
169 if (onProgress.hasListener()) {
171 }
172
173 return true;
174 } else {
175 return false;
176 }
177 }
178} // namespace gum
179
180#ifdef GUM_NO_INLINE
182#endif
This file contains general scheme for iteratively convergent algorithms.
Inline implementatioh of gum::ApproximationSettings.
ApproximationScheme()
Build a scheme whose parameters are read from the configuration.
Size current_step_
The current step.
double current_epsilon_
Current epsilon.
double last_epsilon_
Last epsilon value.
double eps_
Threshold for convergence.
static Size sizeFromConfiguration_(const std::string &section, const std::string &key)
Read a non negative integer key of gum::Configuration.
void setMaxIter(Size max) override
Stopping criterion on number of iterations.
void disableMaxTime() override
Disable stopping criterion on timeout.
void setMaxTime(double timeout) override
Stopping criterion on timeout.
void setMinEpsilonRate(double rate) override
Given that we approximate f(t), stopping criterion on d/dt(|f(t+1)-f(t)|).
void setFromConfiguration_(const std::string &section, bool withMaxTime, bool withVerbosity=true)
Set the parameters of the scheme from a section of gum::Configuration.
bool enabled_max_time_
If true, the timeout is enabled.
Size max_iter_
The maximum iterations.
bool enabled_eps_
If true, the threshold convergence is enabled.
ApproximationSchemeSTATE current_state_
The current state.
double min_rate_eps_
Threshold for the epsilon rate.
void setPeriodSize(Size p) override
How many samples between two stopping is enable.
std::vector< double > history_
The scheme history, used only if verbosity == true.
~ApproximationScheme() override
Build a scheme whose parameters are read from the configuration.
double current_rate_
Current rate.
ApproximationSchemeSTATE stateApproximationScheme() const override
Returns the approximation scheme state.
Size period_size_
Checking criteria frequency.
bool startOfPeriod() const
Returns true if we are at the beginning of a period (compute error is mandatory).
bool enabled_max_iter_
If true, the maximum iterations stopping criterion is enabled.
bool continueApproximationScheme(double error)
Update the scheme w.r.t the new error.
void stopScheme_(ApproximationSchemeSTATE new_state)
Stop the scheme given a new state.
bool verbosity_
If true, verbosity is enabled.
bool verbosity() const override
Returns true if verbosity is enabled.
Size burn_in_
Number of iterations before checking stopping criteria.
void setVerbosity(bool v) override
Set the verbosity on (true) or off (false).
bool enabled_min_rate_eps_
If true, the minimal threshold for epsilon rate is enabled.
void setEpsilon(double eps) override
Given that we approximate f(t), stopping criterion on |f(t+1)-f(t)|.
Sectioned key/value configuration with typed and documented keys.
static Configuration & instance()
The global configuration.
T typed(std::string_view section, std::string_view key) const
Value of section.key converted according to its declared type.
Signaler< Size, double, double > onProgress
Progression, error and time.
ApproximationSchemeSTATE
The different state of an approximation scheme.
std::string messageApproximationScheme() const
Returns the approximation scheme message.
Exception : operation not allowed.
Exception : out of bound.
double step() const
Returns the delta time between now and the last reset() call (or the constructor).
Definition timer_inl.h:72
Typed, documented, sectioned configuration singleton read from an .ini content.
#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
gum is the global namespace for all aGrUM entities
Definition agrum.h:46
#define GUM_EMIT3(signal, arg1, arg2, arg3)
Definition signaler.h:291