HypervolumeContribution.h
Go to the documentation of this file.
1 /*!
2  *
3  *
4  * \brief Implements the frontend for the HypervolumeContribution algorithms, including the approximations
5  *
6  *
7  * \author O.Krause
8  * \date 2014-2016
9  *
10  *
11  * \par Copyright 1995-2017 Shark Development Team
12  *
13  * <BR><HR>
14  * This file is part of Shark.
15  * <http://shark-ml.org/>
16  *
17  * Shark is free software: you can redistribute it and/or modify
18  * it under the terms of the GNU Lesser General Public License as published
19  * by the Free Software Foundation, either version 3 of the License, or
20  * (at your option) any later version.
21  *
22  * Shark is distributed in the hope that it will be useful,
23  * but WITHOUT ANY WARRANTY; without even the implied warranty of
24  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
25  * GNU Lesser General Public License for more details.
26  *
27  * You should have received a copy of the GNU Lesser General Public License
28  * along with Shark. If not, see <http://www.gnu.org/licenses/>.
29  *
30  */
31 #ifndef SHARK_ALGORITHMS_DIRECTSEARCH_HYPERVOLUMECONTRIBUTION_H
32 #define SHARK_ALGORITHMS_DIRECTSEARCH_HYPERVOLUMECONTRIBUTION_H
33 
34 #include <shark/Algorithms/DirectSearch/Operators/Hypervolume/HypervolumeContribution2D.h>
35 #include <shark/Algorithms/DirectSearch/Operators/Hypervolume/HypervolumeContribution3D.h>
36 #include <shark/Algorithms/DirectSearch/Operators/Hypervolume/HypervolumeContributionMD.h>
37 #include <shark/Algorithms/DirectSearch/Operators/Hypervolume/HypervolumeContributionApproximator.h>
38 
39 
40 namespace shark {
41 /// \brief Frontend for hypervolume contribution algorithms in m dimensions.
42 ///
43 /// Depending on the dimensionality of the problem, one of the specialized algorithms is called.
44 /// For large dimensionalities for which there are no specialized fast algorithms,
45 /// the exponential time algorithm is called.
46 /// Also a log-transformation of points is supported
47 struct HypervolumeContribution {
48 
49  /// \brief Default c'tor.
50  HypervolumeContribution() : m_useApproximation(false) {}
51 
52  ///\brief True if the hypervolume approximation is to be used in dimensions > 3.
53  void useApproximation(bool useApproximation){
54  m_useApproximation = useApproximation;
55  }
56 
57  double approximationEpsilon()const{
58  return m_approximationAlgorithm.epsilon();
59  }
60  double& approximationEpsilon(){
61  return m_approximationAlgorithm.epsilon();
62  }
63 
64  double approximationDelta()const{
65  return m_approximationAlgorithm.delta();
66  }
67 
68  double& approximationDelta(){
69  return m_approximationAlgorithm.delta();
70  }
71 
72  template<typename Archive>
73  void serialize( Archive & archive, const unsigned int version ) {
74  archive & BOOST_SERIALIZATION_NVP(m_useApproximation);
75  archive & BOOST_SERIALIZATION_NVP(m_approximationAlgorithm);
76  }
77 
78  /// \brief Returns the index of the points with smallest contribution as well as their contribution.
79  ///
80  /// \param [in] points The set \f$S\f$ of points from which to select the smallest contributor.
81  /// \param [in] k The number of points to select.
82  /// \param [in] referencePoint The reference Point\f$\vec{r} \in \mathbb{R}^2\f$ for the hypervolume calculation, needs to fulfill: \f$ \forall s \in S: s \preceq \vec{r}\f$.
83  template<class Set, typename VectorType>
84  std::vector<KeyValuePair<double,std::size_t> > smallest(Set const& points, std::size_t k, VectorType const& ref)const{
85  SHARK_RUNTIME_CHECK(points.size() >= k, "There must be at least k points in the set");
86  SIZE_CHECK( points.begin()->size() == ref.size() );
87  std::size_t numObjectives = ref.size();
88  if(numObjectives == 2){
89  HypervolumeContribution2D algorithm;
90  return algorithm.smallest(points, k, ref);
91  }else if(numObjectives == 3){
92  HypervolumeContribution3D algorithm;
93  return algorithm.smallest(points, k, ref);
94  }else if(m_useApproximation){
95  return m_approximationAlgorithm.smallest(points, k, ref);
96  }else{
97  HypervolumeContributionMD algorithm;
98  return algorithm.smallest(points, k, ref);
99  }
100  }
101 
102  /// \brief Returns the index of the points with largest contribution as well as their contribution.
103  ///
104  /// \param [in] points The set \f$S\f$ of points from which to select the largest contributor.
105  /// \param [in] referencePoint The reference Point\f$\vec{r} \in \mathbb{R}^2\f$ for the hypervolume calculation, needs to fulfill: \f$ \forall s \in S: s \preceq \vec{r}\f$.
106  template<class Set, typename VectorType>
107  std::vector<KeyValuePair<double,std::size_t> > largest(Set const& points, std::size_t k, VectorType const& ref)const{
108  SHARK_RUNTIME_CHECK(points.size() >= k, "There must be at least k points in the set");
109  SIZE_CHECK( points.begin()->size() == ref.size() );
110  std::size_t numObjectives = ref.size();
111  if(numObjectives == 2){
112  HypervolumeContribution2D algorithm;
113  return algorithm.largest(points, k, ref);
114  }else if(numObjectives == 3){
115  HypervolumeContribution3D algorithm;
116  return algorithm.largest(points, k, ref);
117  }else{
118  SHARK_RUNTIME_CHECK(!m_useApproximation, "Largest not implemented for approximation algorithm");
119  HypervolumeContributionMD algorithm;
120  return algorithm.largest(points, k, ref);
121  }
122  }
123 
124  /// \brief Returns the index of the points with smallest contribution as well as their contribution.
125  ///
126  /// As no reference point is given, the extremum points can not be computed and are never selected.
127  ///
128  /// \param [in] points The set \f$S\f$ of points from which to select the smallest contributor.
129  /// \param [in] k The number of points to select.
130  /// \param [in] referencePoint The reference Point\f$\vec{r} \in \mathbb{R}^2\f$ for the hypervolume calculation, needs to fulfill: \f$ \forall s \in S: s \preceq \vec{r}\f$.
131  template<class Set>
132  std::vector<KeyValuePair<double,std::size_t> > smallest(Set const& points, std::size_t k)const{
133  SHARK_RUNTIME_CHECK(points.size() >= k, "There must be at least k points in the set");
134  std::size_t numObjectives = points[0].size();
135  if(numObjectives == 2){
136  HypervolumeContribution2D algorithm;
137  return algorithm.smallest(points, k);
138  }else if(numObjectives == 3){
139  HypervolumeContribution3D algorithm;
140  return algorithm.smallest(points, k);
141  }else if(m_useApproximation){
142  return m_approximationAlgorithm.smallest(points, k);
143  }else{
144  HypervolumeContributionMD algorithm;
145  return algorithm.smallest(points, k);
146  }
147  }
148 
149  /// \brief Returns the index of the points with largest contribution as well as their contribution.
150  ///
151  /// As no reference point is given, the extremum points can not be computed and are never selected.
152  ///
153  /// \param [in] points The set \f$S\f$ of points from which to select the smallest contributor.
154  /// \param [in] referencePoint The reference Point\f$\vec{r} \in \mathbb{R}^2\f$ for the hypervolume calculation, needs to fulfill: \f$ \forall s \in S: s \preceq \vec{r}\f$.
155  template<class Set>
156  std::vector<KeyValuePair<double,std::size_t> > largest(Set const& points, std::size_t k)const{
157  SHARK_RUNTIME_CHECK(points.size() >= k, "There must be at least k points in the set");
158  std::size_t numObjectives = points[0].size();
159  if(numObjectives == 2){
160  HypervolumeContribution2D algorithm;
161  return algorithm.largest(points, k);
162  }else if(numObjectives == 3){
163  HypervolumeContribution3D algorithm;
164  return algorithm.largest(points, k);
165  }else{
166  SHARK_RUNTIME_CHECK(!m_useApproximation, "Largest not implemented for approximation algorithm");
167  HypervolumeContributionMD algorithm;
168  return algorithm.largest(points, k);
169  }
170  }
171 
172 private:
173  bool m_useApproximation;
174  HypervolumeContributionApproximator m_approximationAlgorithm;
175 };
176 
177 }
178 #endif