Commit a5c6516e authored by Kutalmis Bercin's avatar Kutalmis Bercin Committed by Andrew Heather
Browse files

DOC: elaborate the usage of function objects

  ENH: update libs of etc/caseDicts/postProcess items
  ENH: ensure destructor=default
  ENH: ensure constness
  ENH: ensure no 'copy construct' and 'no copy assignment' exist
  TUT: add examples of function objects with full set
       of settings into a TUT if unavailable
  TUT: update pisoFoam/RAS/cavity tutorial in terms of usage
parent b5491165
......@@ -6,14 +6,16 @@
\\/ M anipulation |
-------------------------------------------------------------------------------
Description
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.
Computes the min/max/average arbitrary mesh interface (AMI) weights, and
optionally reports to a text file or writes VTK surfaces of the sum of
the weights and mask fields for arbitrarily coupled mesh interface (ACMI)
patches.
\*---------------------------------------------------------------------------*/
type AMIWeights;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
writeFields yes;
writeControl writeTime;
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type CourantNo;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
field phi;
......
......@@ -6,14 +6,14 @@
\\/ M anipulation |
-------------------------------------------------------------------------------
Description
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.
Calculates Lamb vector, i.e. the cross product of vorticity and velocity.
Calculation of the divergence of the Lamb vector can be performed by using
\c div function object on this \c LambVector function object.
\*---------------------------------------------------------------------------*/
type lambVector;
libs ("libfieldFunctionObjects.so");
type LambVector;
libs (fieldFunctionObjects);
field U;
......
......@@ -13,7 +13,7 @@ Description
\*---------------------------------------------------------------------------*/
type Lambda2;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
field U;
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type MachNo;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
field U;
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type PecletNo;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
field phi;
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type Q;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
field U;
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type turbulenceFields;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
field R;
......
......@@ -12,7 +12,7 @@ Description
\*---------------------------------------------------------------------------*/
type XiReactionRate;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
fields (b Xi Su);
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type add;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
fields (<field names>);
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type components;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
field <fieldName>;
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type ddt;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
field <fieldName>;
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type div;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
field <fieldName>;
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type energySpectrum;
libs ("librandomProcessesFunctionObjects.so");
libs (randomProcessesFunctionObjects);
executeControl writeTime;
writeControl writeTime;
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type enstrophy;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
field U;
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type fieldMinMax;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
fields (".*");
......
......@@ -14,7 +14,7 @@ Description
\*---------------------------------------------------------------------------*/
type flowType;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
field U;
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type grad;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
field <fieldName>;
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type mag;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
field <fieldName>;
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type magSqr;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
field <fieldName>;
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type processorField;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
executeControl writeTime;
writeControl writeTime;
......
......@@ -12,7 +12,7 @@ Description
\*---------------------------------------------------------------------------*/
type streamFunction;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
field phi;
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type subtract;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
fields (<field names>);
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type turbulenceFields;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
fields (<field names>);
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type vorticity;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
field U;
......
......@@ -12,7 +12,7 @@ Description
\*---------------------------------------------------------------------------*/
type wallHeatFlux;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
executeControl writeTime;
writeControl writeTime;
......
......@@ -12,7 +12,7 @@ Description
\*---------------------------------------------------------------------------*/
type wallShearStress;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
executeControl writeTime;
writeControl writeTime;
......
......@@ -13,7 +13,7 @@ Description
\*---------------------------------------------------------------------------*/
type writeCellCentres;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
executeControl writeTime;
writeControl writeTime;
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type writeCellVolumes;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
executeControl writeTime;
writeControl writeTime;
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type writeObjects;
libs ("libutilityFunctionObjects.so");
libs (utilityFunctionObjects);
objects (<object names>);
......
......@@ -11,7 +11,7 @@ Description
\*---------------------------------------------------------------------------*/
type yPlus;
libs ("libfieldFunctionObjects.so");
libs (fieldFunctionObjects);
executeControl writeTime;
writeControl writeTime;
......
......@@ -52,28 +52,23 @@ Foam::functionObjects::FUNCTIONOBJECT::FUNCTIONOBJECT
)
:
fvMeshFunctionObject(name, runTime, dict),
boolData_(dict.getOrDefault<bool>("boolData"), true),
labelData_(dict.get<label>("labelData")),
wordData_(dict.getOrDefault<word>("wordData", "defaultWord")),
scalarData_(dict.get<scalar>("scalarData")),
labelData_(dict.get<label>("labelData"))
scalarData_(dict.getOrDefault<scalar>("scalarData", 1.0))
{
read(dict);
}
// * * * * * * * * * * * * * * * * Destructor * * * * * * * * * * * * * * * //
Foam::functionObjects::FUNCTIONOBJECT::~FUNCTIONOBJECT()
{}
// * * * * * * * * * * * * * * * Member Functions * * * * * * * * * * * * * //
bool Foam::functionObjects::FUNCTIONOBJECT::read(const dictionary& dict)
{
dict.readEntry("boolData", boolData_);
dict.readEntry("labelData", labelData_);
dict.readIfPresent("wordData", wordData_);
dict.readEntry("scalarData", scalarData_);
dict.readEntry("labelData", labelData_);
return true;
}
......
......@@ -5,7 +5,7 @@
\\ / A nd | www.openfoam.com
\\/ M anipulation |
-------------------------------------------------------------------------------
Copyright (C) YEAR YEAR AUTHOR,AFFILIATION
Copyright (C) YEAR AUTHOR, AFFILIATION
-------------------------------------------------------------------------------
License
This file is part of OpenFOAM.
......@@ -27,34 +27,120 @@ Class
Foam::functionObjects::FUNCTIONOBJECT
Group
grpFieldFunctionObjects
Description
This function object...
<minimal description of the function object>
Example of function object specification:
<equation>
\f[
x = x_{ref}^x + \rho \omega
\f]
<variable-explanation table>
where
\vartable
\rho | <explanation> [units, e.g. kg/m3]
\omega | \f$ \nabla \cdot \vec U \f$
... | ...
\endvartable
<inline equation>
where \f$ x_k \f$ is ...
<input-output table>
\table
Operand | Type | Location
input | {vol,surface}\<Type\>Field(s) <!--
--> |$FOAM_CASE/\<time\>/\<inpField\>s
output file | dat <!--
--> | $FOAM_CASE/postProcessing/\<FO\>/\<time\>/\<file\>
output field | volScalarField | $FOAM_CASE/\<time\>/\<outField\>
\endtable
Usage
Minimal example by using \c system/controlDict.functions:
\verbatim
FUNCTIONOBJECT1
{
// Mandatory entries (unmodifiable)
type FUNCTIONOBJECT;
libs ("libFUNCTIONOBJECTFunctionObject.so");
libs (FUNCTIONOBJECTFunctionObject);
// Mandatory entries (runtime modifiable)
...
// Mandatory (inherited) entries (unmodifiable)
...
// Mandatory (inherited) entries (runtime unmodifiable)
...
// Optional entries (unmodifiable)
...
// Optional entries (runtime modifiable)
boolData <bool>;
labelData <label>;
wordData <word>;
scalarData <scalar>;
// Optional (inherited) entries
...
wordData someWord;
scalarData 1.0;
labelData 1;
}
\endverbatim
Usage
where the entries mean:
\table
Property | Description | Required | Default value
type | type name: FUNCTIONOBJECT | yes |
wordData | some word option... | no | defaultWord
scalarData | some scalar value... | yes |
labelData | some label value... | yes |
Property | Description | Type | Req'd | Dflt
type | Type name: FUNCTIONOBJECT | word | yes | -
libs | Library name: FUNCTIONOBJECTFunctionObject <!--
--> | word | yes | -
boolData | <explanation> | bool | yes | -
labelData | <explanation> | label | yes | -
wordData | <explanation> | word | yes | -
scalarData | <explanation> | scalar | no | 1.0
wordListData | <explanation> | wordList | yes | -
\endtable
Options for the \c ENTRY entry:
\verbatim
<option1>
<option2> | <explanation>
...
\endverbatim
The inherited entries are elaborated in:
- \link functionObject.H \endlink
- \link fieldExpression.H \endlink
- \link fieldsExpression.H \endlink
- \link writeFile.H \endlink
...
<if \c postProcess is applicable>
Minimal example by using the \c postProcess utility:
\verbatim
postProcess -func FUNCTIONOBJECT
\endverbatim
<if \c postProcess is not applicable>
Usage by the \c postProcess utility is not available.
Note
- <note1>
- <note2>
...
See also
- Foam::functionObject
- Foam::functionObjects::fvMeshFunctionObject
- ExtendedCodeGuide::functionObjects::field::FUNCTIONOBJECT
...
SourceFiles
FUNCTIONOBJECT.C
FUNCTIONOBJECTTEMPLATES.C
...
\*---------------------------------------------------------------------------*/
......@@ -78,26 +164,19 @@ class FUNCTIONOBJECT
:
public fvMeshFunctionObject
{
// Private data
//- word
word wordData_;
// Private Data
//- scalar
scalar scalarData_;
//- bool
bool boolData_;
//- label
label labelData_;
//- word
word wordData_;
// Private Member Functions
//- No copy construct
FUNCTIONOBJECT(const FUNCTIONOBJECT&);
//- No copy assignment
void operator=(const FUNCTIONOBJECT&);
//- scalar
scalar scalarData_;
public:
......@@ -116,9 +195,15 @@ public:
const dictionary& dict
);
//- No copy construct
FUNCTIONOBJECT(const FUNCTIONOBJECT&) = delete;
//- No copy assignment
void operator=(const FUNCTIONOBJECT&) = delete;
//- Destructor
virtual ~FUNCTIONOBJECT();
virtual ~FUNCTIONOBJECT() = default;
// Member Functions
......
......@@ -28,52 +28,88 @@ Namespace
Foam::functionObjects
Description
Namespace for functionObjects.
OpenFOAM includes a collection of functionObjects selected by the user at
run-time to manipulate the simulation and provide mechanisms to extract
field and derived quantities. Alternatively, the same actions can be
executed after the simulation using the \c -postProcess command-line option.
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 \c wallShearStress function object output
in \c fieldAverage function object to produce \c wallShearStressMean field).
\section secFunctionObjects Using function objects
FunctionObjects are selected by additional entries in the global case
system/controlDict dictionary. Each object is listed in the \c
functions sub-dictionary, e.g. to select the \c functionObjectType
functionObject the following entry would be specified:
Function objects can be executed by using two methods:
- \c functions sub-dictionary in the \c system/controlDict file
- \c postProcess command-line utility
For the first method, each selected function object should be listed inside
\c functions sub-dictionary of the \c system/controlDict file as a nested