6.2 Post-processing command line interface (CLI)

Post-processing is provided directly within OpenFOAM through the command line including data processing, sampling (e.g. probes, graph plotting) visualisation, case control and run-time I/O. Functionality can be executed by:

  • conventional post-processing, a data processing activity that occurs after a simulation has run;
  • run-time processing, data processing that is performed during the running of a simulation.

Both approaches have advantages. Conventional post-processing allows the user to choose how to analyse data after the results are obtained. Run-time processing offers greater flexibility because it has access to all the data in the database of the run at all times, rather than just the data written during the simulation. It also allows the user to monitor processed data during a simulation and provides a greater level of convenience because the processed results can be available immediately to the user when the simulation ends.

There are 3 methods of post-processing that cover the options described above

  • Every solver, e.g. simpleFoam can be configured to include run-time processing.
  • The postProcess utility provides conventional post-processing of data written by a simulation.
  • Every solver can be run with the -postProcess option, which only executes post-processing, but with additional access to data available on the database for the particular solver.

6.2.1 Post-processing functionality

All modes of post-processing access the same functionality implemented in OpenFOAM in the function object framework. Function objects can be listed by running a solver with the -listFunctionObjects option, e.g. 


    simpleFoam -listFunctionObjects
The list represents the underlying post-processing functionality. Almost all the functionality is packaged into a set of configured tools that are conveniently integrated within the post-processing CLI. Those tools are located in $FOAM_ETC/caseDicts/postProcessing and are listed by running postProcess with the -list option.


    postProcess -list
This produces a list of tools that are described in the following sections.

6.2.1.1 Field calculation

age
Calculates and writes out the time taken for a particle to travel from an inlet to the location.
components
Writes the component scalar fields (e.g. Ux, Uy, Uz) of a field (e.g. U).
CourantNo
Calculates the Courant Number field from the flux field.
ddt
Calculates the Eulerian time derivative of a field.
div
Calculates the divergence of a field.
enstrophy
Calculates the enstrophy of the velocity field.
fieldAverage
Calculates and writes the time averages of a given list of fields.
flowType
Calculates and writes the flowType of velocity field where: -1 = rotational flow; 0 = simple shear flow; +1 = planar extensional flow.
grad
Calculates the gradient of a field.
Lambda2
Calculates and writes the second largest eigenvalue of the sum of the square of the symmetrical and anti-symmetrical parts of the velocity gradient tensor.
log
Calculates the natural logarithm of the specified scalar field.
MachNo
Calculates the Mach Number field from the velocity field.
mag
Calculates the magnitude of a field.
magSqr
Calculates the magnitude-squared of a field.
PecletNo
Calculates the Peclet Number field from the flux field.
phaseMap
Writes the phase-fraction map field alpha.map with incremental value ranges for each phase e.g., with values 0 for water, 1 for air, 2 for oil, etc.
Q
Calculates the second invariant of the velocity gradient tensor.
randomise
Adds a random component to a field, with a specified perturbation magnitude.
scale
Multiplies a field by a scale factor
shearStress
Calculates the shear stress, outputting the data as a volSymmTensorField.
streamFunction
Writes the stream-function pointScalarField, calculated from the specified flux surfaceScalarField.
totalEnthalpy
Calculates and writes the total enthalpy eqn as the volScalarField eqn.
turbulenceFields
Calculates specified turbulence fields and stores it on the database.
turbulenceIntensity
Calculates and writes the turbulence intensity field I.
vorticity
Calculates the vorticity field, i.e. the curl of the velocity field.
wallHeatFlux
Calculates the heat flux at wall patches, outputting the data as a volVectorField.
wallHeatTransferCoeff
Calculates the estimated incompressible flow heat transfer coefficient at wall patches, outputting the data as a volScalarField.
wallShearStress
Calculates the shear stress at wall patches, outputting the data as a volVectorField.
writeCellCentres
Writes the cell-centres volVectorField and the three component fields as volScalarFields; useful for post-processing thresholding.
writeCellVolumes
Writes the cell-volumes volScalarField
writeVTK
Writes out specified objects in VTK format, e.g. fields, stored on the case database.
yPlus
Calculates the turbulence y+, outputting the data as a yPlus field.

6.2.1.2 Field operations

add
Add a list of fields.
divide
From the first field, divide the remaining fields in the list.
multiply
Multiply a list of fields.
subtract
From the first field, subtracts the remaining fields in the list.
uniform
Create a uniform field.

6.2.1.3 Forces and force coefficients

