1 /* 2 ================================================================================ 3 PROJECT: 4 5 John Eddy's Genetic Algorithms (JEGA) 6 7 CONTENTS: 8 9 Definition of class ExternalEvaluator. 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.1.0 30 31 CHANGES: 32 33 Thu Nov 09 14:54:09 2006 - 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 ExternalEvaluator class. 48 */ 49 50 51 52 53 /* 54 ================================================================================ 55 Prevent Multiple Inclusions 56 ================================================================================ 57 */ 58 #ifndef JEGA_FRONTEND_CONFIGFILE_EXTERNALEVALUATOR_HPP 59 #define JEGA_FRONTEND_CONFIGFILE_EXTERNALEVALUATOR_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 <GeneticAlgorithmEvaluator.hpp> 76 #include <../Utilities/include/JEGATypes.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 Namespace Aliases 99 ================================================================================ 100 */ 101 102 103 104 105 106 107 108 109 /* 110 ================================================================================ 111 Begin Namespace 112 ================================================================================ 113 */ 114 namespace JEGA { 115 namespace Algorithms { 116 117 118 119 120 121 /* 122 ================================================================================ 123 In-Namespace Forward Declares 124 ================================================================================ 125 */ 126 class ExternalEvaluator; 127 128 129 130 131 132 133 134 /* 135 ================================================================================ 136 In-Namespace File Scope Typedefs 137 ================================================================================ 138 */ 139 140 141 142 143 144 145 146 147 /* 148 ================================================================================ 149 Class Definition 150 ================================================================================ 151 */ 152 /** 153 * \brief This evaluator operates by calling an external program and reading 154 * results in from a text file. 155 * 156 * The executable can be anything that can be called via the command line such 157 * as an actual assembly, a script or batch file, etc. The command line will 158 * include two arguments. The first is the name of the file from which the 159 * design variable values can be read. The second is the name of the file that 160 * this evaluator will look for in order to read in the results of the 161 * evaluation. The following is an example of such a command line string. 162 * 163 * \verbatim 164 myevaler.exe params3.in results3.out 165 \endverbatim 166 * 167 * The design variables will be written as floating point values, 1 per line 168 * in the params file. The results must be written in the same fashion. The 169 * objective function values must be written followed by constraint values if 170 * there are any. These must be written in the order in which the objectives 171 * and constraints were described to the DesignTarget. 172 * 173 * If JEGA has been built in thread safe mode, this operator will respect the 174 * concurrency as defined and implemented in the base class. 175 * 176 * The name of the executable, the pattern by which to create parameter file 177 * names, and the pattern by which to create response file names are extracted 178 * from the parameter database using the strings "method.jega.exe_name", 179 * "method.jega.out_file_pat", and "method.jega.in_file_pat" respectively. 180 * The number of concurrent evaluations to run is extracted using the string 181 * "method.jega.eval_concurrency". The first 3 are all extracted as strings. 182 * The concurrency is extracted as a size type variable. If the output file 183 * pattern and input file pattern are not supplied, then the default values as 184 * defined by DEFAULT_OUT_PATTERN and DEFAULT_IN_PATTERN are used. If the 185 * executable name is not supplied, then a warning is issued. If a name is not 186 * supplied by the time an evaluation is requested, then a fatal error occurs. 187 * There is no default for this. If a concurrency value is not supplied, then 188 * the default value as defined by DEFAULT_EVAL_CONCUR is used. These are 189 * required in addition to any requirements of the base class. 190 */ 191 class JEGA_SL_IEDECL ExternalEvaluator : 192 public GeneticAlgorithmEvaluator 193 { 194 /* 195 ============================================================================ 196 Class Scope Typedefs 197 ============================================================================ 198 */ 199 public: 200 201 202 protected: 203 204 205 private: 206 207 208 /* 209 ============================================================================ 210 Member Data Declarations 211 ============================================================================ 212 */ 213 public: 214 215 /// The default number of generations over which to track the metric. 216 static const std::string DEFAULT_OUT_PATTERN; 217 218 /// The default percent change in the metric being sought. 219 static const std::string DEFAULT_IN_PATTERN; 220 221 private: 222 223 /// The name of the executable program to be run for evaluations. 224 std::string _exeName; 225 226 /// The pattern by which parameter file names are written. 227 /** 228 * These are the files into which design variables get written to be 229 * read in by analysis code. 230 */ 231 std::string _outPattern; 232 233 /// The pattern by which response file names are written. 234 /** 235 * These are the files into which objective function and constraint 236 * values get written to be read back in by this evaluator. 237 */ 238 std::string _inPattern; 239 240 std::size_t _evalNum; 241 242 /// The mutex that protects the _evalNum variable in threadsafe mode. 243 EDDY_DECLARE_MUTABLE_MUTEX(_currEvalMutex) 244 245 /* 246 ============================================================================ 247 Mutators 248 ============================================================================ 249 */ 250 public: 251 252 /// Allows mutation of the executable name known by this evaluator. 253 /** 254 * This method issues a verbose level log entry to inform of the new 255 * executable name. 256 * 257 * \param exeName The new name of the program to run for evaluations. 258 */ 259 void 260 SetExecutableName( 261 const std::string& exeName 262 ); 263 264 /// Allows mutation of the output file name pattern. 265 /** 266 * This method issues a verbose level log entry to inform of the new 267 * pattern. 268 * 269 * \param outPattern The new pattern by which output parameter files 270 * are named. 271 */ 272 void 273 SetOutputFilenamePattern( 274 const std::string& outPattern 275 ); 276 277 /// Allows mutation of the input file name pattern. 278 /** 279 * This method issues a verbose level log entry to inform of the new 280 * pattern. 281 * 282 * \param inPattern The new pattern by which input response files 283 * are named. 284 */ 285 void 286 SetInputFilenamePattern( 287 const std::string& inPattern 288 ); 289 290 protected: 291 292 293 private: 294 295 296 /* 297 ============================================================================ 298 Accessors 299 ============================================================================ 300 */ 301 public: 302 303 /// Allows access to the name of the executable used by this evaluator. 304 /** 305 * \return The current executable name used in creating command lines 306 * for performing executions. 307 */ 308 inline 309 const std::string& 310 GetExecutableName( 311 ) const; 312 313 /// Allows access to the parameter output file name pattern. 314 /** 315 * \return The pattern used to create parameter output file names. 316 */ 317 inline 318 const std::string& 319 GetOutputFilenamePattern( 320 ) const; 321 322 /// Allows access to the response input file name pattern. 323 /** 324 * \return The pattern used to create response input file names. 325 */ 326 inline 327 const std::string& 328 GetInputFilenamePattern( 329 ) const; 330 331 protected: 332 333 334 private: 335 336 337 /* 338 ============================================================================ 339 Public Methods 340 ============================================================================ 341 */ 342 public: 343 344 /// Returns the proper name of this operator. 345 /** 346 * \return The string "external". 347 */ 348 static 349 const std::string& 350 Name( 351 ); 352 353 /// Returns a full description of what this operator does and how. 354 /** 355 * The returned text is: 356 * \verbatim 357 \endverbatim. 358 * 359 * \return A description of the operation of this operator. 360 */ 361 static 362 const std::string& 363 Description( 364 ); 365 366 /** 367 * \brief Returns a new instance of this operator class for use by 368 * \a algorithm. 369 * 370 * \param algorithm The GA for which the new evaluator is to be used. 371 * \return A new, default instance of a ExternalEvaluator. 372 */ 373 static 374 GeneticAlgorithmOperator* 375 Create( 376 JEGA::Algorithms::GeneticAlgorithm& algorithm 377 ); 378 379 /* 380 ============================================================================ 381 Subclass Visible Methods 382 ============================================================================ 383 */ 384 protected: 385 386 /** 387 * \brief Creates a new output file name whereby all #'s in 388 * \a _outPattern are replaced by the number \a lbRepl. 389 * 390 * \param lbRepl The number to put in place of all #'s in the returned 391 * output file name. 392 * \return The filename resulting from replacing all #'s in 393 * \a _outPattern by \a lbRepl. 394 */ 395 std::string 396 GetOutputFilename( 397 std::size_t lbRepl 398 ) const; 399 400 /** 401 * \brief Creates a new input file name whereby all #'s in 402 * \a _inPattern are replaced by the number \a lbRepl. 403 * 404 * \param lbRepl The number to put in place of all #'s in the returned 405 * input file name. 406 * \return The filename resulting from replacing all #'s in 407 * \a _inPattern by \a lbRepl. 408 */ 409 std::string 410 GetInputFilename( 411 std::size_t lbRepl 412 ) const; 413 414 /* 415 ============================================================================ 416 Subclass Overridable Methods 417 ============================================================================ 418 */ 419 public: 420 421 /// Does evaluation of each Design in \a group. 422 /** 423 * This method is overridden only to do some sanity checking with the 424 * names of the input files and output files in the case of a >1 425 * evaluation concurrency. If the concurrency is >1, then the names 426 * must have wildcards. After the check, the base class implementation 427 * is invoked. 428 * 429 * \param group The group containing the Designs to be evaluated. 430 * \return True if all Designs evaluate successfully and false 431 * otherwise. 432 */ 433 virtual 434 bool 435 Evaluate( 436 JEGA::Utilities::DesignGroup& group 437 ); 438 439 /** 440 * \brief Overridden to perform evaluation of the Design provided. 441 * 442 * This is the method from which an evaluation is performed. This 443 * method will issue a call to the external evaluation program and 444 * read in the results. 445 * 446 * \param des The design to be evaluated. 447 * \return true if the Design is successfully evaluated and the results 448 * read in and false otherwise. 449 */ 450 virtual 451 bool 452 Evaluate( 453 JEGA::Utilities::Design& des 454 ); 455 456 ///** 457 // * \brief Overridden to perform evaluation of the Design provided in 458 // * the supplied EvaluationJob. 459 // * 460 // * This is the method from which an evaluation is performed. This 461 // * method will issue a call to the external evaluation program and 462 // * read in the results. 463 // * 464 // * \param evalJob The object containing the information needed to 465 // * perform the evaluation of a Design. 466 // * \return true if the Design is successfully evaluated and the results 467 // * read in and false otherwise. 468 // */ 469 //virtual 470 //bool 471 //Evaluate( 472 // EvaluationJob& evalJob 473 // ); 474 475 /// Returns the proper name of this operator. 476 /** 477 * \return See Name(). 478 */ 479 virtual 480 std::string 481 GetName( 482 ) const; 483 484 /// Returns a full description of what this operator does and how. 485 /** 486 * \return See Description(). 487 */ 488 virtual 489 std::string 490 GetDescription( 491 ) const; 492 493 /** 494 * \brief Creates and returns a pointer to an exact duplicate of this 495 * operator. 496 * 497 * \param algorithm The GA for which the clone is being created. 498 * \return A clone of this operator. 499 */ 500 virtual 501 GeneticAlgorithmOperator* 502 Clone( 503 JEGA::Algorithms::GeneticAlgorithm& algorithm 504 ) const; 505 506 /// Retrieves specific parameters using Get...FromDB methods. 507 /** 508 * This method is used to extract needed information for this 509 * operator. It does so using the "Get...FromDB" class 510 * of methods from the GeneticAlgorithmOperator base class. 511 * 512 * This version extracts the output file name pattern, input file name 513 * pattern, and the name of the executable to call. 514 * 515 * \param db The database of parameters from which the configuration 516 * information can be retrieved. 517 * \return true if the extraction completed successfully and false 518 * otherwise. 519 */ 520 virtual 521 bool 522 PollForParameters( 523 const JEGA::Utilities::ParameterDatabase& db 524 ); 525 526 protected: 527 528 529 private: 530 531 532 /* 533 ============================================================================ 534 Private Methods 535 ============================================================================ 536 */ 537 private: 538 539 /** 540 * \brief Replaces all occurrences of the supplied character in the 541 * supplied string with a string representation of the supplied 542 * value. 543 * 544 * \param of The character to replace. 545 * \param in The string in which to do the replacing. 546 * \param with The number to put in place of all \a of's. 547 */ 548 static 549 std::string 550 ReplaceAllOccurrances( 551 char of, 552 const std::string& in, 553 eddy::utilities::uint64_t with 554 ); 555 556 /* 557 ============================================================================ 558 Structors 559 ============================================================================ 560 */ 561 public: 562 563 /// Constructs a ExternalEvaluator for use by \a algorithm. 564 /** 565 * If you use this constructor, it will be necessary for you to supply 566 * an evaluation functor via the SetEvaluationFunctor method prior to 567 * use. 568 * 569 * \param algorithm The GA for which this evaluator is being 570 * constructed. 571 */ 572 ExternalEvaluator( 573 JEGA::Algorithms::GeneticAlgorithm& algorithm 574 ); 575 576 /// Copy constructs an ExternalEvaluator. 577 /** 578 * \param copy The instance from which properties should be copied into 579 * this. 580 */ 581 ExternalEvaluator( 582 const ExternalEvaluator& copy 583 ); 584 585 /// Copy constructs an ExternalEvaluator for use by \a algorithm. 586 /** 587 * \param copy The instance from which properties should be copied into 588 * this. 589 * \param algorithm The GA for which this evaluator is being 590 * constructed. 591 */ 592 ExternalEvaluator( 593 const ExternalEvaluator& copy, 594 JEGA::Algorithms::GeneticAlgorithm& algorithm 595 ); 596 597 }; // class ExternalEvaluator 598 599 600 601 /* 602 ================================================================================ 603 End Namespace 604 ================================================================================ 605 */ 606 } // namespace Algorithms 607 } // namespace JEGA 608 609 610 611 612 613 614 615 /* 616 ================================================================================ 617 Include Inlined Functions File 618 ================================================================================ 619 */ 620 #include "inline/ExternalEvaluator.hpp.inl" 621 622 623 624 /* 625 ================================================================================ 626 End of Multiple Inclusion Check 627 ================================================================================ 628 */ 629 #endif // JEGA_FRONTEND_CONFIGFILE_EXTERNALEVALUATOR_HPP 630