Function objects are OpenFOAM utilities to ease workflow configurations and enhance workflows by producing additional user-requested data both during runtime and postprocessing calculations, typically in the form of additional logging to the screen, or generating text, image and field files.
Function objects eliminate the need to store all runtime generated data, hence saving considerable resources. Furthermore, function objects are readily applied to batch-driven processes, improving reliability by standardising the sequence of operations and reducing the amount of manual interaction.
In addition, the output of most function objects, e.g. output fields, are stored on the mesh database so that it can be retrieved and used for other applications (e.g. directly using wallShearStress
function object output in fieldAverage
function object to produce wallShearStressMean
field).
Function objects can be executed by using two methods:
functions
sub-dictionary in the system/controlDict
filepostProcess
command-line utility, available to solver applications as well with the option -postProcess
.For the first method, each selected function object should be listed inside functions
sub-dictionary of the system/controlDict file as a nested sub-dictionary, typically as in the following example:
functions // sub-dictionary name under the system/controlDict file { <userDefinedSubDictName1> { // Mandatory entries type <functionObjectTypeName>; libs (<libType>FunctionObjects); // Mandatory entries defined in <functionObjectType> ... // Optional entries defined in <functionObjectType> ... // Optional (inherited) entries region region0; enabled true; log true; timeStart 0; timeEnd 1000; executeControl timeStep; executeInterval 1; writeControl timeStep; writeInterval 1; } <userDefinedSubDictName2> { ... } ... <userDefinedSubDictNameN> { ... } }
where the entries mean:
Property | Description | Type | Required | Default |
---|---|---|---|---|
type | Type name of function object | word | yes | - |
libs | Library name containing implementation | word | yes | - |
region | Name of region for multi-region cases | word | no | region0 |
enabled | Switch to turn function object on/off | bool | no | true |
log | Switch to write log info to standard output | bool | no | true |
timeStart | Start time for function object execution | scalar | no | 0 |
timeEnd | End time for function object execution | scalar | no | inf |
executeControl | See time controls below | word | no | timeStep |
executeInterval | Steps/time between execute phases | label | no | 1 |
writeControl | See time controls below | word | no | timeStep |
writeInterval | Steps/time between write phases | label | no | 1 |
The sub-dictionary name <userDefinedSubDictName>
is chosen by the user, and is typically used as the name of the output directory for any data written by the function object.
As the base mandatory entries, the type
entry defines the type of function object properties that follow. Function objects are packaged into separate libraries for flexibility and the libs
entry is used to specify which library should be loaded.
When applied at run-time, the objects are controlled according to the optional two options:
executeControl
: when the object is updated (for updating calculations or for management tasks),writeControl
: when the object output is written (for writing the calculated data to disk).Time controls (take the same type of values as the writeControl
entry in the controlDict, with some additions):
Option | Description none | Trigger is disabled timeStep | Trigger every 'Interval' time-steps, e.g. every x time steps writeTime | Trigger every 'Interval' output times, i.e. alongside standard field output runTime | Trigger every 'Interval' run time period, e.g. every x seconds of calculation time adjustableRunTime | Currently identical to "runTime" clockTime | Trigger every 'Interval' clock time period cpuTime | Trigger every 'Interval' CPU time period onEnd | Trigger on end of simulation run
For example, to set a Courant Number function object to evaluate every 2 time steps and write at every output time:
functions { Co1 { type CourantNo; libs (fieldFunctionObjects); executeControl timeStep; executeInterval 2; writeControl writeTime; } }
Data derived from function objects are written to the case postProcessing
directory or to the time directories, typically in a subdirectory with the same
$FOAM_CASE/postProcessing/<functionObjectName>/<time>/<data> $FOAM_CASE/<time>/<outField>
The second method of executing function objects is to use postProcess
utility.
When specified without additional arguments, the postProcess
utility executes all function objects defined in the system/controlDict
file for all time directories:
postProcess
Most function objects can be invoked directly without the need to specify the input dictionary using the -func
option, e.g. to execute the Courant number function object:
postProcess -func CourantNo
The -postProcess
option is also available to all solvers, and operates similarly to the stand-alone postProcess
utility. For example, having completed a simpleFoam
calculation, the following will execute all function objects defined in the system/controlDict
file for all time directories:
simpleFoam -postProcess
which will execute all function objects defined in the controlDict.
Function objects are grouped into libraries that perform similar operations or operate on similar object types:
Source code: