gum::DefaultTriangulation Class Reference

The default triangulation algorithm used by aGrUM. More...

#include <defaultTriangulation.h>

Inheritance diagram for gum::DefaultTriangulation:

Collaboration diagram for gum::DefaultTriangulation:

Public Member Functions
Constructors / Destructors
	DefaultTriangulation (const UndiGraph *graph, const NodeProperty< Size > *dom_sizes, bool minimality=false, double theRatio=GUM_QUASI_RATIO, double theThreshold=GUM_WEIGHT_THRESHOLD)
	basic constructor. initialize the triangulation More...
	DefaultTriangulation (bool minimality=false, double theRatio=GUM_QUASI_RATIO, double theThreshold=GUM_WEIGHT_THRESHOLD)
	default constructor: initialize the triangulation for an empty graph More...
	DefaultTriangulation (const DefaultTriangulation &from)
	copy constructor More...
	DefaultTriangulation (DefaultTriangulation &&from)
	move constructor More...
	~DefaultTriangulation ()
	destructor More...
virtual DefaultTriangulation *	newFactory () const
	virtual clone constructor More...
virtual DefaultTriangulation *	copyFactory () const
	virtual copy constructor More...
Accessors / Modifiers
double	maxLog10CliqueDomainSize ()
	returns the max of log10DomainSize of the cliques in the junction tree. More...
const NodeProperty< Size > *	domainSizes () const
	returns the domain sizes of the variables of the graph to be triangulated More...

Protected Attributes
EliminationSequenceStrategy *	elimination_sequence_strategy_ {nullptr}
	the elimination sequence strategy used by the triangulation More...
JunctionTreeStrategy *	junction_tree_strategy_ {nullptr}
	the junction tree strategy used by the triangulation More...
const NodeProperty< Size > *	domain_sizes_ {nullptr}
	the domain sizes of the variables/nodes of the graph More...

Accessors / Modifiers
virtual void	setGraph (const UndiGraph *graph, const NodeProperty< Size > *domsizes)
	initialize the triangulation data structures for a new graph More...
const EdgeSet &	fillIns ()
	returns the fill-ins added by the triangulation algorithm More...
const std::vector< NodeId > &	eliminationOrder ()
	returns an elimination ordering compatible with the triangulated graph More...
Idx	eliminationOrder (const NodeId)
	returns the index of a given node in the elimination order (0 = first node eliminated) More...
const NodeProperty< NodeId > &	reverseEliminationOrder ()
	returns a table indicating, for each node, at which step it was deleted by the triangulation process More...
const UndiGraph &	triangulatedGraph ()
	returns the triangulated graph More...
const CliqueGraph &	eliminationTree ()
	returns the elimination tree of a compatible ordering More...
const CliqueGraph &	junctionTree ()
	returns a compatible junction tree More...
NodeId	createdJunctionTreeClique (const NodeId id)
	returns the Id of the clique of the junction tree created by the elimination of a given node during the triangulation process More...
const NodeProperty< NodeId > &	createdJunctionTreeCliques ()
	returns the Ids of the cliques of the junction tree created by the elimination of the nodes More...
const CliqueGraph &	maxPrimeSubgraphTree ()
	returns a junction tree of maximal prime subgraphs More...
NodeId	createdMaxPrimeSubgraph (const NodeId id)
	returns the Id of the maximal prime subgraph created by the elimination of a given node during the triangulation process More...
void	clear ()
	reinitialize the graph to be triangulated to an empty graph More...
void	setMinimalRequirement (bool)
	sets/unset the minimality requirement More...
virtual bool	isMinimalityRequired () const final
	indicates wether minimality is required More...
void	setFillIns (bool)
	sets/unsets the record of the fill-ins in the standard triangulation procedure More...
const UndiGraph *	originalGraph () const
	returns the graph to be triangulated More...
EliminationSequenceStrategy &	eliminationSequenceStrategy () const
	returns the elimination sequence strategy used by the triangulation More...
