Time.H
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------*\
2  ========= |
3  \\ / F ield | OpenFOAM: The Open Source CFD Toolbox
4  \\ / O peration |
5  \\ / A nd | Copyright (C) 2011-2015 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 "IOdictionary.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 "fileMonitor.H"
55 #include "sigWriteNow.H"
56 #include "sigStopAtWriteNow.H"
57 
58 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
59 
60 namespace Foam
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  //- file-change monitor for all registered files
80  mutable autoPtr<fileMonitor> monitorPtr_;
81 
82  //- Any loaded dynamic libraries. Make sure to construct before
83  // reading controlDict.
84  dlLibraryTable libs_;
85 
86  //- The controlDict
87  IOdictionary controlDict_;
88 
89 public:
90 
91  //- Write control options
92  enum writeControls
93  {
98  wcCpuTime
99  };
100 
101  //- Stop-run control options
102  enum stopAtControls
103  {
107  saNextWrite
108  };
109 
110  //- Supported time directory name formats
111  enum fmtflags
112  {
113  general = 0,
116  };
117 
118 
119 protected:
120 
121  // Protected data
124  scalar startTime_;
125  mutable scalar endTime_;
128  mutable stopAtControls stopAt_;
133  scalar writeInterval_;
134 
135  // Additional writing
143 
144  // Additional purging
148 
149 
150  // One-shot writing
151  bool writeOnce_;
152 
153  //- Is the time currently being sub-cycled?
154  bool subCycling_;
155 
156  //- If time is being sub-cycled this is the previous TimeState
158 
159 
160  // Signal handlers for secondary writing
161 
162  //- Enable one-shot writing upon signal
164 
165  //- Enable write and clean exit upon signal
167 
168 
169  //- Time directory name format
170  static fmtflags format_;
171 
172  //- Time directory name precision
173  static int precision_;
174 
175  //- Maximum time directory name precision
176  static const int maxPrecision_;
177 
178  //- Adjust the time step so that writing occurs at the specified time
179  void adjustDeltaT();
180 
181  //- Set the controls from the current controlDict
182  void setControls();
183 
184  //- Read the control dictionary and set the write controls etc.
185  virtual void readDict();
186 
187 
188 private:
189 
190  //- Default write option
191  IOstream::streamFormat writeFormat_;
192 
193  //- Default output file format version number
194  IOstream::versionNumber writeVersion_;
195 
196  //- Default output compression
197  IOstream::compressionType writeCompression_;
198 
199  //- Default graph format
200  word graphFormat_;
201 
202  //- Is runtime modification of dictionaries allowed?
203  Switch runTimeModifiable_;
204 
205  //- Function objects executed at start and on ++, +=
206  mutable functionObjectList functionObjects_;
207 
208 
209 public:
210 
211  TypeName("time");
212 
213  //- The default control dictionary name (normally "controlDict")
214  static word controlDictName;
215 
216 
217  // Constructors
218 
219  //- Construct given name of dictionary to read and argument list
220  Time
221  (
222  const word& name,
223  const argList& args,
224  const word& systemName = "system",
225  const word& constantName = "constant"
226  );
227 
228  //- Construct given name of dictionary to read, rootPath and casePath
229  Time
230  (
231  const word& name,
232  const fileName& rootPath,
233  const fileName& caseName,
234  const word& systemName = "system",
235  const word& constantName = "constant",
236  const bool enableFunctionObjects = true
237  );
238 
239  //- Construct given dictionary, rootPath and casePath
240  Time
241  (
242  const dictionary& dict,
243  const fileName& rootPath,
244  const fileName& caseName,
245  const word& systemName = "system",
246  const word& constantName = "constant",
247  const bool enableFunctionObjects = true
248  );
249 
250  //- Construct given endTime, rootPath and casePath
251  Time
252  (
253  const fileName& rootPath,
254  const fileName& caseName,
255  const word& systemName = "system",
256  const word& constantName = "constant",
257  const bool enableFunctionObjects = true
258  );
259 
260 
261  //- Destructor
262  virtual ~Time();
263 
264 
265  // Member functions
266 
267  // Database functions
268 
269  //- Return root path
270  const fileName& rootPath() const
271  {
272  return TimePaths::rootPath();
273  }
274 
275  //- Return case name
276  const fileName& caseName() const
277  {
278  return TimePaths::caseName();
279  }
280 
281  //- Return path
282  fileName path() const
283  {
284  return rootPath()/caseName();
285  }
287  const dictionary& controlDict() const
288  {
289  return controlDict_;
290  }
292  virtual const fileName& dbDir() const
293  {
294  return fileName::null;
295  }
296 
297  //- Return current time path
298  fileName timePath() const
299  {
300  return path()/timeName();
301  }
302 
303  //- Default write format
305  {
306  return writeFormat_;
307  }
308 
309  //- Default write version number
311  {
312  return writeVersion_;
313  }
314 
315  //- Default write compression
317  {
318  return writeCompression_;
319  }
320 
321  //- Default graph format
322  const word& graphFormat() const
323  {
324  return graphFormat_;
325  }
326 
327  //- Supports re-reading
328  const Switch& runTimeModifiable() const
329  {
330  return runTimeModifiable_;
331  }
332 
333  //- Read control dictionary, update controls and time
334  virtual bool read();
335 
336  // Automatic rereading
337 
338  //- Read the objects that have been modified
339  void readModifiedObjects();
340 
341  //- Add watching of a file. Returns handle
342  label addWatch(const fileName&) const;
343 
344  //- Remove watch on a file (using handle)
345  bool removeWatch(const label) const;
346 
347  //- Get name of file being watched (using handle)
348  const fileName& getFile(const label) const;
349 
350  //- Get current state of file (using handle)
352 
353  //- Set current state of file (using handle) to unmodified
354  void setUnmodified(const label) const;
355 
356 
357  //- Return the location of "dir" containing the file "name".
358  // (eg, used in reading mesh data)
359  // If name is null, search for the directory "dir" only.
360  // Does not search beyond stopInstance (if set) or constant.
362  (
363  const fileName& dir,
364  const word& name = word::null,
366  const word& stopInstance = word::null
367  ) const;
368 
369  //- Search the case for valid time directories
370  instantList times() const;
371 
372  //- Search the case for the time directory path
373  // corresponding to the given instance
374  word findInstancePath(const instant&) const;
375 
376  //- Search the case for the time closest to the given time
377  instant findClosestTime(const scalar) const;
378 
379  //- Search instantList for the time index closest to the given time
381  (
382  const instantList&,
383  const scalar,
384  const word& constantName = "constant"
385  );
386 
387  //- Write using given format, version and compression
388  virtual bool writeObject
389  (
393  ) const;
394 
395  //- Write the objects now (not at end of iteration) and continue
396  // the run
397  bool writeNow();
398 
399  //- Write the objects now (not at end of iteration) and end the run
400  bool writeAndEnd();
401 
402  //- Write the objects once (one shot) and continue the run
403  void writeOnce();
404 
405 
406  // Access
407 
408  //- Return time name of given scalar time
409  // formatted with given precision
410  static word timeName
411  (
412  const scalar,
413  const int precision = precision_
414  );
415 
416  //- Return current time name
417  virtual word timeName() const;
418 
419  //- Search a given directory for valid time directories
420  static instantList findTimes
421  (
422  const fileName&,
423  const word& constantName = "constant"
424  );
425 
426  //- Return start time index
427  virtual label startTimeIndex() const;
428 
429  //- Return start time
430  virtual dimensionedScalar startTime() const;
431 
432  //- Return end time
433  virtual dimensionedScalar endTime() const;
434 
435  //- Return the list of function objects
436  const functionObjectList& functionObjects() const
437  {
438  return functionObjects_;
439  }
440 
441  //- External access to the loaded libraries
442  const dlLibraryTable& libs() const
443  {
444  return libs_;
445  }
446 
447  //- External access to the loaded libraries
449  {
450  return libs_;
451  }
452 
453  //- Return true if time currently being sub-cycled, otherwise false
454  bool subCycling() const
455  {
456  return subCycling_;
457  }
458 
459  //- Return previous TimeState if time is being sub-cycled
460  const TimeState& prevTimeState() const
461  {
462  return prevTimeState_();
463  }
464 
465 
466  // Check
467 
468  //- Return true if run should continue,
469  // also invokes the functionObjectList::end() method
470  // when the time goes out of range
471  // \note
472  // For correct behaviour, the following style of time-loop
473  // is recommended:
474  // \code
475  // while (runTime.run())
476  // {
477  // runTime++;
478  // solve;
479  // runTime.write();
480  // }
481  // \endcode
482  virtual bool run() const;
483 
484  //- Return true if run should continue and if so increment time
485  // also invokes the functionObjectList::end() method
486  // when the time goes out of range
487  // \note
488  // For correct behaviour, the following style of time-loop
489  // is recommended:
490  // \code
491  // while (runTime.loop())
492  // {
493  // solve;
494  // runTime.write();
495  // }
496  // \endcode
497  virtual bool loop();
498 
499  //- Return true if end of run,
500  // does not invoke any functionObject methods
501  // \note
502  // The rounding heuristics near endTime mean that
503  // \code run() \endcode and \code !end() \endcode may
504  // not yield the same result
505  virtual bool end() const;
506 
507 
508  // Edit
509 
510  //- Adjust the current stopAtControl. Note that this value
511  // only persists until the next time the dictionary is read.
512  // Return true if the stopAtControl changed.
513  virtual bool stopAt(const stopAtControls) const;
514 
515  //- Reset the time and time-index to those of the given time
516  virtual void setTime(const Time&);
517 
518  //- Reset the time and time-index
519  virtual void setTime(const instant&, const label newIndex);
520 
521  //- Reset the time and time-index
522  virtual void setTime
523  (
524  const dimensionedScalar&,
525  const label newIndex
526  );
527 
528  //- Reset the time and time-index
529  virtual void setTime(const scalar, const label newIndex);
530 
531  //- Reset end time
532  virtual void setEndTime(const dimensionedScalar&);
533 
534  //- Reset end time
535  virtual void setEndTime(const scalar);
536 
537  //- Reset time step
538  virtual void setDeltaT
539  (
540  const dimensionedScalar&,
541  const bool adjustDeltaT = true
542  );
543 
544  //- Reset time step
545  virtual void setDeltaT
546  (
547  const scalar,
548  const bool adjustDeltaT = true
549  );
550 
551  //- Set time to sub-cycle for the given number of steps
552  virtual TimeState subCycle(const label nSubCycles);
553 
554  //- Reset time after sub-cycling back to previous TimeState
555  virtual void endSubCycle();
556 
557  //- Return non-const access to the list of function objects
559  {
560  return functionObjects_;
561  }
562 
563 
564  // Member operators
565 
566  //- Set deltaT to that specified and increment time via operator++()
567  virtual Time& operator+=(const dimensionedScalar&);
568 
569  //- Set deltaT to that specified and increment time via operator++()
570  virtual Time& operator+=(const scalar);
571 
572  //- Prefix increment,
573  // also invokes the functionObjectList::start() or
574  // functionObjectList::execute() method, depending on the time-index
575  virtual Time& operator++();
576 
577  //- Postfix increment, this is identical to the prefix increment
578  virtual Time& operator++(int);
579 };
580 
581 
582 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
583 
584 } // End namespace Foam
585 
586 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
587 
588 #endif
589 
590 // ************************************************************************* //
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:433
void readModifiedObjects()
Read the objects that have been modified.
Definition: TimeIO.C:450
FIFOStack< word > previousOutputTimes_
Definition: Time.H:141
writeControls secondaryWriteControl_
Definition: Time.H:136
virtual TimeState subCycle(const label nSubCycles)
Set time to sub-cycle for the given number of steps.
Definition: Time.C:1043
virtual bool end() const
Return true if end of run,.
Definition: Time.C:937
instant findClosestTime(const scalar) const
Search the case for the time closest to the given time.
Definition: Time.C:794
fileName path() const
Return path.
Definition: Time.H:281
virtual const fileName & dbDir() const
Local directory path of this objectRegistry relative to the time.
Definition: Time.H:291
virtual bool read()
Read control dictionary, update controls and time.
Definition: TimeIO.C:436
general distribution model
static int precision_
Time directory name precision.
Definition: Time.H:172
static const NamedEnum< stopAtControls, 4 > stopAtControlNames_
Definition: Time.H:126
const Switch & runTimeModifiable() const
Supports re-reading.
Definition: Time.H:327
FIFOStack< word > previousSecondaryOutputTimes_
Definition: Time.H:146
bool subCycling() const
Return true if time currently being sub-cycled, otherwise false.
Definition: Time.H:453
static fmtflags format_
Time directory name format.
Definition: Time.H:169
static const int maxPrecision_
Maximum time directory name precision.
Definition: Time.H:175
stopAtControls
Stop-run control options.
Definition: Time.H:101
bool writeOnce_
Definition: Time.H:150
Signal handler for interupt defined by OptimisationSwitches::writeNowSignal.
Definition: sigWriteNow.H:52
A class for handling words, derived from string.
Definition: word.H:59
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
bool writeNow()
Write the objects now (not at end of iteration) and continue.
Definition: TimeIO.C:571
The time value with time-stepping information, user-defined remapping, etc.
Definition: TimeState.H:49
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.
Definition: Switch.H:60
virtual void readDict()
Read the control dictionary and set the write controls etc.
Definition: TimeIO.C:33
bool writeAndEnd()
Write the objects now (not at end of iteration) and end the run.
Definition: TimeIO.C:579
autoPtr< TimeState > prevTimeState_
If time is being sub-cycled this is the previous TimeState.
Definition: Time.H:156
scalar writeInterval_
Definition: Time.H:132
static const NamedEnum< writeControls, 5 > writeControlNames_
Definition: Time.H:129
A list of keyword definitions, which are a keyword followed by any number of values (e...
Definition: dictionary.H:137
virtual dimensionedScalar startTime() const
Return start time.
Definition: Time.C:872
scalar secondaryWriteInterval_
Definition: Time.H:138
void setUnmodified(const label) const
Set current state of file (using handle) to unmodified.
Definition: Time.C:735
Namespace for OpenFOAM.
fmtflags
Supported time directory name formats.
Definition: Time.H:110
virtual ~Time()
Destructor.
Definition: Time.C:695
fileState
Enumeration defining the file state.
Definition: fileMonitor.H:69
const word & graphFormat() const
Default graph format.
Definition: Time.H:321
virtual void setEndTime(const dimensionedScalar &)
Reset end time.
Definition: Time.C:1009
sigWriteNow sigWriteNow_
Enable one-shot writing upon signal.
Definition: Time.H:162
Starts timing CPU usage and return elapsed time from start.
Definition: cpuTime.H:52
dictionary dict
Class to control time during OpenFOAM simulations that is also the top-level objectRegistry.
Definition: Time.H:68
List of function objects with start(), execute() and end() functions that is called for each object...
label addWatch(const fileName &) const
Add watching of a file. Returns handle.
Definition: Time.C:709
const fileName & getFile(const label) const
Get name of file being watched (using handle)
Definition: Time.C:720
const dlLibraryTable & libs() const
External access to the loaded libraries.
Definition: Time.H:441
const fileName & caseName() const
Return case name.
Definition: TimePaths.H:108
streamFormat
Enumeration for the format of data in the stream.
Definition: IOstream.H:86
const word & name() const
Return const reference to name.
word findInstancePath(const instant &) const
Search the case for the time directory path.
Definition: Time.C:764
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:841
const functionObjectList & functionObjects() const
Return the list of function objects.
Definition: Time.H:435
A class for addressing time paths without using the Time class.
Definition: TimePaths.H:49
virtual bool run() const
Return true if run should continue,.
Definition: Time.C:884
readOption
Enumeration defining the read options.
Definition: IOobject.H:106
label purgeWrite_
Definition: Time.H:140
IOdictionary is derived from dictionary and IOobject to give the dictionary automatic IO functionalit...
Definition: IOdictionary.H:53
static word controlDictName
The default control dictionary name (normally "controlDict")
Definition: Time.H:213
static const fileName null
An empty fileName.
Definition: fileName.H:97
IOstream::versionNumber writeVersion() const
Default write version number.
Definition: Time.H:309
An instant of time. Contains the time value and name.
Definition: instant.H:64
Signal handler for interupt defined by OptimisationSwitches::stopAtWriteNowSignal.
virtual bool writeObject(IOstream::streamFormat, IOstream::versionNumber, IOstream::compressionType) const
Write using given format, version and compression.
Definition: TimeIO.C:487
IOstream::compressionType writeCompression() const
Default write compression.
Definition: Time.H:315
Extract command arguments and options from the supplied argc and argv parameters. ...
Definition: argList.H:102
scalar startTime_
Definition: Time.H:123
compressionType
Enumeration for the format of data in the stream.
Definition: IOstream.H:193
virtual label startTimeIndex() const
Return start time index.
Definition: Time.C:866
virtual Time & operator++()
Prefix increment,.
Definition: Time.C:1083
IOstream::streamFormat writeFormat() const
Default write format.
Definition: Time.H:303
Foam::argList args(argc, argv)
sigStopAtWriteNow sigStopAtWriteNow_
Enable write and clean exit upon signal.
Definition: Time.H:165
virtual dimensionedScalar endTime() const
Return end time.
Definition: Time.C:878
A FIFO stack based on a singly-linked list.
Definition: FIFOStack.H:51
fileName timePath() const
Return current time path.
Definition: Time.H:297
Registry of regIOobjects.
virtual Time & operator+=(const dimensionedScalar &)
Set deltaT to that specified and increment time via operator++()
Definition: Time.C:1070
Read access to the system clock with formatting.
Definition: clock.H:50
scalar endTime_
Definition: Time.H:124
A class for handling file names.
Definition: fileName.H:69
writeControls
Write control options.
Definition: Time.H:91
void writeOnce()
Write the objects once (one shot) and continue the run.
Definition: TimeIO.C:588
virtual bool loop()
Return true if run should continue and if so increment time.
Definition: Time.C:924
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: findInstance.C:38
fileMonitor::fileState getState(const label) const
Get current state of file (using handle)
Definition: Time.C:727
bool subCycling_
Is the time currently being sub-cycled?
Definition: Time.H:153
void setControls()
Set the controls from the current controlDict.
Definition: Time.C:140
IOstream & scientific(IOstream &io)
Definition: IOstream.H:582
writeControls writeControl_
Definition: Time.H:130
const fileName & rootPath() const
Return root path.
Definition: TimePaths.H:96
instantList times() const
Search the case for valid time directories.
Definition: Time.C:758
virtual void setDeltaT(const dimensionedScalar &, const bool adjustDeltaT=true)
Reset time step.
Definition: Time.C:1022
TypeName("time")
A table of dynamically loaded libraries.
void adjustDeltaT()
Adjust the time step so that writing occurs at the specified time.
Definition: Time.C:83
const fileName & caseName() const
Return case name.
Definition: Time.H:275
Version number type.
Definition: IOstream.H:96
virtual void setTime(const Time &)
Reset the time and time-index to those of the given time.
Definition: Time.C:961
stopAtControls stopAt_
Definition: Time.H:127
const dictionary & controlDict() const
Definition: Time.H:286
label secondaryPurgeWrite_
Definition: Time.H:145
An auto-pointer similar to the STL auto_ptr but with automatic casting to a reference to the type and...
Definition: PtrList.H:117
virtual bool stopAt(const stopAtControls) const
Adjust the current stopAtControl. Note that this value.
Definition: Time.C:943
label startTimeIndex_
Definition: Time.H:122
IOstream & fixed(IOstream &io)
Definition: IOstream.H:576
static instantList findTimes(const fileName &, const word &constantName="constant")
Search a given directory for valid time directories.
Definition: findTimes.C:38
virtual void endSubCycle()
Reset time after sub-cycling back to previous TimeState.
Definition: Time.C:1057
static const word null
An empty word.
Definition: word.H:77
const fileName & rootPath() const
Return root path.
Definition: Time.H:269
const TimeState & prevTimeState() const
Return previous TimeState if time is being sub-cycled.
Definition: Time.H:459
bool removeWatch(const label) const
Remove watch on a file (using handle)
Definition: Time.C:715
virtual word timeName() const
Return current time name.
Definition: Time.C:751