Time.H
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------*\
2  ========= |
3  \\ / F ield | OpenFOAM: The Open Source CFD Toolbox
4  \\ / O peration | Website: https://openfoam.org
5  \\ / A nd | Copyright (C) 2011-2020 OpenFOAM Foundation
6  \\/ M anipulation |
7 -------------------------------------------------------------------------------
8 License
9  This file is part of OpenFOAM.
10 
11  OpenFOAM is free software: you can redistribute it and/or modify it
12  under the terms of the GNU General Public License as published by
13  the Free Software Foundation, either version 3 of the License, or
14  (at your option) any later version.
15 
16  OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
17  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
18  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
19  for more details.
20 
21  You should have received a copy of the GNU General Public License
22  along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
23 
24 Class
25  Foam::Time
26 
27 Description
28  Class to control time during OpenFOAM simulations that is also the
29  top-level objectRegistry.
30 
31 SourceFiles
32  Time.C
33  TimeIO.C
34  findInstance.C
35 
36 \*---------------------------------------------------------------------------*/
37 
38 #ifndef Time_H
39 #define Time_H
40 
41 #include "TimePaths.H"
42 #include "objectRegistry.H"
43 #include "unwatchedIOdictionary.H"
44 #include "FIFOStack.H"
45 #include "clock.H"
46 #include "cpuTime.H"
47 #include "TimeState.H"
48 #include "Switch.H"
49 #include "instantList.H"
50 #include "NamedEnum.H"
51 #include "typeInfo.H"
52 #include "dlLibraryTable.H"
53 #include "functionObjectList.H"
54 #include "sigWriteNow.H"
55 #include "sigStopAtWriteNow.H"
56 
57 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
58 
59 namespace Foam
60 {
61 
62 // Forward declaration of classes
63 class argList;
64 
65 /*---------------------------------------------------------------------------*\
66  Class Time Declaration
67 \*---------------------------------------------------------------------------*/
68 
69 class Time
70 :
71  public clock,
72  public cpuTime,
73  public TimePaths,
74  public objectRegistry,
75  public TimeState
76 {
77  // Private Data
78 
79  //- The controlDict
80  unwatchedIOdictionary controlDict_;
81 
82 public:
83 
84  //- Write control options
85  enum class writeControl
86  {
87  timeStep,
88  runTime,
90  clockTime,
91  cpuTime
92  };
93 
94  //- Stop-run control options
95  enum class stopAtControl
96  {
97  endTime,
98  noWriteNow,
99  writeNow,
100  nextWrite
101  };
102 
103  //- Supported time directory name formats
104  enum class format
105  {
106  general = 0,
109  };
110 
111 
112 protected:
113 
114  // Protected data
117  scalar startTime_;
118  mutable scalar endTime_;
121  mutable stopAtControl stopAt_;
126  scalar writeInterval_;
130 
131  // One-shot writing
132  bool writeOnce_;
133 
134  //- Is the time currently being sub-cycled?
135  bool subCycling_;
136 
137  //- If time is being sub-cycled this is the previous TimeState
139 
140 
141  // Signal handlers for writing
142 
143  //- Enable one-shot writing upon signal
145 
146  //- Enable write and clean exit upon signal
148 
149 
150  //- Time directory name format
151  static format format_;
152 
153  //- Time directory name precision
154  static int precision_;
155 
156  //- Maximum time directory name precision
157  static const int maxPrecision_;
158 
159  //- Adjust the time step so that writing occurs at the specified time
160  void adjustDeltaT();
161 
162  //- Set the controls from the current controlDict
163  void setControls();
164 
165  //- Read the control dictionary and set the write controls etc.
166  virtual void readDict();
167 
168 
169 private:
170 
171  //- Default write option
172  IOstream::streamFormat writeFormat_;
173 
174  //- Default output file format version number
175  IOstream::versionNumber writeVersion_;
176 
177  //- Default output compression
178  IOstream::compressionType writeCompression_;
179 
180  //- Default graph format
181  word graphFormat_;
182 
183  //- Is runtime modification of dictionaries allowed?
184  Switch runTimeModifiable_;
185 
186  //- Is temporary object cache enabled
187  mutable bool cacheTemporaryObjects_;
188 
189  //- Function objects executed at start and on ++, +=
190  mutable functionObjectList functionObjects_;
191 
192 
193 public:
194 
195  TypeName("time");
196 
197  //- The default control dictionary name (normally "controlDict")
198  static word controlDictName;
199 
200 
201  // Constructors
202 
203  //- Construct given name of dictionary to read and argument list
204  Time
205  (
206  const word& name,
207  const argList& args,
208  const word& systemName = "system",
209  const word& constantName = "constant"
210  );
211 
212  //- Construct given name of dictionary to read, rootPath and casePath
213  Time
214  (
215  const word& name,
216  const fileName& rootPath,
217  const fileName& caseName,
218  const word& systemName = "system",
219  const word& constantName = "constant",
220  const bool enableFunctionObjects = true
221  );
222 
223  //- Construct given dictionary, rootPath and casePath
224  Time
225  (
226  const dictionary& dict,
227  const fileName& rootPath,
228  const fileName& caseName,
229  const word& systemName = "system",
230  const word& constantName = "constant",
231  const bool enableFunctionObjects = true
232  );
233 
234  //- Construct given endTime, rootPath and casePath
235  Time
236  (
237  const fileName& rootPath,
238  const fileName& caseName,
239  const word& systemName = "system",
240  const word& constantName = "constant",
241  const bool enableFunctionObjects = true
242  );
243 
244 
245  //- Destructor
246  virtual ~Time();
247 
248 
249  // Member Functions
250 
251  // Database functions
252 
253  //- Return root path
254  const fileName& rootPath() const
255  {
256  return TimePaths::rootPath();
257  }
258 
259  //- Return case name
260  const fileName& caseName() const
261  {
262  return TimePaths::caseName();
263  }
264 
265  //- Return path
266  fileName path() const
267  {
268  return rootPath()/caseName();
269  }
271  const dictionary& controlDict() const
272  {
273  return controlDict_;
274  }
276  virtual const fileName& dbDir() const
277  {
278  return fileName::null;
279  }
280 
281  //- Return current time path
282  fileName timePath() const
283  {
284  return path()/timeName();
285  }
286 
287  //- Default write format
289  {
290  return writeFormat_;
291  }
292 
293  //- Default write version number
295  {
296  return writeVersion_;
297  }
298 
299  //- Default write compression
301  {
302  return writeCompression_;
303  }
304 
305  //- Default graph format
306  const word& graphFormat() const
307  {
308  return graphFormat_;
309  }
310 
311  //- Supports re-reading
312  const Switch& runTimeModifiable() const
313  {
314  return runTimeModifiable_;
315  }
316 
317  //- Read control dictionary, update controls and time
318  virtual bool read();
319 
320  //- Read the objects that have been modified
321  void readModifiedObjects();
322 
323  //- Return the location of "dir" containing the file "name".
324  // (eg, used in reading mesh data)
325  // If name is null, search for the directory "dir" only.
326  // Does not search beyond stopInstance (if set) or constant.
328  (
329  const fileName& dir,
330  const word& name = word::null,
332  const word& stopInstance = word::null
333  ) const;
334 
335  //- Search the case for valid time directories
336  instantList times() const;
337 
338  //- Search the case for the time directory path
339  // corresponding to the given instance
340  word findInstancePath(const fileName& path, const instant&) const;
341 
342  //- Search the case for the time directory path
343  // corresponding to the given instance
344  word findInstancePath(const instant&) const;
345 
346  //- Search the case for the time closest to the given time
347  instant findClosestTime(const scalar) const;
348 
349  //- Search instantList for the time index closest to the given time
351  (
352  const instantList&,
353  const scalar,
354  const word& constantName = "constant"
355  );
356 
357  //- Write time dictionary to the <time>/uniform directory
358  virtual bool writeTimeDict() const;
359 
360  //- Write using given format, version and compression
361  virtual bool writeObject
362  (
366  const bool write
367  ) const;
368 
369  //- Write the objects now (not at end of iteration) and continue
370  // the run
371  bool writeNow();
372 
373  //- Write the objects now (not at end of iteration) and end the run
374  bool writeAndEnd();
375 
376  //- Write the objects once (one shot) and continue the run
377  void writeOnce();
378 
379 
380  // Access
381 
382  //- Return time name of given scalar time
383  // formatted with given precision
384  static word timeName
385  (
386  const scalar,
387  const int precision = precision_
388  );
389 
390  //- Return current time name
391  virtual word timeName() const;
392 
393  //- Search a given directory for valid time directories
394  static instantList findTimes
395  (
396  const fileName&,
397  const word& constantName = "constant"
398  );
399 
400  //- Return start time index
401  virtual label startTimeIndex() const;
402 
403  //- Return start time
404  virtual dimensionedScalar startTime() const;
405 
406  //- Return end time
407  virtual dimensionedScalar endTime() const;
408 
409  //- Return the list of function objects
410  const functionObjectList& functionObjects() const
411  {
412  return functionObjects_;
413  }
414 
415  //- Return true if time currently being sub-cycled, otherwise false
416  bool subCycling() const
417  {
418  return subCycling_;
419  }
420 
421  //- Return previous TimeState if time is being sub-cycled
422  const TimeState& prevTimeState() const
423  {
424  return prevTimeState_();
425  }
426 
427 
428  // Check
429 
430  //- Return true if run should continue without any side effects
431  virtual bool running() const;
432 
433  //- Return true if run should continue,
434  // also invokes the functionObjectList::end() method
435  // when the time goes out of range
436  // \note
437  // For correct behaviour, the following style of time-loop
438  // is recommended:
439  // \code
440  // while (runTime.run())
441  // {
442  // runTime++;
443  // solve;
444  // runTime.write();
445  // }
446  // \endcode
447  virtual bool run() const;
448 
449  //- Return true if run should continue and if so increment time
450  // also invokes the functionObjectList::end() method
451  // when the time goes out of range
452  // \note
453  // For correct behaviour, the following style of time-loop
454  // is recommended:
455  // \code
456  // while (runTime.loop())
457  // {
458  // solve;
459  // runTime.write();
460  // }
461  // \endcode
462  virtual bool loop();
463 
464  //- Return true if end of run,
465  // does not invoke any functionObject methods
466  // \note
467  // The rounding heuristics near endTime mean that
468  // \code run() \endcode and \code !end() \endcode may
469  // not yield the same result
470  virtual bool end() const;
471 
472 
473  // Edit
474 
475  //- Adjust the current stopAtControl. Note that this value
476  // only persists until the next time the dictionary is read.
477  // Return true if the stopAtControl changed.
478  virtual bool stopAt(const stopAtControl) const;
479 
480  //- Reset the time and time-index to those of the given time
481  virtual void setTime(const Time&);
482 
483  //- Reset the time and time-index
484  virtual void setTime(const instant&, const label newIndex);
485 
486  //- Reset the time and time-index
487  virtual void setTime
488  (
489  const dimensionedScalar&,
490  const label newIndex
491  );
492 
493  //- Reset the time and time-index
494  virtual void setTime(const scalar, const label newIndex);
495 
496  //- Reset end time
497  virtual void setEndTime(const dimensionedScalar&);
498 
499  //- Reset end time
500  virtual void setEndTime(const scalar);
501 
502  //- Reset time step
503  virtual void setDeltaT(const dimensionedScalar&);
504 
505  //- Reset time step
506  virtual void setDeltaT(const scalar);
507 
508  //- Reset time step without additional adjustment or modification
509  // by function objects
510  virtual void setDeltaTNoAdjust(const scalar);
511 
512  //- Set time to sub-cycle for the given number of steps
513  virtual TimeState subCycle(const label nSubCycles);
514 
515  //- Reset time after sub-cycling back to previous TimeState
516  virtual void endSubCycle();
517 
518  //- Return non-const access to the list of function objects
520  {
521  return functionObjects_;
522  }
523 
524 
525  // Member Operators
526 
527  //- Set deltaT to that specified and increment time via operator++()
528  virtual Time& operator+=(const dimensionedScalar&);
529 
530  //- Set deltaT to that specified and increment time via operator++()
531  virtual Time& operator+=(const scalar);
532 
533  //- Prefix increment,
534  // also invokes the functionObjectList::start() or
535  // functionObjectList::execute() method, depending on the time-index
536  virtual Time& operator++();
537 
538  //- Postfix increment, this is identical to the prefix increment
539  virtual Time& operator++(int);
540 };
541 
542 
543 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
544 
545 } // End namespace Foam
546 
547 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
548 
549 #endif
550 
551 // ************************************************************************* //
A FIFO stack based on a singly-linked list.
Definition: FIFOStack.H:51
virtual Time & operator++()
Prefix increment,.
Definition: Time.C:1008
dictionary dict
unwatchedIOdictionary is like IOdictionary but stores dependencies as files instead of fileMonitor wa...
fileName path() const
Return path.
Definition: Time.H:265
A class for addressing time paths without using the Time class.
Definition: TimePaths.H:49
intWM_LABEL_SIZE_t label
A label is an int32_t or int64_t as specified by the pre-processor macro WM_LABEL_SIZE.
Definition: label.H:59
A class for handling file names.
Definition: fileName.H:79
bool writeAndEnd()
Write the objects now (not at end of iteration) and end the run.
Definition: TimeIO.C:600
sigStopAtWriteNow sigStopAtWriteNow_
Enable write and clean exit upon signal.
Definition: Time.H:146
The time value with time-stepping information, user-defined remapping, etc.
Definition: TimeState.H:48
writeControl writeControl_
Definition: Time.H:123
void adjustDeltaT()
Adjust the time step so that writing occurs at the specified time.
Definition: Time.C:84
A list of keyword definitions, which are a keyword followed by any number of values (e...
Definition: dictionary.H:158
virtual ~Time()
Destructor.
Definition: Time.C:608
fileName timePath() const
Return current time path.
Definition: Time.H:281
scalar writeInterval_
Definition: Time.H:125
Read access to the system clock with formatting.
Definition: clock.H:50
static const fileName null
An empty fileName.
Definition: fileName.H:97
virtual bool loop()
Return true if run should continue and if so increment time.
Definition: Time.C:842
virtual dimensionedScalar startTime() const
Return start time.
Definition: Time.C:777
bool subCycling() const
Return true if time currently being sub-cycled, otherwise false.
Definition: Time.H:415
word findInstance(const fileName &dir, const word &name=word::null, const IOobject::readOption rOpt=IOobject::MUST_READ, const word &stopInstance=word::null) const
Return the location of "dir" containing the file "name".
Definition: Time.C:645
A simple wrapper around bool so that it can be read as a word: true/false, on/off, yes/no, y/n, t/f, or none/any.
Definition: Switch.H:60
virtual dimensionedScalar endTime() const
Return end time.
Definition: Time.C:783
stopAtControl
Stop-run control options.
Definition: Time.H:94
scalar startTime_
Definition: Time.H:116
IOstream & fixed(IOstream &io)
Definition: IOstream.H:576
const TimeState & prevTimeState() const
Return previous TimeState if time is being sub-cycled.
Definition: Time.H:421
readOption
Enumeration defining the read options.
Definition: IOobject.H:110
virtual word timeName() const
Return current time name.
Definition: Time.C:632
Class to control time during OpenFOAM simulations that is also the top-level objectRegistry.
Definition: Time.H:68
virtual bool run() const
Return true if run should continue,.
Definition: Time.C:795
static const int maxPrecision_
Maximum time directory name precision.
Definition: Time.H:156
virtual bool writeTimeDict() const
Write time dictionary to the <time>/uniform directory.
Definition: TimeIO.C:506
IOstream::versionNumber writeVersion() const
Default write version number.
Definition: Time.H:293
label purgeWrite_
Definition: Time.H:127
virtual TimeState subCycle(const label nSubCycles)
Set time to sub-cycle for the given number of steps.
Definition: Time.C:968
virtual bool stopAt(const stopAtControl) const
Adjust the current stopAtControl. Note that this value.
Definition: Time.C:861
const Switch & runTimeModifiable() const
Supports re-reading.
Definition: Time.H:311
virtual bool writeObject(IOstream::streamFormat, IOstream::versionNumber, IOstream::compressionType, const bool write) const
Write using given format, version and compression.
Definition: TimeIO.C:541
static int precision_
Time directory name precision.
Definition: Time.H:153
TypeName("time")
A class for handling words, derived from string.
Definition: word.H:59
virtual bool running() const
Return true if run should continue without any side effects.
Definition: Time.C:789
Extract command arguments and options from the supplied argc and argv parameters. ...
Definition: argList.H:102
const fileName & caseName() const
Return case name.
Definition: Time.H:259
const fileName & caseName() const
Return case name.
Definition: TimePaths.H:108
const fileName & rootPath() const
Return root path.
Definition: TimePaths.H:96
bool subCycling_
Is the time currently being sub-cycled?
Definition: Time.H:134
streamFormat
Enumeration for the format of data in the stream.
Definition: IOstream.H:86
static const word null
An empty word.
Definition: word.H:77
IOstream::compressionType writeCompression() const
Default write compression.
Definition: Time.H:299
scalar endTime_
Definition: Time.H:117
virtual void setTime(const Time &)
Reset the time and time-index to those of the given time.
Definition: Time.C:879
format
Supported time directory name formats.
Definition: Time.H:103
List of function objects with start(), execute() and end() functions that is called for each object...
Signal handler for interrupt defined by OptimisationSwitches::writeNowSignal.
Definition: sigWriteNow.H:52
Time(const word &name, const argList &args, const word &systemName="system", const word &constantName="constant")
Construct given name of dictionary to read and argument list.
Definition: Time.C:390
static word controlDictName
The default control dictionary name (normally "controlDict")
Definition: Time.H:197
compressionType
Enumeration for the format of data in the stream.
Definition: IOstream.H:193
static format format_
Time directory name format.
Definition: Time.H:150
FIFOStack< word > previousWriteTimes_
Definition: Time.H:128
virtual void setDeltaTNoAdjust(const scalar)
Reset time step without additional adjustment or modification.
Definition: Time.C:961
IOstream::streamFormat writeFormat() const
Default write format.
Definition: Time.H:287
virtual void readDict()
Read the control dictionary and set the write controls etc.
Definition: TimeIO.C:35
static const NamedEnum< stopAtControl, 4 > stopAtControlNames_
Definition: Time.H:119
const word & name() const
Return const reference to name.
void readModifiedObjects()
Read the objects that have been modified.
Definition: TimeIO.C:459
static instantList findTimes(const fileName &, const word &constantName="constant")
Search a given directory for valid time directories.
Definition: findTimes.C:36
virtual void setEndTime(const dimensionedScalar &)
Reset end time.
Definition: Time.C:930
void writeOnce()
Write the objects once (one shot) and continue the run.
Definition: TimeIO.C:609
static const NamedEnum< writeControl, 5 > writeControlNames_
Definition: Time.H:122
An instant of time. Contains the time value and name.
Definition: instant.H:66
virtual bool end() const
Return true if end of run,.
Definition: Time.C:855
virtual bool read()
Read control dictionary, update controls and time.
Definition: TimeIO.C:434
const functionObjectList & functionObjects() const
Return the list of function objects.
Definition: Time.H:409
const word & graphFormat() const
Default graph format.
Definition: Time.H:305
bool writeOnce_
Definition: Time.H:131
sigWriteNow sigWriteNow_
Enable one-shot writing upon signal.
Definition: Time.H:143
instantList times() const
Search the case for valid time directories.
Definition: Time.C:638
const dictionary & controlDict() const
Definition: Time.H:270
Version number type.
Definition: IOstream.H:96
instant findClosestTime(const scalar) const
Search the case for the time closest to the given time.
Definition: Time.C:709
label startTimeIndex_
Definition: Time.H:115
virtual void setDeltaT(const dimensionedScalar &)
Reset time step.
Definition: Time.C:942
writeControl
Write control options.
Definition: Time.H:84
stopAtControl stopAt_
Definition: Time.H:120
virtual void endSubCycle()
Reset time after sub-cycling back to previous TimeState.
Definition: Time.C:982
Signal handler for interrupt defined by OptimisationSwitches::stopAtWriteNowSignal.
An auto-pointer similar to the STL auto_ptr but with automatic casting to a reference to the type and...
Definition: PtrList.H:52
Starts timing CPU usage and return elapsed time from start.
Definition: cpuTime.H:52
virtual bool write(const bool write=true) const
Write using setting from DB.
Registry of regIOobjects.
Foam::argList args(argc, argv)
word findInstancePath(const fileName &path, const instant &) const
Search the case for the time directory path.
Definition: Time.C:675
virtual label startTimeIndex() const
Return start time index.
Definition: Time.C:771
virtual const fileName & dbDir() const
Local directory path of this objectRegistry relative to the time.
Definition: Time.H:275
virtual Time & operator+=(const dimensionedScalar &)
Set deltaT to that specified and increment time via operator++()
Definition: Time.C:995
autoPtr< TimeState > prevTimeState_
If time is being sub-cycled this is the previous TimeState.
Definition: Time.H:137
bool writeNow()
Write the objects now (not at end of iteration) and continue.
Definition: TimeIO.C:593
void setControls()
Set the controls from the current controlDict.
Definition: Time.C:109
IOstream & scientific(IOstream &io)
Definition: IOstream.H:582
Namespace for OpenFOAM.
static label findClosestTimeIndex(const instantList &, const scalar, const word &constantName="constant")
Search instantList for the time index closest to the given time.
Definition: Time.C:746
const fileName & rootPath() const
Return root path.
Definition: Time.H:253