gum::GibbsBNdistance< GUM_SCALAR > Class Template Reference

GibbsKL computes the KL divergence betweens 2 BNs using an approximation pattern: GIBBS sampling. More...

#include <GibbsBNdistance.h>

Inheritance diagram for gum::GibbsBNdistance< GUM_SCALAR >:

Collaboration diagram for gum::GibbsBNdistance< GUM_SCALAR >:

Public Attributes
Signaler3< Size, double, double >	onProgress
	Progression, error and time. More...
Signaler1< std::string >	onStop
	Criteria messageApproximationScheme. More...

Public Member Functions
	GibbsBNdistance (const IBayesNet< GUM_SCALAR > &P, const IBayesNet< GUM_SCALAR > &Q)
	constructor must give 2 BNs More...
	GibbsBNdistance (const BNdistance< GUM_SCALAR > &kl)
	copy constructor More...
	~GibbsBNdistance ()
	destructor More...
void	setBurnIn (Size b)
	Number of burn in for one iteration. More...
Size	burnIn () const
	Returns the number of burn in. More...
Complexity	difficulty () const
	return KL::Complexity::Heavy,KL::Complexity::Difficult,KL::Complexity::Correct depending on the BNs p__ and q__ More...
Size	nbrDrawnVar () const
	Getters and setters. More...
void	setNbrDrawnVar (Size nbr)
bool	isDrawnAtRandom () const
void	setDrawnAtRandom (bool atRandom)
Instantiation	monteCarloSample ()
	draws a Monte Carlo sample More...
Instantiation	nextSample (Instantiation prev)
	draws next sample of Gibbs sampling More...
Accessors to results. The first call do the computations. The
others do not.
double	klPQ ()
Size	errorPQ ()
double	klQP ()
Size	errorQP ()
double	hellinger ()
double	bhattacharya ()
double	jsd ()
const IBayesNet< GUM_SCALAR > &	p () const
const IBayesNet< GUM_SCALAR > &	q () const
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
const IBayesNet< GUM_SCALAR > &	p_
const IBayesNet< GUM_SCALAR > &	q_
GUM_SCALAR	klPQ_
GUM_SCALAR	klQP_
GUM_SCALAR	hellinger_
GUM_SCALAR	bhattacharya_
GUM_SCALAR	jsd_
Size	errorPQ_
Size	errorQP_
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...
Size	counting_
	number of samples drawn More...
const IBayesNet< GUM_SCALAR > &	sampling_bn_
const NodeProperty< Idx > *	hardEv_
Sequence< NodeId >	samplingNodes_
Size	nbr_
bool	atRandom_

Protected Member Functions
void	computeKL_ () final
void	process_ ()

Detailed Description

template<typename GUM_SCALAR>
class gum::GibbsBNdistance< GUM_SCALAR >

GibbsKL computes the KL divergence betweens 2 BNs using an approximation pattern: GIBBS sampling.

KL.process() computes KL(P||Q) using klPQ() and KL(Q||P) using klQP(). The computations are made once. The second is for free :) GibbsKL allows as well to compute in the same time the Hellinger distance ( \( *\sqrt{\sum_i (\sqrt{p_i}-\sqrt{q_i})^2}\)) (Kokolakis and Nanopoulos, 2001) and Bhattacharya distance (Kaylath,T. 1967)

It may happen that P*ln(P/Q) is not computable (Q=0 and P!=0). In such a case, KL keeps working but trace this error (errorPQ() and errorQP()). In those cases, Hellinger distance approximation is under-evaluated.

Warning

: convergence and stop criteria are designed w.r.t the main computation : KL(P||Q). The 3 others have no guarantee.

snippets :

gum::KL base_kl(net1,net2);
if (base_kl.difficulty()!=KL::HEAVY) {
 gum::ExactBNdistance kl(base_kl);
 std::cout<<"KL net1||net2 :"<<kl.klPQ()<<std::endl;
} else {
 gum::GibbsBNdistance kl(base_kl);
 std::cout<<"KL net1||net2 :"<<kl.klPQ()<<std::endl;
}

