gum::KTBNInference< GUM_SCALAR > Class Template Reference

Exact inference on a gum::KTBN with observations and interventions, by the interface algorithm. More...

#include <agrum/KTBN/inference/KTBNInference.h>

Collaboration diagram for gum::KTBNInference< GUM_SCALAR >:

Classes
struct	_Series_
	A cached marginal time-series for one base: owned variable descriptors paired with their marginals, indexed by slice (single entry for an atemporal base). Descriptors are owned so tensors get a stable per-slice name rather than the reused ring-slot name they came from. More...
struct	_Slot_
	One node of a window template: a base (index into baseNames) at a lag behind the window's current slice. lag == ATEMPORAL marks an atemporal base, which sits in every interface and never ages. More...
struct	_Window_
	A compiled window: the junction tree of \(H_t = I_{t-1} \cup V_t\), rooted at the clique holding \(I_t\), plus everything needed to fill and message-pass it. Built once; windows 0..k-2 are the initial ones, window k-1 is the repeating one, re-entered from slice k-1 on. More...

Public Types
using	NodeKey = std::variant< std::string, std::pair< std::string, int > >
	A node designated either by its engine name ("X[2]", "C") or by its (base, slice) identity.

Public Member Functions
Constructors / Destructor
	KTBNInference (const KTBN< GUM_SCALAR > *ktbn)
	Constructor.
	~KTBNInference ()=default
	Destructor.
	KTBNInference (const KTBNInference< GUM_SCALAR > &)=delete
	Copy is disabled (owns per-run variable descriptors and cached tensors).
KTBNInference< GUM_SCALAR > &	operator= (const KTBNInference< GUM_SCALAR > &)=delete
	Constructor.
Interventions
void	addIntervention (std::string_view base, int slice, const KTBNModality &value)
	Records a hard intervention \(do(base[slice]=value)\).
void	addIntervention (std::string_view node_name, const KTBNModality &value)
	Same, using an engine name ("X[2]", "C", …).
void	addIntervention (const std::vector< std::pair< NodeKey, KTBNModality > > &interventions)
	Records several interventions in one call.
void	eraseIntervention (std::string_view base, int slice)
	Removes a recorded intervention (silent no-op if absent).
void	eraseIntervention (std::string_view node_name)
	Same, using an engine name ("X[2]", "C", …).
void	clearInterventions ()
	Removes all recorded interventions.
bool	hasIntervention (std::string_view base, int slice) const
bool	hasIntervention (std::string_view node_name) const
	Same, using an engine name ("X[2]", "C", …).
Observations
void	addObservation (std::string_view base, int slice, const KTBNModality &value)
	Records a hard observation \(base[slice]=value\).
void	addObservation (std::string_view node_name, const KTBNModality &value)
	Same, using an engine name ("X[2]", "C", …).
void	addObservation (std::string_view base, int slice, const std::vector< GUM_SCALAR > &likelihood)
	Records a soft (likelihood) observation on \(base[slice]\).
void	addObservation (std::string_view node_name, const std::vector< GUM_SCALAR > &likelihood)
	Same, using an engine name ("X[2]", "C", …).
void	addObservations (const std::vector< std::pair< NodeKey, KTBNModality > > &observations)
	Records several observations in one call, all-or-nothing.
void	eraseObservation (std::string_view base, int slice)
	Removes a recorded observation (silent no-op if absent).
void	eraseObservation (std::string_view node_name)
	Same, using an engine name ("X[2]", "C", …).
void	clearObservation ()
	Removes all recorded observations.
bool	hasObservation (std::string_view base, int slice) const
bool	hasObservation (std::string_view node_name) const
	Same, using an engine name ("X[2]", "C", …).
bool	hasObservation () const
Targets
void	addTarget (std::string_view base)
	Declares a target: a base variable whose marginals we want.
void	eraseTarget (std::string_view base)
	Removes a target; when the last one is removed, default-all-targets mode is restored.
void	clearTargets ()
	Removes all targets (restores default-all-targets mode).
bool	isTarget (std::string_view base) const
bool	isInTargetMode () const
Inference
void	makeInference (Size nbTimeSlices)
	Runs the interface algorithm over nbTimeSlices slices ( \(0..nbTimeSlices-1\)) and caches, for every targeted base, its marginal at every slice.
const Tensor< GUM_SCALAR > &	posterior (std::string_view base, int slice)
	Returns \(P(base[slice] \mid \text{obs}, do(\cdot))\).
const Tensor< GUM_SCALAR > &	posterior (std::string_view node_name)
	Same, using an engine name ("X[2]", "C", …).
const std::vector< Tensor< GUM_SCALAR > > &	posteriors (std::string_view base)
	The whole marginal time-series of a targeted base: tensors[t] is \(P(base[t] \mid \cdot)\) for \(t = 0..T-1\) (a single-element vector, holding the atemporal marginal, for an atemporal base).
GUM_SCALAR	logObservationProbability ()
	\(\log P(\text{obs} \mid do(\cdot))\) for the last run: the likelihood of the observations under the (possibly mutilated) model. 0 when nothing is observed. Lazily (re)runs makeInference() if out of date.
GUM_SCALAR	observationProbability ()
	\(P(\text{obs} \mid do(\cdot))\), i.e. exp of logObservationProbability(). Underflows to 0 on long horizons; prefer the log form.
Various
const KTBN< GUM_SCALAR > &	ktbn () const
std::string	toString () const
const JunctionTree &	windowJunctionTree () const
	The junction tree of the repeating window – the one compiled from the k-slice template and re-entered at every step from slice \(k-1\) on. Introspection only.
Size	interfaceSize () const
	Size of the forward interface of the repeating window: how many node occurrences have to cross each slice boundary. Introspection only.

Static Public Attributes
static constexpr int	ATEMPORAL = KTBN< GUM_SCALAR >::ATEMPORAL
	Convenience alias for the atemporal-slice sentinel.

Private Member Functions
Size	_psiKey_ (int t) const
	Cache slot for slice t: the initial slices keep their own, the repeating window contributes one per phase.
Runtime
const _Window_ &	_windowAt_ (int t) const
	The window for absolute slice t: its own while t is inside the initial block, the repeating one (index k) from then on.
const std::unordered_map< NodeId, Tensor< GUM_SCALAR > > &	_windowPotentials_ (const _Window_ &w, int t) const
	Clique potentials of the window at slice t: every requisite family's CPT (or, under an intervention, a point mass severing it from its causes), times every observation's likelihood.
void	_applyTemporalObservations_ (const _Window_ &w, int t, std::unordered_map< NodeId, Tensor< GUM_SCALAR > > &psi) const
	Multiplies slice t's temporal observation likelihoods into an already-built base. Atemporal ones are skipped: the base holds them.
void	_fillWindow_ (const _Window_ &w, int t, std::unordered_map< NodeId, Tensor< GUM_SCALAR > > &psi, bool withTemporalEvidence=true) const
void	_propagate_ (const _Window_ &w, int t, const std::unordered_map< NodeId, Tensor< GUM_SCALAR > > &psi, const Tensor< GUM_SCALAR > *inPrev, const Tensor< GUM_SCALAR > *inNext, bool distribute, std::map< std::pair< NodeId, NodeId >, Tensor< GUM_SCALAR > > &msgs) const
	Shafer-Shenoy pass over a filled window. inPrev / inNext are the interface messages arriving at rootD / rootC (null when absent); division-free, so deterministic potentials need no special casing.
Tensor< GUM_SCALAR >	_belief_ (const _Window_ &w, const std::unordered_map< NodeId, Tensor< GUM_SCALAR > > &psi, const std::map< std::pair< NodeId, NodeId >, Tensor< GUM_SCALAR > > &msgs, const Tensor< GUM_SCALAR > *inPrev, const Tensor< GUM_SCALAR > *inNext, NodeId c, NodeId skipNeighbour) const
	The belief of clique c: its potential times every message reaching it, interface messages included.
void	_snapshot_ (const std::string &base, int slice, const Tensor< GUM_SCALAR > &marginal)
	Snapshots marginal onto an owned, stably-named descriptor and appends it to that base's series (index == slice for a temporal base). Positional fillWith, not name-matched: marginal's axis is a shared ring object, reused across residue-k slices, whose name generally isn't base[slice].
const _Series_ &	_series_ (const std::string &base)
	The cached series of a targeted base, running makeInference() lazily (with the last horizon) if out of date. Shared by both accessors.

Private Attributes
const KTBN< GUM_SCALAR > *	_ktbn_
	The k-DBN (referenced, not owned).
int	_k_
	The order k, cached as int for slice arithmetic.
std::map< std::string, Idx >	_interventions_
	Recorded interventions, keyed by engine name -> forced value.
std::map< std::string, std::vector< GUM_SCALAR > >	_observations_
	Recorded observations, keyed by engine name -> likelihood vector (one-hot for a hard observation).
std::set< std::string >	_targets_
	Recorded targets (base names). Empty <=> default-all-targets mode.
bool	_targeted_mode_ {false}
	Whether at least one explicit target has been declared.
Size	_horizon_ {0}
	Horizon (nbTimeSlices) of the last/next run; 0 <=> makeInference never run.
bool	_done_ {false}
	Whether the cached posteriors are up to date.
GUM_SCALAR	_logObservation_ {0}
	log P(observation | do) of the last run.
std::unordered_map< std::string, _Series_ >	_posteriors_
	Cached marginal series of the last run, keyed by base name.
