1 /** 2 * 3 * Copyright (c) 2005-2021 by Pierre-Henri WUILLEMIN(_at_LIP6) & Christophe GONZALES(_at_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 * @brief This file contains getters and setters defintion for 25 * ApproximationSchem settings 26 * 27 * @see ApproximationScheme 28 * 29 * @author Pierre-Henri WUILLEMIN(_at_LIP6) 30 */ 31 #ifndef GUM_APPROXIMATION_SCHEME_CONFIGURATION_H 32 #define GUM_APPROXIMATION_SCHEME_CONFIGURATION_H 33 34 #include <agrum/agrum.h> 35 #include <agrum/tools/core/math/math_utils.h> 36 #include <agrum/tools/core/signal/signaler.h> 37 #include <agrum/tools/core/timer.h> 38 39 namespace gum { 40 41 /** 42 * @class IApproximationSchemeConfiguration 43 * @brief Approximation Scheme. 44 * @ingroup approximationpolicy_group 45 * 46 * @warning Doxygen does not like spanning command on multiple line, so we 47 * could not configure it with the correct include directive. Use the 48 * following code snippet to include this file. 49 * @code 50 * #include <agrum/tools/core/approximations/IApproximationSchemeConfiguration.h> 51 * @endcode 52 * 53 * An interface for configuration of approximation scheme. 54 */ 55 class IApproximationSchemeConfiguration { 56 public: 57 /// Progression, error and time. 58 Signaler3< Size, double, double > onProgress; 59 60 /// Criteria messageApproximationScheme 61 Signaler1< std::string > onStop; 62 63 /// The different state of an approximation scheme. 64 enum class ApproximationSchemeSTATE : char 65 { 66 Undefined, 67 Continue, 68 Epsilon, 69 Rate, 70 Limit, 71 TimeLimit, 72 Stopped 73 }; 74 75 // ====================================================================== 76 /// @name Constructor and destructor 77 // ====================================================================== 78 /// @{ 79 /** 80 * @brief Class constructors. 81 */ 82 IApproximationSchemeConfiguration(); 83 84 /** 85 * @brief Class destructor. 86 */ 87 ~IApproximationSchemeConfiguration(); 88 /// @} 89 90 // ====================================================================== 91 /// @name Getters and setters 92 // ====================================================================== 93 /// @{ 94 95 /** 96 * @brief Returns the approximation scheme message. 97 * @return Returns the approximation scheme message. 98 */ 99 std::string messageApproximationScheme() const; 100 101 /** 102 * @brief Given that we approximate f(t), stopping criterion on 103 * |f(t+1)-f(t)|. 104 * 105 * If the criterion was disabled it will be enabled. 106 * 107 * @param eps The new epsilon value. 108 * @throw OutOfBounds Raised if eps < 0. 109 */ 110 virtual void setEpsilon(double eps) = 0; 111 112 /** 113 * @brief Returns the value of epsilon. 114 * @return Returns the value of epsilon. 115 */ 116 virtual double epsilon() const = 0; 117 118 /** 119 * @brief Disable stopping criterion on epsilon. 120 */ 121 virtual void disableEpsilon() = 0; 122 123 /** 124 * @brief Enable stopping criterion on epsilon. 125 */ 126 virtual void enableEpsilon() = 0; 127 128 /** 129 * @brief Returns true if stopping criterion on epsilon is enabled, false 130 * otherwise. 131 * @return Returns true if stopping criterion on epsilon is enabled, false 132 * otherwise. 133 */ 134 virtual bool isEnabledEpsilon() const = 0; 135 136 /** 137 * @brief Given that we approximate f(t), stopping criterion on 138 * d/dt(|f(t+1)-f(t)|). 139 * 140 * If the criterion was disabled it will be enabled 141 * 142 * @param rate The minimal epsilon rate. 143 * @throw OutOfBounds if rate<0 144 */ 145 virtual void setMinEpsilonRate(double rate) = 0; 146 147 /** 148 * @brief Returns the value of the minimal epsilon rate. 149 * @return Returns the value of the minimal epsilon rate. 150 */ 151 virtual double minEpsilonRate() const = 0; 152 153 /** 154 * @brief Disable stopping criterion on epsilon rate. 155 */ 156 virtual void disableMinEpsilonRate() = 0; 157 158 /** 159 * @brief Enable stopping criterion on epsilon rate. 160 */ 161 virtual void enableMinEpsilonRate() = 0; 162 163 /** 164 * @brief Returns true if stopping criterion on epsilon rate is enabled, 165 * false otherwise. 166 * @return Returns true if stopping criterion on epsilon rate is enabled, 167 * false otherwise. 168 */ 169 virtual bool isEnabledMinEpsilonRate() const = 0; 170 171 /** 172 * @brief Stopping criterion on number of iterations. 173 * 174 * If the criterion was disabled it will be enabled. 175 * 176 * @param max The maximum number of iterations. 177 * @throw OutOfBounds Raised if max <= 1. 178 */ 179 virtual void setMaxIter(Size max) = 0; 180 181 /** 182 * @brief Returns the criterion on number of iterations. 183 * @return Returns the criterion on number of iterations. 184 */ 185 virtual Size maxIter() const = 0; 186 187 /** 188 * @brief Disable stopping criterion on max iterations. 189 */ 190 virtual void disableMaxIter() = 0; 191 192 /** 193 * @brief Enable stopping criterion on max iterations. 194 */ 195 virtual void enableMaxIter() = 0; 196 197 /** 198 * @brief Returns true if stopping criterion on max iterations is enabled, 199 * false otherwise. 200 * @return Returns true if stopping criterion on max iterations is enabled, 201 * false otherwise. 202 */ 203 virtual bool isEnabledMaxIter() const = 0; 204 205 /** 206 * @brief Stopping criterion on timeout. 207 * 208 * If the criterion was disabled it will be enabled. 209 * 210 * @param timeout The timeout value in seconds. 211 * @throw OutOfBounds Raised if timeout <= 0.0. 212 */ 213 virtual void setMaxTime(double timeout) = 0; 214 215 /** 216 * @brief Returns the timeout (in seconds). 217 * @return Returns the timeout (in seconds). 218 */ 219 virtual double maxTime() const = 0; 220 221 /** 222 * @brief Returns the current running time in second. 223 * @return Returns the current running time in second. 224 */ 225 virtual double currentTime() const = 0; 226 227 /** 228 * @brief Disable stopping criterion on timeout. 229 * @return Disable stopping criterion on timeout. 230 */ 231 virtual void disableMaxTime() = 0; 232 233 /** 234 * @brief Enable stopping criterion on timeout. 235 */ 236 virtual void enableMaxTime() = 0; 237 238 /** 239 * @brief Returns true if stopping criterion on timeout is enabled, false 240 * otherwise. 241 * @return Returns true if stopping criterion on timeout is enabled, false 242 * otherwise. 243 */ 244 virtual bool isEnabledMaxTime() const = 0; 245 246 /** 247 * @brief How many samples between two stopping is enable. 248 * @param p The new period value. 249 * @throw OutOfBounds Raised if p < 1. 250 */ 251 virtual void setPeriodSize(Size p) = 0; 252 253 /** 254 * @brief Returns the period size. 255 * @return Returns the period size. 256 */ 257 virtual Size periodSize() const = 0; 258 259 /** 260 * @brief Set the verbosity on (true) or off (false). 261 * @param v If true, then verbosity is turned on. 262 */ 263 virtual void setVerbosity(bool v) = 0; 264 265 /** 266 * @brief Returns true if verbosity is enabled. 267 * @return Returns true if verbosity is enabled. 268 */ 269 virtual bool verbosity() const = 0; 270 271 /** 272 * @brief Returns the approximation scheme state. 273 * @return Returns the approximation scheme state. 274 */ 275 virtual ApproximationSchemeSTATE stateApproximationScheme() const = 0; 276 277 /** 278 * @brief Returns the number of iterations. 279 * @return Returns the number of iterations. 280 * @throw OperationNotAllowed Raised if the scheme did not perform. 281 */ 282 virtual Size nbrIterations() const = 0; 283 284 /** 285 * @brief Returns the scheme history. 286 * @return Returns the scheme history. 287 * @throw OperationNotAllowed Raised if the scheme did not performed or 288 * if verbosity is set to false. 289 */ 290 virtual const std::vector< double >& history() const = 0; 291 }; 292 } // namespace gum 293 294 #ifndef GUM_NO_INLINE 295 # include <agrum/tools/core/approximations/IApproximationSchemeConfiguration_inl.h> 296 #endif 297 298 #endif // GUM_APPROXIMATION_SCHEME_CONFIGURATION_H 299