aGrUM  0.20.2
a C++ library for (probabilistic) graphical models
multiDimCombination.h
Go to the documentation of this file.
1 /**
2  *
3  * Copyright 2005-2020 Pierre-Henri WUILLEMIN(@LIP6) & Christophe GONZALES(@AMU)
4  * info_at_agrum_dot_org
5  *
6  * This library is free software: you can redistribute it and/or modify
7  * it under the terms of the GNU Lesser General Public License as published by
8  * the Free Software Foundation, either version 3 of the License, or
9  * (at your option) any later version.
10  *
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14  * GNU Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public License
17  * along with this library. If not, see <http://www.gnu.org/licenses/>.
18  *
19  */
20 
21 
22 /**
23  * @file
24  *
25  * @author Christophe GONZALES(@AMU) and Pierre-Henri WUILLEMIN(@LIP6)
26  */
27 
28 #ifndef GUM_MULTI_DIM_COMBINATION_H
29 #define GUM_MULTI_DIM_COMBINATION_H
30 
31 #include <agrum/tools/core/sequence.h>
32 #include <agrum/tools/core/set.h>
33 #include <agrum/tools/variables/discreteVariable.h>
34 #include <utility>
35 
36 namespace gum {
37 
38  /**
39  * @class MultiDimCombination
40  * @headerfile multiDimCombination.h <agrum/tools/multidim/multiDimCombination.h>
41  * @ingroup multidim_op_group
42  *
43  * @brief A generic interface to combine efficiently several MultiDim tables
44  *
45  * MultiDimCombination is a generic interface designed to combine efficiently
46  * several multidimensional objects, that is, to compute expressions like T1
47  * op T2 op T3 op .... op Tn, where the Ti's are the multidimensional objects
48  * and op is an operator or a function taking in argument two such objects
49  * and producing a new (combined) Ti object. By default, the combination
50  * operation "op" is assumed to be COMMUTATIVE and ASSOCIATIVE.
51  *
52  * By multidimensional objects, we mean of course MultiDimImplementations,
53  * but also more complex objects such as, for instance, pairs of
54  * MultiDimImplementation the first one of which being a utility function and
55  * the second one being a table of instantiations (useful, e.g., for
56  * computing MPE's) but this can also be a pair (Utility,Potential) for the
57  * inference in an Influence Diagram. Actually, the important point for a
58  * multidimensional object to be eligible to be combined by the
59  * MultiDimCombination is:
60  *
61  * # that there exists a function taking in arguments two such
62  * multidimensional objects and producing a new object of the same type,
63  * which is the so-called combined result of these two objects.
64  *
65  * To be quite generic, the MultiDimCombination takes in argument the
66  * function that produces the result of the combination of two
67  * multidimensional objects. The following code gives an example of the
68  * usage of MultiDimCombinations:
69  *
70  * @code
71  * // a function used to combine two Potential<float>'s:
72  * Potential<float>* addPotential ( const Potential<float>& t1,
73  * const Potential<float>& t2 ) {
74  * return new Potential<float> (t1 + t2);
75  * }
76  *
77  * // another function used to combine two Potential<float>'s:
78  * Potential<float>* multPotential ( const Potential<float>& t1,
79  * const Potential<float>& t2 ) {
80  * return new Potential<float> (t1 * t2);
81  * }
82  *
83  * Potential<float> t1, t2, t3;
84  * Set<const Potential<float>*> set;
85  * set << &table1 << &table2 << &table3;
86  * MultiDimCombinationDefault<float,Potential> Comb ( addPotential );
87  * Potential<float>* combined_table = Comb.combine ( set );
88  *
89  * // change the operator to apply
90  * Comb.setCombineFunction ( multPotential );
91  * Potential<float>* combined_table2 = Comb.combine ( set );
92  *
93  * @endcode
94  */
95  template < typename GUM_SCALAR, template < typename > class TABLE >
97  public:
98  // =========================================================================
99  /// @name Constructors / Destructors
100  // =========================================================================
101  /// @{
102 
103  /// default constructor
105 
106  /// copy constructor
108 
109  /// destructor
110  virtual ~MultiDimCombination();
111 
112  /**
113  * @brief virtual constructor
114  *
115  * @return a new fresh MultiDimCombinator with the same combination
116  * function.
117  */
118  virtual MultiDimCombination< GUM_SCALAR, TABLE >* newFactory() const = 0;
119 
120  /// @}
121  // =========================================================================
122  /// @name Accessors/Modifiers
123  // =========================================================================
124  /// @{
125 
126  /**
127  * @brief creates and returns the result of the combination of the tables
128  * within set
129  *
130  * @return a new freshly created TABLE which is the result of the
131  * combination of all the TABLES passed in argument
132  *
133  * @throws InvalidArgumentsNumber exception is thrown if the set passed in
134  * argument contains less than two elements.
135  */
136  virtual TABLE< GUM_SCALAR >*
137  combine(const Set< const TABLE< GUM_SCALAR >* >& set)
138  = 0;
139  virtual void combine(TABLE< GUM_SCALAR >& container,
140  const Set< const TABLE< GUM_SCALAR >* >& set)
141  = 0;
142 
143  /// changes the function used for combining two TABLES
144  virtual void setCombineFunction(TABLE< GUM_SCALAR >* (
145  *combine)(const TABLE< GUM_SCALAR >&, const TABLE< GUM_SCALAR >&))
146  = 0;
147 
148  /// returns the combination function currently used by the combinator
149  virtual TABLE< GUM_SCALAR >* (*combineFunction())(const TABLE< GUM_SCALAR >&,
150  const TABLE< GUM_SCALAR >&)
151  = 0;
152 
153  /**
154  * @brief returns a rough estimate of the number of operations that will be
155  * performed to compute the combination.
156  */
157  virtual float
158  nbOperations(const Set< const TABLE< GUM_SCALAR >* >& set) const = 0;
159  virtual float nbOperations(
160  const Set< const Sequence< const DiscreteVariable* >* >& set) const = 0;
161 
162  /**
163  * @brief Returns the memory consumption used during the combination.
164  *
165  * Actually, this function does not return a precise account of the memory
166  * used by the multidimCombination but a rough estimate based on the sizes
167  * of the tables involved in the combination.
168  *
169  * @return a pair of memory consumption: the first one is the maximum
170  * amount of memory used during the combination and the second one is the
171  * amount of memory still used at the end of the function ( the memory used
172  * by the resulting table ).
173  */
174  virtual std::pair< long, long >
175  memoryUsage(const Set< const TABLE< GUM_SCALAR >* >& set) const = 0;
176  virtual std::pair< long, long > memoryUsage(
177  const Set< const Sequence< const DiscreteVariable* >* >& set) const = 0;
178 
179  private:
180  /// forbid copy operators
183 
184  /// @}
185  };
186 
187 } /* namespace gum */
188 
189 // always include the template implementation
190 #include <agrum/tools/multidim/utils/operators/multiDimCombination_tpl.h>
191 
192 #endif /* GUM_MULTI_DIM_COMBINATION_H */
virtual void combine(TABLE< GUM_SCALAR > &container, const Set< const TABLE< GUM_SCALAR > * > &set)=0
creates and returns the result of the combination of the tables within set
virtual TABLE< GUM_SCALAR > * combine(const Set< const TABLE< GUM_SCALAR > * > &set)=0
creates and returns the result of the combination of the tables within set
virtual void setCombineFunction(TABLE< GUM_SCALAR > *(*combine)(const TABLE< GUM_SCALAR > &, const TABLE< GUM_SCALAR > &))=0
changes the function used for combining two TABLES
INLINE void emplace(Args &&... args)
Definition: set_tpl.h:669
MultiDimCombination()
default constructor
MultiDimCombination(const MultiDimCombination< GUM_SCALAR, TABLE > &)
copy constructor
virtual MultiDimCombination< GUM_SCALAR, TABLE > * newFactory() const =0
virtual constructor
MultiDimCombination< GUM_SCALAR, TABLE > & operator=(const MultiDimCombination< GUM_SCALAR, TABLE > &)
forbid copy operators
virtual ~MultiDimCombination()
destructor
A generic interface to combine efficiently several MultiDim tables.
virtual std::pair< long, long > memoryUsage(const Set< const Sequence< const DiscreteVariable * > * > &set) const =0
creates and returns the result of the combination of the tables within set
virtual float nbOperations(const Set< const Sequence< const DiscreteVariable * > * > &set) const =0
creates and returns the result of the combination of the tables within set