JunctionTreeStrategy &	junctionTreeStrategy () const
	returns the junction tree strategy used by the triangulation More...
virtual void	initTriangulation_ (UndiGraph &graph)
	the function called to initialize the triangulation process More...

Detailed Description

The default triangulation algorithm used by aGrUM.

By default, this is the very class used by aGrUM for performing triangulations. The algorithm used is the following:

the graph passed in argument is completed by fill-ins until it becomes

triangulated

then an elimination tree is computed from this triangulated graph

finally, a junction tree is derived from the elimination tree

The triangulation step first tries to remove simplicial nodes, that is, nodes that belong to only one clique. Then almost simplicial nodes of low width are removed (almost simplicial nodes are nodes such that all but one of their neighbors form a clique). Then quasi simplicial nodes are removed, that is, nodes such that the ratio of the number of fill-ins to add to form a clique by the number of edges in a clique is small. Then nodes that create cliques of small weight are removed.

The transformation from the elimination tree to the join tree is performed bottom-up. Each time a node of the elimination tree is identified to be a sub-clique, it is removed and all of its parents but one are linked to the latter. The identification of sub-cliques is very fast (comparison of 2 ints).

Definition at line 61 of file defaultTriangulation.h.

Constructor & Destructor Documentation

DefaultTriangulation() [1/4]

gum::DefaultTriangulation::DefaultTriangulation ( const UndiGraph *  graph, const NodeProperty< Size > *  dom_sizes, bool  minimality = false, double  theRatio = GUM_QUASI_RATIO, double  theThreshold = GUM_WEIGHT_THRESHOLD  )

explicit

basic constructor. initialize the triangulation

DefaultTriangulation() [2/4]

gum::DefaultTriangulation::DefaultTriangulation ( bool  minimality = false, double  theRatio = GUM_QUASI_RATIO, double  theThreshold = GUM_WEIGHT_THRESHOLD  )

explicit

default constructor: initialize the triangulation for an empty graph

DefaultTriangulation() [3/4]

gum::DefaultTriangulation::DefaultTriangulation

(

const DefaultTriangulation &

from

)

copy constructor

DefaultTriangulation() [4/4]

gum::DefaultTriangulation::DefaultTriangulation

(

DefaultTriangulation &&

from

)

move constructor

~DefaultTriangulation()

gum::DefaultTriangulation::~DefaultTriangulation

(

)

destructor

Member Function Documentation

clear()

void gum::StaticTriangulation::clear ( )

virtualinherited

reinitialize the graph to be triangulated to an empty graph

Implements gum::Triangulation.

Definition at line 154 of file staticTriangulation.cpp.

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

                                  {
    // clear the factories
    elimination_sequence_strategy_->clear();
    junction_tree_strategy_->clear();

    // remove the current graphs
    _original_graph_ = nullptr;
    _junction_tree_  = nullptr;
    _triangulated_graph_.clear();
    _elim_tree_.clear();
    _max_prime_junction_tree_.clear();
    _elim_cliques_.clear();
    _node_2_max_prime_clique_.clear();

    // remove all fill-ins and orderings
    _fill_ins_.clear();
    _added_fill_ins_.clear();
    _elim_order_.clear();
    _reverse_elim_order_.clear();

    // indicates that the junction tree, the max prime tree, etc, are updated
    _has_triangulation_           = true;
    _has_triangulated_graph_      = true;
    _has_elimination_tree_        = true;
    _has_junction_tree_           = true;
    _has_max_prime_junction_tree_ = true;
    _has_fill_ins_                = true;
  }

Here is the call graph for this function:

copyFactory()

virtual DefaultTriangulation* gum::DefaultTriangulation::copyFactory ( ) const

virtual

virtual copy constructor

Implements gum::UnconstrainedTriangulation.

createdJunctionTreeClique()

NodeId gum::StaticTriangulation::createdJunctionTreeClique ( const NodeId  id )

virtualinherited

returns the Id of the clique of the junction tree created by the elimination of a given node during the triangulation process

