gum::KTBN< GUM_SCALAR > Class Template Reference

Class representing a k-order dynamic Bayesian network (k-DBN). More...

#include <agrum/KTBN/KTBN.h>

Public Member Functions
Constructors and Destructor
	KTBN (Size k=2)
	Default constructor.
virtual	~KTBN ()
	Destructor.
	KTBN (const KTBN< GUM_SCALAR > &source)
	Copy constructor.
	KTBN (KTBN< GUM_SCALAR > &&source) noexcept
	Move constructor.
KTBN< GUM_SCALAR > &	operator= (const KTBN< GUM_SCALAR > &source)
	Copy assignment operator.
KTBN< GUM_SCALAR > &	operator= (KTBN< GUM_SCALAR > &&source) noexcept
	Move assignment operator.
Accessors
Size	k () const
Size	size () const
Size	sizeArcs () const
bool	empty () const
void	clear ()
	Removes all variables and arcs, keeping the order \(k\).
Variable management
void	add (const DiscreteVariable &var, bool temporal=true)
	Adds a variable to the k-DBN.
void	add (std::string_view fast_description, bool temporal=true, unsigned int default_nbrmod=2)
	Adds a variable using the "fast" textual description syntax.
void	addTemporal (const DiscreteVariable &var)
	Convenience shortcut for add(var, true).
void	addAtemporal (const DiscreteVariable &var)
	Convenience shortcut for add(var, false).
void	addTemporal (std::string_view fast_description, unsigned int default_nbrmod=2)
	Convenience shortcut for add(fast_description, true, default_nbrmod).
void	addAtemporal (std::string_view fast_description, unsigned int default_nbrmod=2)
	Convenience shortcut for add(fast_description, false, default_nbrmod).
void	erase (std::string_view base)
	Removes a variable and all its incident arcs.
void	changeVariableName (std::string_view oldBase, std::string_view newBase)
	Renames a variable (temporal process or atemporal variable).
Variable queries
bool	exists (std::string_view base) const
const std::unordered_set< std::string > &	temporalVarNames () const
const std::unordered_set< std::string > &	atemporalVarNames () const
Size	nbTemporalVars () const
Size	nbAtemporalVars () const
std::vector< std::pair< std::string, int > >	nodes () const
std::vector< std::pair< std::string, int > >	parents (std::string_view base, int slice) const
	Parents of a node as (base, slice) pairs (ATEMPORAL if atemporal).
std::vector< std::pair< std::string, int > >	parents (std::string_view node_name) const
	Returns the parents using an engine name ("X[1]", "C", …).
std::vector< std::pair< std::string, int > >	children (std::string_view base, int slice) const
	Children of a node as (base, slice) pairs (ATEMPORAL if atemporal).
std::vector< std::pair< std::string, int > >	children (std::string_view node_name) const
	Returns the children using an engine name ("X[1]", "C", …).
const DiscreteVariable &	variable (std::string_view base, int slice) const
	Returns the gum::DiscreteVariable of a (process, slice) couple.
const DiscreteVariable &	variable (std::string_view node_name) const
	Same, using an engine name: resolved via _determineNode_, so "X[1]" and bare "C" are both accepted.
int	timeSlice (const DiscreteVariable &var) const
	The time slice of var, or ATEMPORAL if it is atemporal.
std::string	baseName (const DiscreteVariable &var) const
	Returns the base name (without bracket encoding) of var.
Arc management
void	addArc (std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice)
	Adds an arc between two (process, slice) endpoints.
void	addArc (std::string_view tail, std::string_view head)
	Adds an arc using internal engine names (bracket notation: "X[0]", "C", …).
void	eraseArc (std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice)
	Removes an arc between two (process, slice) endpoints.
void	eraseArc (std::string_view tail, std::string_view head)
	Removes an arc using internal engine names (bracket notation).
bool	existsArc (std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice) const
bool	existsArc (std::string_view tail, std::string_view head) const
std::vector< std::pair< std::pair< std::string, int >, std::pair< std::string, int > > >	arcs () const
Conditional probability tables
const Tensor< GUM_SCALAR > &	cpt (std::string_view base, int slice) const
	Returns the CPT of a (process, slice) couple.
const Tensor< GUM_SCALAR > &	cpt (std::string_view node_name) const
	Returns the CPT using an engine name ("X[1]", "C", …).
void	fillCPT (std::string_view base, int slice, const std::map< std::pair< std::string, int >, KTBNModality > &parents, const std::vector< GUM_SCALAR > &distribution) const
	Fills one conditional distribution P(node | parent configuration).
void	fillCPT (std::string_view node_name, const std::map< std::variant< std::string, std::pair< std::string, int > >, KTBNModality > &parents, const std::vector< GUM_SCALAR > &distribution) const
	Fills one conditional distribution using internal bracket-notation engine name for the target node — the bracket notation visible in toDot() and toString(): "X[t]" for a temporal variable at slice t, and the bare variable name for an atemporal variable (e.g.
void	generateCPTs () const
	Randomly generates every CPT of the template.
void	generateCPT (std::string_view base, int slice) const
	Randomly generates the CPT of a single node.
void	generateCPT (std::string_view node_name) const
	Same, using an engine name ("X[1]", "C", …).
Transformations
BayesNet< GUM_SCALAR >	toBN () const
BayesNet< GUM_SCALAR >	unroll (Size nbTimeSlices) const
	Unrolls the k-DBN into a standard gum::BayesNet.
Various
std::string	toString () const
std::string	toDot () const
	Returns a Graphviz DOT string with one cluster per time slice.
std::string	toUnrolledDot (Size T, bool highlightReplicated=false) const
	Returns a Graphviz DOT string of the k-DBN unrolled over T time slices.
std::string	bnToDot () const
	Returns the Graphviz DOT string of the underlying storage BayesNet.
std::string	summaryGraph () const
	Returns the Graphviz DOT string of the summary graph: the projection of the transition kernel alone (the pattern that actually repeats through time when unrolling), not the whole template.

Static Public Attributes
static constexpr int	ATEMPORAL = -1
	Conventional time-slice value denoting an atemporal (static) variable.

Private Member Functions
std::string	_encode_ (std::string_view base, int slice) const
	Encodes (base, slice) → engine name: base[t], or base if atemporal.
std::pair< std::string, int >	_decodeName_ (std::string_view name) const
	Purely syntactic parse of an engine name → (base, slice). Slice is ATEMPORAL when there is no [digits] suffix. Does not consult the cached name sets, so a bracket-named atemporal node decodes as temporal here.
std::pair< std::string, int >	_determineNode_ (const std::string &name) const
	Cache-aware classification of a node name → (base, slice): nodes registered in _atemporal_ (atemporal and orphan-bracket) map to ATEMPORAL, every other name is parsed by decodeName.
std::vector< std::pair< std::string, int > >	_determineNodeSet_ (const NodeSet &ids) const
	Maps a set of node ids to (base, slice) pairs (via determineNode).
NodeId	_validateVariable_ (std::string_view base, int slice) const
	Resolves and validates a (base, slice) endpoint into its NodeId.
void	_validateAdd_ (const std::string &base, bool temporal) const
	Checks that a variable named base can be added.
void	_determineNodesFromBN_ (const std::unordered_set< std::string > &atemporalNodes, std::vector< std::string > *warnings)
	Rebuilds the cached name sets from the storage engine content (used by fromBN()/load(); decodes names once).
std::string	_timeSlicesToDot_ (const BayesNet< GUM_SCALAR > &bn, bool highlightReplicated) const
	Renders bn as time-slice-clustered DOT. Shared engine behind toDot() (on _bn_) and toUnrolledDot() (on unroll(T)).

Static Private Member Functions
static std::pair< std::string, bool >	_resolveGumFormat_ (std::string_view filename)
	Resolves a user filename to (filepath, binary): ensures a .jgum/.bgum extension (.bgum appended by default) and reports whether the format is binary. Single source of truth for the GUM format convention shared by save() and load().
static std::string	_escapeDot_ (std::string_view name)
	Escapes double quotes for a DOT identifier or label. Shared by timeSlicesToDot() and summaryGraph().

Private Attributes
Size	_k_
	The order (number of time slices in the template).
BayesNet< GUM_SCALAR >	_bn_
	The underlying Bayesian network used as a storage engine for the template.
std::unordered_set< std::string >	_temporal_
	Base names of the registered temporal processes.
std::unordered_set< std::string >	_atemporal_
	Base names of the registered atemporal variables.

Persistence and conversion
void	save (std::string_view filename) const
	Saves the template in the GUM format (text .jgum or binary .bgum).
static KTBN< GUM_SCALAR >	load (std::string_view filename)
	Loads a k-DBN from a GUM file produced by save().
static KTBN< GUM_SCALAR >	fromBN (const BayesNet< GUM_SCALAR > &bn, const std::unordered_set< std::string > &atemporalNodes={}, std::vector< std::string > *warnings=nullptr)
	Builds a k-DBN from an existing gum::BayesNet, reading its node names under one of two mutually exclusive conventions.

Detailed Description

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

Class representing a k-order dynamic Bayesian network (k-DBN).

A k-order dynamic Bayesian network (k-DBN, sometimes called a k-Time-slice Bayesian Network or k-TBN) generalizes the classical 2-TBN: the conditional distribution of a variable at time \(t\) may depend on the \(k\) most recent time slices \(t, t-1, \ldots, t-k+1\) instead of a single step backward.

Rather than storing an (infinite) unrolled network, a KTBN only stores a template made of exactly \(k\) time slices. This template captures both:

• the initial distribution, encoded by slices \(0, \ldots, k-2\) (the initial slices, where the full \(k\)-history is not yet available), and
• the transition kernel, encoded by slice \(k-1\) as a function of slices \(0, \ldots, k-1\). Because the process is time-homogeneous, this kernel is reused for every \(t \geq k-1\) when unrolling.

Two kinds of random variables are distinguished:

• temporal variables (also called processes here), which evolve through time and are therefore represented by \(k\) instances (one per slice) in the template;
• atemporal variables, which are constant through time (e.g. a static context parameter) and are represented by a single instance.

Node identity: the bracket notation

The identity of a node in the underlying engine is its name. Temporal nodes are stored using bracket notation: the \(t\)-th instance of a process base is named base[t] (e.g. "X[0]", "X[1]", ...). Atemporal variables keep their bare name. The class holds no gum::NodeId index table: a (process, slice) couple is resolved to its node by encoding it and asking the engine, and a node's slice is recovered by decoding its name. The public API is always expressed in terms of (process, slice) couples; the bracket encoding is an internal detail.

Internal storage

Structure and parameters are stored in an underlying gum::BayesNet (the template) used purely as a storage engine, so that gum::Tensor CPTs, cycle detection, topological ordering and the existing I/O readers/writers are reused as-is. The gum::BayesNet is the single source of truth; the class only caches two name sets (the temporal processes and the atemporal variables) for fast O(1) membership queries. These sets are std::unordered_set, so their iteration order is unspecified; methods that need a deterministic order must sort explicitly.

Name collision rule

All base names must be globally unique: a name cannot be used for both a temporal process and an atemporal variable simultaneously. In addition, an atemporal variable named "X[0]" is forbidden when a temporal process "X" exists (and vice-versa), because both would map to the same BN node "X[0]". The reservation covers every bracket-suffixed name over an existing process, not only the slices that process actually holds: "X[999]" is refused for \(k=3\) as well, since the slice index is parsed without an upper bound and such a name would otherwise shadow the process. add() and changeVariableName() enforce these rules and throw DuplicateLabel or InvalidArgument on violation.

Arc semantics

Arcs must respect temporal causality. For an arc \(u \rightarrow v\):

• if v is atemporal, then u must be atemporal too (a static variable cannot depend on a time-varying one);
• if v is temporal at slice \(t_v\) and u is temporal at slice \(t_u\), then \(t_u \leq t_v\) (no arc from the future to the past). The lag of the arc is \(t_v - t_u \in [0, k-1]\);
• an atemporal u may point to a temporal v at any slice.

Warning

Unlike the Python prototype, unroll() correctly handles arcs of arbitrary lag (e.g. an arc X[0] -> X[2] for \(k=3\)), not only arcs between consecutive slices.

Definition at line 197 of file KTBN.h.

Constructor & Destructor Documentation

KTBN() [1/3]

template<GUM_Numeric GUM_SCALAR>

gum::KTBN< GUM_SCALAR >::KTBN ( Size k = 2 )

explicit

Default constructor.

Parameters

k	The order of the k-DBN, i.e. the number of time slices stored in the template. Must be \(\geq 1\).

Exceptions

InvalidArgument

if k is 0.

Definition at line 131 of file KTBN_tpl.h.

                                 : _k_(k) {
    if (k == 0) GUM_ERROR(InvalidArgument, "A k-DBN must have an order k >= 1.")
    GUM_CONSTRUCTOR(KTBN)
  }

References KTBN(), _k_, GUM_ERROR, and k().

Referenced by KTBN(), KTBN(), KTBN(), ~KTBN(), operator=(), and operator=().

Here is the call graph for this function:

Here is the caller graph for this function:

~KTBN()

template<GUM_Numeric GUM_SCALAR>

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

virtual

Destructor.

Definition at line 137 of file KTBN_tpl.h.

                            {
    GUM_DESTRUCTOR(KTBN)
  }

References KTBN().

Here is the call graph for this function:

KTBN() [2/3]

template<GUM_Numeric GUM_SCALAR>

gum::KTBN< GUM_SCALAR >::KTBN

(

const KTBN< GUM_SCALAR > &

source

)

Copy constructor.

Definition at line 142 of file KTBN_tpl.h.

                                                           :
      _k_(source._k_), _bn_(source._bn_), _temporal_(source._temporal_),
      _atemporal_(source._atemporal_) {
    GUM_CONS_CPY(KTBN)
  }

References KTBN(), _atemporal_, _bn_, _k_, and _temporal_.

Here is the call graph for this function:

KTBN() [3/3]

template<GUM_Numeric GUM_SCALAR>

gum::KTBN< GUM_SCALAR >::KTBN ( KTBN< GUM_SCALAR > && source )

noexcept

Move constructor.

Definition at line 149 of file KTBN_tpl.h.

                                                               :
      _k_(source._k_), _bn_(std::move(source._bn_)), _temporal_(std::move(source._temporal_)),
      _atemporal_(std::move(source._atemporal_)) {
    GUM_CONS_MOV(KTBN)
  }

References KTBN(), _atemporal_, _bn_, _k_, and _temporal_.

Here is the call graph for this function:

Member Function Documentation

_decodeName_()

template<GUM_Numeric GUM_SCALAR>

std::pair< std::string, int > gum::KTBN< GUM_SCALAR >::_decodeName_ ( std::string_view name ) const

private

Purely syntactic parse of an engine name → (base, slice). Slice is ATEMPORAL when there is no [digits] suffix. Does not consult the cached name sets, so a bracket-named atemporal node decodes as temporal here.

Definition at line 84 of file KTBN_tpl.h.

                                                                                      {
    const std::size_t bracketPos = name.rfind('[');
    if (bracketPos == std::string_view::npos) return {std::string{name}, ATEMPORAL};
 
    const std::string_view bracketContent = name.substr(bracketPos + 1);
    if (bracketContent.empty() || bracketContent.back() != ']')
      return {std::string{name}, ATEMPORAL};
 
    const std::string_view digits = bracketContent.substr(0, bracketContent.size() - 1);
    if (digits.empty()) return {std::string{name}, ATEMPORAL};
    for (const char c: digits)
      if (std::isdigit(static_cast< unsigned char >(c)) == 0) return {std::string{name}, ATEMPORAL};
 
    int slice{};
    try {
      slice = std::stoi(std::string{digits});
    } catch (const std::out_of_range&) {
      GUM_ERROR(InvalidArgument,
                "Node name '" << name << "' has a slice index too large to represent as int.")
    }
    return {std::string{name.substr(0, bracketPos)}, slice};
  }

References ATEMPORAL, and GUM_ERROR.

Referenced by _determineNode_(), _determineNodesFromBN_(), _timeSlicesToDot_(), _validateAdd_(), changeVariableName(), and summaryGraph().

Here is the caller graph for this function:

_determineNode_()

template<GUM_Numeric GUM_SCALAR>

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

private

Cache-aware classification of a node name → (base, slice): nodes registered in _atemporal_ (atemporal and orphan-bracket) map to ATEMPORAL, every other name is parsed by decodeName.

Definition at line 109 of file KTBN_tpl.h.

                                                                        {
    // Atemporal and orphan-bracket nodes are registered in _atemporal_ and map to ATEMPORAL;
    // any other name is a temporal "base[t]" parsed by _decodeName_.
    if (_atemporal_.contains(name)) return {name, ATEMPORAL};
    return _decodeName_(name);
  }

References _atemporal_, _decodeName_(), and ATEMPORAL.

Referenced by _determineNodeSet_(), _determineNodesFromBN_(), addArc(), arcs(), baseName(), children(), cpt(), eraseArc(), existsArc(), generateCPT(), parents(), timeSlice(), and variable().

Here is the call graph for this function:

Here is the caller graph for this function:

_determineNodeSet_()

template<GUM_Numeric GUM_SCALAR>

std::vector< std::pair< std::string, int > > gum::KTBN< GUM_SCALAR >::_determineNodeSet_ ( const NodeSet & ids ) const

private

Maps a set of node ids to (base, slice) pairs (via determineNode).

Definition at line 118 of file KTBN_tpl.h.

                                                                     {
    std::vector< std::pair< std::string, int > > result;
    result.reserve(ids.size());
    for (const NodeId id: ids)
      result.push_back(_determineNode_(_bn_.variable(id).name()));
    return result;
  }

References _bn_, _determineNode_(), and gum::Set< Key >::size().

Referenced by children(), and parents().

Here is the call graph for this function:

Here is the caller graph for this function:

_determineNodesFromBN_()

template<GUM_Numeric GUM_SCALAR>

void gum::KTBN< GUM_SCALAR >::_determineNodesFromBN_ ( const std::unordered_set< std::string > & atemporalNodes, std::vector< std::string > * warnings )

private

Rebuilds the cached name sets from the storage engine content (used by fromBN()/load(); decodes names once).

Definition at line 890 of file KTBN_tpl.h.

                                                     {
    _temporal_.clear();
    _atemporal_.clear();
 
    // a declared name must be a node of the BN: checked before any mutation, so
    // a typo cannot leave the object half-built
    for (const std::string& name: atemporalNodes)
      if (!_bn_.exists(name))
        GUM_ERROR(NotFound, "fromBN: '" << name << "' is not a node of the BN.")
 
    const auto warn = [warnings](const std::string& message) {
      if (warnings != nullptr) warnings->push_back(message);
    };
 
    // fromBN()'s bracket-free convention: a name ending in a run of digits
    // denotes a temporal variable at the timeslice given by that integer (base =
    // everything before the run); a name with no trailing digit is atemporal.
    // Purely syntactic, like _decodeName_, but that one expects the engine's own
    // base[t] convention. Used below only when the source BN carries no bracket
    // at all (see hasBracket).
    const auto decodeTrailingSlice = [](std::string_view name) -> std::pair< std::string, int > {
      std::size_t pos = name.size();
      while (pos > 0 && std::isdigit(static_cast< unsigned char >(name[pos - 1])))
        --pos;
      if (pos == name.size()) return {std::string{name}, ATEMPORAL};
 
      const std::string_view digits = name.substr(pos);
      int                    slice{};
      try {
        slice = std::stoi(std::string{digits});
      } catch (const std::out_of_range&) {
        GUM_ERROR(InvalidArgument,
                  "Node name '" << name << "' has a slice index too large to represent as int.")
      }
      return {std::string{name.substr(0, pos)}, slice};
    };
 
    // The two conventions never mix within one graph: if any node name already
    // carries the engine's own base[t] bracket notation, the WHOLE graph is read
    // that way (legacy behaviour -- what KTBNLearner and toBN() round-trips
    // produce); only when no node carries a bracket at all does every node get
    // read via the trailing-integer convention above. Nodes declared in
    // atemporalNodes are skipped here: their shape says nothing about the rest
    // of the graph's convention, so a bracket-shaped one (e.g. an orphan
    // "Y[0]" named atemporal on purpose, see below) must not force
    // bracket-reading onto otherwise bracket-free temporal nodes.
    bool hasBracket = false;
    for (const NodeId n: _bn_.nodes()) {
      const std::string& name = _bn_.variable(n).name();
      if (atemporalNodes.contains(name)) continue;
      if (_decodeName_(name).second != ATEMPORAL) {
        hasBracket = true;
        break;
      }
    }
 
    // first pass: determine every node, collecting the slices seen per process
    std::vector< std::string >                         discovered;   // temporal bases, in order
    HashTable< std::string, HashTable< int, NodeId > > slicesPerProcess;
    int                                                maxSlice = -1;
 
    for (const NodeId n: _bn_.nodes()) {
      const std::string& name = _bn_.variable(n).name();
 
      // an explicitly declared node is atemporal whatever its shape, trailing
      // digits included: it never enters slicesPerProcess, so the completeness
      // rules below never see it and never warn about it
      if (atemporalNodes.contains(name)) {
        _atemporal_.insert(name);
        continue;
      }
 
      const auto [base, slice] = hasBracket ? _decodeName_(name) : decodeTrailingSlice(name);
 
      if (slice == ATEMPORAL) {
        _atemporal_.insert(base);
      } else {
        if (!slicesPerProcess.exists(base)) {
          slicesPerProcess.insert(base, HashTable< int, NodeId >());
          discovered.push_back(base);
        }
 
        if (slicesPerProcess[base].exists(slice))
          GUM_ERROR(OperationNotAllowed,
                    "Two variables map to process '" << base << "' at slice " << slice << ".")
 
        slicesPerProcess[base].insert(slice, n);
 
        if (slice > maxSlice) maxSlice = slice;
      }
    }
 
    _k_ = (maxSlice < 0) ? Size(1) : Size(maxSlice + 1);
 
    // second pass: register the complete processes. A group that does not cover
    // every slice 0..k-1 is NOT rejected: each of its nodes becomes an atemporal
    // variable, original name kept, and a warning is recorded. Only a base used
    // BOTH bare and temporal-shaped stays an error -- there the two readings
    // collide on one name, and no reclassification can resolve that.
    const char* const conventionNoun = hasBracket ? "bracket" : "digit-suffixed";
    for (const auto& base: discovered) {
      const HashTable< int, NodeId >& sliceMap = slicesPerProcess[base];
 
      if (_atemporal_.contains(base))
        GUM_ERROR(OperationNotAllowed,
                  "Base name '" << base << "' is used both as an atemporal variable (bare node '"
                                << base << "') and as a temporal process (via " << conventionNoun
                                << " nodes). " << "Rename one of them before calling fromBN().")
 
      std::string missing;
      for (Size t = 0; t < _k_; ++t)
        if (!sliceMap.exists(static_cast< int >(t))) {
          if (!missing.empty()) missing += ", ";
          missing += std::to_string(t);
        }
 
      if (missing.empty()) {
        // Every slice of a process must carry the SAME variable. add() cannot
        // break this -- it clones one variable into k instances -- so fromBN()
        // is the only way in, and nothing downstream re-checks: KTBNInference
        // sizes every ring slot of a process from the kernel slice alone, so a
        // slice with a divergent domain would be triangulated against the wrong
        // size and then filled with a tensor of another dimension.
        // Names necessarily differ between slices, and Variable::operator==
        // compares them, so the reference is renamed onto each slice in turn.
        const DiscreteVariable&             ref = _bn_.variable(sliceMap[0]);
        std::unique_ptr< DiscreteVariable > probe(ref.clone());
        for (Size t = 1; t < _k_; ++t) {
          const DiscreteVariable& other = _bn_.variable(sliceMap[static_cast< int >(t)]);
          probe->setName(other.name());
          if (!(*probe == other))
            GUM_ERROR(OperationNotAllowed,
                      "The temporal process '"
                          << base << "' has mismatched slice variables: '" << ref.name() << "' is "
                          << ref.domain() << " but '" << other.name() << "' is " << other.domain()
                          << ". Every slice of a process must have the same type and domain.")
        }
        _temporal_.insert(base);
        if (!hasBracket) {
          // Under the trailing-integer convention the slices just matched above
          // carry no bracket notation yet: rename them onto the engine's
          // canonical base[t] form -- the invariant every other method (add(),
          // unroll(), rename(), ...) relies on. Under the bracket convention
          // source names are already canonical, so nothing to do here.
          for (Size t = 0; t < _k_; ++t)
            _bn_.changeVariableName(_bn_.variable(sliceMap[static_cast< int >(t)]).name(),
                                    _encode_(base, static_cast< int >(t)));
        }
        continue;
      }
 
      std::string reclassified;
      for (auto it = sliceMap.cbegin(); it != sliceMap.cend(); ++it) {
        const std::string& nodeName = _bn_.variable(it.val()).name();
        _atemporal_.insert(nodeName);
        if (!reclassified.empty()) reclassified += ", ";
        reclassified += "'" + nodeName + "'";
      }
      warn("Node(s) " + reclassified + " look temporal (base='" + base + "', " + conventionNoun
           + " convention) but the process is missing slice(s) " + missing
           + " for k=" + std::to_string(_k_)
           + ": they are classified as atemporal variables, original name kept. Pass them in "
             "fromBN()'s atemporalNodes argument to make that explicit and silence this warning.");
    }
 
    // Every surviving process holds exactly the slices 0..k-1, so k is still the
    // one the first pass computed -- unless none survived, in which case the
    // largest slice index was contributed by a group that is now atemporal and
    // k has nothing left to describe.
    if (_temporal_.empty()) _k_ = Size(1);
 
 
    // third pass: validate temporal causality of the foreign arcs.
    for (const auto& arc: _bn_.arcs()) {
      const int tailSlice = _determineNode_(_bn_.variable(arc.tail()).name()).second;
      const int headSlice = _determineNode_(_bn_.variable(arc.head()).name()).second;
      if (headSlice == ATEMPORAL && tailSlice != ATEMPORAL)
        GUM_ERROR(OperationNotAllowed,
                  "The network has a temporal->atemporal arc into '"
                      << _bn_.variable(arc.head()).name() << "'.")
      if (headSlice != ATEMPORAL && tailSlice != ATEMPORAL && tailSlice > headSlice)
        GUM_ERROR(OperationNotAllowed,
                  "The network has a future->past arc " << _bn_.variable(arc.tail()).name() << "->"
                                                        << _bn_.variable(arc.head()).name() << ".")
    }
  }

References _atemporal_, _bn_, _decodeName_(), _determineNode_(), _encode_(), _k_, _temporal_, ATEMPORAL, gum::HashTable< Key, Val >::cbegin(), gum::HashTable< Key, Val >::cend(), gum::DiscreteVariable::clone(), gum::DiscreteVariable::domain(), gum::HashTable< Key, Val >::exists(), exists(), GUM_ERROR, gum::HashTable< Key, Val >::insert(), and gum::Variable::name().

Here is the call graph for this function:

_encode_()

template<GUM_Numeric GUM_SCALAR>

INLINE std::string gum::KTBN< GUM_SCALAR >::_encode_ ( std::string_view base, int slice ) const

private

Encodes (base, slice) → engine name: base[t], or base if atemporal.

Definition at line 78 of file KTBN_tpl.h.

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

References ATEMPORAL.

Referenced by _determineNodesFromBN_(), _timeSlicesToDot_(), _validateAdd_(), _validateVariable_(), add(), changeVariableName(), erase(), fillCPT(), and unroll().

Here is the caller graph for this function:

_escapeDot_()

template<GUM_Numeric GUM_SCALAR>

std::string gum::KTBN< GUM_SCALAR >::_escapeDot_ ( std::string_view name )

staticprivate

Escapes double quotes for a DOT identifier or label. Shared by timeSlicesToDot() and summaryGraph().

Definition at line 1131 of file KTBN_tpl.h.

                                                               {
    std::string out;
    out.reserve(name.size());
    for (const char c: name) {
      if (c == '"') out += '\\';
      out += c;
    }
    return out;
  }

Referenced by _timeSlicesToDot_(), and summaryGraph().

Here is the caller graph for this function:

_resolveGumFormat_()

template<GUM_Numeric GUM_SCALAR>

std::pair< std::string, bool > gum::KTBN< GUM_SCALAR >::_resolveGumFormat_ ( std::string_view filename )

staticprivate

Resolves a user filename to (filepath, binary): ensures a .jgum/.bgum extension (.bgum appended by default) and reports whether the format is binary. Single source of truth for the GUM format convention shared by save() and load().

Definition at line 786 of file KTBN_tpl.h.

                                                                                           {
    // The extension selects the format: ".jgum" is text, anything else is binary
    // and gets a ".bgum" extension appended if missing.
    std::string filepath{filename};
    const bool  text = filepath.ends_with(".jgum");
    if (!text && !filepath.ends_with(".bgum")) filepath += ".bgum";
    return {std::move(filepath), !text};   // .second = binary
  }

Referenced by load(), and save().

Here is the caller graph for this function:

_timeSlicesToDot_()

template<GUM_Numeric GUM_SCALAR>

std::string gum::KTBN< GUM_SCALAR >::_timeSlicesToDot_ ( const BayesNet< GUM_SCALAR > & bn, bool highlightReplicated ) const

private

Renders bn as time-slice-clustered DOT. Shared engine behind toDot() (on _bn_) and toUnrolledDot() (on unroll(T)).

Definition at line 1146 of file KTBN_tpl.h.

                                                                                    {
    // Group (full name, base label) by timeslice. std::map keeps keys sorted, and
    // ATEMPORAL == -1 so atemporal variables naturally sort first, followed by
    // increasing slice indices — mirroring pyAgrum's noTimeCluster-then-slices order.
    std::map< int, std::vector< std::pair< std::string, std::string > > > timeslices;
    for (const NodeId n: bn.nodes()) {
      const std::string& name  = bn.variable(n).name();
      const auto [base, slice] = _decodeName_(name);
      timeslices[slice].emplace_back(name, base);
    }
 
    std::stringstream dot;
    dot << "digraph KTBN {\n";
    dot << "  rankdir=LR;\n";
    dot << "  splines=ortho;\n";
    dot << "  node [color=\"#000000\", fillcolor=white, style=filled];\n\n";
 
    for (auto& [slice, nodes]: timeslices) {
      std::sort(nodes.begin(), nodes.end());
      if (slice == ATEMPORAL) {
        dot << "  subgraph cluster_atemporal {\n";
        dot << "    label=\"atemporal\";\n";
        dot << "    style=filled;\n";
        dot << "    bgcolor=\"lightyellow\";\n";
        for (const auto& [full, label]: nodes)
          dot << "    \"" << _escapeDot_(full) << "\" [label=\"" << _escapeDot_(label) << "\"];\n";
        dot << "  }\n";
      } else {
        const bool replicated = highlightReplicated && Size(slice) >= _k_;
        dot << "  subgraph cluster_" << slice << " {\n";
        dot << "    label=\"Time slice " << slice << "\";\n";
        dot << "    style=filled;\n";
        dot << "    bgcolor=\"" << (replicated ? "lightcyan" : "#DDDDDD") << "\";\n";
        for (const auto& [full, label]: nodes)
          dot << "    \"" << _escapeDot_(full) << "\" [label=\"" << _escapeDot_(label) << "\"];\n";
        dot << "  }\n";
      }
      dot << "\n";
    }
 
    dot << "  edge [color=black, constraint=false];\n";
    for (const auto& arc: bn.arcs())
      dot << "  \"" << _escapeDot_(bn.variable(arc.tail()).name()) << "\" -> \""
          << _escapeDot_(bn.variable(arc.head()).name()) << "\";\n";
 
    dot << "\n  edge [style=invis, constraint=true];\n";
    if (const auto it0 = timeslices.find(0); it0 != timeslices.end()) {
      for (const auto& node0: it0->second) {
        const std::string& label = node0.second;
        int                prec  = ATEMPORAL;
        bool               first = true;
        for (const auto& [slice, nodes]: timeslices) {
          if (slice == ATEMPORAL) continue;
          if (!first)
            dot << "  \"" << _escapeDot_(_encode_(label, prec)) << "\" -> \""
                << _escapeDot_(_encode_(label, slice)) << "\";\n";
          prec  = slice;
          first = false;
        }
      }
    }
 
    dot << "}\n";
    return dot.str();
  }

References _decodeName_(), _encode_(), _escapeDot_(), _k_, ATEMPORAL, and nodes().

Referenced by toDot(), and toUnrolledDot().

Here is the call graph for this function:

Here is the caller graph for this function:

_validateAdd_()

template<GUM_Numeric GUM_SCALAR>

void gum::KTBN< GUM_SCALAR >::_validateAdd_ ( const std::string & base, bool temporal ) const

private

Checks that a variable named base can be added.

Parameters

temporal

true for a temporal process, false for an atemporal variable.

Exceptions

DuplicateLabel

/ InvalidArgument on a name collision (see add()).

Definition at line 215 of file KTBN_tpl.h.

                                                                                   {
    const auto& ownSet   = temporal ? _temporal_ : _atemporal_;
    const auto& otherSet = temporal ? _atemporal_ : _temporal_;
 
    if (ownSet.contains(base))
      GUM_ERROR(DuplicateLabel,
                (temporal ? "A temporal process '" : "An atemporal variable '")
                    << base << "' already exists.")
    if (otherSet.contains(base))
      GUM_ERROR(DuplicateLabel,
                (temporal ? "Cannot add temporal process '" : "Cannot add atemporal variable '")
                    << base << "': " << (temporal ? "an atemporal variable" : "a temporal process")
                    << " with that name already exists.")
 
    if (temporal) {
      for (Size t = 0; t < _k_; ++t) {
        const std::string encoded = _encode_(base, static_cast< int >(t));
        if (_atemporal_.contains(encoded))
          GUM_ERROR(InvalidArgument,
                    "Temporal process '" << base << "' at slice " << t << " would produce node '"
                                         << encoded << "' which conflicts with atemporal variable '"
                                         << encoded << "'.")
      }
    } else {
      const auto [decodedBase, decodedSlice] = _decodeName_(base);
      if (decodedSlice != ATEMPORAL && _temporal_.contains(decodedBase)) {
        // Bracket notation over an existing temporal process is reserved in
        // FULL, whatever the index: _decodeName_ has no upper bound, so
        // "X[999]" decodes to (X, 999) and would shadow the process even though
        // no such node exists. Only the in-range case can claim an actual node
        // collision -- promising one for an out-of-range index would send the
        // caller looking for a node that was never there.
        if (Size(decodedSlice) < _k_)
          GUM_ERROR(InvalidArgument,
                    "Atemporal variable name '" << base << "' conflicts with temporal process '"
                                                << decodedBase
                                                << "': that name is already used by its slice "
                                                   "nodes.")
        GUM_ERROR(InvalidArgument,
                  "Atemporal variable name '"
                      << base << "' is invalid: '" << decodedBase
                      << "' is a temporal process, so every bracket-suffixed name over it is "
                         "reserved -- including slice "
                      << decodedSlice << ", beyond the current order k=" << _k_ << ".")
      }
    }
  }

References _atemporal_, _decodeName_(), _encode_(), _k_, _temporal_, ATEMPORAL, and GUM_ERROR.

Referenced by add().

Here is the call graph for this function:

Here is the caller graph for this function:

_validateVariable_()

template<GUM_Numeric GUM_SCALAR>

NodeId gum::KTBN< GUM_SCALAR >::_validateVariable_ ( std::string_view base, int slice ) const

private

Resolves and validates a (base, slice) endpoint into its NodeId.

Definition at line 434 of file KTBN_tpl.h.

                                                                                    {
    const std::string baseStr{base};
 
    if (slice == ATEMPORAL) {
      if (!_atemporal_.contains(baseStr)) {
        if (_temporal_.contains(baseStr))
          GUM_ERROR(OperationNotAllowed,
                    "'" << baseStr << "' is a temporal process but is used as atemporal.")
        GUM_ERROR(NotFound, "There is no atemporal variable named '" << baseStr << "'.")
      }
      return _bn_.idFromName(baseStr);
    }
 
    if (!_temporal_.contains(baseStr)) {
      if (_atemporal_.contains(baseStr))
        GUM_ERROR(OperationNotAllowed,
                  "'" << baseStr << "' is an atemporal variable but is used at slice " << slice
                      << ".")
      GUM_ERROR(NotFound, "There is no temporal process named '" << baseStr << "'.")
    }
    if (slice < 0 || Size(slice) >= _k_)
      GUM_ERROR(OutOfBounds,
                "Slice " << slice << " is out of [0," << (_k_ - 1) << "] for process '" << baseStr
                         << "'.")
    return _bn_.idFromName(_encode_(baseStr, slice));
  }

References _atemporal_, _bn_, _encode_(), _k_, _temporal_, ATEMPORAL, and GUM_ERROR.

Referenced by addArc(), children(), cpt(), eraseArc(), existsArc(), fillCPT(), generateCPT(), parents(), and variable().

Here is the call graph for this function:

Here is the caller graph for this function:

add() [1/2]

template<GUM_Numeric GUM_SCALAR>

void gum::KTBN< GUM_SCALAR >::add	(	const DiscreteVariable &	var,
		bool	temporal = true )

Adds a variable to the k-DBN.

A temporal variable (process) is cloned into \(k\) instances (one per slice); an atemporal variable is added once.

Parameters

var	The variable to add (added by copy).
temporal	Whether the variable is temporal.

Exceptions

DuplicateLabel	if a variable with that base name already exists (any kind — base names are globally unique).
InvalidArgument	if a temporal base[t] would collide with an existing atemporal node of that encoded name, or vice-versa.

Definition at line 264 of file KTBN_tpl.h.

                                                                         {
    const std::string base = var.name();
 
    if (temporal) {
      _validateAdd_(base, true);
      for (Size t = 0; t < _k_; ++t) {
        // clone() to rename; BayesNet::add() clones again internally (unavoidable via public API).
        std::unique_ptr< DiscreteVariable > clone(var.clone());
        clone->setName(_encode_(base, static_cast< int >(t)));
        _bn_.add(*clone);
      }
      _temporal_.insert(base);
    } else {
      _validateAdd_(base, false);
      _bn_.add(var);
      _atemporal_.insert(base);
    }
  }

References _atemporal_, _bn_, _encode_(), _k_, _temporal_, _validateAdd_(), gum::DiscreteVariable::clone(), and gum::Variable::name().

Referenced by add(), addAtemporal(), addAtemporal(), addTemporal(), and addTemporal().

Here is the call graph for this function:

Here is the caller graph for this function:

add() [2/2]

template<GUM_Numeric GUM_SCALAR>

void gum::KTBN< GUM_SCALAR >::add	(	std::string_view	fast_description,
		bool	temporal = true,
		unsigned int	default_nbrmod = 2 )

Adds a variable using the "fast" textual description syntax.

See also

gum::BayesNet::add(std::string_view,unsigned int)

Definition at line 284 of file KTBN_tpl.h.

                                                                {
    auto v = fastVariable< GUM_SCALAR >(std::string{fast_description}, Size(default_nbrmod));
    add(*v, temporal);
  }

References add(), and gum::fastVariable().

Here is the call graph for this function:

addArc() [1/2]

template<GUM_Numeric GUM_SCALAR>

void gum::KTBN< GUM_SCALAR >::addArc	(	std::string_view	tail,
		std::string_view	head )

Adds an arc using internal engine names (bracket notation: "X[0]", "C", …).

See also

fillCPT(node_name, …) for the same naming convention.

Exceptions

NotFound	if an endpoint name is not in the template.
OutOfBounds	/ OperationNotAllowed / DuplicateElement / InvalidDirectedCycle — same conditions as the (base, slice) overload.

Definition at line 529 of file KTBN_tpl.h.

                                                                          {
    const auto [tb, ts] = _determineNode_(std::string{tail});
    const auto [hb, hs] = _determineNode_(std::string{head});
    addArc(tb, ts, hb, hs);
  }

References _determineNode_(), and addArc().

Here is the call graph for this function:

addArc() [2/2]

template<GUM_Numeric GUM_SCALAR>

void gum::KTBN< GUM_SCALAR >::addArc	(	std::string_view	tailBase,
		int	tailSlice,
		std::string_view	headBase,
		int	headSlice )

Adds an arc between two (process, slice) endpoints.

Parameters

tailBase	Base name of the tail variable.
tailSlice	Slice of the tail (KTBN::ATEMPORAL for an atemporal tail).
headBase	Base name of the head variable.
headSlice	Slice of the head (KTBN::ATEMPORAL for an atemporal head).

Exceptions

NotFound	if an endpoint does not exist.
OutOfBounds	if a slice argument is out of \([0,k-1]\) for a temporal endpoint.
OperationNotAllowed	if the arc violates temporal causality (a temporal variable pointing to an atemporal one, or an arc from a future slice to a past slice).
DuplicateElement	if the arc already exists.
InvalidDirectedCycle	if the arc would create a cycle.

Definition at line 490 of file KTBN_tpl.h.

                                                              {
    const NodeId tail = _validateVariable_(tailBase, tailSlice);
    const NodeId head = _validateVariable_(headBase, headSlice);
 
    if (headSlice == ATEMPORAL) {
      if (tailSlice != ATEMPORAL)
        GUM_ERROR(OperationNotAllowed,
                  "A temporal variable cannot be a parent of the atemporal variable '" << headBase
                                                                                       << "'.")
    } else if (tailSlice != ATEMPORAL && tailSlice > headSlice) {
      GUM_ERROR(OperationNotAllowed,
                "An arc cannot go from a future slice (" << tailSlice << ") to a past slice ("
                                                         << headSlice << ").")
    }
 
    _bn_.addArc(tail, head);
  }

References _bn_, _validateVariable_(), ATEMPORAL, and GUM_ERROR.

Referenced by addArc().

Here is the call graph for this function:

Here is the caller graph for this function:

addAtemporal() [1/2]

template<GUM_Numeric GUM_SCALAR>

INLINE void gum::KTBN< GUM_SCALAR >::addAtemporal

(

const DiscreteVariable &

var

)

Convenience shortcut for add(var, false).

Definition at line 297 of file KTBN_tpl.h.

                                                                          {
    add(var, false);
  }

References add().

Here is the call graph for this function:

addAtemporal() [2/2]

template<GUM_Numeric GUM_SCALAR>

INLINE void gum::KTBN< GUM_SCALAR >::addAtemporal	(	std::string_view	fast_description,
		unsigned int	default_nbrmod = 2 )

Convenience shortcut for add(fast_description, false, default_nbrmod).

Definition at line 308 of file KTBN_tpl.h.

                                                                                {
    add(fast_description, false, default_nbrmod);
  }

References add().

Here is the call graph for this function:

addTemporal() [1/2]

template<GUM_Numeric GUM_SCALAR>

INLINE void gum::KTBN< GUM_SCALAR >::addTemporal

(

const DiscreteVariable &

var

)

Convenience shortcut for add(var, true).

Definition at line 292 of file KTBN_tpl.h.

                                                                         {
    add(var, true);
  }

References add().

Here is the call graph for this function:

addTemporal() [2/2]

template<GUM_Numeric GUM_SCALAR>

INLINE void gum::KTBN< GUM_SCALAR >::addTemporal	(	std::string_view	fast_description,
		unsigned int	default_nbrmod = 2 )

Convenience shortcut for add(fast_description, true, default_nbrmod).

Definition at line 302 of file KTBN_tpl.h.

                                                                               {
    add(fast_description, true, default_nbrmod);
  }

References add().

Here is the call graph for this function:

arcs()

template<GUM_Numeric GUM_SCALAR>

std::vector< std::pair< std::pair< std::string, int >, std::pair< std::string, int > > > gum::KTBN< GUM_SCALAR >::arcs

(

)

const

Returns

All arcs as (tail, head) pairs of (base, slice).

Definition at line 551 of file KTBN_tpl.h.

                                     {
    std::vector< std::pair< std::pair< std::string, int >, std::pair< std::string, int > > > result;
    result.reserve(_bn_.sizeArcs());
    for (const auto& arc: _bn_.arcs()) {
      result.emplace_back(_determineNode_(_bn_.variable(arc.tail()).name()),
                          _determineNode_(_bn_.variable(arc.head()).name()));
    }
    return result;
  }

References _bn_, and _determineNode_().

Referenced by toString().

Here is the call graph for this function:

Here is the caller graph for this function:

atemporalVarNames()

template<GUM_Numeric GUM_SCALAR>

INLINE const std::unordered_set< std::string > & gum::KTBN< GUM_SCALAR >::atemporalVarNames

(

)

const

Returns

The set of atemporal variable base names.

Definition at line 329 of file KTBN_tpl.h.

                                                                                          {
    return _atemporal_;
  }

References _atemporal_.

baseName()

template<GUM_Numeric GUM_SCALAR>

INLINE std::string gum::KTBN< GUM_SCALAR >::baseName

(

const DiscreteVariable &

var

)

const

Returns the base name (without bracket encoding) of var.

Exceptions

NotFound

if var is not a node of this k-DBN.

Definition at line 480 of file KTBN_tpl.h.

                                                                                 {
    _bn_.idFromName(var.name());   // throws NotFound if var is not in this k-DBN
    return _determineNode_(var.name()).first;
  }

References _bn_, _determineNode_(), and gum::Variable::name().

Here is the call graph for this function:

bnToDot()

template<GUM_Numeric GUM_SCALAR>

INLINE std::string gum::KTBN< GUM_SCALAR >::bnToDot

(

)

const

Returns the Graphviz DOT string of the underlying storage BayesNet.

Nodes are labelled with their internal engine names (bracket notation: base[t] for temporal nodes, bare name for atemporal nodes). No time-slice clustering is applied.

Definition at line 1214 of file KTBN_tpl.h.

                                                     {
    return _bn_.toDot();
  }

References _bn_.

changeVariableName()

template<GUM_Numeric GUM_SCALAR>

void gum::KTBN< GUM_SCALAR >::changeVariableName	(	std::string_view	oldBase,
		std::string_view	newBase )

Renames a variable (temporal process or atemporal variable).

The kind is determined automatically from the registered name sets. For a temporal process all \(k\) slice names are re-encoded with the new base.

Exceptions

NotFound	if no variable named oldBase exists.
DuplicateLabel	if a variable named newBase already exists (any kind).
InvalidArgument	if newBase is empty or would create a BN node-name collision.

Definition at line 398 of file KTBN_tpl.h.

                                                                                            {
    const std::string oldStr{oldBase};
    const std::string newStr{newBase};
 
    if (oldStr == newStr) return;
    if (newStr.empty()) GUM_ERROR(InvalidArgument, "New base name must not be empty.")
 
    if (!_temporal_.contains(oldStr) && !_atemporal_.contains(oldStr))
      GUM_ERROR(NotFound, "No variable named '" << oldStr << "' in the k-DBN.")
    if (_temporal_.contains(newStr) || _atemporal_.contains(newStr))
      GUM_ERROR(DuplicateLabel, "A variable named '" << newStr << "' already exists.")
 
    if (_temporal_.contains(oldStr)) {
      for (Size t = 0; t < _k_; ++t)
        if (_atemporal_.contains(_encode_(newStr, static_cast< int >(t))))
          GUM_ERROR(InvalidArgument,
                    "Renaming to '" << newStr << "': slice " << t
                                    << " collides with an atemporal variable.")
      for (Size t = 0; t < _k_; ++t)
        _bn_.changeVariableName(_encode_(oldStr, static_cast< int >(t)),
                                _encode_(newStr, static_cast< int >(t)));
      _temporal_.erase(oldStr);
      _temporal_.insert(newStr);
    } else {
      const auto [decodedBase, decodedSlice] = _decodeName_(newStr);
      if (decodedSlice != ATEMPORAL && _temporal_.contains(decodedBase))
        GUM_ERROR(InvalidArgument,
                  "'" << newStr << "' conflicts with temporal process '" << decodedBase
                      << "': that name is already used by its slice nodes.")
      _bn_.changeVariableName(oldStr, newStr);
      _atemporal_.erase(oldStr);
      _atemporal_.insert(newStr);
    }
  }

References _atemporal_, _bn_, _decodeName_(), _encode_(), _k_, _temporal_, ATEMPORAL, and GUM_ERROR.

Here is the call graph for this function:

children() [1/2]

template<GUM_Numeric GUM_SCALAR>

std::vector< std::pair< std::string, int > > gum::KTBN< GUM_SCALAR >::children	(	std::string_view	base,
		int	slice ) const

Children of a node as (base, slice) pairs (ATEMPORAL if atemporal).

Definition at line 369 of file KTBN_tpl.h.

                                                                                             {
    return _determineNodeSet_(_bn_.children(_validateVariable_(base, slice)));
  }

References _bn_, _determineNodeSet_(), and _validateVariable_().

Referenced by children().

Here is the call graph for this function:

Here is the caller graph for this function:

children() [2/2]

template<GUM_Numeric GUM_SCALAR>

std::vector< std::pair< std::string, int > > gum::KTBN< GUM_SCALAR >::children

(

std::string_view

node_name

)

const

Returns the children using an engine name ("X[1]", "C", …).

Definition at line 376 of file KTBN_tpl.h.

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

References _determineNode_(), and children().

Here is the call graph for this function:

clear()

template<GUM_Numeric GUM_SCALAR>

void gum::KTBN< GUM_SCALAR >::clear

(

)

Removes all variables and arcs, keeping the order \(k\).

Definition at line 204 of file KTBN_tpl.h.

                                 {
    _bn_.clear();
    _temporal_.clear();
    _atemporal_.clear();
  }

References _atemporal_, _bn_, and _temporal_.

cpt() [1/2]

template<GUM_Numeric GUM_SCALAR>

INLINE const Tensor< GUM_SCALAR > & gum::KTBN< GUM_SCALAR >::cpt	(	std::string_view	base,
		int	slice ) const

Returns the CPT of a (process, slice) couple.

The returned reference is const but its content is mutable — use any standard gum::Tensor method to fill it:

m.cpt("C").fillWith({0.4, 0.6});
m.cpt("X", 2).fillWith({0.8,0.2, 0.3,0.7, 0.6,0.4, 0.1,0.9});
m.cpt("Y", 1).fillWith(GUM_SCALAR(0.5));  // uniform

Values for the vector overload are in the CPT's natural iteration order: the node's own variable varies fastest, parents follow in the order they appear in cpt().variable(1..n). Use cpt().variable(i).name() to inspect the ordering before filling.

Definition at line 566 of file KTBN_tpl.h.

                                                                                           {
    return _bn_.cpt(_validateVariable_(base, slice));
  }

References _bn_, and _validateVariable_().

Referenced by cpt(), fillCPT(), and fillCPT().

Here is the call graph for this function:

Here is the caller graph for this function:

cpt() [2/2]

template<GUM_Numeric GUM_SCALAR>

INLINE const Tensor< GUM_SCALAR > & gum::KTBN< GUM_SCALAR >::cpt

(

std::string_view

node_name

)

const

Returns the CPT using an engine name ("X[1]", "C", …).

Definition at line 572 of file KTBN_tpl.h.

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

References _determineNode_(), and cpt().

Here is the call graph for this function:

empty()

template<GUM_Numeric GUM_SCALAR>

INLINE bool gum::KTBN< GUM_SCALAR >::empty

(

)

const

Returns

true if the template contains no variable.

Definition at line 199 of file KTBN_tpl.h.

                                              {
    return _bn_.empty();
  }

References _bn_.

erase()

template<GUM_Numeric GUM_SCALAR>

void gum::KTBN< GUM_SCALAR >::erase

(

std::string_view

base

)

Removes a variable and all its incident arcs.

The kind (temporal or atemporal) is determined automatically from the registered name sets. For a temporal process all \(k\) slice nodes are removed.

Exceptions

NotFound

if no variable with that name exists.

Definition at line 382 of file KTBN_tpl.h.

                                                    {
    const std::string baseStr{base};
 
    if (_temporal_.contains(baseStr)) {
      for (Size t = 0; t < _k_; ++t)
        _bn_.erase(_encode_(baseStr, static_cast< int >(t)));
      _temporal_.erase(baseStr);
    } else if (_atemporal_.contains(baseStr)) {
      _bn_.erase(baseStr);
      _atemporal_.erase(baseStr);
    } else {
      GUM_ERROR(NotFound, "No variable named '" << baseStr << "' in the k-DBN.")
    }
  }

References _atemporal_, _bn_, _encode_(), _k_, _temporal_, and GUM_ERROR.

Here is the call graph for this function:

eraseArc() [1/2]

template<GUM_Numeric GUM_SCALAR>

void gum::KTBN< GUM_SCALAR >::eraseArc	(	std::string_view	tail,
		std::string_view	head )

Removes an arc using internal engine names (bracket notation).

Exceptions

NotFound

if an endpoint name is unknown or the arc does not exist.

Definition at line 536 of file KTBN_tpl.h.

                                                                            {
    const auto [tb, ts] = _determineNode_(std::string{tail});
    const auto [hb, hs] = _determineNode_(std::string{head});
    eraseArc(tb, ts, hb, hs);
  }

References _determineNode_(), and eraseArc().

Here is the call graph for this function:

eraseArc() [2/2]

template<GUM_Numeric GUM_SCALAR>

void gum::KTBN< GUM_SCALAR >::eraseArc	(	std::string_view	tailBase,
		int	tailSlice,
		std::string_view	headBase,
		int	headSlice )

Removes an arc between two (process, slice) endpoints.

The arc must exist: erasing an absent arc throws (via the underlying CPT update), even when both endpoints are valid variables.

Exceptions

NotFound

/ OperationNotAllowed / OutOfBounds if an endpoint variable does not exist (same rules as addArc()), or if the arc itself does not exist.

Definition at line 512 of file KTBN_tpl.h.

                                                                {
    _bn_.eraseArc(_validateVariable_(tailBase, tailSlice), _validateVariable_(headBase, headSlice));
  }

References _bn_, and _validateVariable_().

Referenced by eraseArc().

Here is the call graph for this function:

Here is the caller graph for this function:

exists()

template<GUM_Numeric GUM_SCALAR>

INLINE bool gum::KTBN< GUM_SCALAR >::exists

(

std::string_view

base

)

const

Returns

true if a variable with this base name exists.

Definition at line 318 of file KTBN_tpl.h.

                                                                  {
    const std::string baseStr{base};
    return _temporal_.contains(baseStr) || _atemporal_.contains(baseStr);
  }

References _atemporal_, and _temporal_.

Referenced by _determineNodesFromBN_().

Here is the caller graph for this function:

existsArc() [1/2]

template<GUM_Numeric GUM_SCALAR>

bool gum::KTBN< GUM_SCALAR >::existsArc	(	std::string_view	tail,
		std::string_view	head ) const

Returns

true if the arc exists; uses internal engine names (bracket notation).

Exceptions

NotFound

if an endpoint name is unknown.

Definition at line 543 of file KTBN_tpl.h.

                                                                                   {
    const auto [tb, ts] = _determineNode_(std::string{tail});
    const auto [hb, hs] = _determineNode_(std::string{head});
    return existsArc(tb, ts, hb, hs);
  }

References _determineNode_(), and existsArc().

Here is the call graph for this function:

existsArc() [2/2]

template<GUM_Numeric GUM_SCALAR>

bool gum::KTBN< GUM_SCALAR >::existsArc	(	std::string_view	tailBase,
		int	tailSlice,
		std::string_view	headBase,
		int	headSlice ) const

Returns

true if the arc exists in the template.

Definition at line 520 of file KTBN_tpl.h.

                                                                       {
    return _bn_.existsArc(_validateVariable_(tailBase, tailSlice),
                          _validateVariable_(headBase, headSlice));
  }

References _bn_, and _validateVariable_().

Referenced by existsArc().

Here is the call graph for this function:

Here is the caller graph for this function:

fillCPT() [1/2]

template<GUM_Numeric GUM_SCALAR>

void gum::KTBN< GUM_SCALAR >::fillCPT	(	std::string_view	base,
		int	slice,
		const std::map< std::pair< std::string, int >, KTBNModality > &	parents,
		const std::vector< GUM_SCALAR > &	distribution ) const

Fills one conditional distribution P(node | parent configuration).

The order-safe, bracket-free way to fill a CPT: the node and its parents are addressed by their (base, slice) identity, so the result does not depend on the positional order of cpt().fillWith({...}).

Each parent is a dictionary entry keyed by its (base, slice) identity (use ATEMPORAL as slice for a static parent). ALL parents of the node must be listed, in any order. distribution holds the probabilities over the node's own modalities for that parent configuration.

A parent's value is either a modality index or a modality label, and the two may be mixed — see gum::KTBNModality, whose warning on numeric modalities applies here.

m.fillCPT("C", KTBN::ATEMPORAL, {}, {0.4, 0.6});      // P(C), no parents
m.fillCPT("X", 0, {}, {0.7, 0.3});                    // P(X[0]), no parents
m.fillCPT("X", 1, {{{"X", 0}, 1}, {{"C", KTBN::ATEMPORAL}, 0}},
          {0.6, 0.4});                                // P(X[1] | X[0]=1, C=0)
m.fillCPT("X", 1, {{{"X", 0}, "1"}, {{"C", KTBN::ATEMPORAL}, 0}},
          {0.6, 0.4});                                // same, X[0] by label

Parameters

base	Base name of the target node.
slice	Slice of the target node (ATEMPORAL for static).
parents	One (base, slice) -> value entry per parent, any order.
distribution	Probabilities over the node's modalities; its size must equal the node's domain size.

Exceptions

NotFound	/ OutOfBounds if the node or a parent does not exist, if a parent index is out of range, or if a parent label is not one of that parent's modalities (which of the two is raised for an unknown label depends on the variable type).
SizeError	if distribution size differs from the node domain size, or if not every parent is specified.
InvalidArgument	if an entry's node is not a parent of the target.

Definition at line 594 of file KTBN_tpl.h.

                                                                                       {
    const NodeId                id   = _validateVariable_(base, slice);
    const Tensor< GUM_SCALAR >& cpt  = _bn_.cpt(id);
    const DiscreteVariable&     self = _bn_.variable(id);
 
    if (distribution.size() != self.domainSize())
      GUM_ERROR(SizeError,
                "fillCPT: distribution has " << distribution.size() << " value(s) but '" << base
                                             << "' has " << self.domainSize() << " modalities.")
 
    const Size nbParents = cpt.nbrDim() - 1;
    if (parents.size() != nbParents)
      GUM_ERROR(SizeError,
                "fillCPT: " << parents.size() << " parent value(s) given but the node has "
                            << nbParents << " parent(s); every parent must be specified.")
 
    // Address each parent by its (base, slice) identity — order-independent.
    // No duplicate-parent check needed: a dictionary key is unique by
    // construction, and here each (base, slice) pair names exactly one node,
    // so no two distinct keys can alias the same parent.
    Instantiation inst(cpt);
    for (const auto& [parNode, parVal]: parents) {
      const auto& [parBase, parSlice] = parNode;
      const NodeId            parId   = _validateVariable_(parBase, parSlice);
      const DiscreteVariable& parVar  = _bn_.variable(parId);
      if (parId == id || !cpt.contains(parVar))
        GUM_ERROR(InvalidArgument,
                  "fillCPT: '" << parBase << "' is not a parent of the target node.")
      inst.chgVal(parVar, parVal.toIndex(parVar));
    }
 
    // Write the whole conditional distribution over the node's own modalities.
    for (Idx m = 0; m < self.domainSize(); ++m) {
      inst.chgVal(self, m);
      cpt.set(inst, distribution[m]);
    }
  }

References _bn_, _validateVariable_(), gum::Instantiation::chgVal(), cpt(), gum::DiscreteVariable::domainSize(), GUM_ERROR, and parents().

Here is the call graph for this function:

fillCPT() [2/2]

template<GUM_Numeric GUM_SCALAR>

void gum::KTBN< GUM_SCALAR >::fillCPT	(	std::string_view	node_name,
		const std::map< std::variant< std::string, std::pair< std::string, int > >, KTBNModality > &	parents,
		const std::vector< GUM_SCALAR > &	distribution ) const

Fills one conditional distribution using internal bracket-notation engine name for the target node — the bracket notation visible in toDot() and toString(): "X[t]" for a temporal variable at slice t, and the bare variable name for an atemporal variable (e.g.

"C"). Each parent is keyed either by its engine name ("X[0]") or by its (base, slice) identity — both spellings may be mixed in the same dictionary.

Warning

An engine-name key can be written as a bare string literal, but a (base, slice) key needs an explicit std::pair{...}: std::variant's converting constructor takes one value convertible to an alternative, not a nested brace list, so a bare {"X", 0} cannot implicitly construct the pair alternative the way it would a std::pair or std::tuple element.

As in the (base, slice) overload, a parent's value is either a modality index or a modality label — see gum::KTBNModality.

m.fillCPT("X[1]", {{"X[0]", 1}, {"C", 0}}, {0.6, 0.4});
m.fillCPT("X[1]", {{std::pair{"X", 0}, 1}, {std::pair{"C", KTBN::ATEMPORAL}, 0}},
          {0.6, 0.4});
m.fillCPT("X[1]", {{"X[0]", 1}, {std::pair{"C", KTBN::ATEMPORAL}, 0}},
          {0.6, 0.4});                                // mixed key styles
m.fillCPT("X[1]", {{"X[0]", "1"}, {"C", 0}}, {0.6, 0.4});   // mixed value styles

Parameters

node_name	Internal engine name of the target node.
parents	One engine_name-or-(base,slice) -> value entry per parent, any order.
distribution	Probabilities over the node's modalities; its size must equal the node's domain size.

Exceptions

NotFound	if node_name or a parent does not exist.
SizeError	/ InvalidArgument / OutOfBounds — same conditions as the (base, slice) overload.

Definition at line 637 of file KTBN_tpl.h.

                                                         {
    const NodeId                id   = _bn_.idFromName(std::string{node_name});
    const Tensor< GUM_SCALAR >& cpt  = _bn_.cpt(id);
    const DiscreteVariable&     self = _bn_.variable(id);
 
    if (distribution.size() != self.domainSize())
      GUM_ERROR(SizeError,
                "fillCPT: distribution has " << distribution.size() << " value(s) but '"
                                             << node_name << "' has " << self.domainSize()
                                             << " modalities.")
 
    const Size nbParents = cpt.nbrDim() - 1;
    if (parents.size() != nbParents)
      GUM_ERROR(SizeError,
                "fillCPT: " << parents.size() << " parent value(s) given but the node has "
                            << nbParents << " parent(s); every parent must be specified.")
 
    // Unlike the (base, slice)-keyed overload above, duplicates ARE possible here
    // despite unique map keys: "X[0]" and (base="X", slice=0) compare unequal as
    // std::variant values yet name the same node. Both are resolved to an engine
    // name first, so the seen-check below can catch the alias.
    Instantiation inst(cpt);
    NodeSet       seen;
    for (const auto& [parKey, parVal]: parents) {
      const std::string parName
          = std::holds_alternative< std::string >(parKey)
              ? std::get< std::string >(parKey)
              : _encode_(std::get< std::pair< std::string, int > >(parKey).first,
                         std::get< std::pair< std::string, int > >(parKey).second);
      const NodeId            parId  = _bn_.idFromName(parName);
      const DiscreteVariable& parVar = _bn_.variable(parId);
      if (parId == id || !cpt.contains(parVar))
        GUM_ERROR(InvalidArgument,
                  "fillCPT: '" << parName << "' is not a parent of the target node.")
      if (seen.contains(parId))
        GUM_ERROR(InvalidArgument, "fillCPT: parent '" << parName << "' is listed more than once.")
      seen.insert(parId);
      inst.chgVal(parVar, parVal.toIndex(parVar));
    }
 
    for (Idx m = 0; m < self.domainSize(); ++m) {
      inst.chgVal(self, m);
      cpt.set(inst, distribution[m]);
    }
  }

References _bn_, _encode_(), gum::Instantiation::chgVal(), gum::Set< Key >::contains(), cpt(), gum::DiscreteVariable::domainSize(), GUM_ERROR, gum::Set< Key >::insert(), and parents().

Here is the call graph for this function:

fromBN()

template<GUM_Numeric GUM_SCALAR>

KTBN< GUM_SCALAR > gum::KTBN< GUM_SCALAR >::fromBN ( const BayesNet< GUM_SCALAR > & bn, const std::unordered_set< std::string > & atemporalNodes = {}, std::vector< std::string > * warnings = nullptr )

static

Builds a k-DBN from an existing gum::BayesNet, reading its node names under one of two mutually exclusive conventions.

If any node name already carries the engine's own bracket notation (base[t]), the whole network is read that way: exactly the legacy behaviour, temporal node names assumed canonical (a plain decimal slice, no leading zeros – the form produced by add() / unroll() / toBN()). Otherwise – no node name carries a bracket at all – every node is read under the bracket-free convention: a name ending in a run of digits denotes a temporal variable at the timeslice given by that integer (base = everything before the digits, e.g. "X0" and "X12" both belong to process "X", at slices 0 and 12); any other name is atemporal.

The order \(k\) is inferred as one plus the largest slice index found. A group of same-base nodes that does not cover every slice \(0..k-1\) is not an error: each of its nodes becomes an atemporal variable, original name kept, and a message is appended to warnings. When no temporal process survives, \(k\) falls back to 1.

Parameters

bn	The source Bayesian network (copied).
atemporalNodes	Node names – exactly as they appear in bn – to classify atemporal outright. Only needed to lift an ambiguity: a name the active convention already reads as atemporal changes nothing by being listed, while listing a temporal-shaped name says "I meant this atemporally" where the reclassification above would only guess (and warn).
warnings	If non-null, receives one message per reclassified group.

Exceptions

NotFound	if a name in atemporalNodes is not a node of bn.
OperationNotAllowed	if the temporal structure is inconsistent: two variables mapping to the same (process, slice), a base name used both as an atemporal variable and as a temporal process, an arc from a temporal node into an atemporal one, or an arc from the future to the past.

Warning

A lone temporal-shaped node with no sibling sharing its base (e.g. "X0" alone under the bracket-free convention, or "X[0]" alone under the bracket one) yields \(k=1\), where a single slice is a complete process: it is kept temporal, silently. List it in atemporalNodes to say otherwise.

Definition at line 880 of file KTBN_tpl.h.

                                                                                {
    KTBN< GUM_SCALAR > res(1);   // _determineNodesFromBN_ below will modify this k=1
    res._bn_ = bn;
    res._determineNodesFromBN_(atemporalNodes, warnings);
    return res;
  }

Referenced by gum::learning::KTBNLearner< GUM_SCALAR >::_assemble_(), and load().

Here is the caller graph for this function:

generateCPT() [1/2]

template<GUM_Numeric GUM_SCALAR>

INLINE void gum::KTBN< GUM_SCALAR >::generateCPT	(	std::string_view	base,
		int	slice ) const

Randomly generates the CPT of a single node.

Definition at line 583 of file KTBN_tpl.h.

                                                                                  {
    _bn_.generateCPT(_validateVariable_(base, slice));
  }

References _bn_, and _validateVariable_().

Referenced by generateCPT().

Here is the call graph for this function:

Here is the caller graph for this function:

generateCPT() [2/2]

template<GUM_Numeric GUM_SCALAR>

INLINE void gum::KTBN< GUM_SCALAR >::generateCPT

(

std::string_view

node_name

)

const

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

Definition at line 588 of file KTBN_tpl.h.

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

References _determineNode_(), and generateCPT().

Here is the call graph for this function:

generateCPTs()

template<GUM_Numeric GUM_SCALAR>

INLINE void gum::KTBN< GUM_SCALAR >::generateCPTs

(

)

const

Randomly generates every CPT of the template.

Definition at line 578 of file KTBN_tpl.h.

                                                     {
    _bn_.generateCPTs();
  }

References _bn_.

k()

template<GUM_Numeric GUM_SCALAR>

INLINE Size gum::KTBN< GUM_SCALAR >::k

(

)

const

Returns

The order \(k\) of the k-DBN.

Definition at line 184 of file KTBN_tpl.h.

                                          {
    return _k_;
  }

References _k_.

Referenced by KTBN().

Here is the caller graph for this function:

load()

template<GUM_Numeric GUM_SCALAR>

KTBN< GUM_SCALAR > gum::KTBN< GUM_SCALAR >::load ( std::string_view filename )

static

Loads a k-DBN from a GUM file produced by save().

Text iff the name ends with .jgum, otherwise binary (gaining a .bgum extension if missing). If the file carries the KTBN classification properties it is restored exactly; otherwise it is re-derived from node names via fromBN().

Parameters

filename

The GUM file.

Exceptions

IOError	if the file cannot be read or is not valid.
OperationNotAllowed	if the classification properties are absent and the fallback fromBN() finds an inconsistent temporal structure.

Definition at line 824 of file KTBN_tpl.h.

                                                                     {
    const auto [filepath, binary] = _resolveGumFormat_(filename);
 
    BayesNet< GUM_SCALAR >    bn;
    GumBNReader< GUM_SCALAR > reader(&bn, filepath, binary);
    const Size                nbErr = reader.proceed();
    if (nbErr > 0) {
      std::stringstream stream;
      reader.showElegantErrorsAndWarnings(stream);
      reader.showErrorCounts(stream);
      GUM_ERROR(IOError, "KTBN::load: " << stream.str())
    }
 
    // A file written by save() carries the classification as properties: restore it
    // directly. Otherwise fall back to fromBN(), which re-derives it from node names.
    if (!(bn.existsProperty("KTBN.k") && bn.existsProperty("KTBN.temporal")
          && bn.existsProperty("KTBN.atemporal")))
      return fromBN(bn);
 
    auto split = [](std::string_view csv, std::unordered_set< std::string >& out) {
      std::string current;
      bool        escaped = false;
      for (const char c: csv) {
        if (escaped) {
          current += c;
          escaped = false;
        } else if (c == '\\') {
          escaped = true;
        } else if (c == ',') {
          if (!current.empty()) out.insert(current);
          current.clear();
        } else {
          current += c;
        }
      }
      if (!current.empty()) out.insert(current);
    };
 
    Size k_val{};
    try {
      k_val = static_cast< Size >(std::stoul(bn.property("KTBN.k")));
    } catch (const std::exception& e) {
      GUM_ERROR(IOError,
                "KTBN::load: malformed KTBN.k property ('" << bn.property("KTBN.k")
                                                           << "'): " << e.what())
    }
    KTBN< GUM_SCALAR > res(k_val);
    res._bn_ = bn;
    split(bn.property("KTBN.temporal"), res._temporal_);
    split(bn.property("KTBN.atemporal"), res._atemporal_);
 
    return res;
  }

References _resolveGumFormat_(), fromBN(), GUM_ERROR, gum::GumBNReader< GUM_SCALAR >::proceed(), gum::GumBNReader< GUM_SCALAR >::showElegantErrorsAndWarnings(), gum::GumBNReader< GUM_SCALAR >::showErrorCounts(), and gum::split().

Here is the call graph for this function:

nbAtemporalVars()

template<GUM_Numeric GUM_SCALAR>

INLINE Size gum::KTBN< GUM_SCALAR >::nbAtemporalVars

(

)

const

Returns

The number of atemporal variables.

Definition at line 339 of file KTBN_tpl.h.

                                                        {
    return _atemporal_.size();
  }

References _atemporal_.

nbTemporalVars()

template<GUM_Numeric GUM_SCALAR>

INLINE Size gum::KTBN< GUM_SCALAR >::nbTemporalVars

(

)

const

Returns

The number of temporal processes.

Definition at line 334 of file KTBN_tpl.h.

                                                       {
    return _temporal_.size();
  }

References _temporal_.

nodes()

template<GUM_Numeric GUM_SCALAR>

std::vector< std::pair< std::string, int > > gum::KTBN< GUM_SCALAR >::nodes

(

)

const

Returns

All nodes as (base, slice) pairs (atemporal nodes use KTBN::ATEMPORAL).

Definition at line 344 of file KTBN_tpl.h.

                                                                         {
    std::vector< std::pair< std::string, int > > result;
    result.reserve(size());
    for (const auto& a: _atemporal_)
      result.emplace_back(a, ATEMPORAL);
    for (const auto& p: _temporal_)
      for (Size t = 0; t < _k_; ++t)
        result.emplace_back(p, static_cast< int >(t));
    return result;
  }

References _atemporal_, _k_, _temporal_, ATEMPORAL, and size().

Referenced by _timeSlicesToDot_().

Here is the call graph for this function:

Here is the caller graph for this function:

operator=() [1/2]

template<GUM_Numeric GUM_SCALAR>

KTBN< GUM_SCALAR > & gum::KTBN< GUM_SCALAR >::operator=

(

const KTBN< GUM_SCALAR > &

source

)

Copy assignment operator.

Definition at line 156 of file KTBN_tpl.h.

                                                                                  {
    if (this != &source) {
      GUM_OP_CPY(KTBN);
      _k_         = source._k_;
      _bn_        = source._bn_;
      _temporal_  = source._temporal_;
      _atemporal_ = source._atemporal_;
    }
    return *this;
  }

References KTBN(), _atemporal_, _bn_, _k_, and _temporal_.

Here is the call graph for this function:

operator=() [2/2]

template<GUM_Numeric GUM_SCALAR>

KTBN< GUM_SCALAR > & gum::KTBN< GUM_SCALAR >::operator= ( KTBN< GUM_SCALAR > && source )

noexcept

Move assignment operator.

Definition at line 168 of file KTBN_tpl.h.

                                                                                      {
    if (this != &source) {
      GUM_OP_MOV(KTBN);
      _k_         = source._k_;
      _bn_        = std::move(source._bn_);
      _temporal_  = std::move(source._temporal_);
      _atemporal_ = std::move(source._atemporal_);
    }
    return *this;
  }

References KTBN(), _atemporal_, _bn_, _k_, and _temporal_.

Here is the call graph for this function:

parents() [1/2]

template<GUM_Numeric GUM_SCALAR>

std::vector< std::pair< std::string, int > > gum::KTBN< GUM_SCALAR >::parents	(	std::string_view	base,
		int	slice ) const

Parents of a node as (base, slice) pairs (ATEMPORAL if atemporal).

Definition at line 356 of file KTBN_tpl.h.

                                                                                            {
    return _determineNodeSet_(_bn_.parents(_validateVariable_(base, slice)));
  }

References _bn_, _determineNodeSet_(), and _validateVariable_().

Referenced by fillCPT(), fillCPT(), parents(), and unroll().

Here is the call graph for this function:

Here is the caller graph for this function:

parents() [2/2]

template<GUM_Numeric GUM_SCALAR>

std::vector< std::pair< std::string, int > > gum::KTBN< GUM_SCALAR >::parents

(

std::string_view

node_name

)

const

Returns the parents using an engine name ("X[1]", "C", …).

Definition at line 363 of file KTBN_tpl.h.

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

References _determineNode_(), and parents().

Here is the call graph for this function:

save()

template<GUM_Numeric GUM_SCALAR>

void gum::KTBN< GUM_SCALAR >::save

(

std::string_view

filename

)

const

Saves the template in the GUM format (text .jgum or binary .bgum).

The extension selects the format: .jgum writes the text (JSON) variant, anything else the binary (msgpack) one, gaining a .bgum extension if missing. The temporal/atemporal classification and the order \(k\) are stored as properties, so load() reconstructs the k-DBN exactly — including k=1 processes and bracket-named atemporal variables, which fromBN() cannot disambiguate from node names alone.

Parameters

filename

The destination file.

Definition at line 796 of file KTBN_tpl.h.

                                                             {
    const auto [filepath, binary] = _resolveGumFormat_(filename);
 
    // Persist the temporal/atemporal classification (and k) as BN properties so that
    // load() restores the k-DBN exactly, instead of re-deriving it heuristically from
    // node names (ambiguous for k=1 processes and bracket-named atemporal variables).
    // Separator is ','; '\' and ',' inside names are backslash-escaped so any name is safe.
    auto join = [](const std::unordered_set< std::string >& names) {
      std::string out;
      for (const auto& n: names) {
        if (!out.empty()) out += ',';
        for (const char c: n) {
          if (c == '\\' || c == ',') out += '\\';
          out += c;
        }
      }
      return out;
    };
 
    BayesNet< GUM_SCALAR > annotated = _bn_;
    annotated.setProperty("KTBN.k", std::to_string(_k_));
    annotated.setProperty("KTBN.temporal", join(_temporal_));
    annotated.setProperty("KTBN.atemporal", join(_atemporal_));
    GumBNWriter< GUM_SCALAR > writer(binary);
    writer.write(filepath, annotated);
  }

References _atemporal_, _bn_, _k_, _resolveGumFormat_(), _temporal_, and gum::BNWriter< GUM_SCALAR >::write().

Here is the call graph for this function:

size()

template<GUM_Numeric GUM_SCALAR>

INLINE Size gum::KTBN< GUM_SCALAR >::size

(

)

const

Returns

The number of nodes in the template (all slices).

Definition at line 189 of file KTBN_tpl.h.

                                             {
    return _bn_.size();
  }

References _bn_.

Referenced by nodes().

Here is the caller graph for this function:

sizeArcs()

template<GUM_Numeric GUM_SCALAR>

INLINE Size gum::KTBN< GUM_SCALAR >::sizeArcs

(

)

const

Returns

The number of arcs in the template.

Definition at line 194 of file KTBN_tpl.h.

                                                 {
    return _bn_.sizeArcs();
  }

References _bn_.

summaryGraph()

template<GUM_Numeric GUM_SCALAR>

std::string gum::KTBN< GUM_SCALAR >::summaryGraph

(

)

const

Returns the Graphviz DOT string of the summary graph: the projection of the transition kernel alone (the pattern that actually repeats through time when unrolling), not the whole template.

Every process (temporal or atemporal) becomes a single node. Only arcs whose head lies in the last time slice ( \(k-1\)) are kept – an arc between two earlier slices belongs to the initial-condition structure (slices \(0, \ldots, k-2\)), not to the repeated pattern, and is dropped. Several arcs may connect the same pair of nodes when the kernel depends on more than one lag (e.g. both X[k-2] and X[k-3] pointing to X[k-1]): each is kept and labelled with its lag (head slice minus tail slice). An arc from an atemporal variable has no lag and is left unlabelled.

Definition at line 1219 of file KTBN_tpl.h.

                                                   {
    std::set< std::string > baseNames(_temporal_.begin(), _temporal_.end());
    baseNames.insert(_atemporal_.begin(), _atemporal_.end());
 
    const int                                               lastSlice = static_cast< int >(_k_) - 1;
    std::set< std::tuple< std::string, std::string, int > > edges;
    for (const auto& arc: _bn_.arcs()) {
      const auto [tailBase, tailSlice] = _decodeName_(_bn_.variable(arc.tail()).name());
      const auto [headBase, headSlice] = _decodeName_(_bn_.variable(arc.head()).name());
      if (headSlice != lastSlice) continue;   // not part of the repeated transition kernel
 
      const int lag = (tailSlice == ATEMPORAL) ? ATEMPORAL : headSlice - tailSlice;
      edges.emplace(tailBase, headBase, lag);
    }
 
    std::stringstream dot;
    dot << "digraph KTBN {\n";
    dot << "  rankdir=LR;\n";
    dot << "  node [color=\"#000000\", fillcolor=white, style=filled];\n\n";
 
    for (const auto& base: baseNames)
      dot << "  \"" << _escapeDot_(base) << "\";\n";
    dot << "\n";
 
    for (const auto& [tailBase, headBase, lag]: edges) {
      dot << "  \"" << _escapeDot_(tailBase) << "\" -> \"" << _escapeDot_(headBase) << "\"";
      if (lag != ATEMPORAL) dot << " [label=\"" << lag << "\"]";
      dot << ";\n";
    }
 
    dot << "}\n";
    return dot.str();
  }

References _atemporal_, _bn_, _decodeName_(), _escapeDot_(), _k_, _temporal_, and ATEMPORAL.

Here is the call graph for this function:

temporalVarNames()

template<GUM_Numeric GUM_SCALAR>

INLINE const std::unordered_set< std::string > & gum::KTBN< GUM_SCALAR >::temporalVarNames

(

)

const

Returns

The set of temporal process base names.

Definition at line 324 of file KTBN_tpl.h.

                                                                                         {
    return _temporal_;
  }

References _temporal_.

timeSlice()

template<GUM_Numeric GUM_SCALAR>

INLINE int gum::KTBN< GUM_SCALAR >::timeSlice

(

const DiscreteVariable &

var

)

const

The time slice of var, or ATEMPORAL if it is atemporal.

Exceptions

NotFound

if var is not a node of this k-DBN.

Definition at line 474 of file KTBN_tpl.h.

                                                                            {
    _bn_.idFromName(var.name());   // throws NotFound if var is not in this k-DBN
    return _determineNode_(var.name()).second;
  }

References _bn_, _determineNode_(), and gum::Variable::name().

Here is the call graph for this function:

toBN()

template<GUM_Numeric GUM_SCALAR>

BayesNet< GUM_SCALAR > gum::KTBN< GUM_SCALAR >::toBN

(

)

const

Returns

A deep copy of the underlying template as a gum::BayesNet.

Definition at line 692 of file KTBN_tpl.h.

                                                        {
    return BayesNet< GUM_SCALAR >(_bn_);
  }

References _bn_.

toDot()

template<GUM_Numeric GUM_SCALAR>

std::string gum::KTBN< GUM_SCALAR >::toDot

(

)

const

Returns a Graphviz DOT string with one cluster per time slice.

Definition at line 1119 of file KTBN_tpl.h.

                                            {
    return _timeSlicesToDot_(_bn_, false);
  }

References _bn_, and _timeSlicesToDot_().

Here is the call graph for this function:

toString()

template<GUM_Numeric GUM_SCALAR>

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

(

)

const

Returns

A human-readable description of the k-DBN.

Definition at line 1084 of file KTBN_tpl.h.

                                               {
    const auto join = [](const std::vector< std::string >& v) {
      std::string s;
      for (const auto& n: v) {
        if (!s.empty()) s += ", ";
        s += n;
      }
      return s;
    };
 
    const std::vector< std::string > temporalNames(_temporal_.begin(), _temporal_.end());
    const std::vector< std::string > atemporalNames(_atemporal_.begin(), _atemporal_.end());
 
    std::string arcs;
    for (const auto& arc: _bn_.arcs())
      arcs += std::format("    {} -> {}\n",
                          _bn_.variable(arc.tail()).name(),
                          _bn_.variable(arc.head()).name());
 
    return std::format("k-TBN (k={}, {} nodes, {} arcs)\n"
                       "  temporal processes ({}): {}\n"
                       "  atemporal variables ({}): {}\n"
                       "\n  arcs ({}):\n{}",
                       _k_,
                       _bn_.size(),
                       _bn_.sizeArcs(),
                       _temporal_.size(),
                       join(temporalNames),
                       _atemporal_.size(),
                       join(atemporalNames),
                       _bn_.sizeArcs(),
                       arcs);
  }

References _atemporal_, _bn_, _k_, _temporal_, and arcs().

Here is the call graph for this function:

toUnrolledDot()

template<GUM_Numeric GUM_SCALAR>

std::string gum::KTBN< GUM_SCALAR >::toUnrolledDot	(	Size	T,
		bool	highlightReplicated = false ) const

Returns a Graphviz DOT string of the k-DBN unrolled over T time slices.

Parameters

T	Total number of time slices to display. Must be \(\geq k\).
highlightReplicated	If true, shade slices \(\geq k\) (lightcyan) differently from the template slices \(0, \ldots, k-1\) (gray).

Exceptions

OperationNotAllowed

if T < k.

Definition at line 1124 of file KTBN_tpl.h.

                                                                                    {
    if (T < _k_)
      GUM_ERROR(OperationNotAllowed, "toUnrolledDot: T=" << T << " must be >= k=" << _k_ << ".")
    return _timeSlicesToDot_(unroll(T), highlightReplicated);
  }

References _k_, _timeSlicesToDot_(), GUM_ERROR, and unroll().

Here is the call graph for this function:

unroll()

template<GUM_Numeric GUM_SCALAR>

BayesNet< GUM_SCALAR > gum::KTBN< GUM_SCALAR >::unroll

(

Size

nbTimeSlices

)

const

Unrolls the k-DBN into a standard gum::BayesNet.

The result has exactly nbTimeSlices time slices. Slices \(0, \ldots, k-1\) are copied verbatim from the template; every additional slice \(t \geq k\) replicates the incoming pattern of slice \(k-1\) (the transition kernel), shifting each temporal parent's slice accordingly so that lags are preserved. Variables are named with the same base[slice] bracket-notation convention (atemporal variables keep their name).

Parameters

nbTimeSlices

Total number of time slices of the unrolled network.

Exceptions

OperationNotAllowed

if nbTimeSlices is smaller than \(k\).

Definition at line 697 of file KTBN_tpl.h.

                                                                           {
    if (nbTimeSlices < _k_)
      GUM_ERROR(OperationNotAllowed,
                "Cannot unroll over " << nbTimeSlices << " slices: fewer than the order k=" << _k_
                                      << ".")
 
    BayesNet< GUM_SCALAR > unrolled;
    const int              kernelSlice = static_cast< int >(_k_ - 1);
 
    // 1. atemporal variables (kept as-is)
    for (const auto& a: _atemporal_) {
      unrolled.add(_bn_.variable(_bn_.idFromName(a)));
    }
 
    // 2. temporal variables, instantiated for every slice 0..nbTimeSlices-1
    for (const auto& p: _temporal_) {
      const DiscreteVariable& templateVar
          = _bn_.variable(_bn_.idFromName(_encode_(p, kernelSlice)));
      for (Size t = 0; t < nbTimeSlices; ++t) {
        // clone() to rename; BayesNet::add() clones again internally (unavoidable via public API).
        std::unique_ptr< DiscreteVariable > clone(templateVar.clone());
        clone->setName(_encode_(p, static_cast< int >(t)));
        unrolled.add(*clone);
      }
    }
 
    // 3. template arcs (slices 0..k-1) are copied verbatim: the engine names of
    //    the template already match the unrolled names for those slices.
    for (const auto& arc: _bn_.arcs()) {
      unrolled.addArc(_bn_.variable(arc.tail()).name(), _bn_.variable(arc.head()).name());
    }
 
    // 4. CPTs of the template nodes (slices 0..k-1): copied by name.
    for (const NodeId n: _bn_.nodes()) {
      unrolled.cpt(_bn_.variable(n).name()).fillWith(_bn_.cpt(n));
    }
 
    // 5. transition kernel: for each extra slice t = k..nbTimeSlices-1,
    //    add arcs and fill the CPT in one pass using lags computed once per process.
    for (const auto& p: _temporal_) {
      const NodeId                lastSliceNodeId = _bn_.idFromName(_encode_(p, kernelSlice));
      const Tensor< GUM_SCALAR >& templateCpt     = _bn_.cpt(lastSliceNodeId);
 
      // (parBase, lag): lag == ATEMPORAL for static parents, otherwise lag = (k-1) - parSlice.
      std::vector< std::pair< std::string, int > > lags;
      for (const auto& [parBase, parSlice]: parents(p, kernelSlice)) {
        const int lag = (parSlice == ATEMPORAL) ? ATEMPORAL : kernelSlice - parSlice;
        lags.emplace_back(parBase, lag);
      }
 
      HashTable< std::string, std::string > unrolledToTemplate;
      std::vector< std::string >            templateVarNames;
 
      for (Size t = _k_; t < nbTimeSlices; ++t) {
        const std::string child = _encode_(p, static_cast< int >(t));
 
        // Add arcs and build the unrolled->template name mapping simultaneously.
        unrolledToTemplate.clear();
        unrolledToTemplate.insert(child, _encode_(p, kernelSlice));
        for (const auto& [parBase, lag]: lags) {
          if (lag == ATEMPORAL) {
            unrolled.addArc(parBase, child);
            unrolledToTemplate.insert(parBase, parBase);
          } else {
            const std::string parName = _encode_(parBase, static_cast< int >(t) - lag);
            unrolled.addArc(parName, child);
            unrolledToTemplate.insert(parName, _encode_(parBase, kernelSlice - lag));
          }
        }
 
        // Fill the CPT using the mapping built above.
        const Tensor< GUM_SCALAR >& unrolledCpt = unrolled.cpt(child);
        templateVarNames.clear();
        templateVarNames.reserve(unrolledCpt.nbrDim());
        for (Idx i = 0; i < unrolledCpt.nbrDim(); ++i) {
          templateVarNames.push_back(unrolledToTemplate[unrolledCpt.variable(i).name()]);
        }
        unrolledCpt.fillWith(templateCpt, templateVarNames);
      }
    }
 
    return unrolled;
  }

References _atemporal_, _bn_, _encode_(), _k_, _temporal_, ATEMPORAL, gum::HashTable< Key, Val >::clear(), gum::DiscreteVariable::clone(), GUM_ERROR, gum::HashTable< Key, Val >::insert(), and parents().

Referenced by toUnrolledDot().

Here is the call graph for this function:

Here is the caller graph for this function:

variable() [1/2]

template<GUM_Numeric GUM_SCALAR>

INLINE const DiscreteVariable & gum::KTBN< GUM_SCALAR >::variable	(	std::string_view	base,
		int	slice ) const

Returns the gum::DiscreteVariable of a (process, slice) couple.

Use KTBN::ATEMPORAL as slice for atemporal variables.

Exceptions

NotFound	if no such variable exists.
OutOfBounds	if slice is out of \([0,k-1]\) for a temporal variable.
OperationNotAllowed	if the temporal/atemporal kind does not match slice.

Definition at line 462 of file KTBN_tpl.h.

                                                                                            {
    return _bn_.variable(_validateVariable_(base, slice));
  }

References _bn_, and _validateVariable_().

Referenced by variable().

Here is the call graph for this function:

Here is the caller graph for this function:

variable() [2/2]

template<GUM_Numeric GUM_SCALAR>

INLINE const DiscreteVariable & gum::KTBN< GUM_SCALAR >::variable

(

std::string_view

node_name

)

const

Same, using an engine name: resolved via _determineNode_, so "X[1]" and bare "C" are both accepted.

Definition at line 468 of file KTBN_tpl.h.

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

References _determineNode_(), and variable().

Here is the call graph for this function:

Member Data Documentation

_atemporal_

template<GUM_Numeric GUM_SCALAR>

std::unordered_set< std::string > gum::KTBN< GUM_SCALAR >::_atemporal_

private

Base names of the registered atemporal variables.

Definition at line 713 of file KTBN.h.

Referenced by KTBN(), KTBN(), _determineNode_(), _determineNodesFromBN_(), _validateAdd_(), _validateVariable_(), add(), atemporalVarNames(), changeVariableName(), clear(), erase(), exists(), nbAtemporalVars(), nodes(), operator=(), operator=(), save(), summaryGraph(), toString(), and unroll().

_bn_

template<GUM_Numeric GUM_SCALAR>

BayesNet< GUM_SCALAR > gum::KTBN< GUM_SCALAR >::_bn_

private

The underlying Bayesian network used as a storage engine for the template.

Definition at line 707 of file KTBN.h.

Referenced by KTBN(), KTBN(), _determineNodeSet_(), _determineNodesFromBN_(), _validateVariable_(), add(), addArc(), arcs(), baseName(), bnToDot(), changeVariableName(), children(), clear(), cpt(), empty(), erase(), eraseArc(), existsArc(), fillCPT(), fillCPT(), generateCPT(), generateCPTs(), operator=(), operator=(), parents(), save(), size(), sizeArcs(), summaryGraph(), timeSlice(), toBN(), toDot(), toString(), unroll(), and variable().

_k_

template<GUM_Numeric GUM_SCALAR>

Size gum::KTBN< GUM_SCALAR >::_k_

private

The order (number of time slices in the template).

Definition at line 704 of file KTBN.h.

Referenced by KTBN(), KTBN(), KTBN(), _determineNodesFromBN_(), _timeSlicesToDot_(), _validateAdd_(), _validateVariable_(), add(), changeVariableName(), erase(), k(), nodes(), operator=(), operator=(), save(), summaryGraph(), toString(), toUnrolledDot(), and unroll().

_temporal_

template<GUM_Numeric GUM_SCALAR>

std::unordered_set< std::string > gum::KTBN< GUM_SCALAR >::_temporal_

private

Base names of the registered temporal processes.

Definition at line 710 of file KTBN.h.

Referenced by KTBN(), KTBN(), _determineNodesFromBN_(), _validateAdd_(), _validateVariable_(), add(), changeVariableName(), clear(), erase(), exists(), nbTemporalVars(), nodes(), operator=(), operator=(), save(), summaryGraph(), temporalVarNames(), toString(), and unroll().

ATEMPORAL

template<GUM_Numeric GUM_SCALAR>

int gum::KTBN< GUM_SCALAR >::ATEMPORAL = -1

staticconstexpr

Conventional time-slice value denoting an atemporal (static) variable.

Definition at line 200 of file KTBN.h.

Referenced by gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::_build_(), gum::learning::KTBNLearner< GUM_SCALAR >::_build_(), gum::learning::IKTBNLearner< GUM_SCALAR >::_checkArcTemporallyFeasible_(), gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::_decode_(), _decodeName_(), _determineNode_(), gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _determineNodesFromBN_(), gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::_drawSamples_(), _encode_(), gum::learning::IKTBNLearner< GUM_SCALAR >::_encode_(), gum::learning::KTBNLearner< GUM_SCALAR >::_forEachAllSlicesPair_(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_forEachScoredNode_(), gum::learning::KTBNLearner< GUM_SCALAR >::_forOwningLearner_(), gum::KTBNGenerator< GUM_SCALAR >::_legalArcs_(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_raiseKMinForSlice_(), _timeSlicesToDot_(), _validateAdd_(), _validateVariable_(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_verifyBase_(), addArc(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addForbiddenArcAllSlices(), gum::learning::KTBNLearner< GUM_SCALAR >::addNoChildrenNode(), gum::learning::KTBNLearner< GUM_SCALAR >::addNoParentNode(), gum::learning::KTBNLearner< GUM_SCALAR >::addPossibleEdge(), changeVariableName(), gum::learning::KTBNLearner< GUM_SCALAR >::domainSize(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseForbiddenArcAllSlices(), gum::learning::KTBNLearner< GUM_SCALAR >::eraseNoChildrenNode(), gum::learning::KTBNLearner< GUM_SCALAR >::eraseNoParentNode(), gum::learning::KTBNLearner< GUM_SCALAR >::erasePossibleEdge(), gum::learning::KTBNLearner< GUM_SCALAR >::learnParameters(), nodes(), gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::setVarOrderTopological(), gum::learning::KTBNLearner< GUM_SCALAR >::state(), summaryGraph(), and unroll().

---

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

• agrum/KTBN/KTBN.h
• agrum/KTBN/KTBN_tpl.h