1 /* 2 ================================================================================ 3 PROJECT: 4 5 John Eddy's Genetic Algorithms (JEGA) 6 7 CONTENTS: 8 9 Implementation of class DiscreteDesignVariableNature. 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 Jun 03 08:55:37 2003 - 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 DiscreteDesignVariableNature class. 48 */ 49 50 51 52 /* 53 ================================================================================ 54 Prevent Multiple Inclusions 55 ================================================================================ 56 */ 57 #ifndef JEGA_UTILITIES_DISCRETEDESIGNVARIABLENATURE_HPP 58 #define JEGA_UTILITIES_DISCRETEDESIGNVARIABLENATURE_HPP 59 60 61 62 63 64 65 66 /* 67 ================================================================================ 68 Includes 69 ================================================================================ 70 */ 71 // JEGAConfig.hpp should be the first include in all JEGA files. 72 #include <../Utilities/include/JEGAConfig.hpp> 73 74 #include <../Utilities/include/JEGATypes.hpp> 75 76 #include <../Utilities/include/DesignVariableNatureBase.hpp> 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 ================================================================================ 99 Namespace Aliases 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 124 125 /* 126 ================================================================================ 127 In Namespace File Scope Typedefs 128 ================================================================================ 129 */ 130 131 132 133 134 135 136 /* 137 ================================================================================ 138 In-Namespace Forward Declares 139 ================================================================================ 140 */ 141 class DiscreteDesignVariableNature; 142 143 144 145 146 147 148 149 /* 150 ================================================================================ 151 Class Definition 152 ================================================================================ 153 */ 154 155 /// A nature for discrete design variables. 156 /** 157 * This nature is used to store discrete values for any type variable type. 158 * By forwarding work onto this class, DesignVariableInfo objects can get 159 * valid random values, boundary values, etc. 160 * 161 * To be a discrete variable for the purposes of this project, 162 * it must be the case that there is a finite number of values for 163 * which there is no regular and patterned progression from one to 164 * the next. For example, it is not intended that you use this nature 165 * to represent all the integers from some lower bound to some upper 166 * bound. Use the continuum nature with the integer type for that. 167 */ 168 class JEGA_SL_IEDECL DiscreteDesignVariableNature : 169 public DesignVariableNatureBase 170 { 171 /* 172 ============================================================================ 173 Member Data Declarations 174 ============================================================================ 175 */ 176 private: 177 178 /** 179 * \brief This vector holds all the allowed discrete values for this 180 * variable. 181 * 182 * They are stored as doubles and their double representation is 183 * the index of their location in the vector. 184 */ 185 JEGA::DoubleVector _disVals; 186 187 188 189 190 /* 191 ============================================================================ 192 Mutators 193 ============================================================================ 194 */ 195 public: 196 197 198 199 200 201 /* 202 ============================================================================ 203 Accessors 204 ============================================================================ 205 */ 206 public: 207 208 /// Allows immutable access to the discrete values for this variable. 209 /** 210 * \return The list of discrete values for this variable. 211 */ 212 inline 213 const JEGA::DoubleVector& 214 GetDiscreteValues( 215 ) const; 216 217 218 219 220 /* 221 ============================================================================ 222 Public Methods 223 ============================================================================ 224 */ 225 public: 226 227 228 229 /* 230 ============================================================================ 231 Subclass Visible Methods 232 ============================================================================ 233 */ 234 protected: 235 236 237 238 239 240 /* 241 ============================================================================ 242 Subclass Overridable Methods 243 ============================================================================ 244 */ 245 public: 246 247 /// Returns the string name of this nature. 248 /** 249 * \return The string "Discrete". 250 */ 251 virtual 252 std::string 253 ToString( 254 ) const; 255 256 /// Returns an exact duplicate of this nature object. 257 /** 258 * \param forType The type base with which this nature is being used. 259 * \return An exact duplicate of this nature created for use with the 260 * supplied type. 261 */ 262 virtual 263 DesignVariableNatureBase* 264 Clone( 265 DesignVariableTypeBase& forType 266 ) const; 267 268 /** 269 * \brief Returns the representation of the max value for this nature 270 * as a double. 271 * 272 * A return of -limits::max indicates failure. 273 * 274 * \return The representation of the maximum value for this variable or 275 * -limits::max if error. 276 */ 277 virtual 278 var_rep_t 279 GetMaxRep( 280 ) const; 281 282 /** 283 * \brief Returns the representation of the min value for this nature 284 * as a double. 285 * 286 * A return of -limits::max indicates failure. 287 * 288 * \return The representation of the minimum value for this variable or 289 * -limits::max if error. 290 */ 291 virtual 292 var_rep_t 293 GetMinRep( 294 ) const; 295 296 /** 297 * \brief Returns a random representation existing within 298 * the supplied range. 299 * 300 * A return of -limits::max indicates failure. 301 * 302 * \param lb The lower bound on the desired random value. 303 * \param ub The upper bound on the desired value. 304 * \return The representation of a random value inside \a within. 305 */ 306 virtual 307 var_rep_t 308 GetRandomRep( 309 var_rep_t lb, 310 var_rep_t ub 311 ) const; 312 313 /// Returns the proper representation of \a value as a double. 314 /** 315 * A return of -limits::max indicates failure. 316 * 317 * \param value The value to retrieve the representation of. 318 * \return The representation of the value \a value. 319 */ 320 virtual 321 var_rep_t 322 GetRepOf( 323 double value 324 ) const; 325 326 /// Returns a random valid value for this type as a double. 327 /** 328 * A return of -limits::max indicates failure. 329 * 330 * \return A random value for this variable for which IsValidValue will 331 * return true; 332 */ 333 virtual 334 double 335 GetRandomValue( 336 ) const; 337 338 /// Returns the maximum value this nature may have as a double. 339 /** 340 * A return of -limits::max indicates failure. 341 * 342 * \return The largest legitimate value for this variable. 343 */ 344 virtual 345 double 346 GetMaxValue( 347 ) const; 348 349 /// Returns the minimum value this nature may have as a double. 350 /** 351 * A return of -limits::max indicates failure. 352 * 353 * \return The smallest legitimate value for this variable. 354 */ 355 virtual 356 double 357 GetMinValue( 358 ) const; 359 360 /// Returns the value represented by \a rep as a double. 361 /** 362 * A return of -limits::max indicates failure. 363 * 364 * \param rep The representation to convert to a value. 365 * \return The value associated with or represented by \a rep. 366 */ 367 virtual 368 double 369 GetValueOf( 370 var_rep_t rep 371 ) const; 372 373 /// Returns the nearest valid value to \a value. 374 /** 375 * A return of -limits::max indicates failure. 376 * 377 * \param value The value to correct to a valid value. 378 * \return The nearest value to \a value for which IsValidValue will 379 * return true; 380 */ 381 virtual 382 double 383 GetNearestValidValue( 384 double value 385 ) const; 386 387 /// Returns the nearest valid double rep to \a rep. 388 /** 389 * A return of -limits::max indicates failure. 390 * 391 * \param rep The representation to correct to a valid representation. 392 * \return The nearest representation to \a rep for which 393 * IsValidRep will return true; 394 */ 395 virtual 396 var_rep_t 397 GetNearestValidRep( 398 var_rep_t rep 399 ) const; 400 401 /// Returns the distance between valid representations as a double. 402 /** 403 * A return of -limits::max indicates failure. 404 * 405 * \return The increment that exists between consecutive 406 * representations according to the decimal precision. 407 */ 408 virtual 409 var_rep_t 410 GetDistanceBetweenReps( 411 ) const; 412 413 /** 414 * \brief The mechanism by which discrete values can be added to this 415 * object. 416 * 417 * \a value is checked to see that it is unique in the list of discrete 418 * values. Returns true if \a value was successfully added and false 419 * otherwise. 420 * 421 * \param value The value that would be added to the list of discrete 422 * values. 423 * \return true if the value is added and false otherwise. 424 */ 425 virtual 426 bool 427 AddDiscreteValue( 428 double value 429 ); 430 431 /// This method empties the list of discrete values. 432 virtual 433 void 434 ClearDiscreteValues( 435 ); 436 437 /** 438 * \brief This method allows the removal of the specified discrete 439 * value \a value. 440 * 441 * Returns true if \a value was removed and false otherwise (which 442 * usually means that \a value was not found). 443 * 444 * \param value The value that to be removed from the list of 445 * discrete values. 446 * \return true if the value is found and removed and false otherwise. 447 */ 448 virtual 449 bool 450 RemoveDiscreteValue( 451 double value 452 ); 453 454 /** 455 * \brief Sets the upper bound or largest value for this variable to 456 * \a value. 457 * 458 * This method causes the removal of any discrete values larger than 459 * value. 460 * 461 * \param value The new maximum value for this variable. 462 */ 463 virtual 464 void 465 SetMaxValue( 466 double value 467 ); 468 469 /** 470 * \brief Sets the lower bound or smallest value for this variable to 471 * \a value. 472 * 473 * This method causes the removal of any discrete values smaller than 474 * value. 475 * 476 * \param value The new minimum value for this variable. 477 */ 478 virtual 479 void 480 SetMinValue( 481 double value 482 ); 483 484 /** 485 * \brief Always returns false b/c discrete values can be handled 486 * by this nature. 487 * 488 * \return false, always. 489 */ 490 virtual 491 bool 492 IsDiscreteValueLocked( 493 ) const; 494 495 /** 496 * \brief Returns true if \a value is one of the discrete values known 497 * to this nature. 498 * 499 * \param value The value to check to see if it is in bounds or not. 500 * \return True if value is in bounds and false otherwise. 501 */ 502 virtual 503 bool 504 IsValueInBounds( 505 double value 506 ) const; 507 508 /** 509 * \brief Returns true if \a rep lies within the upper and lower bounds 510 * of this variable in terms of representations ( not values ). 511 * 512 * In order for a rep to be in bounds for a discrete value, it must 513 * not only be within the upper and lower bound but must also be a 514 * whole number. 515 * 516 * \param rep The representation to check to see if it is in bounds or 517 * not. 518 * \return True if rep is in bounds and false otherwise. 519 */ 520 virtual 521 bool 522 IsRepInBounds( 523 var_rep_t rep 524 ) const; 525 526 /** 527 * \brief Returns true if this nature can take on values outside of the 528 * bounds and still be evaluated (even though it will no doubt 529 * be infeasible). 530 * 531 * This is useful to be sure that an algorithm does not generate values 532 * that cannot be used. In this case of a discrete variable, it 533 * makes no sense to attempt to use the 10th variable if only 9 exist. 534 * 535 * \return false, always. 536 */ 537 virtual 538 bool 539 IsOutOfBoundsDefined( 540 ) const; 541 542 /** 543 * \brief Returns true b/c the precision refers to representations 544 * which are always integral for this nature. 545 * 546 * \return true, always. 547 */ 548 virtual 549 bool 550 IsPrecisionLocked( 551 ) const; 552 553 /// Returns true if \a value is a valid value for this variable. 554 /** 555 * Valid values are those that may be returned by GetRandomValue. 556 * This method considers a value to be valid if it is in bounds. 557 * 558 * \param value The value to check for validity with this variable 559 * nature. 560 * \return true if \a value is a valid value for this variable and 561 * false otherwise. 562 */ 563 virtual 564 bool 565 IsValidValue( 566 double value 567 ) const; 568 569 /** 570 * \brief Returns true if \a rep is the representation of a valid value 571 * for this variable. 572 * 573 * Valid representations are those that may be returned by 574 * GetRandomRep. This method considers a representation to be 575 * valid if it is in bounds. 576 * 577 * \param rep The representation to check for validity with this 578 * variable nature. 579 * \return true if \a rep is a valid representation for this variable 580 * and false otherwise. 581 */ 582 virtual 583 bool 584 IsValidRep( 585 var_rep_t rep 586 ) const; 587 588 /// Returns true b/c this is the discrete nature. 589 /** 590 * \return true, always. 591 */ 592 virtual 593 bool 594 IsDiscrete( 595 ) const; 596 597 598 /// Returns false b/c this is the discrete nature. 599 /** 600 * \return false, always. 601 */ 602 virtual 603 bool 604 IsContinuum( 605 ) const; 606 607 protected: 608 609 610 private: 611 612 613 614 615 616 /* 617 ============================================================================ 618 Private Methods 619 ============================================================================ 620 */ 621 private: 622 623 624 625 626 627 /* 628 ============================================================================ 629 Structors 630 ============================================================================ 631 */ 632 public: 633 634 /// Constructs a DiscreteDesignVariableNature known by \a type. 635 /** 636 * \param type The type along with which this nature will be used to 637 * describe/define the behavior of a design variable. 638 */ 639 DiscreteDesignVariableNature( 640 DesignVariableTypeBase& type 641 ); 642 643 /// Copy constructs a DiscreteDesignVariableNature known by \a type. 644 /** 645 * \param copy The existing DesignVariableNatureBase from which to copy 646 * properties into this. 647 * \param type The type along with which this nature will be used to 648 * describe/define the behavior of a design variable. 649 */ 650 DiscreteDesignVariableNature( 651 const DiscreteDesignVariableNature& copy, 652 DesignVariableTypeBase& type 653 ); 654 655 /// Destructs a DiscreteDesignVariableNature object. 656 virtual 657 ~DiscreteDesignVariableNature( 658 ); 659 660 661 662 663 }; // class DiscreteDesignVariableNature 664 665 666 /* 667 ================================================================================ 668 End Namespace 669 ================================================================================ 670 */ 671 } // namespace Utilities 672 } // namespace JEGA 673 674 675 676 677 678 679 680 /* 681 ================================================================================ 682 Include Inlined Methods File 683 ================================================================================ 684 */ 685 #include "./inline/DiscreteDesignVariableNature.hpp.inl" 686 687 688 689 /* 690 ================================================================================ 691 End of Multiple Inclusion Check 692 ================================================================================ 693 */ 694 #endif // JEGA_UTILITIES_DISCRETEDESIGNVARIABLENATURE_HPP 695