Definition at line 78 of file GibbsBNdistance.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 64 of file IApproximationSchemeConfiguration.h.

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

Constructor & Destructor Documentation

GibbsBNdistance() [1/2]

template<typename GUM_SCALAR >

gum::GibbsBNdistance< GUM_SCALAR >::GibbsBNdistance	(	const IBayesNet< GUM_SCALAR > &	P,
		const IBayesNet< GUM_SCALAR > &	Q
	)

constructor must give 2 BNs

Exceptions

gum::OperationNotAllowed

if the 2 BNs have not the same domainSize or compatible node sets.

Definition at line 51 of file GibbsKL_tpl.h.

                                       :
      BNdistance< GUM_SCALAR >(P, Q),
      ApproximationScheme(),
      GibbsOperator< GUM_SCALAR >(
         P,
         nullptr,
         1 + (P.size() * GIBBSKL_POURCENT_DRAWN_SAMPLE / 100),
         GIBBSKL_DRAWN_AT_RANDOM) {
    GUM_CONSTRUCTOR(GibbsBNdistance);

    setEpsilon(GIBBSKL_DEFAULT_EPSILON);
    setMinEpsilonRate(GIBBSKL_DEFAULT_MIN_EPSILON_RATE);
    setMaxIter(GIBBSKL_DEFAULT_MAXITER);
    setVerbosity(GIBBSKL_DEFAULT_VERBOSITY);
    setBurnIn(GIBBSKL_DEFAULT_BURNIN);
    setPeriodSize(GIBBSKL_DEFAULT_PERIOD_SIZE);
    setMaxTime(GIBBSKL_DEFAULT_TIMEOUT);
  }

GibbsBNdistance() [2/2]

template<typename GUM_SCALAR >

gum::GibbsBNdistance< GUM_SCALAR >::GibbsBNdistance ( const BNdistance< GUM_SCALAR > &  kl )

explicit

copy constructor

Definition at line 73 of file GibbsKL_tpl.h.

References gum::Set< Key, Alloc >::emplace().

                                         :
      BNdistance< GUM_SCALAR >(kl),
      ApproximationScheme()
      // Gibbs operator with 10% of nodes changes at random between each samples
      ,
      GibbsOperator< GUM_SCALAR >(
         kl.p(),
         nullptr,
         1 + (kl.p().size() * GIBBSKL_POURCENT_DRAWN_SAMPLE / 100),
         true) {
    GUM_CONSTRUCTOR(GibbsBNdistance);

    setEpsilon(GIBBSKL_DEFAULT_EPSILON);
    setMinEpsilonRate(GIBBSKL_DEFAULT_MIN_EPSILON_RATE);
    setMaxIter(GIBBSKL_DEFAULT_MAXITER);
    setVerbosity(GIBBSKL_DEFAULT_VERBOSITY);
    setBurnIn(GIBBSKL_DEFAULT_BURNIN);
    setPeriodSize(GIBBSKL_DEFAULT_PERIOD_SIZE);
    setMaxTime(GIBBSKL_DEFAULT_TIMEOUT);
  }

Here is the call graph for this function:

~GibbsBNdistance()

template<typename GUM_SCALAR >

gum::GibbsBNdistance< GUM_SCALAR >::~GibbsBNdistance

(

)

destructor

Definition at line 96 of file GibbsKL_tpl.h.

References gum::Set< Key, Alloc >::emplace().

                                                  {
    GUM_DESTRUCTOR(GibbsBNdistance);
  }

Here is the call graph for this function:

Member Function Documentation

bhattacharya()

template<typename GUM_SCALAR >

INLINE double gum::BNdistance< GUM_SCALAR >::bhattacharya ( )

inherited

Returns

