createTurbulenceFields: utility replaced by 'turbulenceFields' functionObject used with the '-postProcess' option

Replaces the dictionary access functionality of foamInfoExec and
provides additional options to edit individual entries.
Contributed by Mattijs Janssens

for consistency with the 'Log' macro.

Patch contributed by Mattijs Janssens
Resolves bug-report http://bugs.openfoam.org/view.php?id=2057

Resolves patch request http://bugs.openfoam.org/view.php?id=2103
Patch contributed by Mattijs Janssens

Resolves bug-report http://bugs.openfoam.org/view.php?id=2104

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.

In most boundary conditions, fvOptions etc. required and optional fields
to be looked-up from the objectRegistry are selected by setting the
keyword corresponding to the standard field name in the BC etc. to the
appropriate name in the objectRegistry.  Usually a default is provided
with sets the field name to the keyword name, e.g. in the
totalPressureFvPatchScalarField the velocity is selected by setting the
keyword 'U' to the appropriate name which defaults to 'U':

        Property     | Description             | Required    | Default value
        U            | velocity field name     | no          | U
        phi          | flux field name         | no          | phi
        .
        .
        .

However, in some BCs and functionObjects and many fvOptions another
convention is used in which the field name keyword is appended by 'Name'
e.g.

        Property     | Description             | Required    | Default value
        pName        | pressure field name     | no          | p
        UName        | velocity field name     | no          | U

This difference in convention is unnecessary and confusing, hinders code
and dictionary reuse and complicates code maintenance.  In this commit
the appended 'Name' is removed from the field selection keywords
standardizing OpenFOAM on the first convention above.

functionObjects, foamCalcFunctions, fvOptions: Standardized keywords for selecting fields and objects

Generally fields and objects are selected using the 'field[s]' and
'object[s]' keywords but this was not consistent between all
functionObject, fvOptions etc. and now fixed by applying the following
renaming:

fieldName -> field
fieldNames -> fields
objectName -> object
objectNames -> objects

   the equivalent functionality is provided by the writeRegisteredObject
   functionObject in a MUCH simpler, easier and extensible manner.

functionObject: Removed the now redundant 'timeSet' function.

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.

  - 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'.

splitMeshRegions: handle flipping of faces for surface fields

subsetMesh: subset dimensionedFields

decomposePar: use run-time selection of decomposition constraints. Used to
    keep cells on particular processors. See the decomposeParDict in

$FOAM_UTILITIES/parallel/decomposePar:
  - preserveBaffles: keep baffle faces on same processor
  - preserveFaceZones: keep faceZones owner and neighbour on same processor
  - preservePatches: keep owner and neighbour on same processor. Note: not
    suitable for cyclicAMI since these are not coupled on the patch level
  - singleProcessorFaceSets: keep complete faceSet on a single processor
  - refinementHistory: keep cells originating from a single cell on the
    same processor.

decomposePar: clean up decomposition of refinement data from snappyHexMesh

reconstructPar: reconstruct refinement data (refineHexMesh, snappyHexMesh)

reconstructParMesh: reconstruct refinement data (refineHexMesh, snappyHexMesh)

redistributePa...

All patches are preserved if the 'keepPatches' option is set true.
Patch contributed by Mattijs Janssens

Patch contributed by Mattijs Janssens
Resolves bug-report http://bugs.openfoam.org/view.php?id=2088

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.

functionObjects: Changed options 'outputControl' -> 'writeControl' and 'outputInterval' -> 'writeInterval'

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.

Construction failure and recovery is not handled with exceptions in functionObjectList

Description
    This functionObject writes objects registered to the database in VTK format
    using the foamToVTK library.

    Currently only the writing of the cell-values of volFields is supported but
    support for other field types, patch fields, Lagrangian data etc. will be
    added.

    Example of function object specification:
    \verbatim
        writeVTK1
        {
            type        writeVTK;
            functionObjectLibs ("libIOFunctionObjects.so");
            ...
            objectNames (obj1 obj2);
        }
    \endverbatim

    \heading Function object usage
    \table
        Property     | Description             | Required    | Default value
        type         | type name: writeVTK     | yes         |
        objectNames  | objects to write        | yes         |
    \endtable

applications/solvers/heatTransfer/chtMultiRegionFoam: Check there are fluid meshes present for the '-postProcess' option

execFlowFunctionObjects: Replaced with script providing instructions to use the '-postProcess' option

See also commit 30e2f912

to ensure MRF functionality is available for the -postProcess option

See also commit 30e2f912

See also commit 30e2f912

See also commit 30e2f912

See also commit 30e2f912