Draft: ENH: fieldStatistics: New function object for statistics of input fields

Summary

This update introduces a new function object, fieldStatistics, which is expected to replace the fieldMinMax function object in future releases.

Details of new models

A typical example of the new keywords is as follows:

fieldStatistics
{
    // Mandatory entries
    type            fieldStatistics;
    libs            (fieldFunctionObjects);
    fields          (p U k Co);
    statistics      (mean variance min max);

    // Optional entries
    mode            magnitude;  // component;
    mean            arithmetic;  // volumetric;
    extrema         true;
    internal        false;

    // Inherited entries
    writePrecision  8;
    writeToFile      true;
    useUserTime      true;

    region          region0;
    enabled         true;
    log             true;
    timeStart       0;
    timeEnd         1000;
    executeControl  timeStep;
    executeInterval 1;
    writeControl    writeTime;
    writeInterval   1;
}

The following functionalities can be highlighted:

• The fieldMinMax functionality, i.e. providing the extrema values of the input fields and their metadata, can be reproduced by the optional bool keyword extrema.
• The internal fields, i.e. excluding the boundary fields, are handled by the optional bool keyword internal.
• Two different averaging routines can be chosen, i.e. arithmetic and volumetric, by the keyword mean.
• Four statistics of the input fields can be calculated:
  • Central-tendency statistics: mean.
  • Dispersion statistics: variance, min, max.
• The statistics are output to a file per input field and to the standard stream with uniform delimiter.

Risks

• When using mode=magnitude, the fieldStatistics function object (FO) calculates the statistics of the magnitude of the input fields, rather than the magnitude of the statistics of the input fields. The effect of mode=magnitude in the fieldMinMax FO differs in that mode=magnitude and mode=component behave identically for scalar fields.
  • For example, in a scalar field with two values, -1 and 1, the fieldMinMax FO with either mode=magnitude or mode=component produces min=-1. This happens because, for scalar fields, the mode is always treated as component, even if mode=magnitude is input.
  • However, in fieldStatistics's backward-compatibility for fieldMinMax by setting the extrema=true, this behavior is different:
    • With mode=magnitude, the minimum value is computed as min=1.
    • With mode=component, the minimum value is computed as min=-1 for the scalar field.
• Unlike the fieldMinMax, the fieldStatistics's backward-compatibility for fieldMinMax outputs the extrema data per field, rather than a single file for all fields.
• Stable algorithms for the calculation of variance need to be investigated.