functionObject.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 | www.openfoam.com
6  \\/ M anipulation |
7 -------------------------------------------------------------------------------
8  Copyright (C) 2011-2016 OpenFOAM Foundation
9  Copyright (C) 2017-2020 OpenCFD Ltd.
10 -------------------------------------------------------------------------------
11 License
12  This file is part of OpenFOAM.
13 
14  OpenFOAM is free software: you can redistribute it and/or modify it
15  under the terms of the GNU General Public License as published by
16  the Free Software Foundation, either version 3 of the License, or
17  (at your option) any later version.
18 
19  OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
20  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
21  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
22  for more details.
23 
24  You should have received a copy of the GNU General Public License
25  along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
26 
27 Namespace
28  Foam::functionObjects
29 
30 Description
31  Function objects are OpenFOAM utilities to ease workflow configurations and
32  enhance workflows by producing additional user-requested data both during
33  runtime and postprocessing calculations, typically in the form of
34  additional logging to the screen, or generating text, image and field files.
35 
36  Function objects eliminate the need to store all runtime generated data,
37  hence saving considerable resources. Furthermore, function objects are
38  readily applied to batch-driven processes, improving reliability by
39  standardising the sequence of operations and reducing the amount of manual
40  interaction.
41 
42  In addition, the output of most function objects, e.g. output fields, are
43  stored on the mesh database so that it can be retrieved and used for other
44  applications (e.g. directly using \c wallShearStress function object output
45  in \c fieldAverage function object to produce \c wallShearStressMean field).
46 
47  \section secFunctionObjects Using function objects
48 
49  Function objects can be executed by using two methods:
50 
51  - \c functions sub-dictionary in the \c system/controlDict file
52  - \c postProcess command-line utility
53 
54  For the first method, each selected function object should be listed inside
55  \c functions sub-dictionary of the \c system/controlDict file as a nested
56  sub-dictionary, typically as in the following example:
57 
58  \verbatim
59  functions // sub-dictionary name under the system/controlDict file
60  {
61  <userDefinedSubDictName1>
62  {
63  // Mandatory entries
64  type <functionObjectTypeName>;
65  libs (<libType>FunctionObjects);
66 
67  // Mandatory entries defined in <functionObjectType>
68  ...
69 
70  // Optional entries defined in <functionObjectType>
71  ...
72 
73  // Optional (inherited) entries
74  region region0;
75  enabled true;
76  log true;
77  timeStart 0;
78  timeEnd 1000;
79  executeControl timeStep;
80  executeInterval 1;
81  writeControl timeStep;
82  writeInterval 1;
83  }
84 
85  <userDefinedSubDictName2>
86  {
87  ...
88  }
89 
90  ...
91 
92  <userDefinedSubDictNameN>
93  {
94  ...
95  }
96  }
97  \endverbatim
98 
99  where the entries mean:
100  \table
101  Property | Description | Type | Req'd | Dflt
102  type | Type name of function object | word | yes | -
103  libs | Library name containing implementation | word | yes | -
104  region | Name of region for multi-region cases | word | no | region0
105  enabled | Switch to turn function object on/off | bool | no | true
106  log | Switch to write log info to standard output | bool | no | true
107  timeStart | Start time for function object execution | scalar | no | 0
108  timeEnd | End time for function object execution | scalar | no | inf
109  executeControl | See time controls below | word | no | timeStep
110  executeInterval | Steps/time between execute phases | label | no | 1
111  writeControl | See time controls below | word | no | timeStep
112  writeInterval | Steps/time between write phases | label | no | 1
113  \endtable
114 
115  Time controls:
116  \table
117  Option | Description
118  none | Trigger is disabled
119  timeStep | Trigger every 'Interval' time-steps
120  writeTime | Trigger every 'Interval' output times
121  runTime | Trigger every 'Interval' run time period
122  adjustableRunTime | Currently identical to "runTime"
123  clockTime | Trigger every 'Interval' clock time period
124  cpuTime | Trigger every 'Interval' CPU time period
125  onEnd | Trigger on end of simulation run
126  \endtable
127 
128  The sub-dictionary name \c <userDefinedSubDictName> is chosen by the user,
129  and is typically used as the name of the output directory for any data
130  written by the function object.
131 
132  As the base mandatory entries, the \c type entry defines the type of
133  function object properties that follow. Function objects are packaged into
134  separate libraries for flexibility and the \c libs entry is used to specify
135  which library should be loaded.
136 
137  Each function object has two separate run phases:
138 
139  - The \c execute phase is meant to be used for updating calculations
140  or for management tasks.
141  - The \c write phase is meant for writing the calculated data to disk.
142 
143  For each phase the respective time controls are provided, as listed above.
144 
145 
146  The second method of executing function objects is to use \c postProcess
147  utility.
148 
149  When specified without additional arguments, the \c postProcess utility
150  executes all function objects defined in the \c system/controlDict file
151  for all time directories:
152 
153  \verbatim
154  postProcess
155  \endverbatim
156 
157  Most function objects can be invoked directly without the need to specify
158  the input dictionary using the \c -func option, e.g. to execute the Courant
159  number function object:
160 
161  \verbatim
162  postProcess -func CourantNo
163  \endverbatim
164 
165  In addition, the \c -postProcess option is available to all solvers,
166  and operates similarly to the stand-alone \c postProcess utility.
167  For example, having completed a \c simpleFoam calculation, the following
168  will execute all function objects defined in the \c system/controlDict file
169  for all time directories:
170 
171  \verbatim
172  simpleFoam -postProcess
173  \endverbatim
174 
175 Class
176  Foam::functionObject
177 
178 Description
179  Abstract base-class for Time/database function objects.
180 
181 See also
182  - Foam::functionObjectList
183  - Foam::functionObjects::timeControl
184 
185 SourceFiles
186  functionObject.C
187 
188 \*---------------------------------------------------------------------------*/
189 
190 #ifndef functionObject_H
191 #define functionObject_H
192 
193 #include "typeInfo.H"
194 #include "autoPtr.H"
195 #include "runTimeSelectionTables.H"
196 
197 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
198 
199 namespace Foam
200 {
201 
202 // Forward declarations
203 class Time;
204 class polyMesh;
205 class mapPolyMesh;
206 
207 /*---------------------------------------------------------------------------*\
208  Class functionObject Declaration
209 \*---------------------------------------------------------------------------*/
210 
211 class functionObject
212 {
213  // Private Data
214 
215  //- Name
216  const word name_;
217 
218 
219 protected:
220 
221  // Protected Member Functions
222 
223  //- Return a scoped name, e.g. used to construct local field names
224  word scopedName(const word& name) const;
225 
226 
227 public:
228 
229  // Forward declarations
230  class unavailableFunctionObject;
231 
232  //- Runtime type information
233  virtual const word& type() const = 0;
234 
235  //- Flag to execute debug content
236  static int debug;
237 
238  //- Global post-processing mode switch
239  static bool postProcess;
240 
241  //- Directory prefix
242  static word outputPrefix;
243 
244  //- Flag to write log into Info
245  bool log;
246 
247 
248  // Declare run-time constructor selection tables
249 
251  (
252  autoPtr,
254  dictionary,
255  (const word& name, const Time& runTime, const dictionary& dict),
256  (name, runTime, dict)
257  );
258 
259 
260  // Constructors
261 
262  //- Construct from components
263  functionObject(const word& name);
264 
265  //- Return clone
266  autoPtr<functionObject> clone() const
267  {
269  return nullptr;
270  }
271 
272 
273  // Selectors
274 
275  //- Select from dictionary, based on its "type" entry
276  static autoPtr<functionObject> New
277  (
278  const word& name,
279  const Time& runTime,
280  const dictionary& dict
281  );
282 
283 
284  //- Destructor
285  virtual ~functionObject() = default;
286 
287 
288  // Member Functions
289 
290  //- Return the name of this functionObject
291  const word& name() const;
292 
293  //- Read and set the function object if its data have changed
294  virtual bool read(const dictionary& dict);
295 
296  //- Called at each ++ or += of the time-loop.
297  // postProcess overrides the usual executeControl behaviour and
298  // forces execution (used in post-processing mode)
299  virtual bool execute() = 0;
300 
301  //- Execute using the specified subIndex.
302  // The base implementation is a no-op.
303  // \param subIndex an execution sub-index corresponding to a
304  // sub-cycle or something similar.
305  virtual bool execute(const label subIndex);
306 
307  //- Called at each ++ or += of the time-loop.
308  // postProcess overrides the usual writeControl behaviour and
309  // forces writing always (used in post-processing mode)
310  virtual bool write() = 0;
311 
312  //- Called when Time::run() determines that the time-loop exits.
313  // The base implementation is a no-op.
314  virtual bool end();
315 
316  //- Called at the end of Time::adjustDeltaT() if adjustTime is true
317  virtual bool adjustTimeStep();
318 
319  //- Did any file get changed during execution?
320  virtual bool filesModified() const;
321 
322  //- Update for changes of mesh
323  // The base implementation is a no-op.
324  virtual void updateMesh(const mapPolyMesh& mpm);
325 
326  //- Update for changes of mesh
327  // The base implementation is a no-op.
328  virtual void movePoints(const polyMesh& mesh);
329 };
330 
331 
332 /*---------------------------------------------------------------------------*\
333  Class functionObject::unavailableFunctionObject Declaration
334 \*---------------------------------------------------------------------------*/
335 
336 //- Abstract functionObject to report when a real version is unavailable.
338 :
339  public functionObject
340 {
341 protected:
342 
343  //- Construct with name
345 
346  //- Report it is unavailable, emitting a FatalError for try/catch
347  //- in the caller
348  void carp(std::string message = "") const;
349 
350 
351 public:
352 
353  // Member Functions
354 
355  //- No nothing
356  virtual bool execute();
357 
358  //- No nothing
359  virtual bool write();
360 };
361 
362 
363 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
364 
365 } // End namespace Foam
366 
367 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
368 
369 #endif
370 
371 // ************************************************************************* //
Foam::functionObject::unavailableFunctionObject::execute
virtual bool execute()
No nothing.
Definition: functionObject.C:212
runTime
engineTime & runTime
Definition: createEngineTime.H:13
Foam::functionObject::execute
virtual bool execute()=0
Called at each ++ or += of the time-loop.
Foam::Time
Class to control time during OpenFOAM simulations that is also the top-level objectRegistry.
Definition: Time.H:73
Foam::functionObject::write
virtual bool write()=0
Called at each ++ or += of the time-loop.
Foam::word
A class for handling words, derived from Foam::string.
Definition: word.H:62
typeInfo.H
Foam::functionObject::New
static autoPtr< functionObject > New(const word &name, const Time &runTime, const dictionary &dict)
Select from dictionary, based on its "type" entry.
Definition: functionObject.C:67
Foam::polyMesh
Mesh consisting of general polyhedral cells.
Definition: polyMesh.H:77
Foam::functionObject
Abstract base-class for Time/database function objects.
Definition: functionObject.H:309
Foam::functionObject::unavailableFunctionObject::unavailableFunctionObject
unavailableFunctionObject(const word &name)
Construct with name.
Definition: functionObject.C:183
Foam::functionObject::declareRunTimeSelectionTable
declareRunTimeSelectionTable(autoPtr, functionObject, dictionary,(const word &name, const Time &runTime, const dictionary &dict),(name, runTime, dict))
Foam::functionObject::unavailableFunctionObject::write
virtual bool write()
No nothing.
Definition: functionObject.C:218
NotImplemented
#define NotImplemented
Issue a FatalErrorIn for a function not currently implemented.
Definition: error.H:436
Foam::functionObject::~functionObject
virtual ~functionObject()=default
Destructor.
Foam::functionObject::postProcess
static bool postProcess
Global post-processing mode switch.
Definition: functionObject.H:337
Foam::functionObject::read
virtual bool read(const dictionary &dict)
Read and set the function object if its data have changed.
Definition: functionObject.C:137
Foam::functionObject::outputPrefix
static word outputPrefix
Directory prefix.
Definition: functionObject.H:340
Foam::functionObject::clone
autoPtr< functionObject > clone() const
Return clone.
Definition: functionObject.H:364
dict
dictionary dict
Definition: searchingEngine.H:14
Foam::dictionary
A list of keyword definitions, which are a keyword followed by a number of values (eg,...
Definition: dictionary.H:121
Foam::functionObject::adjustTimeStep
virtual bool adjustTimeStep()
Called at the end of Time::adjustDeltaT() if adjustTime is true.
Definition: functionObject.C:160
mesh
dynamicFvMesh & mesh
Definition: createDynamicFvMesh.H:6
Foam
Namespace for OpenFOAM.
Definition: atmBoundaryLayer.C:33
Foam::functionObject::movePoints
virtual void movePoints(const polyMesh &mesh)
Update for changes of mesh.
Definition: functionObject.C:176
Foam::functionObject::unavailableFunctionObject::carp
void carp(std::string message="") const
Definition: functionObject.C:192
Foam::functionObject::end
virtual bool end()
Called when Time::run() determines that the time-loop exits.
Definition: functionObject.C:154
Foam::functionObject::scopedName
word scopedName(const word &name) const
Return a scoped name, e.g. used to construct local field names.
Definition: functionObject.C:49
Foam::autoPtr
Pointer management similar to std::unique_ptr, with some additional methods and type checking.
Definition: HashPtrTable.H:53
Foam::functionObject::updateMesh
virtual void updateMesh(const mapPolyMesh &mpm)
Update for changes of mesh.
Definition: functionObject.C:172
Foam::functionObject::unavailableFunctionObject
Abstract functionObject to report when a real version is unavailable.
Definition: functionObject.H:435
Foam::functionObject::debug
static int debug
Flag to execute debug content.
Definition: functionObject.H:334
Foam::functionObject::name
const word & name() const
Return the name of this functionObject.
Definition: functionObject.C:131
runTimeSelectionTables.H
Macros to ease declaration of run-time selection tables.
Foam::functionObject::type
virtual const word & type() const =0
Runtime type information.
Foam::functionObject::filesModified
virtual bool filesModified() const
Did any file get changed during execution?
Definition: functionObject.C:166
Foam::mapPolyMesh
Class containing mesh-to-mesh mapping information after a change in polyMesh topology.
Definition: mapPolyMesh.H:160
Foam::functionObject::log
bool log
Flag to write log into Info.
Definition: functionObject.H:343
Foam::functionObject::functionObject
functionObject(const word &name)
Construct from components.
Definition: functionObject.C:57
autoPtr.H