NOMAD Source  Version 4.0.0 Beta
Step.hpp
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------------*/
2 /* NOMAD - Nonlinear Optimization by Mesh Adaptive Direct Search - */
3 /* */
4 /* NOMAD - Version 4.0.0 has been created by */
5 /* Viviane Rochon Montplaisir - Polytechnique Montreal */
6 /* Christophe Tribes - Polytechnique Montreal */
7 /* */
8 /* The copyright of NOMAD - version 4.0.0 is owned by */
9 /* Charles Audet - Polytechnique Montreal */
10 /* Sebastien Le Digabel - Polytechnique Montreal */
11 /* Viviane Rochon Montplaisir - Polytechnique Montreal */
12 /* Christophe Tribes - Polytechnique Montreal */
13 /* */
14 /* NOMAD v4 has been funded by Rio Tinto, Hydro-Québec, NSERC (Natural */
15 /* Sciences and Engineering Research Council of Canada), InnovÉÉ (Innovation */
16 /* en Énergie Électrique) and IVADO (The Institute for Data Valorization) */
17 /* */
18 /* NOMAD v3 was created and developed by Charles Audet, Sebastien Le Digabel, */
19 /* Christophe Tribes and Viviane Rochon Montplaisir and was funded by AFOSR */
20 /* and Exxon Mobil. */
21 /* */
22 /* NOMAD v1 and v2 were created and developed by Mark Abramson, Charles Audet, */
23 /* Gilles Couture, and John E. Dennis Jr., and were funded by AFOSR and */
24 /* Exxon Mobil. */
25 /* */
26 /* Contact information: */
27 /* Polytechnique Montreal - GERAD */
28 /* C.P. 6079, Succ. Centre-ville, Montreal (Quebec) H3C 3A7 Canada */
29 /* e-mail: nomad@gerad.ca */
30 /* */
31 /* This program is free software: you can redistribute it and/or modify it */
32 /* under the terms of the GNU Lesser General Public License as published by */
33 /* the Free Software Foundation, either version 3 of the License, or (at your */
34 /* option) any later version. */
35 /* */
36 /* This program is distributed in the hope that it will be useful, but WITHOUT */
37 /* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or */
38 /* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License */
39 /* for more details. */
40 /* */
41 /* You should have received a copy of the GNU Lesser General Public License */
42 /* along with this program. If not, see <http://www.gnu.org/licenses/>. */
43 /* */
44 /* You can find information on the NOMAD software at www.gerad.ca/nomad */
45 /*---------------------------------------------------------------------------------*/
46 
47 #ifndef __NOMAD400_STEP__
48 #define __NOMAD400_STEP__
49 
50 #include "../Algos/MeshBase.hpp"
51 #include "../Eval/Barrier.hpp"
52 #include "../Output/OutputInfo.hpp"
53 #include "../Param/PbParameters.hpp"
54 #include "../Param/RunParameters.hpp"
55 #include "../Type/CallbackType.hpp"
56 #include "../Type/EvalType.hpp"
57 #include "../Util/AllStopReasons.hpp"
58 
59 #include "../nomad_nsbegin.hpp"
60 
61 class Step;
62 class Algorithm;
63 
64 typedef std::function<void(const Step& step, bool &stop)> StepEndCbFunc; ///< Type definitions for callback functions at the end of a step.
65 typedef std::function<void(std::vector<std::string>& paramLines)> HotRestartCbFunc; ///< Type definitions for callback functions for hot restart.
66 
67 /// Base class of all types of steps (Iteration, Termination, Initialization, Poll, Mads,...).
68 class Step
69 {
70 
71 protected:
72  static bool _userInterrupt; ///< Interrupt NOMAD if Ctrl-C is pressed.
73  static bool _userTerminate; ///< Terminate NOMAD if Ctrl-C is pressed again.
74 
75  const Step* _parentStep; ///< The parent of this step.
76  std::string _name; ///< The name of this step.
77 
78  std::shared_ptr<AllStopReasons> _stopReasons; ///< The stop reasons of an algorithm.
79 
80 
81  std::shared_ptr<RunParameters> _runParams; ///< The run parameters that control a step.
82  std::shared_ptr<PbParameters> _pbParams; ///< The problem parameters that control a step.
83 
84  // Callbacks that may be re-implemented by the user
88 
89  // By default, always show warnings.
90  // Some warnings do not need to be shown in some cases, ex. unit tests.
91  static bool _showWarnings;
92 
93 public:
94 
95  /// Constructor #1 for MainStep (no parent)
96  /**
97  */
98  explicit Step()
99  : _parentStep(nullptr),
100  _name("Main Step"),
101  _stopReasons(nullptr),
102  _runParams(nullptr),
103  _pbParams(nullptr)
104  {
105  init();
106  }
107 
108 
109  /// Constructor #2 for child step of a parent sharing the same stopReason
110  /**
111  \param parentStep The parent of this step (cannot be nullptr).
112  \param runParams The run parameters that control this step (null by default).
113  \param pbParams The problem parameters that control this step (null by default).
114  */
115  explicit Step(const Step* parentStep,
116  const std::shared_ptr<RunParameters> &runParams = nullptr,
117  const std::shared_ptr<PbParameters> &pbParams = nullptr)
118  : _parentStep(parentStep),
119  _name("Step"),
120  _runParams(runParams),
121  _pbParams(pbParams)
122  {
123  if (_parentStep == nullptr)
124  {
125  throw Exception(__FILE__, __LINE__, "Parent step is NULL. This constructor is for child steps having a parent only.");
126  }
127  else
128  {
129  _name = "Child step";
130  _stopReasons = parentStep->getAllStopReasons();
131  }
132  init();
133  }
134 
135  /// Constructor #3: for a child Step with a provided stopReason (such as an algorithm)
136  /**
137  \param parentStep The parent of this step (can be nullptr if child of a MainStep).
138  \param stopReasons The stop reasons for all the steps of an algo (cannot be nullptr)
139  \param runParams The run parameters that control this step (null by default).
140  \param pbParams The problem parameters that control this step (null by default).
141  */
142  explicit Step(const Step* parentStep,
143  std::shared_ptr<AllStopReasons> stopReasons,
144  const std::shared_ptr<RunParameters> &runParams = nullptr,
145  const std::shared_ptr<PbParameters> &pbParams = nullptr)
146  : _parentStep(parentStep),
147  _name("Step"),
148  _stopReasons(stopReasons),
149  _runParams(runParams),
150  _pbParams(pbParams)
151  {
152  if (nullptr == _stopReasons)
153  {
154  throw Exception(__FILE__, __LINE__, "StopReason is NULL. Must be provided for this child step.");
155  }
156 
157  init();
158  }
159 
160 
161  /// Destructor
162  /**
163  Upon destruction of a step the output queue is flushed. Time to print.
164  */
165  virtual ~Step();
166 
167  // Get / Set
168 
169  /// Interruption call by user.
170  /**
171  Called by pressing Ctrl-C.
172  */
173  static bool getUserTerminate() { return _userTerminate; }
174 
175  /// Interruption requested
176  static void setUserTerminate() { _userTerminate = true; }
177 
178  /// Get the parent step.
179  /**
180  * There is no setParentStep(). We should not change parent step externally.
181 
182  \return The parent step of this step.
183  */
184  const Step* getParentStep() const { return _parentStep; }
185 
186  /// Get the name of this step
187  /**
188  \return A /c string containing the name of this step.
189  */
190  virtual const std::string& getName() const { return _name; }
191 
192  /// Set the name of this step
193  /**
194  \param name The name is provided as a \c string -- \b IN.
195  */
196  void setName(const std::string& name) { _name = name; }
197 
198  const std::shared_ptr<AllStopReasons>& getAllStopReasons() const { return _stopReasons ; }
199 
200  const std::shared_ptr<RunParameters>& getRunParams() const { return _runParams; }
201  const std::shared_ptr<PbParameters>& getPbParams() const { return _pbParams; }
202 
203  /// Interruption call by user.
204  /**
205  * Called when the user pressed Ctrl-C.
206  \param signalValue Signal value -- \b IN.
207  */
208  static void userInterrupt(int signalValue);
209  static void debugSegFault(int signalValue);
210 
211  static bool getUserInterrupt() { return _userInterrupt; }
212 
213  /// \brief Set user callback
214  void addCallback(const CallbackType& callbackType,
215  const StepEndCbFunc& stepEndCbFunc);
216  void addCallback(const CallbackType& callbackType,
217  const HotRestartCbFunc& hotRestartCbFunc);
218 
219  /// \brief Run user callback
220  static void runCallback(CallbackType callbackType,
221  const Step& step,
222  bool &stop);
223  static void runCallback(CallbackType callbackType,
224  std::vector<std::string>& paramLines);
225 
226  static void disableWarnings() { _showWarnings = false; }
227 
228  /// \brief display output
229  void AddOutputInfo(const std::string& s, bool isBlockStart, bool isBlockEnd) const;
230  void AddOutputInfo(const std::string& s, OutputLevel outputLevel = OutputLevel::LEVEL_INFO) const;
231  void AddOutputError(const std::string& s) const;
232  void AddOutputWarning(const std::string& s) const;
233  void AddOutputVeryHigh(const std::string& s) const;
234  void AddOutputHigh(const std::string& s) const;
235  void AddOutputDebug(const std::string& s) const;
236  void AddOutputInfo(OutputInfo outputInfo) const;
237 
238  /// Template function to get the parent of given type.
239  /**
240  * Starting with parent of current Step, and going through ancestors,
241  get first Step that is of type T.
242  * By default, stop if an Algorithm is found. Returned Step could be
243  irrelevant otherwise. To go further up than an Algorithm, set optional
244  parameter stopAtAlgo to false.
245  */
246  template<typename T>
247  T getParentOfType(const bool stopAtAlgo = true) const
248  {
249  Step* retStep = nullptr;
250 
251  Step* step = const_cast<Step*>(_parentStep);
252  while (nullptr != step)
253  {
254  if (nullptr != dynamic_cast<T>(step))
255  {
256  retStep = step;
257  break;
258  }
259  else if (stopAtAlgo && step->isAnAlgorithm())
260  {
261  break;
262  }
263  step = const_cast<Step*>(step->getParentStep());
264  }
265 
266  return dynamic_cast<T>(retStep);
267  }
268 
269 
270  bool isAnAlgorithm() const;
271 
272  /// Get Algorithm ancestor that has no Algorithm ancestor.
273  const Algorithm* getRootAlgorithm() const;
274 
275  /**
276  \return the name of the first Algorithm ancestor of this Step,
277  or the Step itself, if it is an Algorithm.
278  \note If the Algorithm ancestor exists, a blank space is added at
279  the end of the string for easier use. This method is mostly used
280  to compute Step names as sub-steps of algorithms.
281  */
282  std::string getAlgoName() const;
283 
284  /**
285  Get comment that will be shown in normal display for additional information.
286  */
287  virtual std::string getAlgoComment() const;
288  /**
289  Set comment that will be shown in normal display for additional information.
290  */
291  virtual void setAlgoComment(const std::string& algoComment, const bool force = false);
292 
293  virtual void resetPreviousAlgoComment(const bool force = false);
294 
295  /**
296  \return The MeshBase for the first Iteration ancestor of this Step.
297  */
298  const std::shared_ptr<MeshBase> getIterationMesh() const;
299 
300  /**
301  \return The frameCenter for the first Iteration ancestor of this Step.
302  */
303  const std::shared_ptr<EvalPoint> getIterationFrameCenter() const;
304 
305  /**
306  \return The Barrier for the main MegaIteration ancestor of this Step.
307  */
308  const std::shared_ptr<Barrier> getMegaIterationBarrier() const;
309 
310  /**
311  Start of the Step. Initialize values for the run.
312  */
313  void start() ;
314 
315  /**
316  Placeholder to be implemented in derived classes. Called by start.
317  */
318  virtual void startImp() = 0 ;
319 
320  /**
321  * Perform main step task.
322  * Main part of the Step
323  \return \c true if the Step was positive, for instance, a success was found;
324  \c false if there was no success running this step
325  */
326  bool run();
327 
328  /**
329  Placeholder to be implemented in derived classes. Called by run.
330  */
331  virtual bool runImp() = 0 ;
332 
333  /**
334  * End of the Step. Clean up structures, flush output.
335  */
336  void end();
337 
338  /**
339  Placeholder to be implemented by derived classes. Called by end.
340  */
341  virtual void endImp() = 0 ;
342 
343  /// Helper for hot restart functionalities
344  virtual void hotRestartOnUserInterrupt();
345 
346  /// For debugging purposes. Show the stack of Steps for this step.
347  void debugShowCallStack() const;
348 
349 protected:
350  /// Helper for constructors.
351  /**
352  Throw Exception when not verified.
353  */
354  void verifyParentNotNull();
355 
356  /// Helper for validating steps depending on parameter GENERATE_ALL_POINTS_BEFORE_EVAL
357  void verifyGenerateAllPointsBeforeEval(const std::string& method, const bool expected) const;
358 
359  /// Helpers for hot restart, to be called at the start and end of any override.
360  void hotRestartBeginHelper();
361  /// Helpers for hot restart, to be called at the start and end of any override.
362  void hotRestartEndHelper();
363 
364 private:
365 
366  /// Helper for constructor
367  void init();
368 
369  // Default callbacks. They do nothing.
370  static void defaultStepEnd(const Step& step __attribute__((unused)), bool &stop) { stop = false; }
371  static void defaultHotRestart(std::vector<std::string>& paramLines __attribute__((unused))) {};
372 
373  /**
374  Default task always executed when start() is called
375  */
376  void defaultStart();
377 
378  /**
379  Default task always executed when end() is called
380  */
381  void defaultEnd();
382 
383 };
384 
385 
386 class StepException : public Exception
387 {
388 public:
389  /// Constructor
390  StepException(const std::string& file, const size_t line, const std::string & msg, const Step* step)
391  : Exception(file, line, msg)
392  {
393  if (nullptr != step)
394  {
395  step->debugShowCallStack();
396  }
397  }
398 };
399 
400 #include "../nomad_nsend.hpp"
401 
402 #endif // __NOMAD400_STEP__
OutputLevel
OutputLevel
Level of output AKA Display degree.
Definition: OutputInfo.hpp:55
Step::debugShowCallStack
void debugShowCallStack() const
For debugging purposes. Show the stack of Steps for this step.
Step::getPbParams
const std::shared_ptr< PbParameters > & getPbParams() const
Definition: Step.hpp:201
Step::_showWarnings
static bool _showWarnings
Definition: Step.hpp:91
StepException
Definition: Step.hpp:386
Step::getName
virtual const std::string & getName() const
Get the name of this step.
Definition: Step.hpp:190
Step::~Step
virtual ~Step()
Destructor.
Step::defaultStart
void defaultStart()
Step::_cbMegaIterationEnd
static StepEndCbFunc _cbMegaIterationEnd
Definition: Step.hpp:86
Step::getAlgoComment
virtual std::string getAlgoComment() const
Step::getRootAlgorithm
const Algorithm * getRootAlgorithm() const
Get Algorithm ancestor that has no Algorithm ancestor.
Step::runImp
virtual bool runImp()=0
Step::_runParams
std::shared_ptr< RunParameters > _runParams
The run parameters that control a step.
Definition: Step.hpp:81
Step::userInterrupt
static void userInterrupt(int signalValue)
Interruption call by user.
Step::Step
Step()
Constructor #1 for MainStep (no parent)
Definition: Step.hpp:98
Algorithm
Generic class for any direct search optimizer algorithm.
Definition: Algorithm.hpp:68
StepException::StepException
StepException(const std::string &file, const size_t line, const std::string &msg, const Step *step)
Constructor.
Definition: Step.hpp:390
Step::setUserTerminate
static void setUserTerminate()
Interruption requested.
Definition: Step.hpp:176
Step::_parentStep
const Step * _parentStep
The parent of this step.
Definition: Step.hpp:75
Step
Base class of all types of steps (Iteration, Termination, Initialization, Poll, Mads,...
Definition: Step.hpp:68
Step::_stopReasons
std::shared_ptr< AllStopReasons > _stopReasons
The stop reasons of an algorithm.
Definition: Step.hpp:78
Step::runCallback
static void runCallback(CallbackType callbackType, const Step &step, bool &stop)
Run user callback.
Step::_userInterrupt
static bool _userInterrupt
Interrupt NOMAD if Ctrl-C is pressed.
Definition: Step.hpp:72
Step::getAllStopReasons
const std::shared_ptr< AllStopReasons > & getAllStopReasons() const
Definition: Step.hpp:198
Step::_userTerminate
static bool _userTerminate
Terminate NOMAD if Ctrl-C is pressed again.
Definition: Step.hpp:73
Step::setAlgoComment
virtual void setAlgoComment(const std::string &algoComment, const bool force=false)
Step::AddOutputWarning
void AddOutputWarning(const std::string &s) const
Step::run
bool run()
CallbackType
CallbackType
Definition: CallbackType.hpp:60
Step::verifyGenerateAllPointsBeforeEval
void verifyGenerateAllPointsBeforeEval(const std::string &method, const bool expected) const
Helper for validating steps depending on parameter GENERATE_ALL_POINTS_BEFORE_EVAL.
Step::Step
Step(const Step *parentStep, std::shared_ptr< AllStopReasons > stopReasons, const std::shared_ptr< RunParameters > &runParams=nullptr, const std::shared_ptr< PbParameters > &pbParams=nullptr)
Constructor #3: for a child Step with a provided stopReason (such as an algorithm)
Definition: Step.hpp:142
Step::isAnAlgorithm
bool isAnAlgorithm() const
Step::endImp
virtual void endImp()=0
Exception
Exception utility.
Definition: WriteAttributeDefinitionFile.cpp:86
Step::init
void init()
Helper for constructor.
Step::getParentOfType
T getParentOfType(const bool stopAtAlgo=true) const
Template function to get the parent of given type.
Definition: Step.hpp:247
Step::start
void start()
Step::getAlgoName
std::string getAlgoName() const
Step::AddOutputInfo
void AddOutputInfo(const std::string &s, bool isBlockStart, bool isBlockEnd) const
display output
Step::getParentStep
const Step * getParentStep() const
Get the parent step.
Definition: Step.hpp:184
Step::getUserInterrupt
static bool getUserInterrupt()
Definition: Step.hpp:211
Step::_pbParams
std::shared_ptr< PbParameters > _pbParams
The problem parameters that control a step.
Definition: Step.hpp:82
Step::_name
std::string _name
The name of this step.
Definition: Step.hpp:76
Step::hotRestartOnUserInterrupt
virtual void hotRestartOnUserInterrupt()
Helper for hot restart functionalities.
Step::resetPreviousAlgoComment
virtual void resetPreviousAlgoComment(const bool force=false)
Step::getRunParams
const std::shared_ptr< RunParameters > & getRunParams() const
Definition: Step.hpp:200
Step::end
void end()
Step::verifyParentNotNull
void verifyParentNotNull()
Helper for constructors.
Step::setName
void setName(const std::string &name)
Set the name of this step.
Definition: Step.hpp:196
StepEndCbFunc
std::function< void(const Step &step, bool &stop)> StepEndCbFunc
Type definitions for callback functions at the end of a step.
Definition: Step.hpp:62
Step::defaultStepEnd
static void defaultStepEnd(const Step &step __attribute__((unused)), bool &stop)
Definition: Step.hpp:370
Step::getUserTerminate
static bool getUserTerminate()
Interruption call by user.
Definition: Step.hpp:173
Step::AddOutputHigh
void AddOutputHigh(const std::string &s) const
Step::getIterationFrameCenter
const std::shared_ptr< EvalPoint > getIterationFrameCenter() const
HotRestartCbFunc
std::function< void(std::vector< std::string > &paramLines)> HotRestartCbFunc
Type definitions for callback functions for hot restart.
Definition: Step.hpp:65
OutputInfo
Definition: OutputInfo.hpp:75
Step::getIterationMesh
const std::shared_ptr< MeshBase > getIterationMesh() const
Step::AddOutputError
void AddOutputError(const std::string &s) const
Step::addCallback
void addCallback(const CallbackType &callbackType, const StepEndCbFunc &stepEndCbFunc)
Set user callback.
Step::disableWarnings
static void disableWarnings()
Definition: Step.hpp:226
Step::hotRestartBeginHelper
void hotRestartBeginHelper()
Helpers for hot restart, to be called at the start and end of any override.
OutputLevel::LEVEL_INFO
@ LEVEL_INFO
Lots of information.
Step::AddOutputVeryHigh
void AddOutputVeryHigh(const std::string &s) const
Step::Step
Step(const Step *parentStep, const std::shared_ptr< RunParameters > &runParams=nullptr, const std::shared_ptr< PbParameters > &pbParams=nullptr)
Constructor #2 for child step of a parent sharing the same stopReason.
Definition: Step.hpp:115
Step::defaultEnd
void defaultEnd()
Step::AddOutputDebug
void AddOutputDebug(const std::string &s) const
Step::debugSegFault
static void debugSegFault(int signalValue)
Step::_cbIterationEnd
static StepEndCbFunc _cbIterationEnd
Definition: Step.hpp:85
Step::hotRestartEndHelper
void hotRestartEndHelper()
Helpers for hot restart, to be called at the start and end of any override.
Step::defaultHotRestart
static void defaultHotRestart(std::vector< std::string > &paramLines __attribute__((unused)))
Definition: Step.hpp:371
Step::_cbHotRestart
static HotRestartCbFunc _cbHotRestart
Definition: Step.hpp:87
Step::getMegaIterationBarrier
const std::shared_ptr< Barrier > getMegaIterationBarrier() const
Step::startImp
virtual void startImp()=0