forceCoeffsCompressible
Calculates lift, drag and moment coefficients by summing forces on specified patches for a case where the solver is compressible (pressure is in units M/(LTˆ2), e.g. Pa).
forceCoeffsIncompressible
Calculates lift, drag and moment coefficients by summing forces on specified patches for a case where the solver is incompressible (pressure is kinematic, e.g. mˆ2/sˆ2).
forcesCompressible
Calculates pressure and viscous forces over specified patches for a case where the solver is compressible (pressure is in units M/(LTˆ2), e.g. Pa).
forcesIncompressible
Calculates pressure and viscous forces over specified patches for a case where the solver is incompressible (pressure is kinematic, e.g. mˆ2/sˆ2).
phaseForces
Calculates the blended interfacial forces acting on a given phase, i.e. drag, virtual mass, lift, wall-lubrication and turbulent dispersion. Note that it works only in solver post-processing mode and in combination with multiphaseEulerFoam. For a simulation involving more than two phases, the accumulated force is calculated by looping over all phasePairs the phase is a part of.

6.2.1.4 Sampling for graph plotting

graphCell
Writes graph data for specified fields along a line, specified by start and end points. One graph point is generated in each cell that the line intersects.
graphUniform
Writes graph data for specified fields along a line, specified by start and end points. A specified number of graph points are used, distributed uniformly along the line.

6.2.1.5 Lagrangian data

dsmcFields
Calculate intensive fields UMean, translationalT, internalT, overallT from averaged extensive fields from a DSMC calculation.

6.2.1.6 Monitoring minima and maxima

cellMax
Writes out the maximum cell value for one or more fields.
cellMaxMag
Writes out the maximum cell value magnitude for one or more fields.
cellMin
Writes out the minimum cell value for one or more fields.
cellMinMag
Writes out the maximum cell value magnitude for one or more fields.

6.2.1.7 Numerical data

residuals
For specified fields, writes out the initial residuals for the first solution of each time step; for non-scalar fields (e.g. vectors), writes the largest of the residuals for each component (e.g. x, y, z).

6.2.1.8 Control

stopAtClockTime
Stops the run when the specified clock time in second has been reached and optionally write results before stopping.
stopAtFile
Stops the run when the file stop is created in the case directory.
time
Writes run time, CPU time and clock time and optionally the CPU and clock times per time step.
timeStep
Writes the time step to a file for monitoring.
writeObjects
Writes out specified objects, e.g. fields, stored on the case database.

6.2.1.9 Pressure tools

staticPressureIncompressible
Calculates the pressure field in units M/(LTˆ2) (e.g. Pa) from kinematic pressure by scaling by a specified density.
totalPressureCompressible
Calculates the total pressure field for a case where the solver is compressible (pressure is in units M/(LTˆ2), e.g. Pa).
totalPressureIncompressible
Calculates the total pressure field for a case where the solver is incompressible (pressure is kinematic, e.g. mˆ2/sˆ2).

6.2.1.10 Combustion

Qdot
Calculates and outputs the heat release rate for the current combustion model.
XiReactionRate
Writes the turbulent flame-speed and reaction-rate volScalarFields for the Xi-based combustion models.

6.2.1.11 Probes

boundaryProbes
Writes out values of fields at a cloud of points, interpolated to specified boundary patches.
interfaceHeight
Reports the height of the interface above a set of locations. For each location, it writes the vertical distance of the interface above both the location and the lowest boundary. It also writes the point on the interface from which these heights are computed.
internalProbes
Writes out values of fields interpolated to a specified cloud of points.
probes
Writes out values of fields from cells nearest to specified locations.

6.2.1.12 Surface region

faceZoneAverage
Calculates the average value of one or more fields on a faceZone.
faceZoneFlowRate
Calculates the flow rate through a specified face zone by summing the flux on patch faces. For solvers where the flux is volumetric, the flow rate is volumetric; where flux is mass flux, the flow rate is mass flow rate.
patchAverage
Calculates the average value of one or more fields on a patch.
patchDifference
Calculates the difference between the average values of fields on two specified patches. Calculates the average value of one or more fields on a patch.
patchFlowRate
Calculates the flow rate through a specified patch by summing the flux on patch faces. For solvers where the flux is volumetric, the flow rate is volumetric; where flux is mass flux, the flow rate is mass flow rate.
patchIntegrate
Calculates the surface integral of one or more fields on a patch.
triSurfaceDifference
Calculates the difference between the average values of fields on two specified triangulated surfaces.
triSurfaceVolumetricFlowRate
Calculates volumetric flow rate through a specified triangulated surface by interpolating velocity onto the triangles and integrating over the surface area. Triangles need to be small (¡= cell size) for an accurate result.

6.2.1.13 ‘Pluggable’ solvers

particles
Tracks a cloud of parcels driven by the flow of the continuous phase.
phaseScalarTransport
Solves a transport equation for a scalar field within one phase of a multiphase simulation.
scalarTransport
Solves a transport equation for a scalar field.

6.2.1.14 Visualisation tools

cutPlaneSurface
Writes out cut-plane surface files with interpolated field data in VTK format.
isoSurface
Writes out iso-surface files with interpolated field data in VTK format.
patchSurface
Writes out patch surface files with interpolated field data in VTK format.
streamlinesLine
Writes out files of stream lines with interpolated field data in VTK format, with initial points uniformly distributed along a line.
streamlinesPatch
Writes out files of stream lines with interpolated field data in VTK format, with initial points randomly selected within a patch.
streamlinesPoints
Writes out files of stream lines with interpolated field data in VTK format, with specified initial points.
streamlinesSphere
Writes out files of stream lines with interpolated field data in VTK format, with initial points randomly selected within a sphere.

