aGrUM 3.3.2
a C++ library for (probabilistic) graphical models
approximationScheme.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
54#ifndef GUM_APPROXIMATION_SCHEME_H
55#define GUM_APPROXIMATION_SCHEME_H
56
57#include <agrum/agrum.h>
58
60
61namespace gum {
62
116 * }
117 * }
118 * // equivalent to
119 * if (verbosity()) {
120 * GUM_TRACE(messageApproximationScheme());
121 * }
122 * @endcode
123 */
124 class GUM_SHARED_PUBLIC ApproximationScheme: public IApproximationSchemeConfiguration {
125 public:
126 // ========================================================================
128 // ========================================================================
130
139
144 explicit ApproximationScheme(bool verbosity);
145
146 ~ApproximationScheme() override;
147
149 // ========================================================================
151 // ========================================================================
153
163 void setEpsilon(double eps) override;
164
169 double epsilon() const override;
170
174 void disableEpsilon() override;
175
179 void enableEpsilon() override;
180
187 bool isEnabledEpsilon() const override;
188
198 void setMinEpsilonRate(double rate) override;
199
204 double minEpsilonRate() const override;
205
209 void disableMinEpsilonRate() override;
210
214 void enableMinEpsilonRate() override;
215
222 bool isEnabledMinEpsilonRate() const override;
223
232 void setMaxIter(Size max) override;
233
238 Size maxIter() const override;
239
243 void disableMaxIter() override;
244
248 void enableMaxIter() override;
249
256 bool isEnabledMaxIter() const override;
257
266 void setMaxTime(double timeout) override;
267
272 double maxTime() const override;
273
278 double currentTime() const override;
279
284 void disableMaxTime() override;
285
289 void enableMaxTime() override;
290
297 bool isEnabledMaxTime() const override;
298
304 void setPeriodSize(Size p) override;
305
310 Size periodSize() const override;
311
316 void setVerbosity(bool v) override;
317
322 bool verbosity() const override;
323
329
335 Size nbrIterations() const override;
336
343 const std::vector< double >& history() const override;
344
349
356 bool startOfPeriod() const;
357
362 void updateApproximationScheme(unsigned int incr = 1);
363
368 Size remainingBurnIn() const;
369
374
385 bool continueApproximationScheme(double error);
386
387
389
390 private:
396
397 protected:
413 void setFromConfiguration_(const std::string& section,
414 bool withMaxTime,
415 bool withVerbosity = true);
416
424 static Size sizeFromConfiguration_(const std::string& section, const std::string& key);
427 double current_epsilon_{-1.};
430 double last_epsilon_{-1.};
433 double current_rate_{-1.};
445 std::vector< double > history_;
448 double eps_;
451 bool enabled_eps_;
454 double min_rate_eps_;
460 double max_time_;
473
476
478 bool verbosity_;
479 };
480} // namespace gum
481
482#ifndef GUM_NO_INLINE
484#endif
485
486#endif // GUM_APPROXIMATION_SCHEME_H
This file contains getters and setters definition for ApproximationScheme settings.
Inline implementatioh of gum::ApproximationSettings.
ApproximationScheme()
Build a scheme whose parameters are read from the configuration.
Size remainingBurnIn() const
Returns the remaining burn in.
void updateApproximationScheme(unsigned int incr=1)
Update the scheme w.r.t the new error and increment steps.
Size current_step_
The current step.
double current_epsilon_
Current epsilon.
bool isEnabledEpsilon() const override
Returns true if stopping criterion on epsilon is enabled, false otherwise.
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 enableMaxIter() override
Enable stopping criterion on max iterations.
double minEpsilonRate() const override
Returns the value of the minimal epsilon rate.
void setMinEpsilonRate(double rate) override
Given that we approximate f(t), stopping criterion on d/dt(|f(t+1)-f(t)|).
void disableEpsilon() override
Disable stopping criterion on epsilon.
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.
double epsilon() const override
Returns the value of epsilon.
void setPeriodSize(Size p) override
How many samples between two stopping is enable.
bool isEnabledMaxTime() const override
Returns true if stopping criterion on timeout is enabled, false otherwise.
std::vector< double > history_
The scheme history, used only if verbosity == true.
double current_rate_
Current rate.
ApproximationSchemeSTATE stateApproximationScheme() const override
Returns the approximation scheme state.
void enableEpsilon() override
Enable stopping criterion on epsilon.
Size period_size_
Checking criteria frequency.
double currentTime() const override
Returns the current running time in second.
bool isEnabledMinEpsilonRate() const override
Returns true if stopping criterion on epsilon rate is enabled, false otherwise.
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.
double maxTime() const override
Returns the timeout (in seconds).
void disableMinEpsilonRate() override
Disable stopping criterion on epsilon rate.
Size periodSize() const override
Returns the period size.
void enableMaxTime() override
Enable stopping criterion on timeout.
bool continueApproximationScheme(double error)
Update the scheme w.r.t the new error.
void initApproximationScheme()
Initialise the scheme.
Size nbrIterations() const override
Returns the number of iterations.
const std::vector< double > & history() const override
Returns the scheme history.
void stopScheme_(ApproximationSchemeSTATE new_state)
Stop the scheme given a new state.
Size maxIter() const override
Returns the criterion on number of iterations.
bool verbosity_
If true, verbosity is enabled.
void stopApproximationScheme()
Stop the approximation scheme.
void enableMinEpsilonRate() override
Enable stopping criterion on epsilon rate.
bool verbosity() const override
Returns true if verbosity is enabled.
bool isEnabledMaxIter() const override
Returns true if stopping criterion on max iterations is enabled, false otherwise.
void disableMaxIter() override
Disable stopping criterion on max iterations.
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)|.
ApproximationSchemeSTATE
The different state of an approximation scheme.
Class used to compute response times for benchmark purposes.
Definition timer.h:69
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