Implements gum::Triangulation.

createdJunctionTreeCliques()

const NodeProperty< NodeId >& gum::StaticTriangulation::createdJunctionTreeCliques ( )

virtualinherited

returns the Ids of the cliques of the junction tree created by the elimination of the nodes

Implements gum::Triangulation.

createdMaxPrimeSubgraph()

NodeId gum::StaticTriangulation::createdMaxPrimeSubgraph ( const NodeId  id )

virtualinherited

returns the Id of the maximal prime subgraph created by the elimination of a given node during the triangulation process

Implements gum::Triangulation.

domainSizes()

const NodeProperty< Size >* gum::Triangulation::domainSizes ( ) const

inherited

returns the domain sizes of the variables of the graph to be triangulated

eliminationOrder() [1/2]

const std::vector< NodeId >& gum::StaticTriangulation::eliminationOrder ( )

virtualinherited

returns an elimination ordering compatible with the triangulated graph

Implements gum::Triangulation.

eliminationOrder() [2/2]

Idx gum::StaticTriangulation::eliminationOrder ( const NodeId  )

virtualinherited

returns the index of a given node in the elimination order (0 = first node eliminated)

Implements gum::Triangulation.

eliminationSequenceStrategy()

EliminationSequenceStrategy& gum::StaticTriangulation::eliminationSequenceStrategy ( ) const

inherited

returns the elimination sequence strategy used by the triangulation

eliminationTree()

const CliqueGraph& gum::StaticTriangulation::eliminationTree ( )

virtualinherited

returns the elimination tree of a compatible ordering

Implements gum::Triangulation.

fillIns()

const EdgeSet & gum::StaticTriangulation::fillIns ( )

virtualinherited

returns the fill-ins added by the triangulation algorithm

Implements gum::Triangulation.

Definition at line 653 of file staticTriangulation.cpp.

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

                                              {
    // if we did not compute the triangulation yet, do it and commpute
    // the fill-ins at the same time
    if (!_has_triangulation_) {
      bool want_fill_ins = _we_want_fill_ins_;
      _we_want_fill_ins_ = true;
      _triangulate_();
      _we_want_fill_ins_ = want_fill_ins;
      _has_fill_ins_     = true;
    }

    // here, we already computed a triangulation and we already computed
    // the fill-ins, so return them
    if (_has_fill_ins_) {
      if (elimination_sequence_strategy_->providesFillIns())
        return elimination_sequence_strategy_->fillIns();
      else
        return _fill_ins_;
    } else {
      // ok, here, we shall compute the fill-ins as they were not precomputed
      if (!_original_graph_) return _fill_ins_;

      // just in case, be sure that the junction tree has been constructed
      if (!_has_junction_tree_) junctionTree();

      for (const auto clik_id: _junction_tree_->nodes()) {
        // for each clique, add the edges necessary to make it complete
        const NodeSet&        clique = _junction_tree_->clique(clik_id);
        std::vector< NodeId > clique_nodes(clique.size());
        unsigned int          i = 0;

        for (const auto node: clique) {
          clique_nodes[i] = node;
          i += 1;
        }

        for (i = 0; i < clique_nodes.size(); ++i) {
          for (unsigned int j = i + 1; j < clique_nodes.size(); ++j) {
            Edge edge(clique_nodes[i], clique_nodes[j]);

            if (!_original_graph_->existsEdge(edge)) {
              try {
                _fill_ins_.insert(edge);
              } catch (DuplicateElement&) {}
            }
          }
        }
      }

      return _fill_ins_;
    }
  }

Here is the call graph for this function:

initTriangulation_()

void gum::StaticTriangulation::initTriangulation_ ( UndiGraph &  graph )

protectedvirtualinherited

the function called to initialize the triangulation process

This function is called when the triangulation process starts and is used to initialize the elimination sequence strategy. Actually, the graph that is modified by the triangulation algorithm is a copy of the original graph, and this copy needs be known by the elimination sequence strategy. initTriangulation_ is used to transmit this knowledge to the elimination sequence (through method setGraph of the elimination sequence class).

