This change means this function is determining the sequence in which
points are plotted topologically. This makes it possible to plot a layer
average along a pipe that goes through many changes of direction.
Previously, the function determined the order by means of a geometric
sort in the plot direction. This only worked when the layers were
perpendicular to one of the coordinate axes.
This function generates plots of fields averaged over the layers in the
mesh. It is a generalised replacement for the postChannel utility, which
has been removed. An example of this function's usage is as follows:
layerAverage1
{
type layerAverage;
libs ("libfieldFunctionObjects.so");
writeControl writeTime;
setFormat raw;
// Patches and/or zones from which layers extrude
patches (bottom);
zones (quarterPlane threeQuartersPlane);
// Spatial component against which to plot
component y;
// Is the geometry symmetric around the centre layer?
symmetric true;
// Fields to average and plot
fields (pMean pPrime2Mean UMean UPrime2Mean k);
}
Sampled sets and streamlines now write all their fields to the same
file. This prevents excessive duplication of the geometry and makes
post-processing tasks more convenient.
"axis" entries are now optional in sampled sets and streamlines. When
omitted, a default entry will be used, which is chosen appropriately for
the coordinate set and the write format. Some combinations are not
supported. For example, a scalar ("x", "y", "z" or "distance") axis
cannot be used to write in the vtk format, as vtk requires 3D locations
with which to associate data. Similarly, a point ("xyz") axis cannot be
used with the gnuplot format, as gnuplot needs a single scalar to
associate with the x-axis.
Streamlines can now write out fields of any type, not just scalars and
vectors, and there is no longer a strict requirement for velocity to be
one of the fields.
Streamlines now output to postProcessing/<functionName>/time/<file> in
the same way as other functions. The additional "sets" subdirectory has
been removed.
The raw set writer now aligns columns correctly.
The handling of segments in coordSet and sampledSet has been
fixed/completed. Segments mean that a coordinate set can represent a
number of contiguous lines, disconnected points, or some combination
thereof. This works in parallel; segments remain contiguous across
processor boundaries. Set writers now only need one write method, as the
previous "writeTracks" functionality is now handled by streamlines
providing the writer with the appropriate segment structure.
Coordinate sets and set writers now have a convenient programmatic
interface. To write a graph of A and B against some coordinate X, in
gnuplot format, we can call the following:
setWriter::New("gnuplot")->write
(
directoryName,
graphName,
coordSet(true, "X", X), // <-- "true" indicates a contiguous
"A", // line, "false" would mean
A, // disconnected points
"B",
B
);
This write function is variadic. It supports any number of
field-name-field pairs, and they can be of any primitive type.
Support for Jplot and Xmgrace formats has been removed. Raw, CSV,
Gnuplot, VTK and Ensight formats are all still available.
The old "graph" functionality has been removed from the code, with the
exception of the randomProcesses library and associated applications
(noise, DNSFoam and boxTurb). The intention is that these should also
eventually be converted to use the setWriters. For now, so that it is
clear that the "graph" functionality is not to be used elsewhere, it has
been moved into a subdirectory of the randomProcesses library.
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.
The sampled sets have been renamed in a more explicit and consistent
manner, and two new ones have also been added. The available sets are as
follows:
arcUniform: Uniform samples along an arc. Replaces "circle", and
adds the ability to sample along only a part of the circle's
circumference. Example:
{
type arcUniform;
centre (0.95 0 0.25);
normal (1 0 0);
radial (0 0 0.25);
startAngle -1.57079633;
endAngle 0.52359878;
nPoints 200;
axis x;
}
boundaryPoints: Specified point samples associated with a subset of
the boundary. Replaces "patchCloud". Example:
{
type boundaryPoints;
patches (inlet1 inlet2);
points ((0 -0.05 0.05) (0 -0.05 0.1) (0 -0.05 0.15));
maxDistance 0.01;
axis x;
}
boundaryRandom: Random samples within a subset of the boundary.
Replaces "patchSeed", but changes the behaviour to be entirely
random. It does not seed the boundary face centres first. Example:
{
type boundaryRandom;
patches (inlet1 inlet2);
nPoints 1000;
axis x;
}
boxUniform: Uniform grid of samples within a axis-aligned box.
Replaces "array". Example:
{
type boxUniform;
box (0.95 0 0.25) (1.2 0.25 0.5);
nPoints (2 4 6);
axis x;
}
circleRandom: Random samples within a circle. New. Example:
{
type circleRandom;
centre (0.95 0 0.25);
normal (1 0 0);
radius 0.25;
nPoints 200;
axis x;
}
lineFace: Face-intersections along a line. Replaces "face". Example:
{
type lineFace;
start (0.6 0.6 0.5);
end (0.6 -0.3 -0.1);
axis x;
}
lineCell: Cell-samples along a line at the mid-points in-between
face-intersections. Replaces "midPoint". Example:
{
type lineCell;
start (0.5 0.6 0.5);
end (0.5 -0.3 -0.1);
axis x;
}
lineCellFace: Combination of "lineFace" and "lineCell". Replaces
"midPointAndFace". Example:
{
type lineCellFace;
start (0.55 0.6 0.5);
end (0.55 -0.3 -0.1);
axis x;
}
lineUniform: Uniform samples along a line. Replaces "uniform".
Example:
{
type lineUniform;
start (0.65 0.3 0.3);
end (0.65 -0.3 -0.1);
nPoints 200;
axis x;
}
points: Specified points. Replaces "cloud" when the ordered flag is
false, and "polyLine" when the ordered flag is true. Example:
{
type points;
points ((0 -0.05 0.05) (0 -0.05 0.1) (0 -0.05 0.15));
ordered yes;
axis x;
}
sphereRandom: Random samples within a sphere. New. Example:
{
type sphereRandom;
centre (0.95 0 0.25);
radius 0.25;
nPoints 200;
axis x;
}
triSurfaceMesh: Samples from all the points of a triSurfaceMesh.
Replaces "triSurfaceMeshPointSet". Example:
{
type triSurfaceMesh;
surface "surface.stl";
axis x;
}
The headers have also had documentation added. Example usage and a
description of the control parameters now exists for all sets.
In addition, a number of the algorithms which generate the sets have
been refactored or rewritten. This was done either to take advantage of
the recent changes to random number generation, or to remove ad-hoc
fixes that were made unnecessary by the barycentric tracking algorithm.
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.
This changes simplifies the specification of functionObjects in
controlDict and is consistent with the 'libs' option in controlDict to
load special solver libraries.
Support for the old 'functionObjectLibs' name is supported for backward compatibility.
to have the prefix 'write' rather than 'output'
So outputTime() -> writeTime()
but 'outputTime()' is still supported for backward-compatibility.
Also removed the redundant secondary-writing functionality from Time
which has been superseded by the 'writeRegisteredObject' functionObject.
for consistency with the time controls in controlDict and to avoid
unnecessary confusion. All code and tutorials have been updated.
The old names 'outputControl' and 'outputInterval' are but supported for
backward compatibility but deprecated.
