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