Bhattacharya distance (

See also

http://en.wikipedia.org/wiki/Bhattacharya_distance)

Definition at line 92 of file BNdistance_tpl.h.

                                                       {
    process_();
    return bhattacharya_;
  }

burnIn()

template<typename GUM_SCALAR >

Size gum::GibbsBNdistance< GUM_SCALAR >::burnIn

(

)

const

Returns the number of burn in.

Returns

Returns the number of burn in.

Definition at line 189 of file GibbsKL_tpl.h.

References gum::Set< Key, Alloc >::emplace().

                                                   {
    return this->burn_in_;
  }

Here is the call graph for this function:

computeKL_()

template<typename GUM_SCALAR >

void gum::GibbsBNdistance< GUM_SCALAR >::computeKL_ ( )

finalprotectedvirtual

Reimplemented from gum::BNdistance< GUM_SCALAR >.

Definition at line 101 of file GibbsKL_tpl.h.

References gum::Set< Key, Alloc >::emplace().

                                                 {
    auto Iq = q_.completeInstantiation();

    gum::Instantiation I = this->monteCarloSample();
    initApproximationScheme();

    // map between particle() variables and q_ variables (using name of vars)
    HashTable< const DiscreteVariable*, const DiscreteVariable* > map;

    for (Idx ite = 0; ite < I.nbrDim(); ++ite) {
      map.insert(&I.variable(ite), &q_.variableFromName(I.variable(ite).name()));
    }

    // BURN IN
    for (Idx i = 0; i < burnIn(); i++)
      I = this->nextSample(I);

    // SAMPLING
    klPQ_ = klQP_ = hellinger_ = jsd_ = (GUM_SCALAR)0.0;
    errorPQ_ = errorQP_ = 0;
    GUM_SCALAR delta, ratio, error;
    delta = ratio = error = (GUM_SCALAR)-1;
    GUM_SCALAR oldPQ      = 0.0;
    GUM_SCALAR pp, pq, pmid;

    do {
      this->disableMinEpsilonRate();
      I = this->nextSample(I);
      updateApproximationScheme();

      //_p.synchroInstantiations( Ip,I);
      Iq.setValsFrom(map, I);

      pp   = p_.jointProbability(I);
      pq   = q_.jointProbability(Iq);
      pmid = (pp + pq) / 2.0;

      if (pp != (GUM_SCALAR)0.0) {
        hellinger_ += std::pow(std::sqrt(pp) - std::sqrt(pq), 2) / pp;

        if (pq != (GUM_SCALAR)0.0) {
          bhattacharya_ += std::sqrt(pq / pp);   // std::sqrt(pp*pq)/pp
          this->enableMinEpsilonRate();   // replace check_rate=true;
          ratio = pq / pp;
          delta = (GUM_SCALAR)std::log2(ratio);
          klPQ_ += delta;

          // pmid!=0
          jsd_ -= std::log2(pp / pmid) + ratio * std::log2(pq / pmid);
        } else {
          errorPQ_++;
        }
      }

      if (pq != (GUM_SCALAR)0.0) {
        if (pp != (GUM_SCALAR)0.0) {
          // if we are here, it is certain that delta and ratio have been
          // computed
          // further lines above. (for now #112-113)
          klQP_ += (GUM_SCALAR)(-delta * ratio);
        } else {
          errorQP_++;
        }
      }

      if (this->isEnabledMinEpsilonRate()) {   // replace check_rate
        // delta is used as a temporary variable
        delta = klPQ_ / nbrIterations();
        error = (GUM_SCALAR)std::abs(delta - oldPQ);
        oldPQ = delta;
      }
    } while (continueApproximationScheme(error));   //

    klPQ_         = -klPQ_ / (nbrIterations());
    klQP_         = -klQP_ / (nbrIterations());
    jsd_          = -0.5 * jsd_ / (nbrIterations());
    hellinger_    = std::sqrt(hellinger_ / nbrIterations());
    bhattacharya_ = -std::log(bhattacharya_ / (nbrIterations()));
  }

Here is the call graph for this function:

continueApproximationScheme()

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

inherited

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 226 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

                                                                           {
    // 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:

currentTime()

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

virtualinherited

Returns the current running time in second.

Returns

Returns the current running time in second.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 127 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

{ return timer_.step(); }

Here is the call graph for this function:

difficulty()

template<typename GUM_SCALAR >

Complexity gum::BNdistance< GUM_SCALAR >::difficulty ( ) const

inherited

return KL::Complexity::Heavy,KL::Complexity::Difficult,KL::Complexity::Correct depending on the BNs p__ and q__

Definition at line 69 of file BNdistance_tpl.h.

                                                        {
    return difficulty__;
  }

disableEpsilon()

INLINE void gum::ApproximationScheme::disableEpsilon ( )

virtualinherited

Disable stopping criterion on epsilon.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 53 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

{ enabled_eps_ = false; }

Here is the call graph for this function:

disableMaxIter()

INLINE void gum::ApproximationScheme::disableMaxIter ( )

virtualinherited

Disable stopping criterion on max iterations.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 104 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

{ enabled_max_iter_ = false; }

Here is the call graph for this function:

disableMaxTime()

INLINE void gum::ApproximationScheme::disableMaxTime ( )

virtualinherited

Disable stopping criterion on timeout.

Returns

Disable stopping criterion on timeout.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 130 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

{ enabled_max_time_ = false; }

Here is the call graph for this function:

disableMinEpsilonRate()

INLINE void gum::ApproximationScheme::disableMinEpsilonRate ( )

virtualinherited

Disable stopping criterion on epsilon rate.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 78 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

                                                         {
    enabled_min_rate_eps_ = false;
  }

Here is the call graph for this function:

enableEpsilon()

INLINE void gum::ApproximationScheme::enableEpsilon ( )

virtualinherited

Enable stopping criterion on epsilon.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 56 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

{ enabled_eps_ = true; }

Here is the call graph for this function:

enableMaxIter()

INLINE void gum::ApproximationScheme::enableMaxIter ( )

virtualinherited

Enable stopping criterion on max iterations.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 107 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

{ enabled_max_iter_ = true; }

Here is the call graph for this function:

enableMaxTime()

INLINE void gum::ApproximationScheme::enableMaxTime ( )

virtualinherited

Enable stopping criterion on timeout.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 133 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

{ enabled_max_time_ = true; }

Here is the call graph for this function:

enableMinEpsilonRate()

INLINE void gum::ApproximationScheme::enableMinEpsilonRate ( )

virtualinherited

Enable stopping criterion on epsilon rate.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 83 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

                                                        {
    enabled_min_rate_eps_ = true;
  }

Here is the call graph for this function:

epsilon()

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

virtualinherited

Returns the value of epsilon.

Returns

Returns the value of epsilon.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 50 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

{ return eps_; }

Here is the call graph for this function:

errorPQ()

template<typename GUM_SCALAR >

INLINE Size gum::BNdistance< GUM_SCALAR >::errorPQ ( )

inherited

Returns

the number of errors while processing divergence KL(P||Q)

Definition at line 104 of file BNdistance_tpl.h.

                                                {
    process_();
    return errorPQ_;
  }

errorQP()

template<typename GUM_SCALAR >

INLINE Size gum::BNdistance< GUM_SCALAR >::errorQP ( )

inherited

Returns

the number of errors while processing divergence KL(Q||P)

Definition at line 110 of file BNdistance_tpl.h.

                                                {
    process_();
    return errorQP_;
  }

hellinger()

template<typename GUM_SCALAR >

INLINE double gum::BNdistance< GUM_SCALAR >::hellinger ( )

inherited

Returns

hellinger distance (

See also

http://en.wikipedia.org/wiki/Hellinger_distance)

Definition at line 86 of file BNdistance_tpl.h.

                                                    {
    process_();
    return hellinger_;
  }

history()

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

virtualinherited

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 172 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

                                                                       {
    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:

initApproximationScheme()

INLINE void gum::ApproximationScheme::initApproximationScheme ( )

inherited

Initialise the scheme.

Definition at line 186 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

                                                           {
    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:

isDrawnAtRandom()

template<typename GUM_SCALAR >

bool gum::GibbsOperator< GUM_SCALAR >::isDrawnAtRandom ( ) const

inlineinherited

Definition at line 69 of file gibbsOperator.h.

References gum::GibbsOperator< GUM_SCALAR >::atRandom_.

{ return atRandom_; }

isEnabledEpsilon()

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

virtualinherited

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 60 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

                                                          {
    return enabled_eps_;
  }

Here is the call graph for this function:

isEnabledMaxIter()

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

virtualinherited

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 111 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

                                                          {
    return enabled_max_iter_;
  }

Here is the call graph for this function:

isEnabledMaxTime()

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

virtualinherited

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 137 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

                                                          {
    return enabled_max_time_;
  }

Here is the call graph for this function:

isEnabledMinEpsilonRate()

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

virtualinherited

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 89 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

                                                                 {
    return enabled_min_rate_eps_;
  }

Here is the call graph for this function:

jsd()

template<typename GUM_SCALAR >

INLINE double gum::BNdistance< GUM_SCALAR >::jsd ( )

inherited

Returns

Jensen-Shannon divergence(

See also

https://en.wikipedia.org/wiki/Jensen%E2%80%93Shannon_divergence)

Definition at line 98 of file BNdistance_tpl.h.

                                              {
    process_();
    return jsd_;
  }

klPQ()

template<typename GUM_SCALAR >

INLINE double gum::BNdistance< GUM_SCALAR >::klPQ ( )

inherited

Returns

divergence KL(P||Q)

Definition at line 74 of file BNdistance_tpl.h.

                                               {
    process_();
    return klPQ_;
  }

klQP()

template<typename GUM_SCALAR >

INLINE double gum::BNdistance< GUM_SCALAR >::klQP ( )

inherited

Returns

divergence KL(Q||P)

Definition at line 80 of file BNdistance_tpl.h.

                                               {
    process_();
    return klQP_;
  }

maxIter()

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

virtualinherited

Returns the criterion on number of iterations.

Returns

Returns the criterion on number of iterations.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 101 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

{ return max_iter_; }

Here is the call graph for this function:

maxTime()

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

virtualinherited

Returns the timeout (in seconds).

Returns

Returns the timeout (in seconds).

Implements gum::IApproximationSchemeConfiguration.

Definition at line 124 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

{ return max_time_; }

Here is the call 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 39 of file IApproximationSchemeConfiguration_inl.h.

References gum::Set< Key, Alloc >::emplace().

                                                                         {
    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:

minEpsilonRate()

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

virtualinherited

Returns the value of the minimal epsilon rate.

Returns

Returns the value of the minimal epsilon rate.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 73 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

                                                          {
    return min_rate_eps_;
  }

Here is the call graph for this function:

monteCarloSample()

template<typename GUM_SCALAR >

Instantiation gum::GibbsOperator< GUM_SCALAR >::monteCarloSample ( )

inherited

draws a Monte Carlo sample

returns a MC sample This is not a really sample since we take into account evidence without care about parent of evidence, etc. This is just a not-so-bad first sample for GibbsSampler

Definition at line 69 of file gibbsOperator_tpl.h.

References gum::Set< Key, Alloc >::emplace().

                                                              {
    gum::Instantiation I;

    for (const auto nod: sampling_bn_.topologicalOrder()) {
      I.add(sampling_bn_.variable(nod));
      if (hardEv_ != nullptr && hardEv_->exists(nod)) {
        I.chgVal(sampling_bn_.variable(nod), (*hardEv_)[nod]);
      } else {
        drawVarMonteCarlo__(nod, &I);
      }
    }
    return I;
  }

Here is the call graph for this function:

nbrDrawnVar()

template<typename GUM_SCALAR >

Size gum::GibbsOperator< GUM_SCALAR >::nbrDrawnVar ( ) const

inlineinherited

Getters and setters.

Definition at line 65 of file gibbsOperator.h.

{ return nbr_; }

nbrIterations()

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

virtualinherited

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 162 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

                                                       {
    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:

nextSample()

template<typename GUM_SCALAR >

Instantiation gum::GibbsOperator< GUM_SCALAR >::nextSample ( Instantiation  prev )

inherited

draws next sample of Gibbs sampling

Definition at line 94 of file gibbsOperator_tpl.h.

References gum::Set< Key, Alloc >::emplace().

                                                                          {
    for (Idx i = 0; i < nbr_; i++) {
      auto pos = atRandom_ ? randomValue(samplingNodes_.size())
                           : (counting_ % samplingNodes_.size());
      this->GibbsSample__(samplingNodes_[pos], &prev);
      counting_++;
    }
    return prev;
  }

Here is the call graph for this function:

p()

template<typename GUM_SCALAR >

INLINE const IBayesNet< GUM_SCALAR > & gum::BNdistance< GUM_SCALAR >::p ( ) const

inherited

Returns

p

Definition at line 116 of file BNdistance_tpl.h.

                                                                          {
    return p_;
  }

periodSize()

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

virtualinherited

Returns the period size.

Returns

Returns the period size.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 148 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

{ return period_size_; }

Here is the call graph for this function:

process_()

template<typename GUM_SCALAR >

void gum::BNdistance< GUM_SCALAR >::process_ ( )

protectedinherited

Definition at line 177 of file BNdistance_tpl.h.

                                          {
    if (!done__) {
      computeKL_();
      done__ = true;
    }
  }

q()

template<typename GUM_SCALAR >

INLINE const IBayesNet< GUM_SCALAR > & gum::BNdistance< GUM_SCALAR >::q ( ) const

inherited

Returns

q

Definition at line 121 of file BNdistance_tpl.h.

                                                                          {
    return q_;
  }

remainingBurnIn()

INLINE Size gum::ApproximationScheme::remainingBurnIn ( )

inherited

Returns the remaining burn in.

Returns

Returns the remaining burn in.

Definition at line 209 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

                                                   {
    if (burn_in_ > current_step_) {
      return burn_in_ - current_step_;
    } else {
      return 0;
    }
  }

Here is the call graph for this function:

setBurnIn()

template<typename GUM_SCALAR >

void gum::GibbsBNdistance< GUM_SCALAR >::setBurnIn

(

Size

b

)

Number of burn in for one iteration.

Parameters

b	The number of burn in.

Exceptions

OutOfLowerBound

Raised if b < 1.

Definition at line 184 of file GibbsKL_tpl.h.

References gum::Set< Key, Alloc >::emplace().

                                                      {
    this->burn_in_ = b;
  }

Here is the call graph for this function:

setDrawnAtRandom()

template<typename GUM_SCALAR >

void gum::GibbsOperator< GUM_SCALAR >::setDrawnAtRandom ( bool  atRandom )

inlineinherited

Definition at line 71 of file gibbsOperator.h.

References gum::GibbsOperator< GUM_SCALAR >::atRandom_.

{ atRandom_ = atRandom; }

setEpsilon()

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

virtualinherited

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 42 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

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

    eps_         = eps;
    enabled_eps_ = true;
  }

Here is the call graph for this function:

setMaxIter()

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

virtualinherited

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 94 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

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

Here is the call graph for this function:

setMaxTime()

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

virtualinherited

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 117 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

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

Here is the call graph for this function:

setMinEpsilonRate()

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

virtualinherited

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 65 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

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

    min_rate_eps_         = rate;
    enabled_min_rate_eps_ = true;
  }

Here is the call graph for this function:

setNbrDrawnVar()

template<typename GUM_SCALAR >

void gum::GibbsOperator< GUM_SCALAR >::setNbrDrawnVar ( Size  nbr )

inlineinherited

Definition at line 67 of file gibbsOperator.h.

{ nbr_ = nbr; }

setPeriodSize()

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

virtualinherited

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 142 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

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

    period_size_ = p;
  }

Here is the call graph for this function:

setVerbosity()

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

virtualinherited

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

Parameters

v	If true, then verbosity is turned on.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 151 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

{ verbosity_ = v; }

Here is the call graph for this function:

startOfPeriod()

INLINE bool gum::ApproximationScheme::startOfPeriod ( )

inherited

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 196 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

                                                 {
    if (current_step_ < burn_in_) { return false; }

    if (period_size_ == 1) { return true; }

    return ((current_step_ - burn_in_) % period_size_ == 0);
  }

Here is the call graph for this function:

stateApproximationScheme()

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

virtualinherited

Returns the approximation scheme state.

Returns

Returns the approximation scheme state.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 157 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

                                                             {
    return current_state_;
  }

Here is the call graph for this function:

stopApproximationScheme()

INLINE void gum::ApproximationScheme::stopApproximationScheme ( )

inherited

Stop the approximation scheme.

Definition at line 218 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

                                                           {
    if (current_state_ == ApproximationSchemeSTATE::Continue) {
      stopScheme_(ApproximationSchemeSTATE::Stopped);
    }
  }

Here is the call graph for this function:

updateApproximationScheme()

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

inherited

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

Parameters

incr	The new increment steps.

Definition at line 205 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

                                                                              {
    current_step_ += incr;
  }

Here is the call graph for this function:

verbosity()

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

virtualinherited

Returns true if verbosity is enabled.

Returns

Returns true if verbosity is enabled.

Implements gum::IApproximationSchemeConfiguration.

Definition at line 153 of file approximationScheme_inl.h.

References gum::Set< Key, Alloc >::emplace().

{ return verbosity_; }

Here is the call graph for this function:

Member Data Documentation

atRandom_

template<typename GUM_SCALAR >

bool gum::GibbsOperator< GUM_SCALAR >::atRandom_

protectedinherited

Definition at line 89 of file gibbsOperator.h.

Referenced by gum::GibbsOperator< GUM_SCALAR >::isDrawnAtRandom(), and gum::GibbsOperator< GUM_SCALAR >::setDrawnAtRandom().

bhattacharya_

template<typename GUM_SCALAR >

GUM_SCALAR gum::BNdistance< GUM_SCALAR >::bhattacharya_

protectedinherited

Definition at line 146 of file BNdistance.h.

burn_in_

Size gum::ApproximationScheme::burn_in_

protectedinherited

Number of iterations before checking stopping criteria.

Definition at line 413 of file approximationScheme.h.

counting_

template<typename GUM_SCALAR >

Size gum::GibbsOperator< GUM_SCALAR >::counting_

protectedinherited

number of samples drawn

Definition at line 81 of file gibbsOperator.h.

current_epsilon_

double gum::ApproximationScheme::current_epsilon_

protectedinherited

Current epsilon.

Definition at line 368 of file approximationScheme.h.

current_rate_

double gum::ApproximationScheme::current_rate_

protectedinherited

Current rate.

Definition at line 374 of file approximationScheme.h.

current_state_

ApproximationSchemeSTATE gum::ApproximationScheme::current_state_

protectedinherited

The current state.

Definition at line 383 of file approximationScheme.h.

current_step_

Size gum::ApproximationScheme::current_step_

protectedinherited

The current step.

Definition at line 377 of file approximationScheme.h.

enabled_eps_

bool gum::ApproximationScheme::enabled_eps_

protectedinherited

If true, the threshold convergence is enabled.

Definition at line 392 of file approximationScheme.h.

enabled_max_iter_

bool gum::ApproximationScheme::enabled_max_iter_

protectedinherited

If true, the maximum iterations stopping criterion is enabled.

Definition at line 410 of file approximationScheme.h.

enabled_max_time_

bool gum::ApproximationScheme::enabled_max_time_

protectedinherited

If true, the timeout is enabled.

Definition at line 404 of file approximationScheme.h.

enabled_min_rate_eps_

bool gum::ApproximationScheme::enabled_min_rate_eps_

protectedinherited

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

Definition at line 398 of file approximationScheme.h.

eps_

double gum::ApproximationScheme::eps_

protectedinherited

Threshold for convergence.

Definition at line 389 of file approximationScheme.h.

errorPQ_

template<typename GUM_SCALAR >

Size gum::BNdistance< GUM_SCALAR >::errorPQ_

protectedinherited

Definition at line 149 of file BNdistance.h.

errorQP_

template<typename GUM_SCALAR >

Size gum::BNdistance< GUM_SCALAR >::errorQP_

protectedinherited

Definition at line 150 of file BNdistance.h.

hardEv_

template<typename GUM_SCALAR >

const NodeProperty< Idx >* gum::GibbsOperator< GUM_SCALAR >::hardEv_

protectedinherited

Definition at line 83 of file gibbsOperator.h.

hellinger_

template<typename GUM_SCALAR >

GUM_SCALAR gum::BNdistance< GUM_SCALAR >::hellinger_

protectedinherited

Definition at line 145 of file BNdistance.h.

history_

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

protectedinherited

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

Definition at line 386 of file approximationScheme.h.

jsd_

template<typename GUM_SCALAR >

GUM_SCALAR gum::BNdistance< GUM_SCALAR >::jsd_

protectedinherited

Definition at line 147 of file BNdistance.h.

klPQ_

template<typename GUM_SCALAR >

GUM_SCALAR gum::BNdistance< GUM_SCALAR >::klPQ_

protectedinherited

Definition at line 143 of file BNdistance.h.

klQP_

template<typename GUM_SCALAR >

GUM_SCALAR gum::BNdistance< GUM_SCALAR >::klQP_

protectedinherited

Definition at line 144 of file BNdistance.h.

last_epsilon_

double gum::ApproximationScheme::last_epsilon_

protectedinherited

Last epsilon value.

Definition at line 371 of file approximationScheme.h.

max_iter_

Size gum::ApproximationScheme::max_iter_

protectedinherited

The maximum iterations.

Definition at line 407 of file approximationScheme.h.

max_time_

double gum::ApproximationScheme::max_time_

protectedinherited

The timeout.

Definition at line 401 of file approximationScheme.h.

min_rate_eps_

double gum::ApproximationScheme::min_rate_eps_

protectedinherited

Threshold for the epsilon rate.

Definition at line 395 of file approximationScheme.h.

nbr_

template<typename GUM_SCALAR >

Size gum::GibbsOperator< GUM_SCALAR >::nbr_

protectedinherited

Definition at line 86 of file gibbsOperator.h.

onProgress

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

inherited

Progression, error and time.

Definition at line 58 of file IApproximationSchemeConfiguration.h.

onStop

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

inherited

Criteria messageApproximationScheme.

Definition at line 61 of file IApproximationSchemeConfiguration.h.

p_

template<typename GUM_SCALAR >

const IBayesNet< GUM_SCALAR >& gum::BNdistance< GUM_SCALAR >::p_

protectedinherited

Definition at line 140 of file BNdistance.h.

period_size_

Size gum::ApproximationScheme::period_size_

protectedinherited

Checking criteria frequency.

Definition at line 416 of file approximationScheme.h.

q_

template<typename GUM_SCALAR >

const IBayesNet< GUM_SCALAR >& gum::BNdistance< GUM_SCALAR >::q_

protectedinherited

Definition at line 141 of file BNdistance.h.

sampling_bn_

template<typename GUM_SCALAR >

const IBayesNet< GUM_SCALAR >& gum::GibbsOperator< GUM_SCALAR >::sampling_bn_

protectedinherited

Definition at line 82 of file gibbsOperator.h.

samplingNodes_

template<typename GUM_SCALAR >

Sequence< NodeId > gum::GibbsOperator< GUM_SCALAR >::samplingNodes_

protectedinherited

Definition at line 84 of file gibbsOperator.h.

timer_

Timer gum::ApproximationScheme::timer_

protectedinherited

The timer.

Definition at line 380 of file approximationScheme.h.

verbosity_

bool gum::ApproximationScheme::verbosity_

protectedinherited

If true, verbosity is enabled.

Definition at line 419 of file approximationScheme.h.

---

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

• agrum/BN/algorithms/divergence/GibbsBNdistance.h
• agrum/BN/algorithms/divergence/GibbsKL_tpl.h