Parameters

graph

the very graph that is triangulated (this is a copy of original_graph)

Reimplemented in gum::PartialOrderedTriangulation, and gum::OrderedTriangulation.

Definition at line 707 of file staticTriangulation.cpp.

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

                                                               {
    elimination_sequence_strategy_->setGraph(&graph, domain_sizes_);
  }

Here is the call graph for this function:

isMinimalityRequired()

virtual bool gum::StaticTriangulation::isMinimalityRequired ( ) const

finalvirtualinherited

indicates wether minimality is required

junctionTree()

const CliqueGraph& gum::StaticTriangulation::junctionTree ( )

virtualinherited

returns a compatible junction tree

Implements gum::Triangulation.

junctionTreeStrategy()

JunctionTreeStrategy& gum::StaticTriangulation::junctionTreeStrategy ( ) const

inherited

returns the junction tree strategy used by the triangulation

maxLog10CliqueDomainSize()

double gum::Triangulation::maxLog10CliqueDomainSize ( )

inherited

returns the max of log10DomainSize of the cliques in the junction tree.

This is usefull for instance to estimate the complexity (both in space and in time) of the inference that will use the junction tree.

This method is not 'const' since it can be called before building any junction tree and hence it needs to build it...

Definition at line 64 of file triangulation.cpp.

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

                                                 {
    double              res = 0.0;
    double              dSize;
    const JunctionTree& jt = junctionTree();   // here, the fact that we get
    // a junction tree ensures that domain_sizes_ is different from nullptr

    for (const NodeId cl: jt) {
      dSize = 0.0;

      for (const auto node: jt.clique(cl))
        dSize += std::log10((*domain_sizes_)[node]);

      if (res < dSize) res = dSize;
    }

    return res;
  }

Here is the call graph for this function:

maxPrimeSubgraphTree()

const CliqueGraph& gum::StaticTriangulation::maxPrimeSubgraphTree ( )

virtualinherited

returns a junction tree of maximal prime subgraphs

Warning

Actually, the cliques of the junction tree are guarranteed to be maximal prime subgraph of the original graph that was triangulated only if the triangulation performed is minimal (in the sense that removing any edge in the triangulated graph results in a nontriangulated graph). This can be ensured by requiring minimality of the triangulation.

Implements gum::Triangulation.

newFactory()

virtual DefaultTriangulation* gum::DefaultTriangulation::newFactory ( ) const

virtual

virtual clone constructor

returns a fresh triangulation (over an empty graph) of the same type as the current object

note that we return a pointer as it enables subclasses to return pointers to their types, not Triangulation pointers. See item 25 of the more effective C++.

Implements gum::UnconstrainedTriangulation.

operator=()

DefaultTriangulation& gum::DefaultTriangulation::operator= ( const DefaultTriangulation &  )

private

forbid copy operator

originalGraph()

const UndiGraph* gum::StaticTriangulation::originalGraph ( ) const

inherited

returns the graph to be triangulated

Warning

if we have not set yet a graph, then originalGraph () will return a nullptr.

reverseEliminationOrder()

const NodeProperty< NodeId >& gum::StaticTriangulation::reverseEliminationOrder ( )

inherited

returns a table indicating, for each node, at which step it was deleted by the triangulation process

setFillIns()

void gum::StaticTriangulation::setFillIns ( bool  )

inherited

sets/unsets the record of the fill-ins in the standard triangulation procedure

setGraph()

void gum::StaticTriangulation::setGraph ( const UndiGraph *  graph, const NodeProperty< Size > *  domsizes  )

virtualinherited

initialize the triangulation data structures for a new graph

Parameters

graph	the graph to be triangulated, i.e., the nodes of which will be eliminated
domsizes	the domain sizes of the nodes to be eliminated

Warning

Note that we allow domsizes to be defined over nodes/variables that do not belong to graph. These sizes will simply be ignored. However, it is compulsory that all the nodes of graph belong to dom_sizes

