1 /* 2 ================================================================================ 3 PROJECT: 4 5 John Eddy's Genetic Algorithms (JEGA) 6 7 CONTENTS: 8 9 Definition of class DesignTarget. 10 11 NOTES: 12 13 See notes under Class Definition section 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 2.0.0 30 31 CHANGES: 32 33 Tue Dec 20 08:11:48 2005 - Original Version (JE) 34 35 ================================================================================ 36 */ 37 38 39 40 41 /* 42 ================================================================================ 43 Document This File 44 ================================================================================ 45 */ 46 /** \file 47 * \brief Contains the definition of the DesignTarget class. 48 */ 49 50 51 52 53 /* 54 ================================================================================ 55 Prevent Multiple Inclusions 56 ================================================================================ 57 */ 58 #ifndef JEGA_UTILITIES_DESIGNTARGET_HPP 59 #define JEGA_UTILITIES_DESIGNTARGET_HPP 60 61 62 63 64 65 66 67 /* 68 ================================================================================ 69 Includes 70 ================================================================================ 71 */ 72 // JEGAConfig.hpp should be the first include in all JEGA files. 73 #include <../Utilities/include/JEGAConfig.hpp> 74 75 #include <vector> 76 77 78 79 80 81 82 83 /* 84 ================================================================================ 85 Pre-Namespace Forward Declares 86 ================================================================================ 87 */ 88 89 90 91 92 93 94 95 96 /* 97 ================================================================================ 98 Namespace Aliases 99 ================================================================================ 100 */ 101 102 103 104 105 106 107 108 109 /* 110 ================================================================================ 111 Begin Namespace 112 ================================================================================ 113 */ 114 namespace JEGA { 115 namespace Utilities { 116 117 118 119 120 121 /* 122 ================================================================================ 123 In-Namespace Forward Declares 124 ================================================================================ 125 */ 126 class Design; 127 class DesignTarget; 128 class RegionOfSpace; 129 class LRUDesignCache; 130 class ConstraintInfo; 131 class DesignDVSortSet; 132 class DesignVariableInfo; 133 class ObjectiveFunctionInfo; 134 135 136 137 138 139 140 141 /* 142 ================================================================================ 143 In-Namespace File Scope Typedefs 144 ================================================================================ 145 */ 146 147 /** 148 * \brief A container for all the information objects describing a set of 149 * Design variables. 150 */ 151 typedef 152 std::vector<DesignVariableInfo*> 153 DesignVariableInfoVector; 154 155 /** 156 * \brief A container for all the information objects describing a set of 157 * Constraints. 158 */ 159 typedef 160 std::vector<ConstraintInfo*> 161 ConstraintInfoVector; 162 163 /** 164 * \brief A container for all the information objects describing a set of 165 * objective functions. 166 */ 167 typedef 168 std::vector<ObjectiveFunctionInfo*> 169 ObjectiveFunctionInfoVector; 170 171 172 173 174 175 176 177 /* 178 ================================================================================ 179 Class Definition 180 ================================================================================ 181 */ 182 /** 183 * \brief A basic implementation of the DesignTarget interface. 184 * 185 * This implementation is thread safe if JEGA_THREADSAFE is defined. 186 */ 187 class JEGA_SL_IEDECL DesignTarget 188 { 189 /* 190 ============================================================================ 191 Nested Utility Class Forward Declares 192 ============================================================================ 193 */ 194 private: 195 196 /// A class housing all mutexes used by the DesignTarget. 197 /** 198 * This gets removed if JEGA_THREADSAFE is not defined. 199 */ 200 JEGA_IF_THREADSAFE(class Mutexes;) 201 202 /* 203 ============================================================================ 204 Class Scope Typedefs 205 ============================================================================ 206 */ 207 public: 208 209 210 protected: 211 212 213 private: 214 215 /* 216 ============================================================================ 217 Class Data Declarations 218 ============================================================================ 219 */ 220 public: 221 222 static const std::size_t DEFAULT_MAX_GUFF_SIZE; 223 224 225 /* 226 ============================================================================ 227 Member Data Declarations 228 ============================================================================ 229 */ 230 private: 231 232 /// Cache of discards 233 LRUDesignCache* _discCache; 234 235 /// Collection of discarded Design's 236 //DesignDVSortSet* _discards; 237 238 /// The information objects describing the Design variables. 239 DesignVariableInfoVector _dvInfos; 240 241 /// The information objects describing the objective functions. 242 ObjectiveFunctionInfoVector _ofInfos; 243 244 /// The information objects describing the constraints. 245 ConstraintInfoVector _cnInfos; 246 247 mutable std::vector<Design*> _guff; 248 249 std::size_t _maxGuffSize; 250 251 bool _trackDiscards; 252 253 /// An instance of a set of mutexes used if threadsafe is on. 254 JEGA_IF_THREADSAFE(Mutexes* _mutexes;) 255 256 /* 257 ============================================================================ 258 Mutators 259 ============================================================================ 260 */ 261 public: 262 263 void 264 SetTrackDiscards( 265 bool track 266 ); 267 268 void 269 SetMaxGuffSize( 270 std::size_t maxSize 271 ); 272 273 void 274 SetMaxDiscardCacheSize( 275 std::size_t maxSize 276 ); 277 278 279 280 protected: 281 282 283 private: 284 285 286 /* 287 ============================================================================ 288 Accessors 289 ============================================================================ 290 */ 291 public: 292 293 inline 294 bool 295 GetTrackDiscards( 296 ) const; 297 298 inline 299 std::size_t 300 GetMaxGuffSize( 301 ) const; 302 303 304 std::size_t 305 GetMaxDiscardCacheSize( 306 ) const; 307 308 /// Gets the vector of DesignVariableInfo's for this problem. 309 /** 310 * \return The vector of all design variable information objects. 311 */ 312 inline 313 const DesignVariableInfoVector& 314 GetDesignVariableInfos( 315 ) const; 316 317 /// Gets the vector of ObjectiveFunctionInfo's for this problem. 318 /** 319 * \return The vector of all objective function information objects. 320 */ 321 inline 322 const ObjectiveFunctionInfoVector& 323 GetObjectiveFunctionInfos( 324 ) const; 325 326 /// Gets the vector of DesignVariableInfo's for this problem. 327 /** 328 * \return The vector of all constraint information objects. 329 */ 330 inline 331 const ConstraintInfoVector& 332 GetConstraintInfos( 333 ) const; 334 335 protected: 336 337 338 private: 339 340 341 /* 342 ============================================================================ 343 Public Methods 344 ============================================================================ 345 */ 346 public: 347 348 349 350 351 352 /* 353 ============================================================================ 354 Subclass Visible Methods 355 ============================================================================ 356 */ 357 protected: 358 359 360 361 362 363 /* 364 ============================================================================ 365 Subclass Overridable Methods 366 ============================================================================ 367 */ 368 public: 369 370 /// Gets the discarded Design's stored in this (constant). 371 /** 372 * This method uses mutex protection to protect this set from 373 * multi-thread corruption. A lock is placed on the associated mutex. 374 * Therefore, in order to release the lock, a call to CheckinDiscards 375 * must be paired with each call to this method. 376 * 377 * \return The set of Designs passed to this Target by way of the 378 * TakeDesign* methods. 379 */ 380 const LRUDesignCache& 381 CheckoutDiscards( 382 ) const; 383 384 /** 385 * \brief Ends protection of the discards installed at a call to 386 * CheckoutDiscards. 387 * 388 * The collection of discarded designs is mutex protected. The only 389 * way for an external entity to access that collection is by using 390 * the CheckoutDiscards method. That method locks a mutex. 391 * In order to release the lock, a call to this method must be paired 392 * with each call to CheckoutDiscards. If thread safety is not 393 * compiled in, this method does nothing. 394 */ 395 void 396 CheckinDiscards( 397 ) const; 398 399 /// Returns a Design* properly allocated for this target 400 /** 401 * \return A new Design object properly allocated for this target. 402 */ 403 virtual 404 Design* 405 GetNewDesign( 406 ) const; 407 408 /** 409 * \brief Returns a Design* properly allocated for this target 410 * which is a duplicate of \a copy. 411 * 412 * \param copy An existing Design to duplicate. 413 * \return A new Design copy constructed from \a copy. 414 */ 415 virtual 416 Design* 417 GetNewDesign( 418 const Design& copy 419 ) const; 420 421 /// Returns the number of Design Variables for this problem 422 /** 423 * \return The number of design variables in the problem represented by 424 * this DesignTarget. 425 */ 426 inline 427 std::size_t 428 GetNDV( 429 ) const; 430 431 /// Returns the number of Objective Functions for this problem 432 /** 433 * \return The number of objective functions in the problem represented 434 * by this DesignTarget. 435 */ 436 inline 437 std::size_t 438 GetNOF( 439 ) const; 440 441 /// Returns the number of Constraints for this problem 442 /** 443 * \return The number of constraints in the problem represented by 444 * this DesignTarget. 445 */ 446 inline 447 std::size_t 448 GetNCN( 449 ) const; 450 451 /// Does whatever is necessary to determine the feasibility of \a des. 452 /** 453 * A design is considered feasible if all constraints (including side 454 * constraints) are satisfied. This generally requires checking for 455 * bound and regular constraint violations and tagging the Design 456 * object with appropriate attributes. 457 * 458 * \param des The Design of which to test the feasibility. 459 * \return true if \a des is feasible and false otherwise. 460 */ 461 bool 462 CheckFeasibility( 463 Design& des 464 ) const; 465 466 /// Returns true if all variable values in \a des are in bounds. 467 /** 468 * \param des The Design of which to test compliance with the side 469 * constraints. 470 * \return true if \a des satisfies all side constraints and false 471 * otherwise. 472 */ 473 bool 474 CheckSideConstraints( 475 Design& des 476 ) const; 477 478 /// Returns true if all non-side constraints are satisfied by des". 479 /** 480 * \param des The Design of which to test compliance with the 481 * functional constraints of the problem. 482 * \return true if \a des satisfies all non-side constraints and false 483 * otherwise. 484 */ 485 bool 486 CheckNonSideConstraints( 487 Design& des 488 ) const; 489 490 /// This method should be used to discard a no-longer-wanted Design. 491 /** 492 * The target assumes that if you call this method, you are completely 493 * done with the Design. It may choose to destroy it and so if you try 494 * to use it again, crash. 495 * 496 * \param des The no longer wanted Design. 497 */ 498 void 499 TakeDesign( 500 Design* des 501 ); 502 503 /// This method should be used to discard no-longer-wanted Designs. 504 /** 505 * The target assumes that if you call this method, you are completely 506 * done with these Designs. It may choose to destroy them and so if 507 * you try to use them again, crash. 508 * 509 * DesCont This type must adhere to STL conventions for a simple 510 * forward iteratable container including support for const_iterators, 511 * begin(), and end(). 512 * 513 * \param cont The container of no longer wanted Designs. 514 */ 515 template <typename DesCont> 516 inline 517 void 518 TakeDesigns( 519 const DesCont& cont 520 ); 521 522 /// This method should be used to re-claim what was an unwanted Design. 523 /** 524 * Since the target stores discards under certain circumstances, it is 525 * possible to get them back. It is only safe to call this for designs 526 * that you have discovered by iterating the discards group after a 527 * checkout and prior to a check-in. 528 * 529 * \param des The now again wanted Design. 530 * \return True if the design was in fact a stored discard and no longer 531 * is and false otherwise. 532 */ 533 bool 534 ReclaimDesign( 535 const Design& des 536 ); 537 538 /** 539 * \brief Records all constraint violations of \a des with 540 * the corresponding info objects. 541 * 542 * \param des The design whose constraint violations are to be 543 * recorded. 544 */ 545 void 546 RecordAllConstraintViolations( 547 const Design& des 548 ) const; 549 550 /// Inserts "info" into the list of DesignVariableInfo's. 551 /** 552 * \param info The new design variable information object to add to 553 * this target. 554 * 555 * \return True if \a info is successfully added and false otherwise. 556 * The only current fail conditions are: 557 * - a null "info". 558 * - an "info" built for a different target. 559 */ 560 bool 561 AddDesignVariableInfo( 562 DesignVariableInfo& info 563 ); 564 565 /// Inserts "info" into the list of ConstraintInfo's. 566 /** 567 * \param info The new constraint information object to add to 568 * this target. 569 * 570 * \return True if \a info is successfully added and false otherwise. 571 * The only current fail conditions are: 572 * - a null "info". 573 * - an "info" built for a different target. 574 */ 575 bool 576 AddConstraintInfo( 577 ConstraintInfo& info 578 ); 579 580 /// Inserts "info" into the list of ObjectiveFunctionInfo's. 581 /** 582 * \param info The new objective information object to add to this 583 * target. 584 * 585 * \return True if \a info is successfully added and false otherwise. 586 * The only current fail conditions are: 587 * - a null "info". 588 * - an "info" built for a different target. 589 */ 590 bool 591 AddObjectiveFunctionInfo( 592 ObjectiveFunctionInfo& info 593 ); 594 595 /** 596 * \brief Returns the complete design space represented as a 597 * RegionOfSpace object. 598 * 599 * The limits put into the region of space are based on the variable 600 * representations, not the values. 601 * 602 * \return The complete design space represented as a RegionOfSpace 603 * object. 604 */ 605 RegionOfSpace 606 GetDesignSpace( 607 ) const; 608 609 610 protected: 611 612 613 private: 614 615 616 /* 617 ============================================================================ 618 Private Methods 619 ============================================================================ 620 */ 621 private: 622 623 void 624 FlushTheGuff( 625 ); 626 627 628 629 630 /* 631 ============================================================================ 632 Structors 633 ============================================================================ 634 */ 635 public: 636 637 638 /// Constructs a DesignTarget object. 639 DesignTarget( 640 ); 641 642 /// Destructs a DesignTarget object. 643 virtual 644 ~DesignTarget( 645 ); 646 647 648 649 }; // class DesignTarget 650 651 652 653 /* 654 ================================================================================ 655 End Namespace 656 ================================================================================ 657 */ 658 } // namespace Utilities 659 } // namespace JEGA 660 661 662 663 664 665 666 667 /* 668 ================================================================================ 669 Include Inlined Functions File 670 ================================================================================ 671 */ 672 #include "inline/DesignTarget.hpp.inl" 673 674 675 676 /* 677 ================================================================================ 678 End of Multiple Inclusion Check 679 ================================================================================ 680 */ 681 #endif // JEGA_UTILITIES_DESIGNTARGET_HPP 682