1 /* 2 ================================================================================ 3 PROJECT: 4 5 John Eddy's Genetic Algorithms (JEGA) 6 7 CONTENTS: 8 9 Definition of class GeneticAlgorithmOperator 10 11 NOTES: 12 13 See notes under section "Class Definition" of this file. 14 15 PROGRAMMERS: 16 17 John Eddy (jpeddy@sandia.gov) (JE) 18 19 ORGANIZATION: 20 21 Sandia National Laboratories 22 23 COPYRIGHT: 24 25 See the LICENSE file in the top level JEGA directory. 26 27 VERSION: 28 29 1.0.0 30 31 CHANGES: 32 33 Tue May 13 13:04:06 2003 - Original Version (JE) 34 Wed Dec 07 15:30:05 2005 - Made modifications necessary for replacement 35 of ProblemDescDB with ParameterDatabase.(JE) 36 37 ================================================================================ 38 */ 39 40 41 42 43 /* 44 ================================================================================ 45 Document This File 46 ================================================================================ 47 */ 48 /** \file 49 * \brief Contains the definition of the GeneticAlgorithmOperator class. 50 */ 51 52 53 54 55 /* 56 ================================================================================ 57 Prevent Multiple Inclusions 58 ================================================================================ 59 */ 60 #ifndef JEGA_ALGORITHMS_GENETICALGORITHMOPERATOR_HPP 61 #define JEGA_ALGORITHMS_GENETICALGORITHMOPERATOR_HPP 62 63 64 65 66 67 68 69 /* 70 ================================================================================ 71 Includes 72 ================================================================================ 73 */ 74 // JEGAConfig.hpp should be the first include in all JEGA files. 75 #include <../Utilities/include/JEGAConfig.hpp> 76 77 #include <string> 78 79 80 81 82 83 84 85 /* 86 ================================================================================ 87 Namespace Aliases 88 ================================================================================ 89 */ 90 91 92 93 94 95 /* 96 ================================================================================ 97 Pre Namespace Forward Declares 98 ================================================================================ 99 */ 100 namespace JEGA 101 { 102 namespace Utilities 103 { 104 class DesignTarget; 105 class ParameterDatabase; 106 } 107 108 namespace Logging 109 { 110 class Logger; 111 } 112 } 113 114 115 116 117 118 119 120 121 /* 122 ================================================================================ 123 Begin Namespace 124 ================================================================================ 125 */ 126 namespace JEGA { 127 namespace Algorithms { 128 129 130 131 132 133 134 135 /* 136 ================================================================================ 137 In-Namespace Forward Declares 138 ================================================================================ 139 */ 140 class GeneticAlgorithm; 141 class GeneticAlgorithmOperator; 142 143 144 145 146 147 /* 148 ================================================================================ 149 In Namespace File Scope Typedefs 150 ================================================================================ 151 */ 152 153 /// Signature of the methods required of each operator for creation. 154 typedef 155 GeneticAlgorithmOperator* 156 (*GeneticAlgorithmOperatorCreateFunc)( 157 GeneticAlgorithm& 158 ); 159 160 161 162 /* 163 ================================================================================ 164 Class Definition 165 ================================================================================ 166 */ 167 168 /// The base class for all kinds of GeneticAlgorithm operators. 169 /** 170 * This base class provides some useful capabilities needed by all operators. 171 * It also requires that derived operators implement a few methods. It requires 172 * no configuration input. 173 */ 174 class JEGA_SL_IEDECL GeneticAlgorithmOperator 175 { 176 /* 177 ============================================================================ 178 Class Scope Typedefs 179 ============================================================================ 180 */ 181 public: 182 183 184 protected: 185 186 187 private: 188 189 190 /* 191 ============================================================================ 192 Member Data Declarations 193 ============================================================================ 194 */ 195 private: 196 197 /// The GeneticAlgorithm for which this operator is used. 198 GeneticAlgorithm& _algorithm; 199 200 /* 201 ============================================================================ 202 Mutators 203 ============================================================================ 204 */ 205 public: 206 207 208 209 210 211 /* 212 ============================================================================ 213 Accessors 214 ============================================================================ 215 */ 216 public: 217 218 /** 219 * \brief Allows mutable access to the GeneticAlgorithm know to this 220 * operator. 221 * 222 * \return The GeneticAlgorithm for which this is an operator. 223 */ 224 inline 225 GeneticAlgorithm& 226 GetAlgorithm( 227 ); 228 229 /** 230 * \brief Allows immutable access to the GeneticAlgorithm know to this 231 * operator. 232 * 233 * \return The GeneticAlgorithm for which this is an operator. 234 */ 235 inline 236 const GeneticAlgorithm& 237 GetAlgorithm( 238 ) const; 239 240 /* 241 ============================================================================ 242 Public Methods 243 ============================================================================ 244 */ 245 public: 246 247 /// Used to call PollForParameters. 248 /** 249 * This method issues a call to PollForParameters at which time derived 250 * operators can ask for specific parameters by string. This is the 251 * method that should be used by whomever creates operators. 252 * 253 * \param db The database of parameters from which operators can 254 * extract their needed configuration information. 255 * \return True if polling for parameters succeeds and false otherwise. 256 */ 257 bool 258 ExtractParameters( 259 const JEGA::Utilities::ParameterDatabase& db 260 ); 261 262 /** 263 * \brief Allows immutable access to the DesignTarget of the algorithm 264 * for which this is an operator. 265 * 266 * \return The DesignTarget for Designs manipulated by this operator. 267 */ 268 const JEGA::Utilities::DesignTarget& 269 GetDesignTarget( 270 ) const; 271 272 /* 273 ============================================================================ 274 Subclass Visible Methods 275 ============================================================================ 276 */ 277 protected: 278 279 /** 280 * \brief Allows mutable access to the DesignTarget of the algorithm 281 * for which this is an operator to subclasses. 282 * 283 * \return The DesignTarget for Designs manipulated by this operator. 284 */ 285 JEGA::Utilities::DesignTarget& 286 GetDesignTarget( 287 ); 288 289 /** 290 * \brief Allows subclass access to the Logger being used by the 291 * algorithm for which this is an operator. 292 * 293 * The logger should not be used directly except in the JEGA_LOGGING 294 * macros. If logging from a static method, either include the 295 * logger as a parameter or use the global log via the _G macros. 296 * 297 * \return The Logger class object that should be used by this 298 * operator. 299 */ 300 JEGA::Logging::Logger& 301 GetLogger( 302 ) const; 303 304 /** 305 * \brief Returns the individual name given to the instance of an 306 * algorithm that is using this operator. 307 * 308 * \return The name given to the GA using this operator. 309 */ 310 const std::string& 311 GetAlgorithmName( 312 ) const; 313 314 /* 315 ============================================================================ 316 Subclass Overridable Methods 317 ============================================================================ 318 */ 319 public: 320 321 /// Override to return the proper name of this operator. 322 /** 323 * \return The proper unique name of this operator. 324 */ 325 virtual 326 std::string 327 GetName( 328 ) const = 0; 329 330 /// Override to return the name of the type of this operator. 331 /** 332 * Examples include Crosser, Mutator, etc. 333 * 334 * \return A string describing the type of this operator. 335 */ 336 virtual 337 std::string 338 GetType( 339 ) const = 0; 340 341 /** 342 * \brief Override to return a full description of what this operator 343 * does and how. 344 * 345 * \return A full description the operation of this operator. 346 */ 347 virtual 348 std::string 349 GetDescription( 350 ) const = 0; 351 352 /** 353 * \brief Override to return an exact duplicate of this operator for 354 * use by \a algorithm. 355 * 356 * \param algorithm The GA for which the clone is being created. 357 * \return A clone of this operator. 358 */ 359 virtual 360 GeneticAlgorithmOperator* 361 Clone( 362 GeneticAlgorithm& algorithm 363 ) const = 0; 364 365 /** 366 * \brief Called when the operator is no longer needed. 367 * 368 * This method is called when the algorithm is done with this operator. 369 * It can be assumed that the algorithm will receive no further calls 370 * to the main method after this. This typically happens just prior 371 * to destruction of this operator. 372 * 373 * The default implementation is to do nothing. Override to do any 374 * cleanup, etc. required by this operator. 375 * 376 * \return true if finalization completed successfully and false 377 * otherwise. 378 */ 379 virtual 380 bool 381 Finalize( 382 ); 383 384 protected: 385 386 /** 387 * \brief Override to retrieve specific parameters for this operator. 388 * 389 * This method should be used to extract needed information for this 390 * operator. It should do so using the ParameterExtractor class 391 * methods. The return value should be true if the extraction 392 * completes successfully and false otherwise. 393 * 394 * It is pure virtual and must be overridden by any instantiable 395 * derived class. 396 * 397 * \param db The database of parameter values from which to do 398 * retrieval. 399 * \return true if polling completed successfully and false otherwise. 400 */ 401 virtual 402 bool 403 PollForParameters( 404 const JEGA::Utilities::ParameterDatabase& db 405 ) = 0; 406 407 private: 408 409 410 411 /* 412 ============================================================================ 413 Private Methods 414 ============================================================================ 415 */ 416 private: 417 418 419 420 421 /* 422 ============================================================================ 423 Structors 424 ============================================================================ 425 */ 426 public: 427 428 /// Constructs a GeneticAlgorithmOperator for use with \a algorithm. 429 /** 430 * \param algorithm The GA for which this operator is being 431 * constructed. 432 */ 433 GeneticAlgorithmOperator( 434 GeneticAlgorithm& algorithm 435 ); 436 437 /** 438 * \brief Copy constructs a GeneticAlgorithmOperator for use in the 439 * same algorithm as \a copy. 440 * 441 * \param copy The instance from which properties should be copied into 442 * this. 443 */ 444 GeneticAlgorithmOperator( 445 const GeneticAlgorithmOperator& copy 446 ); 447 448 /// Copy constructs a GeneticAlgorithmOperator for use by \a algorithm. 449 /** 450 * \param copy The instance from which properties should be copied into 451 * this. 452 * \param algorithm The GA for which this operator is being 453 * constructed. 454 */ 455 GeneticAlgorithmOperator( 456 const GeneticAlgorithmOperator& copy, 457 GeneticAlgorithm& algorithm 458 ); 459 460 /// Destructs a GeneticAlgorithmOperator. 461 virtual 462 ~GeneticAlgorithmOperator( 463 ); 464 465 }; // class GeneticAlgorithmOperator 466 467 468 /* 469 ================================================================================ 470 End Namespace 471 ================================================================================ 472 */ 473 } // namespace Algorithms 474 } // namespace JEGA 475 476 477 478 479 480 481 /* 482 ================================================================================ 483 Include Inlined Methods File 484 ================================================================================ 485 */ 486 #include "./inline/GeneticAlgorithmOperator.hpp.inl" 487 488 489 490 /* 491 ================================================================================ 492 End of Multiple Inclusion Check 493 ================================================================================ 494 */ 495 #endif // JEGA_ALGORITHMS_GENETICALGORITHMOPERATOR_HPP 496