• Henry Weller's avatar
    postProcessing: Replaced 'foamCalc' and the 'postCalc' utilities · 8b672f0f
    Henry Weller authored
    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.
    8b672f0f