Draft: ENH: fieldStatistics: New function object for statistics of input fields (!732) · Merge requests · Development / openfoam

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

Open Kutalmış Berçin requested to merge feature-field-statistics into develop 3 weeks ago

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.