#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
token: Changed parseError to use cerr rather than FatalIOError so that it can
report errors when reading debug switches from the case controlDict at start-up.
timeControl functionality is supported for both execution and writing but
previously only instantiated if the writeControl entry is present in the
functionObject dictionary, now it is also instantiated if only the
executeControl entry is present as the functionObject might only have execute
functionality.
This new mapping structure is designed to support run-time mesh-to-mesh mapping
to allow arbitrary changes to the mesh structure, for example during extreme
motion requiring significant topology change including region disconnection etc.
The polyTopoChangeMap is the map specifically relating to polyMesh topological
changes generated by polyTopoChange and used to update and map mesh related
types and fields following the topo-change.
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.
setTimeStep is now compatible with a 'writeControl adjustableRunTime;'
setting in the systemControlDict. If 'adjustableRunTime' is selected
then the time-step values set by this function object will not be
exactly as specified, but write intervals will be matched exactly.
All function object time adjustment is now done during the execute
methods, so the specific setTimeStep hooks have been removed.
This is used to set the directory name for the results of the functionObject, if
not specified a unique name is generated automatically from the function type
and argument list, e.g.
#includeFunc patchAverage(name=inlet, fields=(p U))
writes surfaceFieldValue.dat in postProcessing/patchAverage(name=inlet,fields=(pU))/0 and
#includeFunc patchAverage(funcName=inlet, name=inlet, fields=(p U))
writes surfaceFieldValue.dat in postProcessing/inlet/0.
Additional flexibility for handling of field arguments has been extended
to dictionary lists of field settings, as well as word lists of field
names. This means that the following syntax is now supported:
postProcess -func "fieldAverage(p, U { prime2Mean on; }, T)"
postProcess -func "fieldAverage(fields=(p U { prime2Mean on; } T))"
Function object argument parsing now takes all "field", "fields" and
"objects" arguments and combines them into a single list of
fields/objects that the function should operate on. This means that the
following postProcess executions are now all equivalent and function as
expected:
postProcess -func "
flowRatePatch
(
name=outlet,
phi,
alphaRhoPhi.air,
alphaRhoPhi.particles
)"
postProcess -func "
flowRatePatch
(
name=outlet,
fields=(phi alphaRhoPhi.air alphaRhoPhi.particles)
)"
postProcess -func "
flowRatePatch
(
name=outlet,
objects=(phi),
alphaRhoPhi.air,
field=alphaRhoPhi.particles
)"
As are the following:
postProcess -func "mag(U.air)"
postProcess -func "mag(field=U.air)"
Rather than being tied to the Time class the dlLibraryTable libs is now a global
variable in the Foam namespace which is accessable by any class needing to load
dynamic libraries, in particular argList, Time and codeStream.
When selecting fields with complex automatically generated names it is
cumbersome to escape all the regular expression meta characters and more
convenient to specify the name as a literal string, the new regExp option
provides the ability to switch the regular expression support and defaults to
true for backward compatibility.
For example to cache and write out an intermediate temporary field generated by
the kOmegaSST model:
cacheTemporaryObjects
(
"((interpolate(((1|((1|(1|A(U)))-H(1)))-(1|A(U))))*snGrad(p))*magSf)"
);
functions
{
#includeFunc writeObjects(regExp=off, "((interpolate(((1|((1|(1|A(U)))-H(1)))-(1|A(U))))*snGrad(p))*magSf)")
}
The regExp option can also be specified in a writeObjects dict as
regExp off;
Additionally regular expression support has been added to the includeFunc
argument parsing.
When operating on multi-region cases, function files are now searched
for in the following order:
- First the $FOAM_CASE/system/<region> directory is searched
- Second the $FOAM_CASE/system directory is searched
- Finally a search is done through the preconfigured functions in
$WM_PROJECT_DIR/etc
Previously, in a multi-region case, preconfigured objects were
considered before those in the case's (non-region) system directory.
This was considered counter-intuitive. Functions residing in the system
directory should always take precedence, whether they are in the region
subdirectory or not.
As of 2ebed5ec, functonObjectList::start contains run commands that
trigger if some function objects are executable at time-zero. A call to
this method in functionObjectList::New has been removed (and replaced
with functonObjectList::read) as it was causing postProcess and <solver>
-postProcess to execute twice; once on construction, and once at the
selected initial time.
This change also fixes lookup errors generated by postProcess which
occured because fields (specified with -field or -fields arguments) are
not read and registered prior to function object construction.
Usage of functonObjectList::start within Time::run has not been altered.
By default most functionObjects now execute and write at the start-time except
those that perform averaging (fieldAverage, dsmcFields) which cannot be executed
until the end of the first time-step. There is also a new optional
functionObject dictionary entry "executeAtStart" which defaults to true but can
be set false if the execution and results of the functionObject are not required
or appropriate at the start-time.
A result of this change is that time logs of forces, sampling etc. now include a
values for time 0.
If the functionObject requires an object list rather than a field list the
non-named arguments are now inserted into the object list, for example
functions
{
#includeFunc writeObjects(kEpsilon:G)
}
which is equivalent to
functions
{
#includeFunc writeObjects(objects = (kEpsilon:G))
}
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
db/functionObjects/timeControl/timeControl.H: timeControls
primitives/bools/Switch/Switch.H: class switchType
primitives/strings/fileName/fileName.H: fileType
primitives/strings/wordRe/wordRe.H: compOption
The logic governing function objects' ability to change the time-step
has been modified so that it is compatible with the time-step adjustment
done in the Time class. The behaviour has been split into a method which
sets the step directly, and another which moidifies the time until the
next write operation (i.e., the time that the solver "aims" for).
This fixes an issue where the adjustments in Time and the function
objects interfere and cause the time step to decrease exponentially down
to machine precision. It also means that the set-time-step function
object now does not break the adjustable run-time setting.
This resolves bug report https://bugs.openfoam.org/view.php?id=2820
e.g.
postProcess -func sample -region bottomWater
will now search for the system/bottomWater/sample dictionary before searching
for system/sample so that the fields and type of sampling can optionally be
specified differently for the particular region.
Resolves feature request https://bugs.openfoam.org/view.php?id=2807
When an OpenFOAM simulation runs in parallel, the data for decomposed fields and
mesh(es) has historically been stored in multiple files within separate
directories for each processor. Processor directories are named 'processorN',
where N is the processor number.
This commit introduces an alternative "collated" file format where the data for
each decomposed field (and mesh) is collated into a single file, which is
written and read on the master processor. The files are stored in a single
directory named 'processors'.
The new format produces significantly fewer files - one per field, instead of N
per field. For large parallel cases, this avoids the restriction on the number
of open files imposed by the operating system limits.
The file writing can be threaded allowing the simulation to continue running
while the data is being written to file. NFS (Network File System) is not
needed when using the the collated format and additionally, there is an option
to run without NFS with the original uncollated approach, known as
"masterUncollated".
The controls for the file handling are in the OptimisationSwitches of
etc/controlDict:
OptimisationSwitches
{
...
//- Parallel IO file handler
// uncollated (default), collated or masterUncollated
fileHandler uncollated;
//- collated: thread buffer size for queued file writes.
// If set to 0 or not sufficient for the file size threading is not used.
// Default: 2e9
maxThreadFileBufferSize 2e9;
//- masterUncollated: non-blocking buffer size.
// If the file exceeds this buffer size scheduled transfer is used.
// Default: 2e9
maxMasterFileBufferSize 2e9;
}
When using the collated file handling, memory is allocated for the data in the
thread. maxThreadFileBufferSize sets the maximum size of memory in bytes that
is allocated. If the data exceeds this size, the write does not use threading.
When using the masterUncollated file handling, non-blocking MPI communication
requires a sufficiently large memory buffer on the master node.
maxMasterFileBufferSize sets the maximum size in bytes of the buffer. If the
data exceeds this size, the system uses scheduled communication.
The installation defaults for the fileHandler choice, maxThreadFileBufferSize
and maxMasterFileBufferSize (set in etc/controlDict) can be over-ridden within
the case controlDict file, like other parameters. Additionally the fileHandler
can be set by:
- the "-fileHandler" command line argument;
- a FOAM_FILEHANDLER environment variable.
A foamFormatConvert utility allows users to convert files between the collated
and uncollated formats, e.g.
mpirun -np 2 foamFormatConvert -parallel -fileHandler uncollated
An example case demonstrating the file handling methods is provided in:
$FOAM_TUTORIALS/IO/fileHandling
The work was undertaken by Mattijs Janssens, in collaboration with Henry Weller.
Now the postProcess utility '-region' option works correctly, e.g. for
the chtMultiRegionSimpleFoam/heatExchanger case
postProcess -region air -func "mag(U)"
calculates 'mag(U)' for all the time steps in region 'air'.
To re-use existing 'sampleDict' files simply add the following entries:
type sets;
libs ("libsampling.so");
and run
postProcess -func sampleDict
It is probably better to also rename 'sampleDict' -> 'sample' and then run
postProcess -func sampleDict
Replaced the 'postProcess' argument to the 'write' and 'execute'
functions with the single static member 'postProcess' in the
functionObject base-class.
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.
the equivalent functionality is provided by the writeRegisteredObject
functionObject in a MUCH simpler, easier and extensible manner.
functionObject: Removed the now redundant 'timeSet' function.
- Avoids the need for the 'OutputFilterFunctionObject' wrapper
- Time-control for execution and writing is now provided by the
'timeControlFunctionObject' which instantiates the processing
'functionObject' and controls its operation.
- Alternative time-control functionObjects can now be written and
selected at run-time without the need to compile wrapped version of
EVERY existing functionObject which would have been required in the
old structure.
- The separation of 'execute' and 'write' functions is now formalized in the
'functionObject' base-class and all derived classes implement the
two functions.
- Unnecessary implementations of functions with appropriate defaults
in the 'functionObject' base-class have been removed reducing
clutter and simplifying implementation of new functionObjects.
- The 'coded' 'functionObject' has also been updated, simplified and tested.
- Further simplification is now possible by creating some general
intermediate classes derived from 'functionObject'.
