Approximation Scheme. More...

#include <approximationScheme.h>

Inheritance diagram for gum::ApproximationScheme:

Collaboration diagram for gum::ApproximationScheme:

Public Attributes
Signaler3< Size, double, double >	onProgress
	Progression, error and time. More...

Signaler1< std::string >	onStop
	Criteria messageApproximationScheme. More...

Public Member Functions
Constructors and Destructors
	ApproximationScheme (bool verbosity=false)

virtual	~ApproximationScheme ()

Getters and setters
void	setEpsilon (double eps)
	Given that we approximate f(t), stopping criterion on \|f(t+1)-f(t)\|. More...

double	epsilon () const
	Returns the value of epsilon. More...

void	disableEpsilon ()
	Disable stopping criterion on epsilon. More...

void	enableEpsilon ()
	Enable stopping criterion on epsilon. More...

bool	isEnabledEpsilon () const
	Returns true if stopping criterion on epsilon is enabled, false otherwise. More...

void	setMinEpsilonRate (double rate)
	Given that we approximate f(t), stopping criterion on d/dt(\|f(t+1)-f(t)\|). More...

double	minEpsilonRate () const
	Returns the value of the minimal epsilon rate. More...

void	disableMinEpsilonRate ()
	Disable stopping criterion on epsilon rate. More...

void	enableMinEpsilonRate ()
	Enable stopping criterion on epsilon rate. More...

bool	isEnabledMinEpsilonRate () const
	Returns true if stopping criterion on epsilon rate is enabled, false otherwise. More...

void	setMaxIter (Size max)
	Stopping criterion on number of iterations. More...

Size	maxIter () const
	Returns the criterion on number of iterations. More...

void	disableMaxIter ()
	Disable stopping criterion on max iterations. More...

void	enableMaxIter ()
	Enable stopping criterion on max iterations. More...

bool	isEnabledMaxIter () const
	Returns true if stopping criterion on max iterations is enabled, false otherwise. More...

void	setMaxTime (double timeout)
	Stopping criterion on timeout. More...

double	maxTime () const
	Returns the timeout (in seconds). More...

double	currentTime () const
	Returns the current running time in second. More...

void	disableMaxTime ()
	Disable stopping criterion on timeout. More...

void	enableMaxTime ()
	Enable stopping criterion on timeout. More...

bool	isEnabledMaxTime () const
	Returns true if stopping criterion on timeout is enabled, false otherwise. More...

void	setPeriodSize (Size p)
	How many samples between two stopping is enable. More...

Size	periodSize () const
	Returns the period size. More...

void	setVerbosity (bool v)
	Set the verbosity on (true) or off (false). More...

bool	verbosity () const
	Returns true if verbosity is enabled. More...

ApproximationSchemeSTATE	stateApproximationScheme () const
	Returns the approximation scheme state. More...

Size	nbrIterations () const
	Returns the number of iterations. More...

const std::vector< double > &	history () const
	Returns the scheme history. More...

void	initApproximationScheme ()
	Initialise the scheme. More...

bool	startOfPeriod ()
	Returns true if we are at the beginning of a period (compute error is mandatory). More...

void	updateApproximationScheme (unsigned int incr=1)
	Update the scheme w.r.t the new error and increment steps. More...

Size	remainingBurnIn ()
	Returns the remaining burn in. More...

void	stopApproximationScheme ()
	Stop the approximation scheme. More...

bool	continueApproximationScheme (double error)
	Update the scheme w.r.t the new error. More...

Getters and setters
std::string	messageApproximationScheme () const
	Returns the approximation scheme message. More...

Public Types
enum	ApproximationSchemeSTATE : char { ApproximationSchemeSTATE::Undefined, ApproximationSchemeSTATE::Continue, ApproximationSchemeSTATE::Epsilon, ApproximationSchemeSTATE::Rate, ApproximationSchemeSTATE::Limit, ApproximationSchemeSTATE::TimeLimit, ApproximationSchemeSTATE::Stopped }
	The different state of an approximation scheme. More...

Protected Attributes
double	_current_epsilon
	Current epsilon. More...

double	_last_epsilon
	Last epsilon value. More...

double	_current_rate
	Current rate. More...

Size	_current_step
	The current step. More...

Timer	_timer
	The timer. More...

ApproximationSchemeSTATE	_current_state
	The current state. More...

std::vector< double >	_history
	The scheme history, used only if verbosity == true. More...

double	_eps
	Threshold for convergence. More...

bool	_enabled_eps
	If true, the threshold convergence is enabled. More...

double	_min_rate_eps
	Threshold for the epsilon rate. More...

bool	_enabled_min_rate_eps
	If true, the minimal threshold for epsilon rate is enabled. More...

double	_max_time
	The timeout. More...

bool	_enabled_max_time
	If true, the timeout is enabled. More...

Size	_max_iter
	The maximum iterations. More...

bool	_enabled_max_iter
	If true, the maximum iterations stopping criterion is enabled. More...

Size	_burn_in
	Number of iterations before checking stopping criteria. More...

Size	_period_size
	Checking criteria frequency. More...

bool	_verbosity
	If true, verbosity is enabled. More...

Detailed Description

Approximation Scheme.

Warning: Doxygen does not like spanning command on multiple line, so we could not configure it with the correct include directive. Use the following code snippet to include this file.
#include <agrum/core/approximations/approximationScheme.h>

The approximation scheme is assumed to be used like this:

initApproximationScheme();
// this loop can stop with ApproximationSchemeSTATE::Epsilon,
// ApproximationSchemeSTATE::Rate and ApproximationSchemeSTATE::Limit
do {
// compute new values and a GUM_SCALAR error representing the progress
// in this step.
  updateApproximationScheme();
  // compute state of the approximation
  if (startOfPeriod()) {
     // w.r.t to the state of approximation compute epsilon
  }
} while ( continueApproximationScheme( epsilon ));
// end of loop
if ( verbosity() ) {
  switch ( stateApproximationScheme() ) {
    case ApproximationSchemeSTATE::Continue:  // should not be possible
      break;
    case ApproximationSchemeSTATE::Epsilon: {
        GUM_TRACE( "stop with
            epsilon="<<epsilon() );
        break;
    }
    case ApproximationSchemeSTATE::Rate: {
        GUM_TRACE( "stop with
            rate="<<minEpsilonRate() );
        break;
    }
    case ApproximationSchemeSTATE::Limit: {
        GUM_TRACE( "stop with max
            iteration="<<maxIter() );
        break;
    }
    case ApproximationSchemeSTATE::TimeLimit: {
        GUM_TRACE( "stop with
            timemout="<<currentTime() );
        break;
    }
  }
}
// equivalent to
if (verbosity()) {
  GUM_TRACE(messageApproximationScheme());
}

Definition at line 107 of file approximationScheme.h.

Member Enumeration Documentation

◆ ApproximationSchemeSTATE

enum gum::IApproximationSchemeConfiguration::ApproximationSchemeSTATE : char

stronginherited

The different state of an approximation scheme.

Enumerator
Undefined
Continue
Epsilon
Rate
Limit
TimeLimit
Stopped

Definition at line 65 of file IApproximationSchemeConfiguration.h.

                                         : char {
       Undefined,
       Continue,
       Epsilon,
       Rate,
       Limit,
       TimeLimit,
       Stopped
     };

Constructor & Destructor Documentation

◆ ApproximationScheme()

gum::ApproximationScheme::ApproximationScheme ( bool verbosity = false )

Definition at line 39 of file approximationScheme.cpp.

Referenced by gum::learning::DAG2BNLearner< ALLOC >::DAG2BNLearner().

                                                          :
       _current_state(ApproximationSchemeSTATE::Undefined), _eps(5e-2),
       _enabled_eps(true), _min_rate_eps(1e-2), _enabled_min_rate_eps(true),
       _max_time(1.), _enabled_max_time(false), _max_iter((Size)10000),
       _enabled_max_iter(true), _burn_in((Size)0), _period_size((Size)1),
       _verbosity(verbosity) {
     GUM_CONSTRUCTOR(ApproximationScheme);
   }

Here is the caller graph for this function:

◆ ~ApproximationScheme()

gum::ApproximationScheme::~ApproximationScheme ( )

virtual

Definition at line 48 of file approximationScheme.cpp.

                                             {
     GUM_DESTRUCTOR(ApproximationScheme);
   }

Member Function Documentation

◆ _stopScheme()

INLINE void gum::ApproximationScheme::_stopScheme ( ApproximationSchemeSTATE new_state )

private

Stop the scheme given a new state.

Parameters

new_state The scheme new state.

Definition at line 301 of file approximationScheme_inl.h.

References _current_state, _timer, gum::IApproximationSchemeConfiguration::Continue, GUM_EMIT1, gum::IApproximationSchemeConfiguration::messageApproximationScheme(), gum::IApproximationSchemeConfiguration::onStop, gum::Timer::pause(), and gum::IApproximationSchemeConfiguration::Undefined.

Referenced by continueApproximationScheme(), and stopApproximationScheme().

                                                                         {
     if (new_state == ApproximationSchemeSTATE::Continue) { return; }
 
     if (new_state == ApproximationSchemeSTATE::Undefined) { return; }
 
     _current_state = new_state;
     _timer.pause();
 
     if (onStop.hasListener()) { GUM_EMIT1(onStop, messageApproximationScheme()); }
   }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ continueApproximationScheme()

INLINE bool gum::ApproximationScheme::continueApproximationScheme ( double error )

Update the scheme w.r.t the new error.

Test the stopping criterion that are enabled.

Parameters

error The new error value.

Returns: false if state become != ApproximationSchemeSTATE::Continue

Exceptions

OperationNotAllowed Raised if state != ApproximationSchemeSTATE::Continue.

Definition at line 227 of file approximationScheme_inl.h.

References _current_epsilon, _current_rate, _current_state, _current_step, _enabled_eps, _enabled_max_iter, _enabled_max_time, _enabled_min_rate_eps, _eps, _history, _last_epsilon, _max_iter, _max_time, _min_rate_eps, _stopScheme(), _timer, gum::IApproximationSchemeConfiguration::Continue, gum::IApproximationSchemeConfiguration::Epsilon, GUM_EMIT3, GUM_ERROR, gum::IApproximationSchemeConfiguration::Limit, gum::IApproximationSchemeConfiguration::messageApproximationScheme(), gum::IApproximationSchemeConfiguration::onProgress, gum::IApproximationSchemeConfiguration::Rate, startOfPeriod(), stateApproximationScheme(), gum::Timer::step(), gum::IApproximationSchemeConfiguration::TimeLimit, and verbosity().

Referenced by gum::GibbsBNdistance< GUM_SCALAR >::_computeKL(), gum::SamplingInference< GUM_SCALAR >::_loopApproxInference(), gum::learning::DAG2BNLearner< ALLOC >::createBN(), gum::learning::GreedyHillClimbing::learnStructure(), gum::learning::LocalSearchWithTabuList::learnStructure(), and gum::credal::CNMonteCarloSampling< GUM_SCALAR, BNInferenceEngine >::makeInference().

                                                                            {
     // For coherence, we fix the time used in the method
 
     double timer_step = _timer.step();
 
     if (_enabled_max_time) {
       if (timer_step > _max_time) {
         _stopScheme(ApproximationSchemeSTATE::TimeLimit);
         return false;
       }
     }
 
     if (!startOfPeriod()) { return true; }
 
     if (_current_state != ApproximationSchemeSTATE::Continue) {
       GUM_ERROR(OperationNotAllowed,
                 "state of the approximation scheme is not correct : "
                    + messageApproximationScheme());
     }
 
     if (verbosity()) { _history.push_back(error); }
 
     if (_enabled_max_iter) {
       if (_current_step > _max_iter) {
         _stopScheme(ApproximationSchemeSTATE::Limit);
         return false;
       }
     }
 
     _last_epsilon = _current_epsilon;
     _current_epsilon = error;   // eps rate isEnabled needs it so affectation was
     // moved from eps isEnabled below
 
     if (_enabled_eps) {
       if (_current_epsilon <= _eps) {
         _stopScheme(ApproximationSchemeSTATE::Epsilon);
         return false;
       }
     }
 
     if (_last_epsilon >= 0.) {
       if (_current_epsilon > .0) {
         // ! _current_epsilon can be 0. AND epsilon
         // isEnabled can be disabled !
         _current_rate =
            std::fabs((_current_epsilon - _last_epsilon) / _current_epsilon);
       }
       // limit with current eps ---> 0 is | 1 - ( last_eps / 0 ) | --->
       // infinity the else means a return false if we isEnabled the rate below,
       // as we would have returned false if epsilon isEnabled was enabled
       else {
         _current_rate = _min_rate_eps;
       }
 
       if (_enabled_min_rate_eps) {
         if (_current_rate <= _min_rate_eps) {
           _stopScheme(ApproximationSchemeSTATE::Rate);
           return false;
         }
       }
     }
 
     if (stateApproximationScheme() == ApproximationSchemeSTATE::Continue) {
       if (onProgress.hasListener()) {
         GUM_EMIT3(onProgress, _current_step, _current_epsilon, timer_step);
       }
 
       return true;
     } else {
       return false;
     }
   }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ currentTime()

INLINE double gum::ApproximationScheme::currentTime ( ) const

virtual

Returns the current running time in second.

Returns: Returns the current running time in second.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 128 of file approximationScheme_inl.h.

References _timer, and gum::Timer::step().

Referenced by gum::learning::genericBNLearner::currentTime().

128 { return _timer.step(); }

gum::Timer::step

double step() const

Returns the delta time between now and the last reset() call (or the constructor).

Definition: timer_inl.h:42

gum::ApproximationScheme::_timer

Timer _timer

The timer.

Definition: approximationScheme.h:381

Here is the call graph for this function:

Here is the caller graph for this function:

◆ disableEpsilon()

INLINE void gum::ApproximationScheme::disableEpsilon ( )

virtual

Disable stopping criterion on epsilon.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 54 of file approximationScheme_inl.h.

References _enabled_eps.

Referenced by gum::learning::genericBNLearner::disableEpsilon().

54 { _enabled_eps = false; }

gum::ApproximationScheme::_enabled_eps

bool _enabled_eps

If true, the threshold convergence is enabled.

Definition: approximationScheme.h:393

Here is the caller graph for this function:

◆ disableMaxIter()

INLINE void gum::ApproximationScheme::disableMaxIter ( )

virtual

Disable stopping criterion on max iterations.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 105 of file approximationScheme_inl.h.

References _enabled_max_iter.

Referenced by gum::credal::CNMonteCarloSampling< GUM_SCALAR, BNInferenceEngine >::__mcInitApproximationScheme(), gum::learning::genericBNLearner::disableMaxIter(), and gum::learning::GreedyHillClimbing::GreedyHillClimbing().

105 { _enabled_max_iter = false; }

gum::ApproximationScheme::_enabled_max_iter

bool _enabled_max_iter

If true, the maximum iterations stopping criterion is enabled.

Definition: approximationScheme.h:411

Here is the caller graph for this function:

◆ disableMaxTime()

INLINE void gum::ApproximationScheme::disableMaxTime ( )

virtual

Disable stopping criterion on timeout.

Returns: Disable stopping criterion on timeout.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 131 of file approximationScheme_inl.h.

References _enabled_max_time.

Referenced by gum::learning::genericBNLearner::disableMaxTime(), and gum::learning::GreedyHillClimbing::GreedyHillClimbing().

131 { _enabled_max_time = false; }

gum::ApproximationScheme::_enabled_max_time

bool _enabled_max_time

If true, the timeout is enabled.

Definition: approximationScheme.h:405

Here is the caller graph for this function:

◆ disableMinEpsilonRate()

INLINE void gum::ApproximationScheme::disableMinEpsilonRate ( )

virtual

Disable stopping criterion on epsilon rate.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 79 of file approximationScheme_inl.h.

References _enabled_min_rate_eps.

Referenced by gum::credal::CNMonteCarloSampling< GUM_SCALAR, BNInferenceEngine >::__mcInitApproximationScheme(), gum::GibbsBNdistance< GUM_SCALAR >::_computeKL(), gum::learning::genericBNLearner::disableMinEpsilonRate(), and gum::learning::GreedyHillClimbing::GreedyHillClimbing().

                                                          {
     _enabled_min_rate_eps = false;
   }

Here is the caller graph for this function:

◆ enableEpsilon()

INLINE void gum::ApproximationScheme::enableEpsilon ( )

virtual

Enable stopping criterion on epsilon.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 57 of file approximationScheme_inl.h.

References _enabled_eps.

Referenced by gum::credal::CNMonteCarloSampling< GUM_SCALAR, BNInferenceEngine >::__mcInitApproximationScheme(), and gum::learning::genericBNLearner::enableEpsilon().

57 { _enabled_eps = true; }

gum::ApproximationScheme::_enabled_eps

bool _enabled_eps

If true, the threshold convergence is enabled.

Definition: approximationScheme.h:393

Here is the caller graph for this function:

◆ enableMaxIter()

INLINE void gum::ApproximationScheme::enableMaxIter ( )

virtual

Enable stopping criterion on max iterations.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 108 of file approximationScheme_inl.h.

References _enabled_max_iter.

Referenced by gum::learning::genericBNLearner::enableMaxIter().

108 { _enabled_max_iter = true; }

gum::ApproximationScheme::_enabled_max_iter

bool _enabled_max_iter

If true, the maximum iterations stopping criterion is enabled.

Definition: approximationScheme.h:411

Here is the caller graph for this function:

◆ enableMaxTime()

INLINE void gum::ApproximationScheme::enableMaxTime ( )

virtual

Enable stopping criterion on timeout.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 134 of file approximationScheme_inl.h.

References _enabled_max_time.

Referenced by gum::credal::CNMonteCarloSampling< GUM_SCALAR, BNInferenceEngine >::CNMonteCarloSampling(), and gum::learning::genericBNLearner::enableMaxTime().

134 { _enabled_max_time = true; }

gum::ApproximationScheme::_enabled_max_time

bool _enabled_max_time

If true, the timeout is enabled.

Definition: approximationScheme.h:405

Here is the caller graph for this function:

◆ enableMinEpsilonRate()

INLINE void gum::ApproximationScheme::enableMinEpsilonRate ( )

virtual

Enable stopping criterion on epsilon rate.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 84 of file approximationScheme_inl.h.

References _enabled_min_rate_eps.

Referenced by gum::GibbsBNdistance< GUM_SCALAR >::_computeKL(), and gum::learning::genericBNLearner::enableMinEpsilonRate().

                                                         {
     _enabled_min_rate_eps = true;
   }

Here is the caller graph for this function:

◆ epsilon()

INLINE double gum::ApproximationScheme::epsilon ( ) const

virtual

Returns the value of epsilon.

Returns: Returns the value of epsilon.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 51 of file approximationScheme_inl.h.

References _eps.

Referenced by gum::ImportanceSampling< GUM_SCALAR >::_onContextualize(), and gum::learning::genericBNLearner::epsilon().

51 { return _eps; }

gum::ApproximationScheme::_eps

double _eps

Threshold for convergence.

Definition: approximationScheme.h:390

Here is the caller graph for this function:

◆ history()

INLINE const std::vector< double > & gum::ApproximationScheme::history ( ) const

virtual

Returns the scheme history.

Returns: Returns the scheme history.

Exceptions

OperationNotAllowed Raised if the scheme did not performed or if verbosity is set to false.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 173 of file approximationScheme_inl.h.

References _history, GUM_ERROR, stateApproximationScheme(), gum::IApproximationSchemeConfiguration::Undefined, and verbosity().

Referenced by gum::learning::genericBNLearner::history().

                                                                        {
     if (stateApproximationScheme() == ApproximationSchemeSTATE::Undefined) {
       GUM_ERROR(OperationNotAllowed,
                 "state of the approximation scheme is udefined");
     }
 
     if (verbosity() == false) {
       GUM_ERROR(OperationNotAllowed, "No history when verbosity=false");
     }
 
     return _history;
   }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ initApproximationScheme()

INLINE void gum::ApproximationScheme::initApproximationScheme ( )

Initialise the scheme.

Definition at line 187 of file approximationScheme_inl.h.

References _current_epsilon, _current_rate, _current_state, _current_step, _history, _timer, gum::IApproximationSchemeConfiguration::Continue, and gum::Timer::reset().

Referenced by gum::credal::CNMonteCarloSampling< GUM_SCALAR, BNInferenceEngine >::__mcInitApproximationScheme(), gum::GibbsBNdistance< GUM_SCALAR >::_computeKL(), gum::SamplingInference< GUM_SCALAR >::_loopApproxInference(), gum::SamplingInference< GUM_SCALAR >::_onStateChanged(), gum::learning::DAG2BNLearner< ALLOC >::createBN(), gum::learning::GreedyHillClimbing::learnStructure(), and gum::learning::LocalSearchWithTabuList::learnStructure().

                                                            {
     _current_state = ApproximationSchemeSTATE::Continue;
     _current_step = 0;
     _current_epsilon = _current_rate = -1.0;
     _history.clear();
     _timer.reset();
   }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isEnabledEpsilon()

INLINE bool gum::ApproximationScheme::isEnabledEpsilon ( ) const

virtual

Returns true if stopping criterion on epsilon is enabled, false otherwise.

Returns: Returns true if stopping criterion on epsilon is enabled, false otherwise.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 61 of file approximationScheme_inl.h.

References _enabled_eps.

Referenced by gum::learning::genericBNLearner::isEnabledEpsilon().

                                                           {
     return _enabled_eps;
   }

Here is the caller graph for this function:

◆ isEnabledMaxIter()

INLINE bool gum::ApproximationScheme::isEnabledMaxIter ( ) const

virtual

Returns true if stopping criterion on max iterations is enabled, false otherwise.

Returns: Returns true if stopping criterion on max iterations is enabled, false otherwise.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 112 of file approximationScheme_inl.h.

References _enabled_max_iter.

Referenced by gum::learning::genericBNLearner::isEnabledMaxIter().

                                                           {
     return _enabled_max_iter;
   }

Here is the caller graph for this function:

◆ isEnabledMaxTime()

INLINE bool gum::ApproximationScheme::isEnabledMaxTime ( ) const

virtual

Returns true if stopping criterion on timeout is enabled, false otherwise.

Returns: Returns true if stopping criterion on timeout is enabled, false otherwise.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 138 of file approximationScheme_inl.h.

References _enabled_max_time.

Referenced by gum::learning::genericBNLearner::isEnabledMaxTime().

                                                           {
     return _enabled_max_time;
   }

Here is the caller graph for this function:

◆ isEnabledMinEpsilonRate()

INLINE bool gum::ApproximationScheme::isEnabledMinEpsilonRate ( ) const

virtual

Returns true if stopping criterion on epsilon rate is enabled, false otherwise.

Returns: Returns true if stopping criterion on epsilon rate is enabled, false otherwise.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 90 of file approximationScheme_inl.h.

References _enabled_min_rate_eps.

Referenced by gum::GibbsBNdistance< GUM_SCALAR >::_computeKL(), and gum::learning::genericBNLearner::isEnabledMinEpsilonRate().

                                                                  {
     return _enabled_min_rate_eps;
   }

Here is the caller graph for this function:

◆ maxIter()

INLINE Size gum::ApproximationScheme::maxIter ( ) const

virtual

Returns the criterion on number of iterations.

Returns: Returns the criterion on number of iterations.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 102 of file approximationScheme_inl.h.

References _max_iter.

Referenced by gum::learning::genericBNLearner::maxIter().

102 { return _max_iter; }

gum::ApproximationScheme::_max_iter

Size _max_iter

The maximum iterations.

Definition: approximationScheme.h:408

Here is the caller graph for this function:

◆ maxTime()

INLINE double gum::ApproximationScheme::maxTime ( ) const

virtual

Returns the timeout (in seconds).

Returns: Returns the timeout (in seconds).

Implements gum::IApproximationSchemeConfiguration.

Definition at line 125 of file approximationScheme_inl.h.

References _max_time.

Referenced by gum::learning::genericBNLearner::maxTime().

125 { return _max_time; }

gum::ApproximationScheme::_max_time

double _max_time

The timeout.

Definition: approximationScheme.h:402

Here is the caller graph for this function:

◆ messageApproximationScheme()

INLINE std::string gum::IApproximationSchemeConfiguration::messageApproximationScheme ( ) const

inherited

Returns the approximation scheme message.

Returns: Returns the approximation scheme message.

Definition at line 40 of file IApproximationSchemeConfiguration_inl.h.

Referenced by _stopScheme(), continueApproximationScheme(), and gum::credal::InferenceEngine< GUM_SCALAR >::getApproximationSchemeMsg().

                                                                          {
     std::stringstream s;
 
     switch (stateApproximationScheme()) {
       case ApproximationSchemeSTATE::Continue: s << "in progress"; break;
 
       case ApproximationSchemeSTATE::Epsilon:
         s << "stopped with epsilon=" << epsilon();
         break;
 
       case ApproximationSchemeSTATE::Rate:
         s << "stopped with rate=" << minEpsilonRate();
         break;
 
       case ApproximationSchemeSTATE::Limit:
         s << "stopped with max iteration=" << maxIter();
         break;
 
       case ApproximationSchemeSTATE::TimeLimit:
         s << "stopped with timeout=" << maxTime();
         break;
 
       case ApproximationSchemeSTATE::Stopped: s << "stopped on request"; break;
 
       case ApproximationSchemeSTATE::Undefined: s << "undefined state"; break;
     };
 
     return s.str();
   }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ minEpsilonRate()

INLINE double gum::ApproximationScheme::minEpsilonRate ( ) const

virtual

Returns the value of the minimal epsilon rate.

Returns: Returns the value of the minimal epsilon rate.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 74 of file approximationScheme_inl.h.

References _min_rate_eps.

Referenced by gum::learning::genericBNLearner::minEpsilonRate().

                                                           {
     return _min_rate_eps;
   }

Here is the caller graph for this function:

◆ nbrIterations()

INLINE Size gum::ApproximationScheme::nbrIterations ( ) const

virtual

Returns the number of iterations.

Returns: Returns the number of iterations.

Exceptions

OperationNotAllowed Raised if the scheme did not perform.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 163 of file approximationScheme_inl.h.

References _current_step, GUM_ERROR, stateApproximationScheme(), and gum::IApproximationSchemeConfiguration::Undefined.

Referenced by gum::GibbsBNdistance< GUM_SCALAR >::_computeKL(), and gum::learning::genericBNLearner::nbrIterations().

                                                        {
     if (stateApproximationScheme() == ApproximationSchemeSTATE::Undefined) {
       GUM_ERROR(OperationNotAllowed,
                 "state of the approximation scheme is undefined");
     }
 
     return _current_step;
   }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ periodSize()

INLINE Size gum::ApproximationScheme::periodSize ( ) const

virtual

Returns the period size.

Returns: Returns the period size.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 149 of file approximationScheme_inl.h.

References _period_size.

Referenced by gum::credal::CNMonteCarloSampling< GUM_SCALAR, BNInferenceEngine >::makeInference(), and gum::learning::genericBNLearner::periodSize().

149 { return _period_size; }

gum::ApproximationScheme::_period_size

Size _period_size

Checking criteria frequency.

Definition: approximationScheme.h:417

Here is the caller graph for this function:

◆ remainingBurnIn()

INLINE Size gum::ApproximationScheme::remainingBurnIn ( )

Returns the remaining burn in.

Returns: Returns the remaining burn in.

Definition at line 210 of file approximationScheme_inl.h.

References _burn_in, and _current_step.

                                                    {
     if (_burn_in > _current_step) {
       return _burn_in - _current_step;
     } else {
       return 0;
     }
   }

◆ setEpsilon()

INLINE void gum::ApproximationScheme::setEpsilon ( double eps )

virtual

Given that we approximate f(t), stopping criterion on |f(t+1)-f(t)|.

If the criterion was disabled it will be enabled.

Parameters

eps	The new epsilon value.

Exceptions

OutOfLowerBound Raised if eps < 0.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 43 of file approximationScheme_inl.h.

References _enabled_eps, _eps, and GUM_ERROR.

Referenced by gum::credal::CNMonteCarloSampling< GUM_SCALAR, BNInferenceEngine >::__mcInitApproximationScheme(), gum::GibbsBNdistance< GUM_SCALAR >::GibbsBNdistance(), gum::GibbsSampling< GUM_SCALAR >::GibbsSampling(), gum::learning::GreedyHillClimbing::GreedyHillClimbing(), gum::SamplingInference< GUM_SCALAR >::SamplingInference(), and gum::learning::genericBNLearner::setEpsilon().

                                                         {
     if (eps < 0.) { GUM_ERROR(OutOfLowerBound, "eps should be >=0"); }
 
     _eps = eps;
     _enabled_eps = true;
   }

Here is the caller graph for this function:

◆ setMaxIter()

INLINE void gum::ApproximationScheme::setMaxIter ( Size max )

virtual

Stopping criterion on number of iterations.

If the criterion was disabled it will be enabled.

Parameters

max	The maximum number of iterations.

Exceptions

OutOfLowerBound Raised if max <= 1.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 95 of file approximationScheme_inl.h.

References _enabled_max_iter, _max_iter, and GUM_ERROR.

Referenced by gum::GibbsBNdistance< GUM_SCALAR >::GibbsBNdistance(), gum::SamplingInference< GUM_SCALAR >::SamplingInference(), and gum::learning::genericBNLearner::setMaxIter().

                                                       {
     if (max < 1) { GUM_ERROR(OutOfLowerBound, "max should be >=1"); }
     _max_iter = max;
     _enabled_max_iter = true;
   }

Here is the caller graph for this function:

◆ setMaxTime()

INLINE void gum::ApproximationScheme::setMaxTime ( double timeout )

virtual

Stopping criterion on timeout.

If the criterion was disabled it will be enabled.

Parameters

timeout The timeout value in seconds.

Exceptions

OutOfLowerBound Raised if timeout <= 0.0.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 118 of file approximationScheme_inl.h.

References _enabled_max_time, _max_time, and GUM_ERROR.

Referenced by gum::credal::CNMonteCarloSampling< GUM_SCALAR, BNInferenceEngine >::CNMonteCarloSampling(), gum::GibbsBNdistance< GUM_SCALAR >::GibbsBNdistance(), gum::SamplingInference< GUM_SCALAR >::SamplingInference(), and gum::learning::genericBNLearner::setMaxTime().

                                                             {
     if (timeout <= 0.) { GUM_ERROR(OutOfLowerBound, "timeout should be >0."); }
     _max_time = timeout;
     _enabled_max_time = true;
   }

Here is the caller graph for this function:

◆ setMinEpsilonRate()

INLINE void gum::ApproximationScheme::setMinEpsilonRate ( double rate )

virtual

Given that we approximate f(t), stopping criterion on d/dt(|f(t+1)-f(t)|).

If the criterion was disabled it will be enabled

Parameters

rate	The minimal epsilon rate.

Exceptions

OutOfLowerBound if rate<0

Implements gum::IApproximationSchemeConfiguration.

Definition at line 66 of file approximationScheme_inl.h.

References _enabled_min_rate_eps, _min_rate_eps, and GUM_ERROR.

Referenced by gum::GibbsBNdistance< GUM_SCALAR >::GibbsBNdistance(), gum::GibbsSampling< GUM_SCALAR >::GibbsSampling(), gum::SamplingInference< GUM_SCALAR >::SamplingInference(), and gum::learning::genericBNLearner::setMinEpsilonRate().

                                                                 {
     if (rate < 0) { GUM_ERROR(OutOfLowerBound, "rate should be >=0"); }
 
     _min_rate_eps = rate;
     _enabled_min_rate_eps = true;
   }

Here is the caller graph for this function:

◆ setPeriodSize()

INLINE void gum::ApproximationScheme::setPeriodSize ( Size p )

virtual

How many samples between two stopping is enable.

Parameters

p	The new period value.

Exceptions

OutOfLowerBound Raised if p < 1.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 143 of file approximationScheme_inl.h.

References _period_size, and GUM_ERROR.

Referenced by gum::credal::CNMonteCarloSampling< GUM_SCALAR, BNInferenceEngine >::CNMonteCarloSampling(), gum::GibbsBNdistance< GUM_SCALAR >::GibbsBNdistance(), gum::SamplingInference< GUM_SCALAR >::SamplingInference(), and gum::learning::genericBNLearner::setPeriodSize().

                                                        {
     if (p < 1) { GUM_ERROR(OutOfLowerBound, "p should be >=1"); }
 
     _period_size = p;
   }

Here is the caller graph for this function:

◆ setVerbosity()

INLINE void gum::ApproximationScheme::setVerbosity ( bool v )

virtual

Set the verbosity on (true) or off (false).

Parameters

v	If true, then verbosity is turned on.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 152 of file approximationScheme_inl.h.

References _verbosity.

Referenced by gum::GibbsBNdistance< GUM_SCALAR >::GibbsBNdistance(), gum::SamplingInference< GUM_SCALAR >::SamplingInference(), and gum::learning::genericBNLearner::setVerbosity().

152 { _verbosity = v; }

gum::ApproximationScheme::_verbosity

bool _verbosity

If true, verbosity is enabled.

Definition: approximationScheme.h:420

Here is the caller graph for this function:

◆ startOfPeriod()

INLINE bool gum::ApproximationScheme::startOfPeriod ( )

Returns true if we are at the beginning of a period (compute error is mandatory).

Returns: Returns true if we are at the beginning of a period (compute error is mandatory).

Definition at line 197 of file approximationScheme_inl.h.

References _burn_in, _current_step, and _period_size.

Referenced by continueApproximationScheme().

                                                  {
     if (_current_step < _burn_in) { return false; }
 
     if (_period_size == 1) { return true; }
 
     return ((_current_step - _burn_in) % _period_size == 0);
   }

Here is the caller graph for this function:

◆ stateApproximationScheme()

INLINE IApproximationSchemeConfiguration::ApproximationSchemeSTATE gum::ApproximationScheme::stateApproximationScheme ( ) const

virtual

Returns the approximation scheme state.

Returns: Returns the approximation scheme state.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 158 of file approximationScheme_inl.h.

References _current_state.

Referenced by continueApproximationScheme(), history(), nbrIterations(), and gum::learning::genericBNLearner::stateApproximationScheme().

                                                              {
     return _current_state;
   }

Here is the caller graph for this function:

◆ stopApproximationScheme()

INLINE void gum::ApproximationScheme::stopApproximationScheme ( )

Stop the approximation scheme.

Definition at line 219 of file approximationScheme_inl.h.

References _current_state, _stopScheme(), gum::IApproximationSchemeConfiguration::Continue, and gum::IApproximationSchemeConfiguration::Stopped.

Referenced by gum::learning::DAG2BNLearner< ALLOC >::createBN(), gum::learning::GreedyHillClimbing::learnStructure(), and gum::learning::LocalSearchWithTabuList::learnStructure().

                                                            {
     if (_current_state == ApproximationSchemeSTATE::Continue) {
       _stopScheme(ApproximationSchemeSTATE::Stopped);
     }
   }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ updateApproximationScheme()

INLINE void gum::ApproximationScheme::updateApproximationScheme ( unsigned int incr = 1 )

Update the scheme w.r.t the new error and increment steps.

Parameters

incr	The new increment steps.

Definition at line 206 of file approximationScheme_inl.h.

References _current_step.

Referenced by gum::GibbsBNdistance< GUM_SCALAR >::_computeKL(), gum::SamplingInference< GUM_SCALAR >::_loopApproxInference(), gum::learning::DAG2BNLearner< ALLOC >::createBN(), gum::learning::GreedyHillClimbing::learnStructure(), gum::learning::LocalSearchWithTabuList::learnStructure(), and gum::credal::CNMonteCarloSampling< GUM_SCALAR, BNInferenceEngine >::makeInference().

                                                                               {
     _current_step += incr;
   }

Here is the caller graph for this function:

◆ verbosity()

INLINE bool gum::ApproximationScheme::verbosity ( ) const

virtual

Returns true if verbosity is enabled.

Returns: Returns true if verbosity is enabled.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 154 of file approximationScheme_inl.h.

References _verbosity.

Referenced by continueApproximationScheme(), history(), and gum::learning::genericBNLearner::verbosity().

154 { return _verbosity; }

gum::ApproximationScheme::_verbosity

bool _verbosity

If true, verbosity is enabled.

Definition: approximationScheme.h:420

Here is the caller graph for this function:

Member Data Documentation

◆ _burn_in

Size gum::ApproximationScheme::_burn_in

protected

Number of iterations before checking stopping criteria.

Definition at line 414 of file approximationScheme.h.

Referenced by gum::GibbsSampling< GUM_SCALAR >::burnIn(), gum::GibbsBNdistance< GUM_SCALAR >::burnIn(), remainingBurnIn(), gum::GibbsSampling< GUM_SCALAR >::setBurnIn(), gum::GibbsBNdistance< GUM_SCALAR >::setBurnIn(), and startOfPeriod().

◆ _current_epsilon

double gum::ApproximationScheme::_current_epsilon

protected

Current epsilon.

Definition at line 369 of file approximationScheme.h.

Referenced by continueApproximationScheme(), and initApproximationScheme().

◆ _current_rate

double gum::ApproximationScheme::_current_rate

protected

Current rate.

Definition at line 375 of file approximationScheme.h.

Referenced by continueApproximationScheme(), and initApproximationScheme().

◆ _current_state

ApproximationSchemeSTATE gum::ApproximationScheme::_current_state

protected

The current state.

Definition at line 384 of file approximationScheme.h.

Referenced by _stopScheme(), continueApproximationScheme(), initApproximationScheme(), stateApproximationScheme(), and stopApproximationScheme().

◆ _current_step

Size gum::ApproximationScheme::_current_step

protected

The current step.

Definition at line 378 of file approximationScheme.h.

Referenced by gum::learning::Miic::_initiation(), gum::learning::Miic::_iteration(), gum::learning::Miic::_orientation_3off2(), gum::learning::Miic::_orientation_latents(), gum::learning::Miic::_orientation_miic(), continueApproximationScheme(), initApproximationScheme(), gum::learning::Miic::learnMixedStructure(), nbrIterations(), remainingBurnIn(), startOfPeriod(), and updateApproximationScheme().

◆ _enabled_eps

bool gum::ApproximationScheme::_enabled_eps

protected

If true, the threshold convergence is enabled.

Definition at line 393 of file approximationScheme.h.

Referenced by continueApproximationScheme(), disableEpsilon(), enableEpsilon(), isEnabledEpsilon(), and setEpsilon().

◆ _enabled_max_iter

bool gum::ApproximationScheme::_enabled_max_iter

protected

If true, the maximum iterations stopping criterion is enabled.

Definition at line 411 of file approximationScheme.h.

Referenced by continueApproximationScheme(), disableMaxIter(), enableMaxIter(), isEnabledMaxIter(), and setMaxIter().

◆ _enabled_max_time

bool gum::ApproximationScheme::_enabled_max_time

protected

If true, the timeout is enabled.

Definition at line 405 of file approximationScheme.h.

Referenced by continueApproximationScheme(), disableMaxTime(), enableMaxTime(), isEnabledMaxTime(), and setMaxTime().

◆ _enabled_min_rate_eps

bool gum::ApproximationScheme::_enabled_min_rate_eps

protected

If true, the minimal threshold for epsilon rate is enabled.

Definition at line 399 of file approximationScheme.h.

Referenced by continueApproximationScheme(), disableMinEpsilonRate(), enableMinEpsilonRate(), isEnabledMinEpsilonRate(), and setMinEpsilonRate().

◆ _eps

double gum::ApproximationScheme::_eps

protected

Threshold for convergence.

Definition at line 390 of file approximationScheme.h.

Referenced by continueApproximationScheme(), epsilon(), and setEpsilon().

◆ _history

std::vector< double > gum::ApproximationScheme::_history

protected

The scheme history, used only if verbosity == true.

Definition at line 387 of file approximationScheme.h.

Referenced by continueApproximationScheme(), history(), and initApproximationScheme().

◆ _last_epsilon

double gum::ApproximationScheme::_last_epsilon

protected

Last epsilon value.

Definition at line 372 of file approximationScheme.h.

Referenced by continueApproximationScheme().

◆ _max_iter

Size gum::ApproximationScheme::_max_iter

protected

The maximum iterations.

Definition at line 408 of file approximationScheme.h.

Referenced by continueApproximationScheme(), maxIter(), and setMaxIter().

◆ _max_time

double gum::ApproximationScheme::_max_time

protected

The timeout.

Definition at line 402 of file approximationScheme.h.

Referenced by continueApproximationScheme(), maxTime(), and setMaxTime().

◆ _min_rate_eps

double gum::ApproximationScheme::_min_rate_eps

protected

Threshold for the epsilon rate.

Definition at line 396 of file approximationScheme.h.

Referenced by continueApproximationScheme(), minEpsilonRate(), and setMinEpsilonRate().

◆ _period_size

Size gum::ApproximationScheme::_period_size

protected

Checking criteria frequency.

Definition at line 417 of file approximationScheme.h.

Referenced by periodSize(), setPeriodSize(), and startOfPeriod().

◆ _timer

Timer gum::ApproximationScheme::_timer

protected

The timer.

Definition at line 381 of file approximationScheme.h.

Referenced by gum::learning::Miic::_initiation(), gum::learning::Miic::_iteration(), gum::learning::Miic::_orientation_3off2(), gum::learning::Miic::_orientation_latents(), gum::learning::Miic::_orientation_miic(), _stopScheme(), continueApproximationScheme(), currentTime(), initApproximationScheme(), and gum::learning::Miic::learnMixedStructure().

◆ _verbosity

bool gum::ApproximationScheme::_verbosity

protected

If true, verbosity is enabled.

Definition at line 420 of file approximationScheme.h.

Referenced by setVerbosity(), and verbosity().

◆ onProgress

Signaler3< Size, double, double > gum::IApproximationSchemeConfiguration::onProgress

inherited

Progression, error and time.

Definition at line 59 of file IApproximationSchemeConfiguration.h.

Referenced by gum::learning::Miic::_initiation(), gum::learning::Miic::_iteration(), gum::learning::Miic::_orientation_3off2(), gum::learning::Miic::_orientation_latents(), gum::learning::Miic::_orientation_miic(), continueApproximationScheme(), and gum::learning::genericBNLearner::distributeProgress().

◆ onStop

Signaler1< std::string > gum::IApproximationSchemeConfiguration::onStop

inherited

Criteria messageApproximationScheme.

Definition at line 62 of file IApproximationSchemeConfiguration.h.

Referenced by _stopScheme(), and gum::learning::genericBNLearner::distributeStop().

The documentation for this class was generated from the following files:

agrum/core/approximations/approximationScheme.h
agrum/core/approximations/approximationScheme.cpp
agrum/core/approximations/approximationScheme_inl.h

Public Attributes

Public Member Functions

Public Types

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ ApproximationSchemeSTATE

Constructor & Destructor Documentation

◆ ApproximationScheme()

◆ ~ApproximationScheme()

Member Function Documentation

◆ _stopScheme()

◆ continueApproximationScheme()

◆ currentTime()

◆ disableEpsilon()

◆ disableMaxIter()

◆ disableMaxTime()

◆ disableMinEpsilonRate()

◆ enableEpsilon()

◆ enableMaxIter()

◆ enableMaxTime()

◆ enableMinEpsilonRate()

◆ epsilon()

◆ history()

◆ initApproximationScheme()

◆ isEnabledEpsilon()

◆ isEnabledMaxIter()

◆ isEnabledMaxTime()

◆ isEnabledMinEpsilonRate()

◆ maxIter()

◆ maxTime()

◆ messageApproximationScheme()

◆ minEpsilonRate()

◆ nbrIterations()

◆ periodSize()

◆ remainingBurnIn()

◆ setEpsilon()

◆ setMaxIter()

◆ setMaxTime()

◆ setMinEpsilonRate()

◆ setPeriodSize()

◆ setVerbosity()

◆ startOfPeriod()

◆ stateApproximationScheme()

◆ stopApproximationScheme()

◆ updateApproximationScheme()

◆ verbosity()

Member Data Documentation

◆ _burn_in

◆ _current_epsilon

◆ _current_rate

◆ _current_state

◆ _current_step

◆ _enabled_eps

◆ _enabled_max_iter

◆ _enabled_max_time

◆ _enabled_min_rate_eps

◆ _eps

◆ _history

◆ _last_epsilon

◆ _max_iter

◆ _max_time

◆ _min_rate_eps

◆ _period_size

◆ _timer

◆ _verbosity

◆ onProgress

◆ onStop