6.2.2 Run-time data processing

When a user wishes to process data during a simulation, they need to configure the case accordingly. The configuration process is as follows, using an example of monitoring flow rate at an outlet patch named outlet.

Firstly, the user should include the flowRatePatch function in functions sub-dictionary in the case controlDict file, using the #includeFunc directive.


functions
{
    #includeFunc  flowRatePatch
    ... other function objects here ...
}
That will include the functionality in the flowRatePatch configuration file, located in the directory hierarchy beginning with $FOAM_ETC/caseDicts/postProcessing.

The configuration of flowRatePatch requires the name of the patch to be supplied. Option 1 for doing this is that the user copies the flowRatePatch file into their case system directory. The foamGet script copies the file conveniently, e.g. 


    foamGet flowRatePatch
The patch name can be edited in the copied file to be outlet. When the solver is run, it will pick up an included function in the local case system directory, in precedence over $FOAM_ETC/caseDicts/postProcessing. The flow rate through the patch will be calculated and written out into a file within a directory named postProcessing.

Option 2 for specifying the patch name is to provide the name as an argument to the flowRatePatch in the #includeFunc directive, using the syntax keyword=entry.


functions
{
    #includeFunc  flowRatePatch(patch=outlet)
    ... other function objects here ...
}

In the case where the keyword is field or fields, only the entry is needed when specifying an argument to a function. For example, if the user wanted to calculate and write out the magnitude of velocity into time directories during a simulation they could simply add the following to the functions sub-dictionary in controlDict.


functions
{
    #includeFunc  mag(U)
    ... other function objects here ...
}
This works because the function’s argument U is represented by the keyword field, see $FOAM_ETC/caseDicts/postProcessing/fields/mag.

Some functions require the setting of many parameters, e.g. to calculate forces and generate elements for visualisation, etc. For those functions, it is more reliable and convenient to copy and configure the function using option 1 (above) rather than through arguments.

6.2.3 The postProcess utility

The user can execute post-processing functions after the simulation is complete using the postProcess utility. Let us illustrate the use of postProcess using the pitzDaily case from the tutorials directory. The case can be copied, e.g. into the user’s run directory; the user can then go into the case directory, generate the mesh with blockMesh and then run simpleFoam


    run
    cp -r $FOAM_TUTORIALS/incompressible/simpleFoam/pitzDaily .
    cd pitzDaily
    blockMesh
    simpleFoam
Now the user can run execute post-processing functions with postProcess. The -help option provides a summary of its use.


    postProcess -help
Simple functions like mag can be executed using the -func option; text on the command line generally needs to be quoted ("") if it contains punctuation characters.


    postProcess -func "mag(U)"
This operation calculates and writes the field of magnitude of velocity into a file named mag(U) in each time directory. Similarly, the flowRatePatch example can be executed using postProcess.


    postProcess -func "flowRatePatch(name=outlet)"
Let us say the user now wants to calculate total pressure eqn for incompressible flow with kinematic pressure, eqn. The function is available, named totalPressureIncompressible, which the user could attempt first to run as follows.


    postProcess -func totalPressureIncompressible
This returns the following error message.


    --> FOAM Warning : functionObject pressure: Cannot find required field p
The error message is telling the user that the pressure field p is not loaded; the same is true of the velocity field U. For the function to work, both fields can be loaded as comma separated arguments.


    postProcess -func "totalPressureIncompressible(p,U)"
Alternatively the user can load a space separated list of fields using the -fields option, which the function can access.


    postProcess -fields "(p U)" -func totalPressureIncompressible
Both options work effectively because the pressure and velocity data is available directly from the files, p and U.

6.2.4 Solver post-processing

A more complex example is calculating wall shear stress using the wallShearStress function.


    postProcess -fields "(p U)" -func wallShearStress
Even loading relevant fields, the post-processing fails with the following message.


    --> FOAM FATAL ERROR:
    Unable to find turbulence model in the database
The message is telling us that the postProcess utility has not constructed the necessary models that the solver, simpleFoam, used when running the simulation, i.e. a turbulence model. This is a situation where we need to post-process (as opposed to run-time process) using the solver with the -postProcess option so that the modelling will be available that the post-processing function needs. Help for this operation can be printed with the following command.


    simpleFoam -postProcess -help
It can be seen that the options for a solver with -postProcess are the same as when running postProcess utility. This means that the -func option can be used to execute the wallShearStress function effectively.


    simpleFoam -postProcess -func wallShearStress
Note that no fields need to be supplied, either by function arguments ”(p,U)” or using ”-fields (p U)”, because simpleFoam itself constructs and stores the required fields. Functions can also be selected by the #includeFunc directive in functions in the controlDict file, instead of the -func option.
OpenFOAM v9 User Guide - 6.2 Post-processing command line interface (CLI)