functionObject.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-2023 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 Namespace
25  Foam::functionObjects
26 
27 Description
28  Namespace for functionObjects.
29 
30  OpenFOAM includes a collection of functionObjects selected by the user at
31  run-time to manipulate the simulation and provide mechanisms to extract
32  field and derived quantities. Alternatively, the same actions can be
33  executed after the simulation using the \c -postProcess command-line option.
34 
35  \subsection secFunctionObjects Using functionObjects
36 
37  FunctionObjects are selected by additional entries in the
38  $FOAM_CASE/system/controlDict dictionary. Each object is listed in the \c
39  functions sub-dictionary, e.g. to select the \c functionObjectType
40  functionObject the following entry would be specified:
41 
42  \verbatim
43  functions
44  {
45  <functionObjectName>
46  {
47  type functionObjectType;
48  libs ("libMyFunctionObjectlib.so");
49  region defaultRegion;
50  enabled yes;
51  startTime 0;
52  endTime 10;
53  writeControl writeTime;
54  writeInterval 1;
55  ...
56  }
57  }
58  \endverbatim
59 
60  Where:
61  \table
62  Property | Description | Required | Default value
63  type | Type of functionObject | yes |
64  libs | Libraries containing implementation | yes |
65  region | Name of region for multi-region cases | no |
66  enabled | On/off switch | no | yes
67  log | Log information to standard output | no | no
68  startTime| Start time | no |
69  endTime | End time | no |
70  executeAtStart | Execute at start time switch | no | yes
71  executeControl | See time controls below | no | timeStep
72  executeInterval | Steps between each execution | no |
73  executeTimes | List of execution times | no |
74  writeControl | See time controls below | no | timeStep
75  writeInterval | Steps between each write | no |
76  writeTimes | List of write times | no |
77  \endtable
78 
79  Time controls:
80  \table
81  Option | Description
82  timeStep | Execute/write every 'Interval' time-steps
83  writeTime | Execute/write every 'Interval' write times
84  adjustableRunTime | Execute/write every 'Interval' run time period
85  runTime | Execute/write every 'Interval' run time period
86  runTimes | Execute/write at specified list of run times
87  clockTime | Execute/write every 'Interval' clock time period
88  cpuTime | Execute/write every 'Interval' CPU time period
89  none | No execution
90  \endtable
91 
92  The sub-dictionary name \c <functionObjectName> is chosen by the user, and
93  is typically used as the name of the output directory for any data written
94  by the functionObject. The \c type entry defines the type of function
95  object properties that follow. FunctionObjects are packaged into separate
96  libraries and the \c libs entry is used to specify which library should be
97  loaded.
98 
99  Each functionObject has two separate run phases:
100 
101  - The \c execute phase is meant to be used for updating calculations
102  or for management tasks.
103  - The \c write phase is meant for writing the calculated data to disk.
104 
105  For each phase the respective time controls are provided, as listed above.
106 
107 Class
108  Foam::functionObject
109 
110 Description
111  Abstract base-class for Time/database functionObjects.
112 
113 See also
114  Foam::functionObjectList
115  Foam::functionObjects::timeControl
116 
117 SourceFiles
118  functionObject.C
119 
120 \*---------------------------------------------------------------------------*/
121 
122 #ifndef functionObject_H
123 #define functionObject_H
124 
125 #include "typeInfo.H"
126 #include "autoPtr.H"
127 #include "Switch.H"
128 #include "runTimeSelectionTables.H"
129 
130 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
131 
132 namespace Foam
133 {
134 
135 // Forward declaration of classes
136 class Time;
137 class polyMesh;
138 class polyTopoChangeMap;
139 class polyMeshMap;
140 class polyDistributionMap;
141 
142 /*---------------------------------------------------------------------------*\
143  Class functionObject Declaration
144 \*---------------------------------------------------------------------------*/
145 
146 class functionObject
147 {
148  // Private Data
149 
150  //- Name
151  const word name_;
152 
153 
154 protected:
155 
156  //- Reference to time
157  const Time& time_;
158 
159 
160 public:
161 
162  ClassName("functionObject");
163 
164  //- Runtime type information
165  virtual const word& type() const = 0;
166 
167  //- Global post-processing mode switch
168  static bool postProcess;
169 
170  //- Switch write log to Info
171  Switch log;
172 
173  //- Switch write log to Info
174  Switch executeAtStart_;
175 
176 
177  // Declare run-time constructor selection tables
178 
180  (
181  autoPtr,
183  dictionary,
184  (const word& name, const Time& runTime, const dictionary& dict),
185  (name, runTime, dict)
186  );
187 
188 
189  // Constructors
190 
191  //- Construct from components
192  functionObject(const word& name, const Time& runTime);
193 
194  //- Return clone
195  autoPtr<functionObject> clone() const
196  {
198  return autoPtr<functionObject>(nullptr);
199  }
200 
201  //- Disallow default bitwise copy construction
202  functionObject(const functionObject&) = delete;
203 
204 
205  // Selectors
206 
207  //- Select from dictionary, based on its "type" entry
208  static autoPtr<functionObject> New
209  (
210  const word& name,
211  const Time&,
212  const dictionary&
213  );
214 
215 
216  //- Destructor
217  virtual ~functionObject();
218 
219 
220  // Member Functions
221 
222  //- Return the name of this functionObject
223  const word& name() const;
224 
225  //- Read and set the functionObject if its data have changed
226  virtual bool read(const dictionary&);
227 
228  //- Return the list of fields required
229  virtual wordList fields() const = 0;
230 
231  //- Return true if the functionObject should be executed at the start
232  virtual bool executeAtStart() const;
233 
234  //- Called at each ++ or += of the time-loop.
235  // foamPostProcess overrides the usual executeControl behaviour and
236  // forces execution (used in post-processing mode)
237  virtual bool execute() = 0;
238 
239  //- Called at each ++ or += of the time-loop.
240  // foamPostProcess overrides the usual writeControl behaviour and
241  // forces writing always (used in post-processing mode)
242  virtual bool write() = 0;
243 
244  //- Called when Time::run() determines that the time-loop exits.
245  virtual bool end();
246 
247  //- Called by Time::adjustTimeStep(). Allows the functionObject to
248  // insert a write time earlier than that already in use by the run
249  // time. Returns the write time, or vGreat.
250  virtual scalar timeToNextAction();
251 
252  //- Update topology using the given map
253  virtual void movePoints(const polyMesh& mesh);
254 
255  //- Update topology using the given map
256  virtual void topoChange(const polyTopoChangeMap& map);
257 
258  //- Update from another mesh using the given map
259  virtual void mapMesh(const polyMeshMap&);
260 
261  //- Redistribute or update using the given distribution map
262  virtual void distribute(const polyDistributionMap&);
263 
264 
265  // Member Operators
266 
267  //- Disallow default bitwise assignment
268  void operator=(const functionObject&) = delete;
269 };
270 
271 
272 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
273 
274 } // End namespace Foam
275 
276 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
277 
278 #endif
279 
280 // ************************************************************************* //
Abstract base-class for Time/database functionObjects.
Switch log
Switch write log to Info.
virtual const word & type() const =0
Runtime type information.
const Time & time_
Reference to time.
functionObject(const word &name, const Time &runTime)
Construct from components.
virtual ~functionObject()
Destructor.
declareRunTimeSelectionTable(autoPtr, functionObject, dictionary,(const word &name, const Time &runTime, const dictionary &dict),(name, runTime, dict))
virtual bool executeAtStart() const
Return true if the functionObject should be executed at the start.
autoPtr< functionObject > clone() const
Return clone.
virtual void distribute(const polyDistributionMap &)
Redistribute or update using the given distribution map.
virtual void movePoints(const polyMesh &mesh)
Update topology using the given map.
virtual bool execute()=0
Called at each ++ or += of the time-loop.
ClassName("functionObject")
virtual void mapMesh(const polyMeshMap &)
Update from another mesh using the given map.
virtual wordList fields() const =0
Return the list of fields required.
void operator=(const functionObject &)=delete
Disallow default bitwise assignment.
Switch executeAtStart_
Switch write log to Info.
static autoPtr< functionObject > New(const word &name, const Time &, const dictionary &)
Select from dictionary, based on its "type" entry.
static bool postProcess
Global post-processing mode switch.
virtual scalar timeToNextAction()
Called by Time::adjustTimeStep(). Allows the functionObject to.
const word & name() const
Return the name of this functionObject.
virtual void topoChange(const polyTopoChangeMap &map)
Update topology using the given map.
virtual bool end()
Called when Time::run() determines that the time-loop exits.
virtual bool read(const dictionary &)
Read and set the functionObject if its data have changed.
virtual bool write()=0
Called at each ++ or += of the time-loop.
Class containing mesh-to-mesh mapping information after a mesh distribution where we send parts of me...
Class containing mesh-to-mesh mapping information.
Definition: polyMeshMap.H:51
Mesh consisting of general polyhedral cells.
Definition: polyMesh.H:80
Class containing mesh-to-mesh mapping information after a change in polyMesh topology.
#define NotImplemented
Issue a FatalErrorIn for a function not currently implemented.
Definition: error.H:353
Namespace for OpenFOAM.
List< word > wordList
A List of words.
Definition: fileName.H:54
Macros to ease declaration of run-time selection tables.
dictionary dict