std::vector< std::string >	_temporalSorted_
	Temporal / atemporal base names in a deterministic (sorted) order, cached once at construction (the KTBN's own sets are unordered).
std::vector< std::string >	_atemporalSorted_
std::vector< std::string >	_baseNames_
	All bases: temporal first (indices 0.._nbTemporal_-1), then atemporal. Window slots index into this.
std::size_t	_nbTemporal_ {0}
std::unordered_map< std::string, int >	_baseIdx_
	name -> index into baseNames
std::vector< int >	_maxLag_
	maxLag[i]: largest lag at which the transition kernel still consumes temporal base i – how long an occurrence must stay in the interface, which is what makes |I| finite and the window template time-invariant.
std::vector< _Window_ >	_windows_
	The compiled windows: index t for t <= k-2 (initial), index k-1 for the repeating window, reused by every slice from k-1 on. Built once.
std::vector< bool >	_requisite_
	Bases actually folded by the current run: the targets, the observed nodes and all their ancestors. Rebuilt per makeInference() from the current target/observation sets; anything outside is barren and cannot move an answer.
std::vector< std::unordered_map< NodeId, Tensor< GUM_SCALAR > > >	_psiCache_
	Memoized clique potentials for the slices that carry no temporal evidence, indexed by psiKey(t). Sized 2k: the k initial slices have their own windows and their own CPTs, the repeating one contributes k phases. O(k) whatever the horizon – unlike keeping one per slice, which would make smoothing grow linearly in T.
std::vector< bool >	_psiCached_
std::unordered_set< int >	_observationSlices_
	Slices carrying a temporal observation. Their potentials are the periodic ones times that slice's likelihood, so they are served by copying the cached base and multiplying the evidence in – cheaper than a rebuild, which would redo the unit fill and every CPT product.
std::unordered_set< int >	_interventionSlices_
	Slices carrying a temporal intervention. These need a full rebuild: do(X=x) replaces the node's CPT, which the cached base has already multiplied in, so the base is unusable rather than merely incomplete. Atemporal evidence appears in neither set – it applies at every slice alike and so belongs to the periodic structure.
std::unordered_map< NodeId, Tensor< GUM_SCALAR > >	_psiScratch_
	Potentials of an evidence-carrying slice, rebuilt on each visit.
std::map< std::pair< std::string, int >, Tensor< GUM_SCALAR > >	_kernelCache_
	Memoized transition kernels, keyed by (process, t % k).

Structural helpers
bool	_isTemporal_ (const std::string &base) const
bool	_isAtemporal_ (const std::string &base) const
std::pair< std::string, int >	_determineNode_ (const std::string &name) const
	Cache-aware classification of an engine name -> (base, slice): a name registered as atemporal (incl. bracket-shaped) maps to ATEMPORAL, every other name is parsed syntactically. Mirrors KTBN::determineNode.
void	_validateNode_ (const std::string &base, int slice) const
	Validates that (base, slice) denotes a legal node (future slices ok).
const DiscreteVariable &	_templateVar_ (const std::string &base, int slice) const
	A representative template variable of base for domain/cloning.
const DiscreteVariable *	_varOfSlot_ (const _Slot_ &s, int t) const
	The variable a window slot stands for at absolute slice t: ring slot \((t-\text{lag}) \bmod k\) for a temporal base, the atemporal object otherwise. This is where "advance one slice" happens – a relabelling, not an allocation.
const Tensor< GUM_SCALAR > &	_buildKernel_ (const std::string &p, int t) const
	Transition-kernel tensor of process p at slice t ( \(t \geq k\)): the template kernel remapped onto the k-DBN's own per-slice objects, reused via slice % k (no allocation).
std::vector< _Slot_ >	_familySlots_ (int baseIdx, int t) const
	Parents of base at a window whose current slice is t, as slots (lag = t - parentSlice). Uses the initial CPT structure for \(t \leq k-2\), the transition kernel from \(k-1\) on – which is why the repeating window is compiled from slice k-1's families.
std::vector< _Slot_ >	_interfaceAfter_ (int t) const
	The forward interface after slice t, as slots relative to t: every requisite occurrence at a slice \(\leq t\) still coupled to the future, plus every requisite atemporal base. From \(t=k-2\) on this is the steady \(\{(p,\delta): \delta < maxLag(p)\}\) – why one repeating window suffices.
int	_lastConsumerSlice_ (int baseIdx, int s) const
	The last slice at which occurrence base[s] is still consumed (-1 if never), over both the initial families and the transition kernel.
void	_buildWindows_ ()
	Compiles the k window junction trees, once, from the constructor: moralise each window's families, force \(I_{t-1}\) and \(I_t\) into cliques, triangulate, root at \(C_t\), and assign every family factor to a clique that covers it.
_Window_	_compileWindow_ (const std::vector< _Slot_ > &Iprev, const std::vector< _Slot_ > &Icur, int t, bool withAtemporalFamilies) const
	Compiles one window over the given slot set / interfaces.
void	_markRequisite_ ()
	Marks the requisite bases of the current run (targets, observed bases and all their ancestors) into requisite.
static std::string	_encode_ (const std::string &base, int slice)
	Encodes (base, slice) -> engine name (base[slice] or bare base).

Detailed Description

template<GUM_Numeric GUM_SCALAR>
class gum::KTBNInference< GUM_SCALAR >

Exact inference on a gum::KTBN with observations and interventions, by the interface algorithm.

Usage

KTBNInference<double> ie(&ktbn);
ie.addObservation("Y", 3, 1);            // observe Y[3]=1
ie.addIntervention("X", 2, 1);        // do(X[2]=1)
ie.addTarget("X");                    // want the whole P(X[t] | ...) series
ie.makeInference(10);                 // compute slices 0..9
const Tensor<double>&              p3 = ie.posterior("X", 3);
const std::vector<Tensor<double>>& px = ie.posteriors("X");
double logpe = ie.logObservationProbability();

Targets (the query)

A target is a base variable (temporal or atemporal) whose marginals you want. makeInference(T) computes, for every targeted temporal base, its marginal at every slice \(0..T-1\) (a single entry at ATEMPORAL for an atemporal base). With none declared, every base is a target (mirrors gum::MarginalTargetedInference's default-all-targets mode). Declaring targets restricts the roll to the requisite subnetwork – the targets, the observed nodes, and their ancestors; everything else is barren. posterior()/posteriors() throw for anything not a target.

Warning

The KTBN is referenced, not copied (aGrUM's rule); it must outlive the inference engine.

Definition at line 147 of file KTBNInference.h.

Member Typedef Documentation

NodeKey

template<GUM_Numeric GUM_SCALAR>

using gum::KTBNInference< GUM_SCALAR >::NodeKey = std::variant< std::string, std::pair< std::string, int > >

A node designated either by its engine name ("X[2]", "C") or by its (base, slice) identity.

Definition at line 175 of file KTBNInference.h.

Constructor & Destructor Documentation

KTBNInference() [1/2]

template<GUM_Numeric GUM_SCALAR>

gum::KTBNInference< GUM_SCALAR >::KTBNInference ( const KTBN< GUM_SCALAR > * ktbn )

explicit

Constructor.

Parameters

ktbn	The k-DBN to reason about (referenced, not copied).

Exceptions

InvalidArgument

if ktbn is null.

Definition at line 74 of file KTBNInference_tpl.h.

                                                                           : _ktbn_(ktbn) {
    if (ktbn == nullptr) GUM_ERROR(InvalidArgument, "KTBNInference: the k-DBN is null.")
    _k_ = static_cast< int >(ktbn->k());
 
    // a deterministic base order (the KTBN's own sets are unordered): temporal
    // first, then atemporal, so a slot's base index alone says which it is.
    _temporalSorted_.assign(ktbn->temporalVarNames().begin(), ktbn->temporalVarNames().end());
    std::sort(_temporalSorted_.begin(), _temporalSorted_.end());
    _atemporalSorted_.assign(ktbn->atemporalVarNames().begin(), ktbn->atemporalVarNames().end());
    std::sort(_atemporalSorted_.begin(), _atemporalSorted_.end());
 
    _baseNames_  = _temporalSorted_;
    _nbTemporal_ = _baseNames_.size();
    _baseNames_.insert(_baseNames_.end(), _atemporalSorted_.begin(), _atemporalSorted_.end());
    for (std::size_t i = 0; i < _baseNames_.size(); ++i)
      _baseIdx_[_baseNames_[i]] = static_cast< int >(i);
 
    // compile windows for the default (all-bases) query; _markRequisite_()
    // recompiles only if a later target/observation set changes the subset
    _requisite_.assign(_baseNames_.size(), true);
    _buildWindows_();
  }

References _atemporalSorted_, _baseIdx_, _baseNames_, _buildWindows_(), _k_, _ktbn_, _nbTemporal_, _requisite_, _temporalSorted_, GUM_ERROR, and ktbn().

Referenced by KTBNInference(), and operator=().

Here is the call graph for this function:

Here is the caller graph for this function:

~KTBNInference()

template<GUM_Numeric GUM_SCALAR>

gum::KTBNInference< GUM_SCALAR >::~KTBNInference ( )

default

Destructor.

KTBNInference() [2/2]

template<GUM_Numeric GUM_SCALAR>

gum::KTBNInference< GUM_SCALAR >::KTBNInference ( const KTBNInference< GUM_SCALAR > & )

delete

Copy is disabled (owns per-run variable descriptors and cached tensors).

References KTBNInference().

Here is the call graph for this function:

Member Function Documentation

_applyTemporalObservations_()

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::_applyTemporalObservations_ ( const _Window_ & w, int t, std::unordered_map< NodeId, Tensor< GUM_SCALAR > > & psi ) const

private

Multiplies slice t's temporal observation likelihoods into an already-built base. Atemporal ones are skipped: the base holds them.

Definition at line 761 of file KTBNInference_tpl.h.

                                                                   {
    for (const auto& [c, bases]: w.factorsOf)
      for (const int b: bases) {
        if (b >= static_cast< int >(_nbTemporal_)) continue;   // atemporal: already in the base
        const auto ite = _observations_.find(_encode_(_baseNames_[b], t));
        if (ite == _observations_.end()) continue;
        Tensor< GUM_SCALAR > ev;
        ev << _ktbn_->variable(_baseNames_[b], t % _k_);
        ev.fillWith(ite->second);
        psi.at(c) *= ev;
      }
  }

References _baseNames_, _encode_(), _k_, _ktbn_, _nbTemporal_, _observations_, and gum::KTBNInference< GUM_SCALAR >::_Window_::factorsOf.

Referenced by _windowPotentials_().

Here is the call graph for this function:

Here is the caller graph for this function:

_belief_()

template<GUM_Numeric GUM_SCALAR>

Tensor< GUM_SCALAR > gum::KTBNInference< GUM_SCALAR >::_belief_ ( const _Window_ & w, const std::unordered_map< NodeId, Tensor< GUM_SCALAR > > & psi, const std::map< std::pair< NodeId, NodeId >, Tensor< GUM_SCALAR > > & msgs, const Tensor< GUM_SCALAR > * inPrev, const Tensor< GUM_SCALAR > * inNext, NodeId c, NodeId skipNeighbour ) const

private

The belief of clique c: its potential times every message reaching it, interface messages included.

Definition at line 892 of file KTBNInference_tpl.h.

                                                                                       {
    Tensor< GUM_SCALAR > out = psi.at(c);
    for (const NodeId n: w.jt.neighbours(c)) {
      if (n == skip) continue;
      const auto it = msgs.find({n, c});
      if (it != msgs.end()) out *= it->second;
    }
    // the two virtual leaves: past hangs off D_t, future off C_t. Leaving one
    // out is how Shafer-Shenoy avoids echoing a message back -- no division needed
    if (inPrev != nullptr && c == w.rootD && skip != KTBN_SKIP_PREV) out *= *inPrev;
    if (inNext != nullptr && c == w.rootC && skip != KTBN_SKIP_NEXT) out *= *inNext;
    return out;
  }

References gum::KTBNInference< GUM_SCALAR >::_Window_::jt, gum::EdgeGraphPart::neighbours(), gum::KTBNInference< GUM_SCALAR >::_Window_::rootC, and gum::KTBNInference< GUM_SCALAR >::_Window_::rootD.

Referenced by _propagate_(), and makeInference().

Here is the call graph for this function:

Here is the caller graph for this function:

_buildKernel_()

template<GUM_Numeric GUM_SCALAR>

const Tensor< GUM_SCALAR > & gum::KTBNInference< GUM_SCALAR >::_buildKernel_ ( const std::string & p, int t ) const

private

Transition-kernel tensor of process p at slice t ( \(t \geq k\)): the template kernel remapped onto the k-DBN's own per-slice objects, reused via slice % k (no allocation).

Memoized in kernelCache: the result depends on t only through t % k, so at most \(k\) tensors exist per process however long the horizon. Returns a reference into the cache – valid until the next makeInference(), which clears it.

Definition at line 725 of file KTBNInference_tpl.h.

                                                                                      {
    // The result depends on t only through t % k -- for the child directly, and
    // for each parent as (t - lag) % k, which is fixed once t % k is. So one
    // tensor per (process, phase) serves every slice of that phase.
    const std::pair< std::string, int > key{p, static_cast< int >(t % _k_)};
    const auto                          hit = _kernelCache_.find(key);
    if (hit != _kernelCache_.end()) return hit->second;
 
    // Builds P(p[t] | its absolute-time parents) by rolling the template
    // kernel P(p[k-1] | parents) forward onto slice t. The kernel's own axes
    // use ABSOLUTE-slice identity (variable(base, slice % k), the KTBN's
    // cycled per-process objects); srcNames uses the TEMPLATE's time-invariant
    // names, only to pick which axis of cpt(p, k-1) to copy from -- fillWith's
    // mapSrc maps by position, not name, so the two need not match.
    Tensor< GUM_SCALAR >       kernel;
    std::vector< std::string > srcNames;
 
    kernel << _ktbn_->variable(p, t % _k_);
    srcNames.push_back(_encode_(p, _k_ - 1));
 
    for (const auto& [parBase, parSlice]: _ktbn_->parents(p, _k_ - 1)) {
      if (parSlice == ATEMPORAL) {
        kernel << _ktbn_->variable(parBase, ATEMPORAL);
        srcNames.push_back(parBase);
      } else {
        const int lag = (_k_ - 1) - parSlice;
        kernel << _ktbn_->variable(parBase, (t - lag) % _k_);
        srcNames.push_back(_encode_(parBase, parSlice));
      }
    }
    kernel.fillWith(_ktbn_->cpt(p, _k_ - 1), srcNames);
    return _kernelCache_.emplace(key, std::move(kernel)).first->second;
  }

References _encode_(), _k_, _kernelCache_, _ktbn_, and ATEMPORAL.

Referenced by _fillWindow_().

Here is the call graph for this function:

Here is the caller graph for this function:

_buildWindows_()

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::_buildWindows_ ( )

private

Compiles the k window junction trees, once, from the constructor: moralise each window's families, force \(I_{t-1}\) and \(I_t\) into cliques, triangulate, root at \(C_t\), and assign every family factor to a clique that covers it.

Definition at line 634 of file KTBNInference_tpl.h.

                                                   {
    // how long an occurrence must survive: the deepest lag the requisite
    // kernel still reads it at -- what bounds |I|
    _maxLag_.assign(_nbTemporal_, 0);
    for (int c = 0; c < static_cast< int >(_nbTemporal_); ++c) {
      if (!_requisite_[c]) continue;
      for (const auto& [pb, ps]: _ktbn_->parents(_baseNames_[c], _k_ - 1)) {
        if (ps == ATEMPORAL) continue;
        const int i   = _baseIdx_.at(pb);
        const int lag = (_k_ - 1) - ps;
        if (lag >= 1 && lag > _maxLag_[i]) _maxLag_[i] = lag;
      }
    }
 
    const auto shift = [](std::vector< _Slot_ > v) {
      for (auto& s: v)
        if (s.lag != ATEMPORAL) ++s.lag;
      return v;
    };
 
    // windows 0..k-1 cover slices 0..k-1; window k is the repeating one, used
    // from slice k on. For k>=2, k-1 and k are structurally identical, so the
    // extra compile is free; for k==1 they must differ, since slice 0 alone
    // carries the atemporal layer in.
    _windows_.clear();
    _windows_.reserve(_k_ + 1);
    std::vector< _Slot_ > prev;   // I_{t-1}, in slice-t coordinates
    for (int t = 0; t <= _k_; ++t) {
      std::vector< _Slot_ > cur = _interfaceAfter_(t);
      _windows_.push_back(_compileWindow_(prev, cur, t, /*withAtemporalFamilies=*/t == 0));
      prev = shift(std::move(cur));
    }
  }

References _baseIdx_, _baseNames_, _compileWindow_(), _interfaceAfter_(), _k_, _ktbn_, _maxLag_, _nbTemporal_, _requisite_, _windows_, and ATEMPORAL.

Referenced by KTBNInference(), and _markRequisite_().

Here is the call graph for this function:

Here is the caller graph for this function:

_compileWindow_()

template<GUM_Numeric GUM_SCALAR>

KTBNInference< GUM_SCALAR >::_Window_ gum::KTBNInference< GUM_SCALAR >::_compileWindow_ ( const std::vector< _Slot_ > & Iprev, const std::vector< _Slot_ > & Icur, int t, bool withAtemporalFamilies ) const

private

Compiles one window over the given slot set / interfaces.

Definition at line 458 of file KTBNInference_tpl.h.

                                                                                     {
    _Window_ w;
    w.Iprev = Iprev;
    w.Icur  = Icur;
 
    // ---- node set: H_t = I_{t-1} U V_t (plus the atemporal layer at t == 0) --
    std::map< std::pair< int, int >, NodeId > id;
    UndiGraph                                 graph;
    NodeProperty< Size >                      domSizes;
 
    const auto ensure = [&](const _Slot_& s) -> NodeId {
      const auto key = std::make_pair(s.base, s.lag);
      const auto it  = id.find(key);
      if (it != id.end()) return it->second;
      const NodeId nid = graph.addNode();
      id[key]          = nid;
      if (static_cast< std::size_t >(nid) >= w.slotOfNode.size()) w.slotOfNode.resize(nid + 1);
      w.slotOfNode[nid] = s;
      domSizes.insert(nid,
                      (s.lag == ATEMPORAL)
                          ? _ktbn_->variable(_baseNames_[s.base], ATEMPORAL).domainSize()
                          : _ktbn_->variable(_baseNames_[s.base], _k_ - 1).domainSize());
      return nid;
    };
 
    for (const auto& s: Iprev)
      ensure(s);
    for (int i = 0; i < static_cast< int >(_nbTemporal_); ++i)
      if (_requisite_[i]) ensure({i, 0});
    if (withAtemporalFamilies)
      for (int i = static_cast< int >(_nbTemporal_); i < static_cast< int >(_baseNames_.size());
           ++i)
        if (_requisite_[i]) ensure({i, ATEMPORAL});
    for (const auto& s: Icur)
      ensure(s);
 
    if (graph.size() == 0) return w;   // nothing requisite: an empty window
 
    // ---- moralise: every family becomes a clique ----------------------------
    std::vector< std::pair< int, std::vector< NodeId > > > families;
    const auto                                             addFamily = [&](int b) {
      std::vector< NodeId > scope;
      for (const auto& s: _familySlots_(b, t))
        scope.push_back(ensure(s));
      for (std::size_t a = 0; a < scope.size(); ++a)
        for (std::size_t c = a + 1; c < scope.size(); ++c)
          if (!graph.existsEdge(scope[a], scope[c])) graph.addEdge(scope[a], scope[c]);
      families.emplace_back(b, std::move(scope));
    };
    for (int i = 0; i < static_cast< int >(_nbTemporal_); ++i)
      if (_requisite_[i]) addFamily(i);
    if (withAtemporalFamilies)
      for (int i = static_cast< int >(_nbTemporal_); i < static_cast< int >(_baseNames_.size());
           ++i)
        if (_requisite_[i]) addFamily(i);
 
    // ---- force each interface to be a clique --------------------------------
    // Murphy's constraint: one clique must hold the whole interface, so the
    // message crossing the slice boundary is a single potential.
    const auto makeClique = [&](const std::vector< _Slot_ >& slots) {
      std::vector< NodeId > ids;
      for (const auto& s: slots)
        ids.push_back(ensure(s));
      for (std::size_t a = 0; a < ids.size(); ++a)
        for (std::size_t c = a + 1; c < ids.size(); ++c)
          if (!graph.existsEdge(ids[a], ids[c])) graph.addEdge(ids[a], ids[c]);
    };
    makeClique(Iprev);
    makeClique(Icur);
 
    // ---- triangulate once; this tree is reused for every slice and horizon --
    DefaultTriangulation tri(&graph, &domSizes);
    w.jt = tri.junctionTree();
 
    const auto covers = [&](NodeId c, const std::vector< _Slot_ >& slots) {
      const NodeSet& cl = w.jt.clique(c);
      for (const auto& s: slots)
        if (!cl.contains(id.at({s.base, s.lag}))) return false;
      return true;
    };
 
    bool foundC = false, foundD = false;
    for (const NodeId c: w.jt.nodes()) {
      if (!foundC && covers(c, Icur)) {
        w.rootC = c;
        foundC  = true;
      }
      if (!foundD && covers(c, Iprev)) {
        w.rootD = c;
        foundD  = true;
      }
    }
    if (!foundC || !foundD)
      GUM_ERROR(FatalError, "KTBNInference: the window interfaces did not end up in a clique.")
 
    // ---- assign every family factor to one clique that covers it ------------
    for (const auto& [b, scope]: families) {
      bool placed = false;
      for (const NodeId c: w.jt.nodes()) {
        const NodeSet& cl = w.jt.clique(c);
        bool           ok = true;
        for (const NodeId n: scope)
          if (!cl.contains(n)) {
            ok = false;
            break;
          }
        if (ok) {
          w.factorsOf[c].push_back(b);
          placed = true;
          break;
        }
      }
      if (!placed)
        GUM_ERROR(FatalError, "KTBNInference: family of '" << _baseNames_[b] << "' fits no clique.")
    }
 
    // ---- where to read each base's own marginal (and place its observation) ----
    for (const auto& [key, nid]: id) {
      const int base = key.first;
      for (const NodeId c: w.jt.nodes())
        if (w.jt.clique(c).contains(nid)) {
          if (key.second == 0 || key.second == ATEMPORAL) w.selfClique[base] = c;
          break;
        }
    }
 
    // ---- stitch a junction FOREST into a junction tree ----------------------
    // Barren processes and unused atemporal variables sit in their own
    // components. Linking each to C_t with an EMPTY separator makes one tree
    // without touching any marginal -- the crossing message is just a scalar.
    {
      std::unordered_map< NodeId, int > comp;
      int                               nc = 0;
      for (const NodeId s: w.jt.nodes()) {
        if (comp.count(s) != 0) continue;
        std::vector< NodeId > q{s};
        comp[s] = nc;
        for (std::size_t i = 0; i < q.size(); ++i)
          for (const NodeId nb: w.jt.neighbours(q[i]))
            if (comp.count(nb) == 0) {
              comp[nb] = nc;
              q.push_back(nb);
            }
        ++nc;
      }
      if (nc > 1) {
        std::unordered_set< int > linked{comp.at(w.rootC)};
        for (const NodeId n: w.jt.nodes())
          if (linked.insert(comp.at(n)).second) w.jt.addEdge(w.rootC, n);
      }
    }
 
    // ---- root the tree at C_t and record a BFS order ------------------------
    std::unordered_set< NodeId > seen;
    w.bfs.push_back(w.rootC);
    seen.insert(w.rootC);
    w.parentOf[w.rootC] = w.rootC;
    for (std::size_t qi = 0; qi < w.bfs.size(); ++qi) {
      const NodeId cur = w.bfs[qi];
      for (const NodeId nb: w.jt.neighbours(cur))
        if (seen.insert(nb).second) {
          w.parentOf[nb] = cur;
          w.bfs.push_back(nb);
        }
    }
    // the forced interface cliques rule out a disconnected forest; assert it anyway
    if (w.bfs.size() != w.jt.size())
      GUM_ERROR(FatalError, "KTBNInference: the window junction tree is not connected.")
 
    return w;
  }

References _baseNames_, _familySlots_(), _k_, _ktbn_, _nbTemporal_, _requisite_, gum::CliqueGraph::addEdge(), ATEMPORAL, gum::KTBNInference< GUM_SCALAR >::_Window_::bfs, gum::CliqueGraph::clique(), gum::Set< Key >::contains(), gum::KTBNInference< GUM_SCALAR >::_Window_::factorsOf, GUM_ERROR, gum::KTBNInference< GUM_SCALAR >::_Window_::Icur, gum::HashTable< Key, Val >::insert(), gum::KTBNInference< GUM_SCALAR >::_Window_::Iprev, gum::KTBNInference< GUM_SCALAR >::_Window_::jt, gum::StaticTriangulation::junctionTree(), gum::EdgeGraphPart::neighbours(), gum::NodeGraphPart::nodes(), gum::KTBNInference< GUM_SCALAR >::_Window_::parentOf, gum::KTBNInference< GUM_SCALAR >::_Window_::rootC, gum::KTBNInference< GUM_SCALAR >::_Window_::rootD, gum::KTBNInference< GUM_SCALAR >::_Window_::selfClique, gum::NodeGraphPart::size(), and gum::KTBNInference< GUM_SCALAR >::_Window_::slotOfNode.

Referenced by _buildWindows_().

Here is the call graph for this function:

Here is the caller graph for this function:

_determineNode_()

template<GUM_Numeric GUM_SCALAR>

std::pair< std::string, int > gum::KTBNInference< GUM_SCALAR >::_determineNode_ ( const std::string & name ) const

private

Cache-aware classification of an engine name -> (base, slice): a name registered as atemporal (incl. bracket-shaped) maps to ATEMPORAL, every other name is parsed syntactically. Mirrors KTBN::determineNode.

Definition at line 109 of file KTBNInference_tpl.h.

                                                                              {
    // a name registered as atemporal is atemporal, even if bracket-shaped
    if (_ktbn_->atemporalVarNames().find(name) != _ktbn_->atemporalVarNames().end())
      return {name, ATEMPORAL};
 
    // only a well-formed "base[digits]" suffix is temporal (mirrors
    // KTBN::_decodeName_); anything else falls through to atemporal
    const auto lb = name.rfind('[');
    if (lb == std::string::npos || name.back() != ']') return {name, ATEMPORAL};
 
    const std::string inner = name.substr(lb + 1, name.size() - lb - 2);
    if (inner.empty()) return {name, ATEMPORAL};
    for (const char c: inner)
      if (std::isdigit(static_cast< unsigned char >(c)) == 0) return {name, ATEMPORAL};
 
    int slice{};
    try {
      slice = std::stoi(inner);
    } catch (const std::out_of_range&) {
      GUM_ERROR(InvalidArgument,
                "Node name '" << name << "' has a slice index too large to represent as int.")
    }
    return {name.substr(0, lb), slice};
  }

References _ktbn_, ATEMPORAL, and GUM_ERROR.

Referenced by _markRequisite_(), addIntervention(), addIntervention(), addObservation(), addObservation(), addObservations(), eraseIntervention(), eraseObservation(), hasIntervention(), hasObservation(), makeInference(), and posterior().

Here is the caller graph for this function:

_encode_()

template<GUM_Numeric GUM_SCALAR>

std::string gum::KTBNInference< GUM_SCALAR >::_encode_ ( const std::string & base, int slice )

staticprivate

Encodes (base, slice) -> engine name (base[slice] or bare base).

Definition at line 102 of file KTBNInference_tpl.h.

                                                                                  {
    if (slice == ATEMPORAL) return base;
    return base + "[" + std::to_string(slice) + "]";
  }

References ATEMPORAL.

Referenced by _applyTemporalObservations_(), _buildKernel_(), _fillWindow_(), _snapshot_(), addIntervention(), addIntervention(), addObservation(), addObservation(), addObservations(), eraseIntervention(), eraseObservation(), hasIntervention(), and hasObservation().

Here is the caller graph for this function:

_familySlots_()

template<GUM_Numeric GUM_SCALAR>

std::vector< typename KTBNInference< GUM_SCALAR >::_Slot_ > gum::KTBNInference< GUM_SCALAR >::_familySlots_ ( int baseIdx, int t ) const

private

Parents of base at a window whose current slice is t, as slots (lag = t - parentSlice). Uses the initial CPT structure for \(t \leq k-2\), the transition kernel from \(k-1\) on – which is why the repeating window is compiled from slice k-1's families.

Definition at line 387 of file KTBNInference_tpl.h.

                                                                         {
    std::vector< _Slot_ > out;
    const std::string&    b = _baseNames_[baseIdx];
 
    if (baseIdx >= static_cast< int >(_nbTemporal_)) {
      out.push_back({baseIdx, ATEMPORAL});
      for (const auto& [pb, ps]: _ktbn_->parents(b, ATEMPORAL)) {
        (void)ps;
        out.push_back({_baseIdx_.at(pb), ATEMPORAL});
      }
      return out;
    }
 
    // initial CPTs while inside the initial block, else the (time-invariant)
    // transition kernel -- why one window template serves every later t
    const int structSlice = (t <= _k_ - 1) ? t : _k_ - 1;
    out.push_back({baseIdx, 0});
    for (const auto& [pb, ps]: _ktbn_->parents(b, structSlice)) {
      if (ps == ATEMPORAL) out.push_back({_baseIdx_.at(pb), ATEMPORAL});
      else out.push_back({_baseIdx_.at(pb), structSlice - ps});
    }
    return out;
  }

References _baseIdx_, _baseNames_, _k_, _ktbn_, _nbTemporal_, and ATEMPORAL.

Referenced by _compileWindow_().

Here is the caller graph for this function:

_fillWindow_()

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::_fillWindow_ ( const _Window_ & w, int t, std::unordered_map< NodeId, Tensor< GUM_SCALAR > > & psi, bool withTemporalEvidence = true ) const

private

Parameters

withTemporalEvidence

false builds the base: the periodic part only, i.e. CPTs/kernels plus atemporal evidence, with slice t's own observations and interventions left out. That is what psiCache stores.

Definition at line 813 of file KTBNInference_tpl.h.

                                                                                      {
    psi.clear();
 
    // every clique starts at the unit potential: even one that receives no
    // factor must contribute its variables' free mass to a summed-out message
    for (const NodeId c: w.jt.nodes()) {
      Tensor< GUM_SCALAR > p;
      for (const NodeId n: w.jt.clique(c))
        p << *_varOfSlot_(w.slotOfNode[n], t);
      p.fillWith(GUM_SCALAR(1));
      psi.emplace(c, std::move(p));
    }
 
    const auto applyBase = [&](int b, NodeId owner) {
      const std::string&      base  = _baseNames_[b];
      const bool              atemp = b >= static_cast< int >(_nbTemporal_);
      const std::string       name  = _encode_(base, atemp ? ATEMPORAL : t);
      const DiscreteVariable& var
          = atemp ? _ktbn_->variable(base, ATEMPORAL) : _ktbn_->variable(base, t % _k_);
 
      // do(base[t]=v): the point mass REPLACES the CPT, severing the node
      // from its own causes -- an observation never does this
      // In a base build the slice's own evidence is left out, so a temporal
      // node keeps its CPT and no likelihood is applied; atemporal evidence is
      // slice-independent and stays, being part of the periodic structure.
      const bool sliceEvidence = atemp || withTemporalEvidence;
 
      const auto itv = sliceEvidence ? _interventions_.find(name) : _interventions_.end();
      if (itv != _interventions_.end()) {
        psi.at(owner) *= Tensor< GUM_SCALAR >::deterministicTensor(var, itv->second);
      } else if (atemp) {
        psi.at(owner) *= _ktbn_->cpt(base, ATEMPORAL);
      } else if (t <= _k_ - 1) {
        psi.at(owner) *= _ktbn_->cpt(base, t);   // initial CPT: already on ring slots
      } else {
        psi.at(owner) *= _buildKernel_(base, t);
      }
 
      // base[t] observed: pure conditioning, multiplied in ON TOP of the CPT.
      const auto ite = sliceEvidence ? _observations_.find(name) : _observations_.end();
      if (ite != _observations_.end()) {
        Tensor< GUM_SCALAR > ev;
        ev << var;
        ev.fillWith(ite->second);
        psi.at(owner) *= ev;
      }
    };
 
    for (const auto& [c, bases]: w.factorsOf)
      for (const int b: bases)
        applyBase(b, c);
  }

References _baseNames_, _buildKernel_(), _encode_(), _interventions_, _k_, _ktbn_, _nbTemporal_, _observations_, _varOfSlot_(), ATEMPORAL, gum::CliqueGraph::clique(), gum::Tensor< GUM_SCALAR >::deterministicTensor(), gum::KTBNInference< GUM_SCALAR >::_Window_::factorsOf, gum::KTBNInference< GUM_SCALAR >::_Window_::jt, gum::NodeGraphPart::nodes(), and gum::KTBNInference< GUM_SCALAR >::_Window_::slotOfNode.

Referenced by _windowPotentials_().

Here is the call graph for this function:

Here is the caller graph for this function:

_interfaceAfter_()

template<GUM_Numeric GUM_SCALAR>

std::vector< typename KTBNInference< GUM_SCALAR >::_Slot_ > gum::KTBNInference< GUM_SCALAR >::_interfaceAfter_ ( int t ) const

private

The forward interface after slice t, as slots relative to t: every requisite occurrence at a slice \(\leq t\) still coupled to the future, plus every requisite atemporal base. From \(t=k-2\) on this is the steady \(\{(p,\delta): \delta < maxLag(p)\}\) – why one repeating window suffices.

Definition at line 442 of file KTBNInference_tpl.h.

                                                               {
    std::vector< _Slot_ > out;
    for (int i = 0; i < static_cast< int >(_nbTemporal_); ++i) {
      if (!_requisite_[i]) continue;
      for (int s = t; s >= 0 && t - s <= _k_ - 1; --s)
        if (_lastConsumerSlice_(i, s) > t) out.push_back({i, t - s});
    }
    // an atemporal variable is a parent at every slice, so it never leaves
    // the interface -- the one thing that couples the whole horizon
    for (int i = static_cast< int >(_nbTemporal_); i < static_cast< int >(_baseNames_.size()); ++i)
      if (_requisite_[i]) out.push_back({i, ATEMPORAL});
    return out;
  }

References _baseNames_, _k_, _lastConsumerSlice_(), _nbTemporal_, _requisite_, and ATEMPORAL.

Referenced by _buildWindows_().

Here is the call graph for this function:

Here is the caller graph for this function:

_isAtemporal_()

template<GUM_Numeric GUM_SCALAR>

INLINE bool gum::KTBNInference< GUM_SCALAR >::_isAtemporal_ ( const std::string & base ) const

private

Returns

whether base is an atemporal variable of the k-DBN.

Definition at line 881 of file KTBNInference_tpl.h.

                                                                                    {
    return _ktbn_->atemporalVarNames().find(base) != _ktbn_->atemporalVarNames().end();
  }

References _ktbn_.

Referenced by _validateNode_(), addTarget(), isTarget(), and posterior().

Here is the caller graph for this function:

_isTemporal_()

template<GUM_Numeric GUM_SCALAR>

INLINE bool gum::KTBNInference< GUM_SCALAR >::_isTemporal_ ( const std::string & base ) const

private

Returns

whether base is a temporal process of the k-DBN.

Definition at line 876 of file KTBNInference_tpl.h.

                                                                                   {
    return _ktbn_->temporalVarNames().find(base) != _ktbn_->temporalVarNames().end();
  }

References _ktbn_.

Referenced by _validateNode_(), addTarget(), and isTarget().

Here is the caller graph for this function:

_lastConsumerSlice_()

template<GUM_Numeric GUM_SCALAR>

int gum::KTBNInference< GUM_SCALAR >::_lastConsumerSlice_ ( int baseIdx, int s ) const

private

The last slice at which occurrence base[s] is still consumed (-1 if never), over both the initial families and the transition kernel.

Definition at line 412 of file KTBNInference_tpl.h.

                                                                               {
    int last = -1;
 
    // consumers inside the initial block (their parent sets are per-slice)
    for (int tc = 0; tc <= _k_ - 2; ++tc) {
      if (tc <= last) continue;
      for (int c = 0; c < static_cast< int >(_nbTemporal_); ++c) {
        if (!_requisite_[c]) continue;
        for (const auto& [pb, ps]: _ktbn_->parents(_baseNames_[c], tc)) {
          if (ps == ATEMPORAL) continue;
          if (ps == s && _baseIdx_.at(pb) == baseIdx) {
            last = tc;
            break;
          }
        }
        if (tc == last) break;
      }
    }
 
    // repeating block: the kernel reaches back _maxLag_ slices, so the last
    // consumer sits at s + maxLag
    if (_maxLag_[baseIdx] >= 1) {
      const int tc = s + _maxLag_[baseIdx];
      if (tc >= _k_ - 1 && tc > last) last = tc;
    }
    return last;
  }

References _baseIdx_, _baseNames_, _k_, _ktbn_, _maxLag_, _nbTemporal_, _requisite_, and ATEMPORAL.

Referenced by _interfaceAfter_().

Here is the caller graph for this function:

_markRequisite_()

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::_markRequisite_ ( )

private

Marks the requisite bases of the current run (targets, observed bases and all their ancestors) into requisite.

Definition at line 669 of file KTBNInference_tpl.h.

                                                    {
    std::vector< bool > req(_baseNames_.size(), false);
    std::vector< int >  stack;
 
    const auto push = [&](const std::string& b) {
      const auto it = _baseIdx_.find(b);
      if (it == _baseIdx_.end()) return;
      if (!req[it->second]) {
        req[it->second] = true;
        stack.push_back(it->second);
      }
    };
 
    if (!_targeted_mode_) {
      for (const auto& b: _baseNames_)
        push(b);
    } else {
      for (const auto& b: _targets_)
        push(b);
    }
    // an observed node is requisite even if barren: its likelihood is what
    // revises everything upstream of it.
    for (const auto& [name, like]: _observations_) {
      (void)like;
      push(_determineNode_(name).first);
    }
 
    while (!stack.empty()) {
      const int i = stack.back();
      stack.pop_back();
      const std::string& b = _baseNames_[i];
      if (i < static_cast< int >(_nbTemporal_)) {
        for (int t = 0; t <= _k_ - 1; ++t)
          for (const auto& [pb, ps]: _ktbn_->parents(b, t)) {
            (void)ps;
            push(pb);
          }
      } else {
        for (const auto& [pb, ps]: _ktbn_->parents(b, ATEMPORAL)) {
          (void)ps;
          push(pb);
        }
      }
    }
 
    if (req != _requisite_) {
      _requisite_ = std::move(req);
      _buildWindows_();
    }
  }

References _baseIdx_, _baseNames_, _buildWindows_(), _determineNode_(), _k_, _ktbn_, _nbTemporal_, _observations_, _requisite_, _targeted_mode_, _targets_, and ATEMPORAL.

Referenced by makeInference().

Here is the call graph for this function:

Here is the caller graph for this function:

_propagate_()

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::_propagate_ ( const _Window_ & w, int t, const std::unordered_map< NodeId, Tensor< GUM_SCALAR > > & psi, const Tensor< GUM_SCALAR > * inPrev, const Tensor< GUM_SCALAR > * inNext, bool distribute, std::map< std::pair< NodeId, NodeId >, Tensor< GUM_SCALAR > > & msgs ) const

private

Shafer-Shenoy pass over a filled window. inPrev / inNext are the interface messages arriving at rootD / rootC (null when absent); division-free, so deterministic potentials need no special casing.

Parameters

msgs	out: (from,to) clique message. Collect-only when distribute is false – enough for the forward message alone.

Definition at line 914 of file KTBNInference_tpl.h.

                                                                             {
    msgs.clear();
    if (w.bfs.empty()) return;
 
    const auto sepVars = [&](NodeId a, NodeId b) {
      VariableSet keep;
      for (const NodeId n: w.jt.separator(a, b))
        keep.insert(_varOfSlot_(w.slotOfNode[n], t));
      return keep;
    };
 
    // collect: reverse BFS visits every child before its parent
    for (auto it = w.bfs.rbegin(); it != w.bfs.rend(); ++it) {
      const NodeId j = *it;
      if (j == w.rootC) continue;
      const NodeId p = w.parentOf.at(j);
      msgs[{j, p}]   = _belief_(w, psi, msgs, inPrev, inNext, j, p).sumIn(sepVars(j, p));
    }
    if (!distribute) return;
 
    // distribute: BFS visits every parent before its children
    for (const NodeId j: w.bfs)
      for (const NodeId i: w.jt.neighbours(j)) {
        if (i == j || w.parentOf.at(i) != j) continue;   // children only
        msgs[{j, i}] = _belief_(w, psi, msgs, inPrev, inNext, j, i).sumIn(sepVars(j, i));
      }
  }

References _belief_(), _varOfSlot_(), gum::KTBNInference< GUM_SCALAR >::_Window_::bfs, gum::Set< Key >::insert(), gum::KTBNInference< GUM_SCALAR >::_Window_::jt, gum::EdgeGraphPart::neighbours(), gum::KTBNInference< GUM_SCALAR >::_Window_::parentOf, gum::KTBNInference< GUM_SCALAR >::_Window_::rootC, gum::CliqueGraph::separator(), and gum::KTBNInference< GUM_SCALAR >::_Window_::slotOfNode.

Referenced by makeInference().

Here is the call graph for this function:

Here is the caller graph for this function:

_psiKey_()

template<GUM_Numeric GUM_SCALAR>

INLINE Size gum::KTBNInference< GUM_SCALAR >::_psiKey_ ( int t ) const

private

Cache slot for slice t: the initial slices keep their own, the repeating window contributes one per phase.

Definition at line 778 of file KTBNInference_tpl.h.

                                                               {
    // t < k: the initial windows, each its own. t >= k: the repeating window,
    // one slot per phase. Keying on t % k alone would collide slice 2 with
    // slice 5 at k=3 -- same phase, different window and different CPTs.
    return (t < static_cast< int >(_k_)) ? static_cast< Size >(t)
                                         : _k_ + static_cast< Size >(t % static_cast< int >(_k_));
  }

References _k_.

Referenced by _windowPotentials_().

Here is the caller graph for this function:

_series_()

template<GUM_Numeric GUM_SCALAR>

const KTBNInference< GUM_SCALAR >::_Series_ & gum::KTBNInference< GUM_SCALAR >::_series_ ( const std::string & base )

private

The cached series of a targeted base, running makeInference() lazily (with the last horizon) if out of date. Shared by both accessors.

Definition at line 1156 of file KTBNInference_tpl.h.

                                                                 {
    // lazily (re)run with the last horizon; a horizon of 0 means never run
    if (!_done_) {
      if (_horizon_ == 0)
        GUM_ERROR(OperationNotAllowed, "call makeInference(nbTimeSlices) before querying.")
      makeInference(_horizon_);
    }
    const auto it = _posteriors_.find(base);
    if (it == _posteriors_.end())
      GUM_ERROR(UndefinedElement, "'" << base << "' is not a target of this inference.")
    return it->second;
  }

References _done_, _horizon_, _posteriors_, GUM_ERROR, and makeInference().

Referenced by posterior(), and posteriors().

Here is the call graph for this function:

Here is the caller graph for this function:

_snapshot_()

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::_snapshot_ ( const std::string & base, int slice, const Tensor< GUM_SCALAR > & marginal )

private

Snapshots marginal onto an owned, stably-named descriptor and appends it to that base's series (index == slice for a temporal base). Positional fillWith, not name-matched: marginal's axis is a shared ring object, reused across residue-k slices, whose name generally isn't base[slice].

Definition at line 1131 of file KTBNInference_tpl.h.

                                                                                     {
    // owned, stably-named descriptor: marginal's axis is a reused ring object
    // whose name isn't base[slice], so fillWith is positional, not name-matched
    const std::size_t idx    = (slice == ATEMPORAL) ? 0u : static_cast< std::size_t >(slice);
    _Series_&         series = _posteriors_[base];
    if (series.tensors.size() <= idx) {
      series.tensors.resize(idx + 1);
      series.vars.resize(idx + 1);
    }
 
    std::unique_ptr< DiscreteVariable > outVar(_templateVar_(base, slice).clone());
    outVar->setName(_encode_(base, slice));
 
    Tensor< GUM_SCALAR > out;
    out << *outVar;
    out.fillWith(marginal, {marginal.variablesSequence().atPos(0)->name()});
 
    series.vars[idx]    = std::move(outVar);
    series.tensors[idx] = std::move(out);
  }

References _encode_(), _posteriors_, _templateVar_(), ATEMPORAL, gum::KTBNInference< GUM_SCALAR >::_Series_::tensors, and gum::KTBNInference< GUM_SCALAR >::_Series_::vars.

Referenced by makeInference().

Here is the call graph for this function:

Here is the caller graph for this function:

_templateVar_()

template<GUM_Numeric GUM_SCALAR>

const DiscreteVariable & gum::KTBNInference< GUM_SCALAR >::_templateVar_ ( const std::string & base, int slice ) const

private

A representative template variable of base for domain/cloning.

Definition at line 147 of file KTBNInference_tpl.h.

                                                                                      {
    if (slice == ATEMPORAL) return _ktbn_->variable(base, ATEMPORAL);
    return _ktbn_->variable(base, (slice < _k_) ? slice : _k_ - 1);
  }

References _k_, _ktbn_, and ATEMPORAL.

Referenced by _snapshot_(), addIntervention(), addIntervention(), addObservation(), addObservation(), and addObservations().

Here is the caller graph for this function:

_validateNode_()

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::_validateNode_ ( const std::string & base, int slice ) const

private

Validates that (base, slice) denotes a legal node (future slices ok).

Definition at line 135 of file KTBNInference_tpl.h.

                                                                                         {
    const bool temporal  = _isTemporal_(base);
    const bool atemporal = _isAtemporal_(base);
 
    if (!temporal && !atemporal) GUM_ERROR(NotFound, "Unknown variable '" << base << "'.")
    if (temporal && slice < 0)
      GUM_ERROR(InvalidArgument, "Temporal variable '" << base << "' requires a slice >= 0.")
    if (atemporal && slice != ATEMPORAL)
      GUM_ERROR(InvalidArgument, "Atemporal variable '" << base << "' has no time slice.")
  }

References _isAtemporal_(), _isTemporal_(), ATEMPORAL, and GUM_ERROR.

Referenced by addIntervention(), addIntervention(), addObservation(), addObservation(), and addObservations().

Here is the call graph for this function:

Here is the caller graph for this function:

_varOfSlot_()

template<GUM_Numeric GUM_SCALAR>

const DiscreteVariable * gum::KTBNInference< GUM_SCALAR >::_varOfSlot_ ( const _Slot_ & s, int t ) const

private

The variable a window slot stands for at absolute slice t: ring slot \((t-\text{lag}) \bmod k\) for a temporal base, the atemporal object otherwise. This is where "advance one slice" happens – a relabelling, not an allocation.

Definition at line 154 of file KTBNInference_tpl.h.

                                                                                               {
    if (s.lag == ATEMPORAL) return &_ktbn_->variable(_baseNames_[s.base], ATEMPORAL);
    return &_ktbn_->variable(_baseNames_[s.base], (t - s.lag) % _k_);
  }

References _baseNames_, _k_, _ktbn_, ATEMPORAL, gum::KTBNInference< GUM_SCALAR >::_Slot_::base, and gum::KTBNInference< GUM_SCALAR >::_Slot_::lag.

Referenced by _fillWindow_(), _propagate_(), and makeInference().

Here is the caller graph for this function:

_windowAt_()

template<GUM_Numeric GUM_SCALAR>

INLINE const KTBNInference< GUM_SCALAR >::_Window_ & gum::KTBNInference< GUM_SCALAR >::_windowAt_ ( int t ) const

private

The window for absolute slice t: its own while t is inside the initial block, the repeating one (index k) from then on.

Definition at line 887 of file KTBNInference_tpl.h.

                                                         {
    return _windows_[static_cast< std::size_t >(t < _k_ ? t : _k_)];
  }

References _k_, and _windows_.

Referenced by makeInference().

Here is the caller graph for this function:

_windowPotentials_()

template<GUM_Numeric GUM_SCALAR>

const std::unordered_map< NodeId, Tensor< GUM_SCALAR > > & gum::KTBNInference< GUM_SCALAR >::_windowPotentials_ ( const _Window_ & w, int t ) const

private

Clique potentials of the window at slice t: every requisite family's CPT (or, under an intervention, a point mass severing it from its causes), times every observation's likelihood.

Parameters

psi	out: clique -> its potential (absent clique == unit potential).

Clique potentials for slice t, memoized where they repeat.

psi(t) reads t in exactly four places: windowAt (fixed at windows[k] once t >= k), varOfSlot ((t - lag) % k), buildKernel (t % k) and the encode(base, t) lookups into observations / interventions. The first three are periodic in t % k, so on a slice carrying no temporal evidence the whole map is too: one entry serves every slice of that phase.

Atemporal evidence needs no special case – it applies identically at every slice, so it is part of the periodic structure.

Returns a reference into the cache (or into a scratch map for a slice that does carry evidence). Valid until the next call, and until the next makeInference(), which clears the cache. Callers only read it: propagate and belief both take psi by const reference.

Definition at line 788 of file KTBNInference_tpl.h.

                                                                                    {
    // do(X=x) replaces a CPT the base already applied, so the base is unusable
    if (_interventionSlices_.contains(t)) {
      _fillWindow_(w, t, _psiScratch_, true);
      return _psiScratch_;
    }
 
    const Size key = _psiKey_(t);
    if (!_psiCached_[key]) {
      _fillWindow_(w, t, _psiCache_[key], false);   // base: no slice-specific evidence
      _psiCached_[key] = true;
    }
 
    // unobserved: the base IS the answer, handed over without a copy
    if (!_observationSlices_.contains(t)) return _psiCache_[key];
 
    // observed: an observation multiplies ON TOP of the CPT, so the base still
    // holds. Copying it and applying the likelihood costs one pass per clique,
    // where a rebuild would redo the unit fill and every CPT product.
    _psiScratch_ = _psiCache_[key];
    _applyTemporalObservations_(w, t, _psiScratch_);
    return _psiScratch_;
  }

References _applyTemporalObservations_(), _fillWindow_(), _interventionSlices_, _observationSlices_, _psiCache_, _psiCached_, _psiKey_(), and _psiScratch_.

Referenced by makeInference().

Here is the call graph for this function:

Here is the caller graph for this function:

addIntervention() [1/3]

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::addIntervention

(

const std::vector< std::pair< NodeKey, KTBNModality > > &

interventions

)

Records several interventions in one call.

Each entry is a (node, value) pair: node keyed by engine name or by (base, slice), value an index or a label – freely mixed.

All-or-nothing: every entry is validated before any is recorded. A node listed twice keeps its last value.

ie.addIntervention({{"X[5]", 0}, {std::pair{"Z", 2}, "high"}});

Warning

A (base, slice) key needs an explicit std::pair{...}: a bare {"Z", 2} cannot implicitly construct the variant (same rule as gum::KTBN::fillCPT()).

Exceptions

NotFound

/ InvalidArgument / OutOfBounds – same as the single-node form, raised before anything is recorded.

Definition at line 181 of file KTBNInference_tpl.h.

                                                                          {
    // resolve and validate the whole batch first, so a bad entry cannot leave
    // the engine with the preceding entries already applied
    std::vector< std::pair< std::string, Idx > > resolved;
    resolved.reserve(interventions.size());
    for (const auto& [key, value]: interventions) {
      const auto [b, s] = std::holds_alternative< std::string >(key)
                            ? _determineNode_(std::get< std::string >(key))
                            : std::get< std::pair< std::string, int > >(key);
      _validateNode_(b, s);
      resolved.emplace_back(_encode_(b, s), value.toIndex(_templateVar_(b, s)));
    }
 
    for (const auto& [name, idx]: resolved)
      _interventions_[name] = idx;
    if (!resolved.empty()) _done_ = false;
  }

References _determineNode_(), _done_, _encode_(), _interventions_, _templateVar_(), and _validateNode_().

Here is the call graph for this function:

addIntervention() [2/3]

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::addIntervention	(	std::string_view	base,
		int	slice,
		const KTBNModality &	value )

Records a hard intervention \(do(base[slice]=value)\).

Recorded only; applied at makeInference(). Re-intervening overwrites. value is a modality index or label (see gum::KTBNModality).

ie.addIntervention("X", 5, 0);        // by index
ie.addIntervention("X", 5, "high");   // by label

Exceptions

NotFound	if base is unknown.
InvalidArgument	if the slice is invalid for the variable kind.
OutOfBounds	/ NotFound if value is out of the variable's domain or is not one of its modality labels.

Definition at line 164 of file KTBNInference_tpl.h.

                                                                               {
    const std::string b(base);
    _validateNode_(b, slice);
    _interventions_[_encode_(b, slice)] = value.toIndex(_templateVar_(b, slice));
    _done_                              = false;
  }

References _done_, _encode_(), _interventions_, _templateVar_(), _validateNode_(), and gum::KTBNModality::toIndex().

Referenced by addIntervention().

Here is the call graph for this function:

Here is the caller graph for this function:

addIntervention() [3/3]

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::addIntervention	(	std::string_view	node_name,
		const KTBNModality &	value )

Same, using an engine name ("X[2]", "C", …).

Definition at line 174 of file KTBNInference_tpl.h.

                                                                               {
    const auto [b, s] = _determineNode_(std::string(node_name));
    addIntervention(b, s, value);
  }

References _determineNode_(), and addIntervention().

Here is the call graph for this function:

addObservation() [1/4]

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::addObservation	(	std::string_view	base,
		int	slice,
		const KTBNModality &	value )

Records a hard observation \(base[slice]=value\).

Unlike an intervention, an observation is conditioning: it revises the whole network, ancestors included. Recorded only; applied at makeInference(). Re-observing overwrites. value is a modality index or label (see gum::KTBNModality).

ie.addObservation("X", 5, 0);        // by index
ie.addObservation("X", 5, "high");   // by label

Exceptions

NotFound	if base is unknown.
InvalidArgument	if the slice is invalid for the variable kind.
OutOfBounds	/ NotFound if value is not a legal modality.

Definition at line 234 of file KTBNInference_tpl.h.

                                                                              {
    const std::string b(base);
    _validateNode_(b, slice);
    const DiscreteVariable&   v   = _templateVar_(b, slice);
    const Idx                 idx = value.toIndex(v);
    std::vector< GUM_SCALAR > like(v.domainSize(), GUM_SCALAR(0));
    like[idx]                          = GUM_SCALAR(1);
    _observations_[_encode_(b, slice)] = std::move(like);
    _done_                             = false;
  }

References _done_, _encode_(), _observations_, _templateVar_(), _validateNode_(), gum::DiscreteVariable::domainSize(), and gum::KTBNModality::toIndex().

Referenced by addObservation(), and addObservation().

Here is the call graph for this function:

Here is the caller graph for this function:

addObservation() [2/4]

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::addObservation	(	std::string_view	base,
		int	slice,
		const std::vector< GUM_SCALAR > &	likelihood )

Records a soft (likelihood) observation on \(base[slice]\).

likelihood[i] is the likelihood of the observation given that the node takes its i-th modality; it need not sum to 1, but must be non-negative and not all-zero. A one-hot vector is equivalent to a hard observation.

Exceptions

NotFound	/ InvalidArgument as above.
InvalidArgument	if likelihood has the wrong length, holds a negative entry, or is all zeros.

Definition at line 255 of file KTBNInference_tpl.h.

                                                                                              {
    const std::string b(base);
    _validateNode_(b, slice);
    const DiscreteVariable& v = _templateVar_(b, slice);
    if (likelihood.size() != v.domainSize())
      GUM_ERROR(InvalidArgument,
                "Soft observation on '" << _encode_(b, slice) << "' needs " << v.domainSize()
                                        << " values, got " << likelihood.size() << ".")
    GUM_SCALAR total = GUM_SCALAR(0);
    for (const auto x: likelihood) {
      if (x < GUM_SCALAR(0))
        GUM_ERROR(InvalidArgument,
                  "Soft observation on '" << _encode_(b, slice) << "' has a negative entry.")
      total += x;
    }
    if (total <= GUM_SCALAR(0))
      GUM_ERROR(InvalidArgument,
                "Soft observation on '" << _encode_(b, slice) << "' is all zeros: impossible.")
    _observations_[_encode_(b, slice)] = likelihood;
    _done_                             = false;
  }

References _done_, _encode_(), _observations_, _templateVar_(), _validateNode_(), gum::DiscreteVariable::domainSize(), and GUM_ERROR.

Here is the call graph for this function:

addObservation() [3/4]

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::addObservation	(	std::string_view	node_name,
		const KTBNModality &	value )

Same, using an engine name ("X[2]", "C", …).

Definition at line 248 of file KTBNInference_tpl.h.

                                                                              {
    const auto [b, s] = _determineNode_(std::string(node_name));
    addObservation(b, s, value);
  }

References _determineNode_(), and addObservation().

Here is the call graph for this function:

addObservation() [4/4]

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::addObservation	(	std::string_view	node_name,
		const std::vector< GUM_SCALAR > &	likelihood )

Same, using an engine name ("X[2]", "C", …).

Definition at line 280 of file KTBNInference_tpl.h.

                                                                                              {
    const auto [b, s] = _determineNode_(std::string(node_name));
    addObservation(b, s, likelihood);
  }

References _determineNode_(), and addObservation().

Here is the call graph for this function:

addObservations()

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::addObservations

(

const std::vector< std::pair< NodeKey, KTBNModality > > &

observations

)

Records several observations in one call, all-or-nothing.

Same keying rules (and the same std::pair{...} warning) as the batch addIntervention().

Definition at line 287 of file KTBNInference_tpl.h.

                                                                         {
    // all-or-nothing, like the batch addIntervention()
    std::vector< std::pair< std::string, std::vector< GUM_SCALAR > > > resolved;
    resolved.reserve(observations.size());
    for (const auto& [key, value]: observations) {
      const auto [b, s] = std::holds_alternative< std::string >(key)
                            ? _determineNode_(std::get< std::string >(key))
                            : std::get< std::pair< std::string, int > >(key);
      _validateNode_(b, s);
      const DiscreteVariable&   v = _templateVar_(b, s);
      std::vector< GUM_SCALAR > like(v.domainSize(), GUM_SCALAR(0));
      like[value.toIndex(v)] = GUM_SCALAR(1);
      resolved.emplace_back(_encode_(b, s), std::move(like));
    }
    for (auto& [name, like]: resolved)
      _observations_[name] = std::move(like);
    if (!resolved.empty()) _done_ = false;
  }

References _determineNode_(), _done_, _encode_(), _observations_, _templateVar_(), _validateNode_(), and gum::DiscreteVariable::domainSize().

Here is the call graph for this function:

addTarget()

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::addTarget

(

std::string_view

base

)

Declares a target: a base variable whose marginals we want.

A temporal base yields one marginal per slice \(0..T-1\) at makeInference(T); an atemporal base yields its single marginal. The first declared target switches the engine out of default-all-targets mode. Recorded only; applied at makeInference().

Exceptions

NotFound

if base is neither a temporal process nor an atemporal variable of the k-DBN.

Definition at line 346 of file KTBNInference_tpl.h.

                                                                 {
    const std::string b(base);
    if (!_isTemporal_(b) && !_isAtemporal_(b))
      GUM_ERROR(NotFound, "Unknown variable '" << b << "'.")
    _targets_.insert(b);
    _targeted_mode_ = true;
    _done_          = false;
  }

References _done_, _isAtemporal_(), _isTemporal_(), _targeted_mode_, _targets_, and GUM_ERROR.

Here is the call graph for this function:

clearInterventions()

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::clearInterventions

(

)

Removes all recorded interventions.

Definition at line 213 of file KTBNInference_tpl.h.

                                                       {
    _interventions_.clear();
    _done_ = false;
  }

References _done_, and _interventions_.

clearObservation()

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::clearObservation

(

)

Removes all recorded observations.

Definition at line 320 of file KTBNInference_tpl.h.

                                                     {
    _observations_.clear();
    _done_ = false;
  }

References _done_, and _observations_.

clearTargets()

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::clearTargets

(

)

Removes all targets (restores default-all-targets mode).

Definition at line 363 of file KTBNInference_tpl.h.

                                                 {
    _targets_.clear();
    _targeted_mode_ = false;
    _done_          = false;
  }

References _done_, _targeted_mode_, and _targets_.

eraseIntervention() [1/2]

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::eraseIntervention	(	std::string_view	base,
		int	slice )

Removes a recorded intervention (silent no-op if absent).

Definition at line 201 of file KTBNInference_tpl.h.

                                                                                    {
    _interventions_.erase(_encode_(std::string(base), slice));
    _done_ = false;
  }

References _done_, _encode_(), and _interventions_.

Referenced by eraseIntervention().

Here is the call graph for this function:

Here is the caller graph for this function:

eraseIntervention() [2/2]

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::eraseIntervention

(

std::string_view

node_name

)

Same, using an engine name ("X[2]", "C", …).

Definition at line 207 of file KTBNInference_tpl.h.

                                                                              {
    const auto [b, s] = _determineNode_(std::string(node_name));
    eraseIntervention(b, s);
  }

References _determineNode_(), and eraseIntervention().

Here is the call graph for this function:

eraseObservation() [1/2]

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::eraseObservation	(	std::string_view	base,
		int	slice )

Removes a recorded observation (silent no-op if absent).

Definition at line 308 of file KTBNInference_tpl.h.

                                                                                   {
    _observations_.erase(_encode_(std::string(base), slice));
    _done_ = false;
  }

References _done_, _encode_(), and _observations_.

Referenced by eraseObservation().

Here is the call graph for this function:

Here is the caller graph for this function:

eraseObservation() [2/2]

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::eraseObservation

(

std::string_view

node_name

)

Same, using an engine name ("X[2]", "C", …).

Definition at line 314 of file KTBNInference_tpl.h.

                                                                             {
    const auto [b, s] = _determineNode_(std::string(node_name));
    eraseObservation(b, s);
  }

References _determineNode_(), and eraseObservation().

Here is the call graph for this function:

eraseTarget()

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::eraseTarget

(

std::string_view

base

)

Removes a target; when the last one is removed, default-all-targets mode is restored.

Definition at line 356 of file KTBNInference_tpl.h.

                                                                   {
    _targets_.erase(std::string(base));
    if (_targets_.empty()) _targeted_mode_ = false;
    _done_ = false;
  }

References _done_, _targeted_mode_, and _targets_.

hasIntervention() [1/2]

template<GUM_Numeric GUM_SCALAR>

bool gum::KTBNInference< GUM_SCALAR >::hasIntervention	(	std::string_view	base,
		int	slice ) const

Returns

true if base at slice carries an intervention.

Definition at line 219 of file KTBNInference_tpl.h.

                                                                                        {
    return _interventions_.find(_encode_(std::string(base), slice)) != _interventions_.end();
  }

References _encode_(), and _interventions_.

Referenced by hasIntervention().

Here is the call graph for this function:

Here is the caller graph for this function:

hasIntervention() [2/2]

template<GUM_Numeric GUM_SCALAR>

bool gum::KTBNInference< GUM_SCALAR >::hasIntervention

(

std::string_view

node_name

)

const

Same, using an engine name ("X[2]", "C", …).

Definition at line 224 of file KTBNInference_tpl.h.

                                                                                  {
    const auto [b, s] = _determineNode_(std::string(node_name));
    return hasIntervention(b, s);
  }

References _determineNode_(), and hasIntervention().

Here is the call graph for this function:

hasObservation() [1/3]

template<GUM_Numeric GUM_SCALAR>

bool gum::KTBNInference< GUM_SCALAR >::hasObservation

(

)

const

Returns

true if any observation is recorded. When false, makeInference() needs no backward pass and runs in horizon-independent memory.

Definition at line 337 of file KTBNInference_tpl.h.

                                                         {
    return !_observations_.empty();
  }

References _observations_.

hasObservation() [2/3]

template<GUM_Numeric GUM_SCALAR>

bool gum::KTBNInference< GUM_SCALAR >::hasObservation	(	std::string_view	base,
		int	slice ) const

Returns

true if base at slice carries an observation.

Definition at line 326 of file KTBNInference_tpl.h.

                                                                                       {
    return _observations_.find(_encode_(std::string(base), slice)) != _observations_.end();
  }

References _encode_(), and _observations_.

Referenced by hasObservation(), and makeInference().

Here is the call graph for this function:

Here is the caller graph for this function:

hasObservation() [3/3]

template<GUM_Numeric GUM_SCALAR>

bool gum::KTBNInference< GUM_SCALAR >::hasObservation

(

std::string_view

node_name

)

const

Same, using an engine name ("X[2]", "C", …).

Definition at line 331 of file KTBNInference_tpl.h.

                                                                                 {
    const auto [b, s] = _determineNode_(std::string(node_name));
    return hasObservation(b, s);
  }

References _determineNode_(), and hasObservation().

Here is the call graph for this function:

interfaceSize()

template<GUM_Numeric GUM_SCALAR>

Size gum::KTBNInference< GUM_SCALAR >::interfaceSize

(

)

const

Size of the forward interface of the repeating window: how many node occurrences have to cross each slice boundary. Introspection only.

Definition at line 1229 of file KTBNInference_tpl.h.

                                                        {
    return static_cast< Size >(_windows_[static_cast< std::size_t >(_k_)].Icur.size());
  }

References _k_, and _windows_.

Referenced by toString().

Here is the caller graph for this function:

isInTargetMode()

template<GUM_Numeric GUM_SCALAR>

bool gum::KTBNInference< GUM_SCALAR >::isInTargetMode

(

)

const

Returns

true iff at least one explicit target has been declared; when false, every base is a target. Mirrors gum::MarginalTargetedInference::isInTargetMode().

Definition at line 377 of file KTBNInference_tpl.h.

                                                         {
    return _targeted_mode_;
  }

References _targeted_mode_.

isTarget()

template<GUM_Numeric GUM_SCALAR>

bool gum::KTBNInference< GUM_SCALAR >::isTarget

(

std::string_view

base

)

const

Returns

true if base is a target of the next inference.

Definition at line 370 of file KTBNInference_tpl.h.

                                                                      {
    const std::string b(base);
    if (!_targeted_mode_) return _isTemporal_(b) || _isAtemporal_(b);
    return _targets_.contains(b);
  }

References _isAtemporal_(), _isTemporal_(), _targeted_mode_, and _targets_.

Here is the call graph for this function:

ktbn()

template<GUM_Numeric GUM_SCALAR>

const KTBN< GUM_SCALAR > & gum::KTBNInference< GUM_SCALAR >::ktbn

(

)

const

Returns

The k-DBN reasoned about.

Definition at line 1219 of file KTBNInference_tpl.h.

                                                                    {
    return *_ktbn_;
  }

References _ktbn_.

Referenced by KTBNInference().

Here is the caller graph for this function:

logObservationProbability()

template<GUM_Numeric GUM_SCALAR>

GUM_SCALAR gum::KTBNInference< GUM_SCALAR >::logObservationProbability

(

)

\(\log P(\text{obs} \mid do(\cdot))\) for the last run: the likelihood of the observations under the (possibly mutilated) model. 0 when nothing is observed. Lazily (re)runs makeInference() if out of date.

Exceptions

OperationNotAllowed

if makeInference() has never been run.

Definition at line 1200 of file KTBNInference_tpl.h.

                                                                    {
    if (!_done_) {
      if (_horizon_ == 0)
        GUM_ERROR(OperationNotAllowed, "call makeInference(nbTimeSlices) before querying.")
      makeInference(_horizon_);
    }
    return _logObservation_;
  }

References _done_, _horizon_, _logObservation_, GUM_ERROR, and makeInference().

Referenced by observationProbability().

Here is the call graph for this function:

Here is the caller graph for this function:

makeInference()

template<GUM_Numeric GUM_SCALAR>

void gum::KTBNInference< GUM_SCALAR >::makeInference

(

Size

nbTimeSlices

)

Runs the interface algorithm over nbTimeSlices slices ( \(0..nbTimeSlices-1\)) and caches, for every targeted base, its marginal at every slice.

A forward sweep passes \(m_t\) window to window; if any observation is recorded, a backward sweep passes \(r_t\) the other way and the two combine into exact smoothed posteriors. With no observation the backward pass is skipped and only one window is ever live.

Window junction trees are compiled once, at construction, and reused by every call regardless of horizon or target set; only the requisite subnetwork is recomputed per run. Observations/interventions at slices \(\geq\) nbTimeSlices fall outside the roll and are ignored.

Idempotent. Called lazily by posterior()/posteriors() (last horizon) when out of date. nbTimeSlices becomes the stored horizon.

Exceptions

InvalidArgument	if nbTimeSlices is 0.
FatalError	if the observations have probability 0 under the model.

Definition at line 954 of file KTBNInference_tpl.h.

                                                                   {
    if (nbTimeSlices == 0) GUM_ERROR(InvalidArgument, "makeInference: nbTimeSlices must be >= 1.")
 
    const int T      = static_cast< int >(nbTimeSlices);
    _horizon_        = nbTimeSlices;
    _logObservation_ = GUM_SCALAR(0);
    _posteriors_.clear();
    _kernelCache_.clear();   // CPT values may have been edited since the last run
 
    // Potential cache: same reason to clear, plus the evidence may have moved.
    _psiCache_.assign(2 * _k_, {});
    _psiCached_.assign(2 * _k_, false);
    _psiScratch_.clear();
 
    // Which slices are not the periodic ones. Decoding the (few) evidence keys
    // costs O(#evidence); probing every slice would cost what the cache saves.
    // Atemporal evidence decodes to ATEMPORAL and marks no slice: it applies at
    // every t alike and so belongs to the periodic structure.
    _observationSlices_.clear();
    _interventionSlices_.clear();
    for (const auto& [name, value]: _observations_) {
      (void)value;
      const int s = _determineNode_(name).second;
      if (s != ATEMPORAL) _observationSlices_.insert(s);
    }
    for (const auto& [name, value]: _interventions_) {
      (void)value;
      const int s = _determineNode_(name).second;
      if (s != ATEMPORAL) _interventionSlices_.insert(s);
    }
    _markRequisite_();
 
    const bool defaultAll = !_targeted_mode_;
    const auto targeted = [&](const std::string& b) { return defaultAll || _targets_.contains(b); };
    // nothing observed => backward messages are provably uniform, so the
    // sweep is skipped and only one window is ever live
    const bool smoothing = hasObservation();
 
    // pre-size the series: with smoothing the slices are filled back-to-front
    for (int i = 0; i < static_cast< int >(_baseNames_.size()); ++i) {
      const std::string& b = _baseNames_[i];
      if (!_requisite_[i] || !targeted(b)) continue;
      _Series_&         s = _posteriors_[b];
      const std::size_t n
          = (i < static_cast< int >(_nbTemporal_)) ? static_cast< std::size_t >(T) : std::size_t(1);
      s.vars.resize(n);
      s.tensors.resize(n);
    }
 
    const auto ifaceVars = [&](const std::vector< _Slot_ >& slots, int slice) {
      VariableSet keep;
      for (const auto& s: slots)
        keep.insert(_varOfSlot_(s, slice));
      return keep;
    };
 
    const auto readPosteriors
        = [&](const _Window_&                                                      w,
              int                                                                  slice,
              const std::unordered_map< NodeId, Tensor< GUM_SCALAR > >&            psi,
              const std::map< std::pair< NodeId, NodeId >, Tensor< GUM_SCALAR > >& msgs,
              const Tensor< GUM_SCALAR >*                                          inPrev,
              const Tensor< GUM_SCALAR >*                                          inNext) {
            const int lastBase = (slice == 0) ? static_cast< int >(_baseNames_.size())
                                              : static_cast< int >(_nbTemporal_);
            for (int i = 0; i < lastBase; ++i) {
              if (!_requisite_[i] || !targeted(_baseNames_[i])) continue;
              const auto itc = w.selfClique.find(i);
              if (itc == w.selfClique.end()) continue;
              const bool  atemp = i >= static_cast< int >(_nbTemporal_);
              VariableSet keep;
              keep.insert(atemp ? &_ktbn_->variable(_baseNames_[i], ATEMPORAL)
                                : &_ktbn_->variable(_baseNames_[i], slice % _k_));
              Tensor< GUM_SCALAR > m
                  = _belief_(w, psi, msgs, inPrev, inNext, itc->second, KTBN_SKIP_NONE).sumIn(keep);
              m.normalize();
              _snapshot_(_baseNames_[i], atemp ? ATEMPORAL : slice, m);
            }
          };
 
    std::map< std::pair< NodeId, NodeId >, Tensor< GUM_SCALAR > > msgs;
 
    // ---- forward sweep: carry m_t across each slice boundary ----------------
    // only the interface is retained per slice, and only if smoothing needs it
    std::vector< Tensor< GUM_SCALAR > > fwd;
    if (smoothing && T > 1) fwd.resize(static_cast< std::size_t >(T - 1));
 
    Tensor< GUM_SCALAR > prev;
    bool                 hasPrev = false;
 
    for (int t = 0; t < T; ++t) {
      const _Window_& w = _windowAt_(t);
      if (w.bfs.empty()) break;   // nothing requisite at all
 
      const auto& psi = _windowPotentials_(w, t);
      _propagate_(w, t, psi, hasPrev ? &prev : nullptr, nullptr, !smoothing, msgs);
 
      if (!smoothing) readPosteriors(w, t, psi, msgs, hasPrev ? &prev : nullptr, nullptr);
 
      Tensor< GUM_SCALAR > m
          = _belief_(w, psi, msgs, hasPrev ? &prev : nullptr, nullptr, w.rootC, KTBN_SKIP_NEXT)
                .sumIn(ifaceVars(w.Icur, t));
      const GUM_SCALAR mass = m.sum();
      if (!(mass > GUM_SCALAR(0)))
        GUM_ERROR(FatalError,
                  "makeInference: the observations have probability 0 under this model "
                  "(impossible at slice "
                      << t << ").")
      m.scale(GUM_SCALAR(1) / mass);
      _logObservation_ += static_cast< GUM_SCALAR >(std::log(static_cast< double >(mass)));
 
      if (t + 1 < T) {
        if (smoothing) fwd[static_cast< std::size_t >(t)] = m;
        prev    = std::move(m);
        hasPrev = true;
      }
    }
 
    // ---- backward sweep: carry r_t the other way and combine ---------------
    if (smoothing) {
      Tensor< GUM_SCALAR > nxt;
      bool                 hasNext = false;
      for (int t = T - 1; t >= 0; --t) {
        const _Window_& w = _windowAt_(t);
        if (w.bfs.empty()) break;
 
        const auto&                 psi = _windowPotentials_(w, t);
        const Tensor< GUM_SCALAR >* inPrev
            = (t > 0) ? &fwd[static_cast< std::size_t >(t - 1)] : nullptr;
        const Tensor< GUM_SCALAR >* inNext = hasNext ? &nxt : nullptr;
        _propagate_(w, t, psi, inPrev, inNext, true, msgs);
 
        readPosteriors(w, t, psi, msgs, inPrev, inNext);
 
        if (t > 0) {
          Tensor< GUM_SCALAR > r = _belief_(w, psi, msgs, inPrev, inNext, w.rootD, KTBN_SKIP_PREV)
                                       .sumIn(ifaceVars(w.Iprev, t));
          const GUM_SCALAR     mass = r.sum();
          // Symmetric with the forward sweep. In exact arithmetic this cannot
          // fire -- a null backward mass would mean P(e_{t:T} | I) = 0 for every
          // interface state, hence P(e) = 0, which the forward sweep just
          // disproved. In floating point it fires readily: the intra-window
          // product is formed BEFORE any normalisation, so near-deterministic
          // CPTs flush it to zero while the true value is merely tiny
          // (reproduced with transition probabilities of 1e-100 at T=4).
          //
          // Left unguarded the failure is silent and total: r stays all-zero,
          // becomes the next inNext, and zeroes every belief from here back to
          // slice 0 -- and readPosteriors' normalize() is a no-op on a zero sum,
          // so posterior() would return tensors of zeros looking like
          // distributions. Do NOT reuse the forward sweep's wording here: the
          // observations are *not* impossible, they underflowed.
          if (!(mass > GUM_SCALAR(0)))
            GUM_ERROR(FatalError,
                      "makeInference: the backward message leaving slice "
                          << t
                          << " underflowed to zero. The observations are not impossible -- the "
                             "forward sweep accepted them (log P(obs) = "
                          << _logObservation_
                          << ") -- but the model's probabilities are too extreme for this horizon "
                             "to be resolved in double precision. Soften the near-deterministic "
                             "CPT entries, or shorten the horizon / reduce the observations.")
          r.scale(GUM_SCALAR(1) / mass);
          nxt     = std::move(r);
          hasNext = true;
        }
      }
    }
 
    _done_ = true;
  }

References _baseNames_, _belief_(), _determineNode_(), _done_, _horizon_, _interventions_, _interventionSlices_, _k_, _kernelCache_, _ktbn_, _logObservation_, _markRequisite_(), _nbTemporal_, _observations_, _observationSlices_, _posteriors_, _propagate_(), _psiCache_, _psiCached_, _psiScratch_, _requisite_, _snapshot_(), _targeted_mode_, _targets_, _varOfSlot_(), _windowAt_(), _windowPotentials_(), ATEMPORAL, gum::KTBNInference< GUM_SCALAR >::_Window_::bfs, GUM_ERROR, hasObservation(), gum::KTBNInference< GUM_SCALAR >::_Window_::Icur, gum::Set< Key >::insert(), gum::KTBNInference< GUM_SCALAR >::_Window_::Iprev, gum::KTBNInference< GUM_SCALAR >::_Window_::rootC, gum::KTBNInference< GUM_SCALAR >::_Window_::rootD, gum::KTBNInference< GUM_SCALAR >::_Window_::selfClique, gum::KTBNInference< GUM_SCALAR >::_Series_::tensors, and gum::KTBNInference< GUM_SCALAR >::_Series_::vars.

Referenced by _series_(), and logObservationProbability().

Here is the call graph for this function:

Here is the caller graph for this function:

observationProbability()

template<GUM_Numeric GUM_SCALAR>

GUM_SCALAR gum::KTBNInference< GUM_SCALAR >::observationProbability

(

)

\(P(\text{obs} \mid do(\cdot))\), i.e. exp of logObservationProbability(). Underflows to 0 on long horizons; prefer the log form.

Definition at line 1210 of file KTBNInference_tpl.h.

                                                                 {
    return static_cast< GUM_SCALAR >(std::exp(static_cast< double >(logObservationProbability())));
  }

References logObservationProbability().

Here is the call graph for this function:

operator=()

template<GUM_Numeric GUM_SCALAR>

KTBNInference< GUM_SCALAR > & gum::KTBNInference< GUM_SCALAR >::operator= ( const KTBNInference< GUM_SCALAR > & )

delete

Constructor.

Parameters

ktbn	The k-DBN to reason about (referenced, not copied).

Exceptions

InvalidArgument

if ktbn is null.

References KTBNInference().

Here is the call graph for this function:

posterior() [1/2]

template<GUM_Numeric GUM_SCALAR>

const Tensor< GUM_SCALAR > & gum::KTBNInference< GUM_SCALAR >::posterior	(	std::string_view	base,
		int	slice )

Returns \(P(base[slice] \mid \text{obs}, do(\cdot))\).

Use ATEMPORAL as slice for an atemporal base. Lazily (re)runs makeInference() with the last horizon if out of date. The returned reference is owned by the engine and is invalidated by the next makeInference(); copy it to keep it.

Exceptions

OperationNotAllowed	if makeInference() has never been run.
UndefinedElement	if base is not a target.
OutOfBounds	if slice was not computed ( \(\geq\) the horizon).

Definition at line 1170 of file KTBNInference_tpl.h.

                                                                                             {
    const std::string b(base);
    const _Series_&   series = _series_(b);
 
    if (_isAtemporal_(b)) {
      if (slice != ATEMPORAL)
        GUM_ERROR(InvalidArgument, "Atemporal variable '" << b << "' has no time slice.")
      return series.tensors.front();
    }
    if (slice < 0 || static_cast< Size >(slice) >= series.tensors.size())
      GUM_ERROR(OutOfBounds,
                "Slice " << slice << " for '" << b << "' was not computed (horizon " << _horizon_
                         << ").")
    return series.tensors[static_cast< std::size_t >(slice)];
  }

References _horizon_, _isAtemporal_(), _series_(), ATEMPORAL, GUM_ERROR, and gum::KTBNInference< GUM_SCALAR >::_Series_::tensors.

Referenced by posterior().

Here is the call graph for this function:

Here is the caller graph for this function:

posterior() [2/2]

template<GUM_Numeric GUM_SCALAR>

const Tensor< GUM_SCALAR > & gum::KTBNInference< GUM_SCALAR >::posterior

(

std::string_view

node_name

)

Same, using an engine name ("X[2]", "C", …).

Definition at line 1188 of file KTBNInference_tpl.h.

                                                                                             {
    const auto [b, s] = _determineNode_(std::string(node_name));
    return posterior(b, s);
  }

References _determineNode_(), and posterior().

Here is the call graph for this function:

posteriors()

template<GUM_Numeric GUM_SCALAR>

const std::vector< Tensor< GUM_SCALAR > > & gum::KTBNInference< GUM_SCALAR >::posteriors

(

std::string_view

base

)

The whole marginal time-series of a targeted base: tensors[t] is \(P(base[t] \mid \cdot)\) for \(t = 0..T-1\) (a single-element vector, holding the atemporal marginal, for an atemporal base).

Zero-copy: returns a reference to the engine-owned vector, invalidated by the next makeInference(). Lazily (re)runs makeInference() if out of date.

Exceptions

OperationNotAllowed	if makeInference() has never been run.
UndefinedElement	if base is not a target.

Definition at line 1195 of file KTBNInference_tpl.h.

                                                                 {
    return _series_(std::string(base)).tensors;
  }

References _series_(), and gum::KTBNInference< GUM_SCALAR >::_Series_::tensors.

Here is the call graph for this function:

toString()

template<GUM_Numeric GUM_SCALAR>

std::string gum::KTBNInference< GUM_SCALAR >::toString

(

)

const

Returns

A human-readable summary of the engine's state.

Definition at line 1234 of file KTBNInference_tpl.h.

                                                        {
    std::stringstream s;
    s << "KTBNInference (k=" << _k_ << ", interface=" << interfaceSize() << ")\n";
    s << "  interventions: {";
    bool first = true;
    for (const auto& [name, val]: _interventions_) {
      s << (first ? "" : ", ") << "do(" << name << "=" << val << ")";
      first = false;
    }
    s << "}\n  observations: {";
    first = true;
    for (const auto& [name, like]: _observations_) {
      (void)like;
      s << (first ? "" : ", ") << name;
      first = false;
    }
    s << "}\n  targets: ";
    if (!_targeted_mode_) s << "<all bases>";
    else {
      s << "{";
      first = true;
      for (const auto& name: _targets_) {
        s << (first ? "" : ", ") << name;
        first = false;
      }
      s << "}";
    }
    s << "\n  state: " << (_done_ ? "computed" : "not computed yet") << "\n";
    return s.str();
  }

References _done_, _interventions_, _k_, _observations_, _targeted_mode_, _targets_, and interfaceSize().

Here is the call graph for this function:

windowJunctionTree()

template<GUM_Numeric GUM_SCALAR>

const JunctionTree & gum::KTBNInference< GUM_SCALAR >::windowJunctionTree

(

)

const

The junction tree of the repeating window – the one compiled from the k-slice template and re-entered at every step from slice \(k-1\) on. Introspection only.

Definition at line 1224 of file KTBNInference_tpl.h.

                                                                            {
    return _windows_[static_cast< std::size_t >(_k_)].jt;
  }

References _k_, and _windows_.

Member Data Documentation

_atemporalSorted_

template<GUM_Numeric GUM_SCALAR>

std::vector< std::string > gum::KTBNInference< GUM_SCALAR >::_atemporalSorted_

private

Definition at line 502 of file KTBNInference.h.

Referenced by KTBNInference().

_baseIdx_

template<GUM_Numeric GUM_SCALAR>

std::unordered_map< std::string, int > gum::KTBNInference< GUM_SCALAR >::_baseIdx_

private

name -> index into baseNames

Definition at line 509 of file KTBNInference.h.

Referenced by KTBNInference(), _buildWindows_(), _familySlots_(), _lastConsumerSlice_(), and _markRequisite_().

_baseNames_

template<GUM_Numeric GUM_SCALAR>

std::vector< std::string > gum::KTBNInference< GUM_SCALAR >::_baseNames_

private

All bases: temporal first (indices 0.._nbTemporal_-1), then atemporal. Window slots index into this.

Definition at line 506 of file KTBNInference.h.

Referenced by KTBNInference(), _applyTemporalObservations_(), _buildWindows_(), _compileWindow_(), _familySlots_(), _fillWindow_(), _interfaceAfter_(), _lastConsumerSlice_(), _markRequisite_(), _varOfSlot_(), and makeInference().

_done_

template<GUM_Numeric GUM_SCALAR>

bool gum::KTBNInference< GUM_SCALAR >::_done_ {false}

private

Whether the cached posteriors are up to date.

Definition at line 491 of file KTBNInference.h.

Referenced by _series_(), addIntervention(), addIntervention(), addObservation(), addObservation(), addObservations(), addTarget(), clearInterventions(), clearObservation(), clearTargets(), eraseIntervention(), eraseObservation(), eraseTarget(), logObservationProbability(), makeInference(), and toString().

_horizon_

template<GUM_Numeric GUM_SCALAR>

Size gum::KTBNInference< GUM_SCALAR >::_horizon_ {0}

private

Horizon (nbTimeSlices) of the last/next run; 0 <=> makeInference never run.

Definition at line 488 of file KTBNInference.h.

Referenced by _series_(), logObservationProbability(), makeInference(), and posterior().

_interventions_

template<GUM_Numeric GUM_SCALAR>

std::map< std::string, Idx > gum::KTBNInference< GUM_SCALAR >::_interventions_

private

Recorded interventions, keyed by engine name -> forced value.

Definition at line 475 of file KTBNInference.h.

Referenced by _fillWindow_(), addIntervention(), addIntervention(), clearInterventions(), eraseIntervention(), hasIntervention(), makeInference(), and toString().

_interventionSlices_

template<GUM_Numeric GUM_SCALAR>

std::unordered_set< int > gum::KTBNInference< GUM_SCALAR >::_interventionSlices_

mutableprivate

Slices carrying a temporal intervention. These need a full rebuild: do(X=x) replaces the node's CPT, which the cached base has already multiplied in, so the base is unusable rather than merely incomplete. Atemporal evidence appears in neither set – it applies at every slice alike and so belongs to the periodic structure.

Definition at line 544 of file KTBNInference.h.

Referenced by _windowPotentials_(), and makeInference().

_k_

template<GUM_Numeric GUM_SCALAR>

int gum::KTBNInference< GUM_SCALAR >::_k_

private

The order k, cached as int for slice arithmetic.

Definition at line 472 of file KTBNInference.h.

Referenced by KTBNInference(), _applyTemporalObservations_(), _buildKernel_(), _buildWindows_(), _compileWindow_(), _familySlots_(), _fillWindow_(), _interfaceAfter_(), _lastConsumerSlice_(), _markRequisite_(), _psiKey_(), _templateVar_(), _varOfSlot_(), _windowAt_(), interfaceSize(), makeInference(), toString(), and windowJunctionTree().

_kernelCache_

template<GUM_Numeric GUM_SCALAR>

std::map< std::pair< std::string, int >, Tensor< GUM_SCALAR > > gum::KTBNInference< GUM_SCALAR >::_kernelCache_

mutableprivate

Memoized transition kernels, keyed by (process, t % k).

buildKernel reads t only through t % k (directly for the child, as (t - lag) % k for each parent – and t >= k with lag <= k-1 there, so the subtraction never goes negative). The kernel is therefore periodic in t with period k: at most k distinct tensors per process, whatever the horizon. Without this, a run rebuilds one per slice per process – and twice per slice once smoothing is on.

Cleared at the top of every makeInference(): cpt() hands out a const reference whose content is mutable, so a caller may edit CPT values between runs. Nothing can change during a run.

Definition at line 565 of file KTBNInference.h.

Referenced by _buildKernel_(), and makeInference().

_ktbn_

template<GUM_Numeric GUM_SCALAR>

const KTBN< GUM_SCALAR >* gum::KTBNInference< GUM_SCALAR >::_ktbn_

private

The k-DBN (referenced, not owned).

Definition at line 469 of file KTBNInference.h.

Referenced by KTBNInference(), _applyTemporalObservations_(), _buildKernel_(), _buildWindows_(), _compileWindow_(), _determineNode_(), _familySlots_(), _fillWindow_(), _isAtemporal_(), _isTemporal_(), _lastConsumerSlice_(), _markRequisite_(), _templateVar_(), _varOfSlot_(), ktbn(), and makeInference().

_logObservation_

template<GUM_Numeric GUM_SCALAR>

GUM_SCALAR gum::KTBNInference< GUM_SCALAR >::_logObservation_ {0}

private

log P(observation | do) of the last run.

Definition at line 494 of file KTBNInference.h.

Referenced by logObservationProbability(), and makeInference().

_maxLag_

template<GUM_Numeric GUM_SCALAR>

std::vector< int > gum::KTBNInference< GUM_SCALAR >::_maxLag_

private

maxLag[i]: largest lag at which the transition kernel still consumes temporal base i – how long an occurrence must stay in the interface, which is what makes |I| finite and the window template time-invariant.

Definition at line 514 of file KTBNInference.h.

Referenced by _buildWindows_(), and _lastConsumerSlice_().

_nbTemporal_

template<GUM_Numeric GUM_SCALAR>

std::size_t gum::KTBNInference< GUM_SCALAR >::_nbTemporal_ {0}

private

Definition at line 507 of file KTBNInference.h.

Referenced by KTBNInference(), _applyTemporalObservations_(), _buildWindows_(), _compileWindow_(), _familySlots_(), _fillWindow_(), _interfaceAfter_(), _lastConsumerSlice_(), _markRequisite_(), and makeInference().

_observations_

template<GUM_Numeric GUM_SCALAR>

std::map< std::string, std::vector< GUM_SCALAR > > gum::KTBNInference< GUM_SCALAR >::_observations_

private

Recorded observations, keyed by engine name -> likelihood vector (one-hot for a hard observation).

Definition at line 479 of file KTBNInference.h.

Referenced by _applyTemporalObservations_(), _fillWindow_(), _markRequisite_(), addObservation(), addObservation(), addObservations(), clearObservation(), eraseObservation(), hasObservation(), hasObservation(), makeInference(), and toString().

_observationSlices_

template<GUM_Numeric GUM_SCALAR>

std::unordered_set< int > gum::KTBNInference< GUM_SCALAR >::_observationSlices_

mutableprivate

Slices carrying a temporal observation. Their potentials are the periodic ones times that slice's likelihood, so they are served by copying the cached base and multiplying the evidence in – cheaper than a rebuild, which would redo the unit fill and every CPT product.

Definition at line 537 of file KTBNInference.h.

Referenced by _windowPotentials_(), and makeInference().

_posteriors_

template<GUM_Numeric GUM_SCALAR>

std::unordered_map< std::string, _Series_ > gum::KTBNInference< GUM_SCALAR >::_posteriors_

private

Cached marginal series of the last run, keyed by base name.

Definition at line 497 of file KTBNInference.h.

Referenced by _series_(), _snapshot_(), and makeInference().

_psiCache_

template<GUM_Numeric GUM_SCALAR>

std::vector< std::unordered_map< NodeId, Tensor< GUM_SCALAR > > > gum::KTBNInference< GUM_SCALAR >::_psiCache_

mutableprivate

Memoized clique potentials for the slices that carry no temporal evidence, indexed by psiKey(t). Sized 2k: the k initial slices have their own windows and their own CPTs, the repeating one contributes k phases. O(k) whatever the horizon – unlike keeping one per slice, which would make smoothing grow linearly in T.

Definition at line 530 of file KTBNInference.h.

Referenced by _windowPotentials_(), and makeInference().

_psiCached_

template<GUM_Numeric GUM_SCALAR>

std::vector< bool > gum::KTBNInference< GUM_SCALAR >::_psiCached_

mutableprivate

Definition at line 531 of file KTBNInference.h.

Referenced by _windowPotentials_(), and makeInference().

_psiScratch_

template<GUM_Numeric GUM_SCALAR>

std::unordered_map< NodeId, Tensor< GUM_SCALAR > > gum::KTBNInference< GUM_SCALAR >::_psiScratch_

mutableprivate

Potentials of an evidence-carrying slice, rebuilt on each visit.

Definition at line 547 of file KTBNInference.h.

Referenced by _windowPotentials_(), and makeInference().

_requisite_

template<GUM_Numeric GUM_SCALAR>

std::vector< bool > gum::KTBNInference< GUM_SCALAR >::_requisite_

private

Bases actually folded by the current run: the targets, the observed nodes and all their ancestors. Rebuilt per makeInference() from the current target/observation sets; anything outside is barren and cannot move an answer.

Definition at line 523 of file KTBNInference.h.

Referenced by KTBNInference(), _buildWindows_(), _compileWindow_(), _interfaceAfter_(), _lastConsumerSlice_(), _markRequisite_(), and makeInference().

_targeted_mode_

template<GUM_Numeric GUM_SCALAR>

bool gum::KTBNInference< GUM_SCALAR >::_targeted_mode_ {false}

private

Whether at least one explicit target has been declared.

Definition at line 485 of file KTBNInference.h.

Referenced by _markRequisite_(), addTarget(), clearTargets(), eraseTarget(), isInTargetMode(), isTarget(), makeInference(), and toString().

_targets_

template<GUM_Numeric GUM_SCALAR>

std::set< std::string > gum::KTBNInference< GUM_SCALAR >::_targets_

private

Recorded targets (base names). Empty <=> default-all-targets mode.

Definition at line 482 of file KTBNInference.h.

Referenced by _markRequisite_(), addTarget(), clearTargets(), eraseTarget(), isTarget(), makeInference(), and toString().

_temporalSorted_

template<GUM_Numeric GUM_SCALAR>

std::vector< std::string > gum::KTBNInference< GUM_SCALAR >::_temporalSorted_

private

Temporal / atemporal base names in a deterministic (sorted) order, cached once at construction (the KTBN's own sets are unordered).

Definition at line 501 of file KTBNInference.h.

Referenced by KTBNInference().

_windows_

template<GUM_Numeric GUM_SCALAR>

std::vector< _Window_ > gum::KTBNInference< GUM_SCALAR >::_windows_

private

The compiled windows: index t for t <= k-2 (initial), index k-1 for the repeating window, reused by every slice from k-1 on. Built once.

Definition at line 518 of file KTBNInference.h.

Referenced by _buildWindows_(), _windowAt_(), interfaceSize(), and windowJunctionTree().

ATEMPORAL

template<GUM_Numeric GUM_SCALAR>

int gum::KTBNInference< GUM_SCALAR >::ATEMPORAL = KTBN< GUM_SCALAR >::ATEMPORAL

staticconstexpr

Convenience alias for the atemporal-slice sentinel.

Definition at line 150 of file KTBNInference.h.

Referenced by _buildKernel_(), _buildWindows_(), _compileWindow_(), _determineNode_(), _encode_(), _familySlots_(), _fillWindow_(), _interfaceAfter_(), _lastConsumerSlice_(), _markRequisite_(), _snapshot_(), _templateVar_(), _validateNode_(), _varOfSlot_(), makeInference(), and posterior().

---

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

• agrum/KTBN/inference/KTBNInference.h
• agrum/KTBN/inference/KTBNInference_tpl.h