aGrUM  0.13.2
approximationScheme_inl.h
Go to the documentation of this file.
1 /***************************************************************************
2  * Copyright (C) 2005 by Pierre-Henri WUILLEMIN et Christophe GONZALES *
3  * {prenom.nom}_at_lip6.fr *
4  * *
5  * This program is free software; you can redistribute it and/or modify *
6  * it under the terms of the GNU General Public License as published by *
7  * the Free Software Foundation; either version 2 of the License, or *
8  * (at your option) any later version. *
9  * *
10  * This program is distributed in the hope that it will be useful, *
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of *
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
13  * GNU General Public License for more details. *
14  * *
15  * You should have received a copy of the GNU General Public License *
16  * along with this program; if not, write to the *
17  * Free Software Foundation, Inc., *
18  * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
19  ***************************************************************************/
20 
33 #include <agrum/agrum.h>
34 // To help IDE parser
36 
37 namespace gum {
38 
39  // Given that we approximate f(t), stopping criterion on |f(t+1)-f(t)| If
40  // the criterion was disabled it will be enabled
41  INLINE void ApproximationScheme::setEpsilon(double eps) {
42  if (eps < 0.) { GUM_ERROR(OutOfLowerBound, "eps should be >=0"); }
43 
44  _eps = eps;
45  _enabled_eps = true;
46  }
47 
48  // Get the value of epsilon
49  INLINE double ApproximationScheme::epsilon() const { return _eps; }
50 
51  // Disable stopping criterion on epsilon
53 
54  // Enable stopping criterion on epsilon
56 
57  // @return true if stopping criterion on epsilon is enabled, false
58  // otherwise
60  return _enabled_eps;
61  }
62 
63  // Given that we approximate f(t), stopping criterion on d/dt(|f(t+1)-f(t)|)
64  INLINE void ApproximationScheme::setMinEpsilonRate(double rate) {
65  if (rate < 0) { GUM_ERROR(OutOfLowerBound, "rate should be >=0"); }
66 
67  _min_rate_eps = rate;
68  _enabled_min_rate_eps = true;
69  }
70 
71  // Get the value of the minimal epsilon rate
72  INLINE double ApproximationScheme::minEpsilonRate() const {
73  return _min_rate_eps;
74  }
75 
76  // Disable stopping criterion on epsilon rate
78  _enabled_min_rate_eps = false;
79  }
80 
81  // Enable stopping criterion on epsilon rate
83  _enabled_min_rate_eps = true;
84  }
85 
86  // @return true if stopping criterion on epsilon rate is enabled, false
87  // otherwise
89  return _enabled_min_rate_eps;
90  }
91 
92  // stopping criterion on number of iterations
94  if (max < 1) { GUM_ERROR(OutOfLowerBound, "max should be >=1"); }
95  _max_iter = max;
96  _enabled_max_iter = true;
97  }
98 
99  // @return the criterion on number of iterations
100  INLINE Size ApproximationScheme::maxIter() const { return _max_iter; }
101 
102  // Disable stopping criterion on max iterations
104 
105  // Enable stopping criterion on max iterations
107 
108  // @return true if stopping criterion on max iterations is enabled, false
109  // otherwise
111  return _enabled_max_iter;
112  }
113 
114  // stopping criterion on timeout (in seconds)
115  // If the criterion was disabled it will be enabled
116  INLINE void ApproximationScheme::setMaxTime(double timeout) {
117  if (timeout <= 0.) { GUM_ERROR(OutOfLowerBound, "timeout should be >0."); }
118  _max_time = timeout;
119  _enabled_max_time = true;
120  }
121 
122  // returns the timeout (in seconds)
123  INLINE double ApproximationScheme::maxTime() const { return _max_time; }
124 
125  // get the current running time in second (double)
126  INLINE double ApproximationScheme::currentTime() const { return _timer.step(); }
127 
128  // Disable stopping criterion on timeout
130 
131  // Enable stopping criterion on timeout
133 
134  // @return true if stopping criterion on timeout is enabled, false
135  // otherwise
137  return _enabled_max_time;
138  }
139 
140  // how many samples between 2 stopping isEnableds
142  if (p < 1) { GUM_ERROR(OutOfLowerBound, "p should be >=1"); }
143 
144  _period_size = p;
145  }
146 
148 
149  // verbosity
150  INLINE void ApproximationScheme::setVerbosity(bool v) { _verbosity = v; }
151 
152  INLINE bool ApproximationScheme::verbosity() const { return _verbosity; }
153 
154  // history
157  return _current_state;
158  }
159 
160  // @throw OperationNotAllowed if scheme not performed
164  "state of the approximation scheme is undefined");
165  }
166 
167  return _current_step;
168  }
169 
170  // @throw OperationNotAllowed if scheme not performed or verbosity=false
171  INLINE const std::vector< double >& ApproximationScheme::history() const {
174  "state of the approximation scheme is udefined");
175  }
176 
177  if (verbosity() == false) {
178  GUM_ERROR(OperationNotAllowed, "No history when verbosity=false");
179  }
180 
181  return _history;
182  }
183 
184  // initialise the scheme
187  _current_step = 0;
189  _history.clear();
190  _timer.reset();
191  }
192 
193  // @return true if we are at the beginning of a period (compute error is
194  // mandatory)
196  if (_current_step < _burn_in) { return false; }
197 
198  if (_period_size == 1) { return true; }
199 
200  return ((_current_step - _burn_in) % _period_size == 0);
201  }
202 
203  // update the scheme w.r.t the new error and incr steps
204  INLINE void ApproximationScheme::updateApproximationScheme(unsigned int incr) {
205  _current_step += incr;
206  }
207 
209  if (_burn_in > _current_step) {
210  return _burn_in - _current_step;
211  } else {
212  return 0;
213  }
214  }
215 
216  // stop approximation scheme by user request.
220  }
221  }
222 
223  // update the scheme w.r.t the new error. Test the stopping criterions that
224  // are enabled
226  // For coherence, we fix the time used in the method
227 
228  double timer_step = _timer.step();
229 
230  if (_enabled_max_time) {
231  if (timer_step > _max_time) {
233  return false;
234  }
235  }
236 
237  if (!startOfPeriod()) { return true; }
238 
241  "state of the approximation scheme is not correct : "
243  }
244 
245  if (verbosity()) { _history.push_back(error); }
246 
247  if (_enabled_max_iter) {
248  if (_current_step > _max_iter) {
250  return false;
251  }
252  }
253 
255  _current_epsilon = error; // eps rate isEnabled needs it so affectation was
256  // moved from eps isEnabled below
257 
258  if (_enabled_eps) {
259  if (_current_epsilon <= _eps) {
261  return false;
262  }
263  }
264 
265  if (_last_epsilon >= 0.) {
266  if (_current_epsilon > .0) {
267  // ! _current_epsilon can be 0. AND epsilon
268  // isEnabled can be disabled !
269  _current_rate =
271  }
272  // limit with current eps ---> 0 is | 1 - ( last_eps / 0 ) | --->
273  // infinity the else means a return false if we isEnabled the rate below,
274  // as we would have returned false if epsilon isEnabled was enabled
275  else {
277  }
278 
279  if (_enabled_min_rate_eps) {
280  if (_current_rate <= _min_rate_eps) {
282  return false;
283  }
284  }
285  }
286 
288  if (onProgress.hasListener()) {
290  }
291 
292  return true;
293  } else {
294  return false;
295  }
296  }
297 
298  INLINE void
300  if (new_state == ApproximationSchemeSTATE::Continue) { return; }
301 
302  if (new_state == ApproximationSchemeSTATE::Undefined) { return; }
303 
304  _current_state = new_state;
305  _timer.pause();
306 
307  if (onStop.hasListener()) { GUM_EMIT1(onStop, messageApproximationScheme()); }
308  }
309 
310 } // namespace gum
unsigned long Size
In aGrUM, hashed values are unsigned long int.
Definition: types.h:50
ApproximationSchemeSTATE stateApproximationScheme() const
Returns the approximation scheme state.
bool isEnabledMinEpsilonRate() const
Returns true if stopping criterion on epsilon rate is enabled, false otherwise.
bool verbosity() const
Returns true if verbosity is enabled.
This file contains general scheme for iteratively convergent algorithms.
Signaler3< Size, double, double > onProgress
Progression, error and time.
void disableMinEpsilonRate()
Disable stopping criterion on epsilon rate.
bool _enabled_max_iter
If true, the maximum iterations stopping criterion is enabled.
std::string messageApproximationScheme() const
Returns the approximation scheme message.
bool _enabled_eps
If true, the threshold convergence is enabled.
double minEpsilonRate() const
Returns the value of the minimal epsilon rate.
#define GUM_EMIT1(signal, arg1)
Definition: signaler1.h:40
void enableMinEpsilonRate()
Enable stopping criterion on epsilon rate.
double currentTime() const
Returns the current running time in second.
void _stopScheme(ApproximationSchemeSTATE new_state)
Stop the scheme given a new state.
void setPeriodSize(Size p)
How many samples between two stopping is enable.
Size remainingBurnIn()
Returns the remaining burn in.
double _current_epsilon
Current epsilon.
bool _enabled_min_rate_eps
If true, the minimal threshold for epsilon rate is enabled.
bool isEnabledMaxTime() const
Returns true if stopping criterion on timeout is enabled, false otherwise.
bool startOfPeriod()
Returns true if we are at the beginning of a period (compute error is mandatory). ...
void initApproximationScheme()
Initialise the scheme.
gum is the global namespace for all aGrUM entities
Definition: agrum.h:25
void setMinEpsilonRate(double rate)
Given that we approximate f(t), stopping criterion on d/dt(|f(t+1)-f(t)|).
const std::vector< double > & history() const
Returns the scheme history.
void setVerbosity(bool v)
Set the verbosity on (true) or off (false).
void setMaxTime(double timeout)
Stopping criterion on timeout.
Size _burn_in
Number of iterations before checking stopping criteria.
void disableEpsilon()
Disable stopping criterion on epsilon.
double _eps
Threshold for convergence.
double step() const
Returns the delta time between now and the last reset() call (or the constructor).
Definition: timer_inl.h:39
void reset()
Reset the timer.
Definition: timer_inl.h:29
double _current_rate
Current rate.
double pause()
Pause the timer and return the delta (.
Definition: timer_inl.h:50
bool continueApproximationScheme(double error)
Update the scheme w.r.t the new error.
double maxTime() const
Returns the timeout (in seconds).
Signaler1< std::string > onStop
Criteria messageApproximationScheme.
bool _enabled_max_time
If true, the timeout is enabled.
void disableMaxTime()
Disable stopping criterion on timeout.
void enableMaxIter()
Enable stopping criterion on max iterations.
Size periodSize() const
Returns the period size.
void stopApproximationScheme()
Stop the approximation scheme.
Size _current_step
The current step.
std::vector< double > _history
The scheme history, used only if verbosity == true.
Size _period_size
Checking criteria frequency.
bool isEnabledEpsilon() const
Returns true if stopping criterion on epsilon is enabled, false otherwise.
double _min_rate_eps
Threshold for the epsilon rate.
bool isEnabledMaxIter() const
Returns true if stopping criterion on max iterations is enabled, false otherwise. ...
double epsilon() const
Returns the value of epsilon.
void setMaxIter(Size max)
Stopping criterion on number of iterations.
bool _verbosity
If true, verbosity is enabled.
double _last_epsilon
Last epsilon value.
void setEpsilon(double eps)
Given that we approximate f(t), stopping criterion on |f(t+1)-f(t)|.
void disableMaxIter()
Disable stopping criterion on max iterations.
Size maxIter() const
Returns the criterion on number of iterations.
ApproximationSchemeSTATE
The different state of an approximation scheme.
Size nbrIterations() const
Returns the number of iterations.
Size _max_iter
The maximum iterations.
#define GUM_EMIT3(signal, arg1, arg2, arg3)
Definition: signaler3.h:40
ApproximationSchemeSTATE _current_state
The current state.
double _max_time
The timeout.
void enableMaxTime()
Enable stopping criterion on timeout.
#define GUM_ERROR(type, msg)
Definition: exceptions.h:66
void updateApproximationScheme(unsigned int incr=1)
Update the scheme w.r.t the new error and increment steps.
void enableEpsilon()
Enable stopping criterion on epsilon.