#includeModel includes an fvModel configuration file into the fvModels file
#includeConstraint includes an fvModel configuration file into the fvConstraints file
These operate in the same manner as #includeFunc does for functionObjects and
search the etc/caseDicts/fvModels and etc/caseDicts/fvConstraints directories
for configuration files and apply optional argument substitution.
Class
Foam::functionEntries::includeFvModelEntry
Description
Specify a fvModel dictionary file to include, expects the
fvModel name to follow with option arguments (without quotes).
Searches for fvModel dictionary file in user/group/shipped
directories allowing for version-specific and version-independent files
using the following hierarchy:
- \b user settings:
- ~/.OpenFOAM/\<VERSION\>/caseDicts/fvModels
- ~/.OpenFOAM/caseDicts/fvModels
- \b group (site) settings (when $WM_PROJECT_SITE is set):
- $WM_PROJECT_SITE/\<VERSION\>/etc/caseDicts/fvModels
- $WM_PROJECT_SITE/etc/caseDicts/fvModels
- \b group (site) settings (when $WM_PROJECT_SITE is not set):
- $WM_PROJECT_INST_DIR/site/\<VERSION\>/etc/caseDicts/fvModels
- $WM_PROJECT_INST_DIR/site/etc/caseDicts/fvModels
- \b other (shipped) settings:
- $WM_PROJECT_DIR/etc/caseDicts/fvModels
The optional field arguments included in the name are inserted in 'field' or
'fields' entries in the fvModel dictionary and included in the name
of the fvModel entry to avoid conflict.
Examples:
\verbatim
#includeModel clouds
#includeModel surfaceFilms
\endverbatim
Other dictionary entries may also be specified using named arguments.
See also
Foam::includeFvConstraintEntry
Foam::includeFuncEntry
Class
Foam::functionEntries::includeFvConstraintEntry
Description
Specify a fvConstraint dictionary file to include, expects the
fvConstraint name to follow with option arguments (without quotes).
Searches for fvConstraint dictionary file in user/group/shipped
directories allowing for version-specific and version-independent files
using the following hierarchy:
- \b user settings:
- ~/.OpenFOAM/\<VERSION\>/caseDicts/fvConstraints
- ~/.OpenFOAM/caseDicts/fvConstraints
- \b group (site) settings (when $WM_PROJECT_SITE is set):
- $WM_PROJECT_SITE/\<VERSION\>/etc/caseDicts/fvConstraints
- $WM_PROJECT_SITE/etc/caseDicts/fvConstraints
- \b group (site) settings (when $WM_PROJECT_SITE is not set):
- $WM_PROJECT_INST_DIR/site/\<VERSION\>/etc/caseDicts/fvConstraints
- $WM_PROJECT_INST_DIR/site/etc/caseDicts/fvConstraints
- \b other (shipped) settings:
- $WM_PROJECT_DIR/etc/caseDicts/fvConstraints
The optional field arguments included in the name are inserted in 'field' or
'fields' entries in the fvConstraint dictionary and included in the name
of the fvConstraint entry to avoid conflict.
Examples:
\verbatim
#includeConstraint limitPressure(minFactor=0.1, maxFactor=2)
#includeConstraint limitTemperature(min=101, max=1000)
\endverbatim
or for a multiphase case:
\verbatim
#includeConstraint limitLowPressure(min=1e4)
#includeConstraint limitTemperature(phase=steam, min=270, max=2000)
#includeConstraint limitTemperature(phase=water, min=270, max=2000)
\endverbatim
Other dictionary entries may also be specified using named arguments.
See also
Foam::includeFvModelEntry
Foam::includeFuncEntry
With this change each functionObject provides the list of fields required so
that the postProcess utility can pre-load them before executing the list of
functionObjects. This provides a more convenient interface than using the
-field or -fields command-line options to postProcess which are now redundant.
Packaged function objects can now be deployed equally effectively by
(a) using a locally edited copy of the configuration file, or by
(b) passing parameters as arguments to the global configuration file.
For example, to post-process the pressure field "p" at a single location
"(1 2 3)", the user could first copy the "probes" packaged function
object file to their system directory by calling "foamGet probes". They
could then edit the file to contain the following entries:
points ((1 2 3));
field p;
The function object can then be executed by the postProcess application:
postProcess -func probes
Or it can be called at run-time, by including from within the functions
section of the system/controlDict file:
#includeFunc probes
Alternatively, the field and points parameters could be passed as
arguments either to the postProcess application by calling:
postProcess -func "probes(points=((1 2 3)), p)"
Or by using the #includeFunc directive:
#includeFunc probes(points=((1 2 3)), p)
In both cases, mandatory parameters that must be either edited or
provided as arguments are denoted in the configuration files with
angle-brackets, e.g.:
points (<points>);
Many of the packaged function objects have been split up to make them
more specific to a particular use-case. For example, the "surfaces"
function has been split up into separate functions for each surface
type; "cutPlaneSurface", "isoSurface", and "patchSurface". This
splitting means that the packaged functions now only contain one set of
relevant parameters so, unlike previously, they now work effectively
with their parameters passed as arguments. To ensure correct usage, all
case-dependent parameters are considered mandatory.
For example, the "streamlines" packaged function object has been split
into specific versions; "streamlinesSphere", "streamlinesLine",
"streamlinesPatch" and "streamlinesPoints". The name ending denotes the
seeding method. So, the following command creates ten streamlines with
starting points randomly seeded within a sphere with a specified centre
and radius:
postProcess -func "streamlinesSphere(nPoints=10, centre=(0 0 0), radius=1)"
The equivalent #includeFunc approach would be:
#includeFunc streamlinesSphere(nPoints=10, centre=(0 0 0), radius=1)
When passing parameters as arguments, error messages report accurately
which mandatory parameters are missing and provide instructions to
correct the format of the input. For example, if "postProcess -func
graphUniform" is called, then the code prints the following error message:
--> FOAM FATAL IO ERROR:
Essential value for keyword 'start' not set
Essential value for keyword 'end' not set
Essential value for keyword 'nPoints' not set
Essential value for keyword 'fields' not set
In function entry:
graphUniform
In command:
postProcess -func graphUniform
The function entry should be:
graphUniform(start = <point>, end = <point>, nPoints = <number>, fields = (<fieldNames>))
file: controlDict/functions/graphUniform from line 15 to line 25.
As always, a full list of all packaged function objects can be obtained
by running "postProcess -list", and a description of each function can
be obtained by calling "foamInfo <functionName>". An example case has
been added at "test/postProcessing/channel" which executes almost all
packaged function objects using both postProcess and #includeFunc. This
serves both as an example of syntax and as a unit test for maintenance.
A number of changes have been made to the surfaceFieldValue and
volFieldValue function objects to improve their usability and
performance, and to extend them so that similar duplicate functionality
elsewhere in OpenFOAM can be removed.
Weighted operations have been removed. Weighting for averages and sums
is now triggered simply by the existence of the "weightField" or
"weightFields" entry. Multiple weight fields are now supported in both
functions.
The distinction between oriented and non-oriented fields has been
removed from surfaceFieldValue. There is now just a single list of
fields which are operated on. Instead of oriented fields, an
"orientedSum" operation has been added, which should be used for
flowRate calculations and other similar operations on fluxes.
Operations minMag and maxMag have been added to both functions, to
calculate the minimum and maximum field magnitudes respectively. The min
and max operations are performed component-wise, as was the case
previously.
In volFieldValue, minMag and maxMag (and min and mag operations when
applied to scalar fields) will report the location, cell and processor
of the maximum or minimum value. There is also a "writeLocation" option
which if set will write this location information into the output file.
The fieldMinMax function has been made obsolete by this change, and has
therefore been removed.
surfaceFieldValue now operates in parallel without accumulating the
entire surface on the master processor for calculation of the operation.
Collecting the entire surface on the master processor is now only done
if the surface itself is to be written out.
The \ continuation line marker is no longer required, multi-line argument lists
are parsed naturally by searching for the end ), e.g. in
tutorials/multiphase/reactingTwoPhaseEulerFoam/laminar/titaniaSynthesis/system/controlDict
#includeFunc writeObjects \
( \
d.particles, \
phaseTransfer:dmidtf.TiO2.particlesAndVapor \
)
is now written in the simpler form:
#includeFunc writeObjects
(
d.particles,
phaseTransfer:dmidtf.TiO2.particlesAndVapor
)
Both the functionObject call context (the command line for postProcess, and the
controlDict path for run-time post-precessing) and the configuration file
context where the arguments are substituted are now printed in the error
message, e.g.
postProcess -func 'patchAverage(name=inlet, ields=(p U))'
generates the message
--> FOAM FATAL IO ERROR:
Essential value for keyword 'fields' not set in function entry
patchAverage(name=inlet, ields=(p U))
in command line postProcess -func patchAverage(name=inlet, ields=(p U))
Placeholder value is <field_names>
file: /home/dm2/henry/OpenFOAM/OpenFOAM-dev/etc/caseDicts/postProcessing/surfaceFieldValue/patchAverage from line 13 to line 17.
and with the following in controlDict
functions
{
#includeFunc patchAverage(name=inlet, ields=(p U))
}
generates the message
--> FOAM FATAL IO ERROR:
Essential value for keyword 'fields' not set in function entry
patchAverage(name=inlet, ields=(p U))
in file /home/dm2/henry/OpenFOAM/OpenFOAM-dev/tutorials/incompressible/pimpleFoam/RAS/pitzDaily/system/controlDict at line 55
Placeholder value is <field_names>
file: /home/dm2/henry/OpenFOAM/OpenFOAM-dev/etc/caseDicts/postProcessing/surfaceFieldValue/patchAverage from line 13 to line 17.
adding support for argument substitution into sub-dictionaries for
e.g. pressureDifferencePatch, white space before, in and after the argument list
and continuation lines, for example:
functions
{
#includeFunc flowRatePatch(name=inlet)
#includeFunc flowRatePatch ( name = outlet )
#includeFunc pressureDifferencePatch \
( \
patch1 = inlet, \
patch2 = outlet \
)
#includeFunc yPlus
#includeFunc residuals
}
for consistency with WM_PROJECT. Now "etc" files are assumed to be in etc
sub-directories of WM_PROJECT_SITE and WM_PROJECT_INST_DIR allowing other files
to be stored in those directories. The search order is now:
Search for files from user/group/shipped directories.
The search scheme allows for version-specific and
version-independent files using the following hierarchy:
- \b user settings:
- ~/.OpenFOAM/\<VERSION\>/
- ~/.OpenFOAM/
- \b group (site) settings (when $WM_PROJECT_SITE is set):
- $WM_PROJECT_SITE/\<VERSION\>/etc/
- $WM_PROJECT_SITE/etc/
- \b group (site) settings (when $WM_PROJECT_SITE is not set):
- $WM_PROJECT_INST_DIR/site/\<VERSION\>/etc/
- $WM_PROJECT_INST_DIR/site/etc/
- \b other (shipped) settings:
- $WM_PROJECT_DIR/etc/
\return The list of full paths of all the matching files or
an empty list if the name cannot be found.
Optionally abort if the file cannot be found.
Optionally stop search after the first file has been found.
This change was proposed and agreed by the sponsors of the OpenFOAM project on
the OpenFOAM Hub, see https://openfoam.org/maintenance/
e.g.
functions
{
#includeFunc mag(U)
}
executes 'mag' on the field 'U' writing the field 'mag(U)'.
The equivalent post-processing command is
postProcess -func 'mag(U)'
with the more general and flexible 'postProcess' utility and '-postProcess' solver option
Rationale
---------
Both the 'postProcess' utility and '-postProcess' solver option use the
same extensive set of functionObjects available for data-processing
during the run avoiding the substantial code duplication necessary for
the 'foamCalc' and 'postCalc' utilities and simplifying maintenance.
Additionally consistency is guaranteed between solver data processing
and post-processing.
The functionObjects have been substantially re-written and generalized
to simplify development and encourage contribution.
Configuration
-------------
An extensive set of simple functionObject configuration files are
provided in
OpenFOAM-dev/etc/caseDicts/postProcessing
and more will be added in the future. These can either be copied into
'<case>/system' directory and included into the 'controlDict.functions'
sub-dictionary or included directly from 'etc/caseDicts/postProcessing'
using the '#includeEtc' directive or the new and more convenient
'#includeFunc' directive which searches the
'<etc>/caseDicts/postProcessing' directories for the selected
functionObject, e.g.
functions
{
#includeFunc Q
#includeFunc Lambda2
}
'#includeFunc' first searches the '<case>/system' directory in case
there is a local configuration.
Description of #includeFunc
---------------------------
Specify a functionObject dictionary file to include, expects the
functionObject name to follow (without quotes).
Search for functionObject dictionary file in
user/group/shipped directories.
The search scheme allows for version-specific and
version-independent files using the following hierarchy:
- \b user settings:
- ~/.OpenFOAM/\<VERSION\>/caseDicts/postProcessing
- ~/.OpenFOAM/caseDicts/postProcessing
- \b group (site) settings (when $WM_PROJECT_SITE is set):
- $WM_PROJECT_SITE/\<VERSION\>/caseDicts/postProcessing
- $WM_PROJECT_SITE/caseDicts/postProcessing
- \b group (site) settings (when $WM_PROJECT_SITE is not set):
- $WM_PROJECT_INST_DIR/site/\<VERSION\>/caseDicts/postProcessing
- $WM_PROJECT_INST_DIR/site/caseDicts/postProcessing
- \b other (shipped) settings:
- $WM_PROJECT_DIR/etc/caseDicts/postProcessing
An example of the \c \#includeFunc directive:
\verbatim
#includeFunc <funcName>
\endverbatim
postProcess
-----------
The 'postProcess' utility and '-postProcess' solver option provide the
same set of controls to execute functionObjects after the run either by
reading a specified set of fields to process in the case of
'postProcess' or by reading all fields and models required to start the
run in the case of '-postProcess' for each selected time:
postProcess -help
Usage: postProcess [OPTIONS]
options:
-case <dir> specify alternate case directory, default is the cwd
-constant include the 'constant/' dir in the times list
-dict <file> read control dictionary from specified location
-field <name> specify the name of the field to be processed, e.g. U
-fields <list> specify a list of fields to be processed, e.g. '(U T p)' -
regular expressions not currently supported
-func <name> specify the name of the functionObject to execute, e.g. Q
-funcs <list> specify the names of the functionObjects to execute, e.g.
'(Q div(U))'
-latestTime select the latest time
-newTimes select the new times
-noFunctionObjects
do not execute functionObjects
-noZero exclude the '0/' dir from the times list, has precedence
over the -withZero option
-parallel run in parallel
-region <name> specify alternative mesh region
-roots <(dir1 .. dirN)>
slave root directories for distributed running
-time <ranges> comma-separated time ranges - eg, ':10,20,40:70,1000:'
-srcDoc display source code in browser
-doc display application documentation in browser
-help print the usage
pimpleFoam -postProcess -help
Usage: pimpleFoam [OPTIONS]
options:
-case <dir> specify alternate case directory, default is the cwd
-constant include the 'constant/' dir in the times list
-dict <file> read control dictionary from specified location
-field <name> specify the name of the field to be processed, e.g. U
-fields <list> specify a list of fields to be processed, e.g. '(U T p)' -
regular expressions not currently supported
-func <name> specify the name of the functionObject to execute, e.g. Q
-funcs <list> specify the names of the functionObjects to execute, e.g.
'(Q div(U))'
-latestTime select the latest time
-newTimes select the new times
-noFunctionObjects
do not execute functionObjects
-noZero exclude the '0/' dir from the times list, has precedence
over the -withZero option
-parallel run in parallel
-postProcess Execute functionObjects only
-region <name> specify alternative mesh region
-roots <(dir1 .. dirN)>
slave root directories for distributed running
-time <ranges> comma-separated time ranges - eg, ':10,20,40:70,1000:'
-srcDoc display source code in browser
-doc display application documentation in browser
-help print the usage
The functionObjects to execute may be specified on the command-line
using the '-func' option for a single functionObject or '-funcs' for a
list, e.g.
postProcess -func Q
postProcess -funcs '(div(U) div(phi))'
In the case of 'Q' the default field to process is 'U' which is
specified in and read from the configuration file but this may be
overridden thus:
postProcess -func 'Q(Ua)'
as is done in the example above to calculate the two forms of the divergence of
the velocity field. Additional fields which the functionObjects may depend on
can be specified using the '-field' or '-fields' options.
The 'postProcess' utility can only be used to execute functionObjects which
process fields present in the time directories. However, functionObjects which
depend on fields obtained from models, e.g. properties derived from turbulence
models can be executed using the '-postProcess' of the appropriate solver, e.g.
pisoFoam -postProcess -func PecletNo
or
sonicFoam -postProcess -func MachNo
In this case all required fields will have already been read so the '-field' or
'-fields' options are not be needed.
Henry G. Weller
CFD Direct Ltd.