the graph is not copied but only referenced by the elimination sequence algorithm.

Implements gum::Triangulation.

Reimplemented in gum::PartialOrderedTriangulation, and gum::OrderedTriangulation.

Definition at line 505 of file staticTriangulation.cpp.

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

                                                                                                 {
    // remove the old graph
    clear();

    if (graph != nullptr) {
      // prepare the size of the data for the new graph
      _elim_order_.resize(graph->size());
      _reverse_elim_order_.resize(graph->size());
      _elim_cliques_.resize(graph->size());
      _added_fill_ins_.resize(graph->size());
      _node_2_max_prime_clique_.resize(graph->size());
    }

    // keep track of the variables passed in argument
    _original_graph_ = graph;
    domain_sizes_    = domsizes;

    // indicate that no triangulation was performed for this graph
    _has_triangulation_           = false;
    _has_triangulated_graph_      = false;
    _has_elimination_tree_        = false;
    _has_junction_tree_           = false;
    _has_max_prime_junction_tree_ = false;
    _has_fill_ins_                = false;
  }

Here is the call graph for this function:

setMinimalRequirement()

void gum::StaticTriangulation::setMinimalRequirement ( bool  )

inherited

sets/unset the minimality requirement

triangulatedGraph()

const UndiGraph & gum::StaticTriangulation::triangulatedGraph ( )

virtualinherited

returns the triangulated graph

Implements gum::Triangulation.

Definition at line 466 of file staticTriangulation.cpp.

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

                                                          {
    if (!_has_triangulation_) _triangulate_();

    // if we did not construct the triangulated graph during the triangulation,
    // that is, we just constructed the junction tree, we shall construct it now
    if (!_has_triangulated_graph_) {
      // just in case, be sure that the junction tree has been constructed
      if (!_has_junction_tree_) junctionTree();

      // copy the original graph
      _triangulated_graph_ = *_original_graph_;

      for (const auto clik_id: *_junction_tree_) {
        // for each clique, add the edges necessary to make it complete
        const NodeSet&        clique = _junction_tree_->clique(clik_id);
        std::vector< NodeId > clique_nodes(clique.size());
        unsigned int          i = 0;

        for (const auto node: clique) {
          clique_nodes[i] = node;
          i += 1;
        }

        for (i = 0; i < clique_nodes.size(); ++i) {
          for (unsigned int j = i + 1; j < clique_nodes.size(); ++j) {
            try {
              _triangulated_graph_.addEdge(clique_nodes[i], clique_nodes[j]);
            } catch (DuplicateElement&) {}
          }
        }
      }

      _has_triangulated_graph_ = true;
    }

    return _triangulated_graph_;
  }

Here is the call graph for this function:

Member Data Documentation

_quasi_ratio_

double gum::DefaultTriangulation::_quasi_ratio_

private

the ratio above which we consider nodes to be quasi simplicial

Definition at line 106 of file defaultTriangulation.h.

_threshold_

double gum::DefaultTriangulation::_threshold_

private

threshold under which almost and quasi simplicial nodes can be chosen to be eliminated

Definition at line 110 of file defaultTriangulation.h.

domain_sizes_

const NodeProperty< Size >* gum::Triangulation::domain_sizes_ {nullptr}

protectedinherited

the domain sizes of the variables/nodes of the graph

Definition at line 150 of file triangulation.h.

elimination_sequence_strategy_

EliminationSequenceStrategy* gum::StaticTriangulation::elimination_sequence_strategy_ {nullptr}

protectedinherited

the elimination sequence strategy used by the triangulation

Definition at line 229 of file staticTriangulation.h.

junction_tree_strategy_

JunctionTreeStrategy* gum::StaticTriangulation::junction_tree_strategy_ {nullptr}

protectedinherited

the junction tree strategy used by the triangulation

Definition at line 232 of file staticTriangulation.h.

---

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

• agrum/tools/graphs/algorithms/triangulations/defaultTriangulation.h