Control ingress for the field-statistics pipeline. More...

#include "variables.h"

Include dependency graph for statistics_config.h:

This graph shows which files directly or indirectly include this file:

Functions
PetscErrorCode	ParseFieldStatisticsConfig (SimCtx *simCtx)
	Resolves field-statistics configuration from the control file.

PetscErrorCode	DestroyFieldStatisticsConfig (SimCtx *simCtx)
	Releases the window definitions resolved by ParseFieldStatisticsConfig().

Detailed Description

Control ingress for the field-statistics pipeline.

Resolves the generated master control into the window definitions the rest of the pipeline consumes. The user-facing keys these options come from are documented in 3. field_statistics.

A window list is variable arity, so its option names are constructed rather than literal. Every constructed name belongs to a family declared in the ingress audit manifest, which is what keeps the audit's guarantee intact rather than opening a hole in it.

This module owns only configuration. It creates no PETSc vectors: the accumulator factory runs later and sizes itself from the definitions resolved here.

Definition in file statistics_config.h.

Function Documentation

◆ ParseFieldStatisticsConfig()

PetscErrorCode ParseFieldStatisticsConfig ( SimCtx * simCtx )

Resolves field-statistics configuration from the control file.

Reads the option families, resolves every field name through the typed catalog, validates each definition through PicurvWindowInit, and stores the resulting windows on the context. Each resolved definition is reported at LOG_INFO through LOG_ALLOW, so it carries the usual dual gate and is surfaced by allow-listing the emitting function. Whether statistics were active at all is recorded unconditionally by the startup banner.

Leaves the context untouched when statistics are disabled or no window is configured, so a run that does not ask for statistics allocates nothing.

Must run before CreateAndInitializeAllVectors, which sizes the per-window accumulators from the window count resolved here.

Parameters

[in,out] simCtx Simulation context to populate.

Returns: Zero on success, or a PETSc error for a malformed or inconsistent configuration. Python validation rejects these earlier with better messages; these checks guard a hand-written control file.

Resolves field-statistics configuration from the control file.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/statistics_config.h.

See also: ParseFieldStatisticsConfig()

Definition at line 291 of file statistics_config.c.

{
    PetscInt window_count = 0;
    PetscBool found = PETSC_FALSE;
 
    PetscFunctionBeginUser;
    PROFILE_FUNCTION_BEGIN;
    PetscCheck(simCtx != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "SimCtx cannot be NULL.");
 
    PetscCall(PetscOptionsGetInt(NULL, NULL, "-statistics_console_output_freq",
                                 &simCtx->statisticsConsoleOutputFreq, NULL));
    PetscCall(PetscOptionsGetBool(NULL, NULL, "-field_statistics_enabled",
                                  &simCtx->fieldStatisticsEnabled, NULL));
    if (!simCtx->fieldStatisticsEnabled) {
        LOG_ALLOW(GLOBAL, LOG_DEBUG, "Field statistics are disabled.\n");
        PROFILE_FUNCTION_END;
        PetscFunctionReturn(0);
    }
 
    PetscCall(PetscOptionsGetInt(NULL, NULL, "-field_statistics_window_count", &window_count, &found));
    PetscCheck(found && window_count > 0, PETSC_COMM_WORLD, PETSC_ERR_ARG_WRONG,
               "Field statistics are enabled but no window is configured.");
    PetscCall(PetscCalloc1((size_t)window_count, &simCtx->fieldStatisticsWindows));
    simCtx->fieldStatisticsWindowCount = window_count;
 
    for (PetscInt window_index = 0; window_index < window_count; ++window_index) {
        PicurvWindowDefinition definition;
        char option_name[STATISTICS_OPTION_NAME_LENGTH];
 
        PetscCall(PetscMemzero(&definition, sizeof(definition)));
        PetscCall(PetscSNPrintf(option_name, sizeof(option_name),
                                "-field_statistics_window_%" PetscInt_FMT "_name", window_index));
        PetscCall(PetscOptionsGetString(NULL, NULL, option_name, definition.name,
                                        sizeof(definition.name), &found));
        PetscCheck(found && definition.name[0] != '\0', PETSC_COMM_WORLD, PETSC_ERR_ARG_WRONG,
                   "Statistics window %" PetscInt_FMT " has no name.", window_index);
 
        /* A duplicate name would make two windows indistinguishable in the
         * checkpoint, where window state is matched by name on restart. */
        for (PetscInt prior = 0; prior < window_index; ++prior) {
            PetscBool clash = PETSC_FALSE;
 
            PetscCall(PetscStrcmp(simCtx->fieldStatisticsWindows[prior].definition.name,
                                  definition.name, &clash));
            PetscCheck(!clash, PETSC_COMM_WORLD, PETSC_ERR_ARG_WRONG,
                       "Statistics window name '%s' is used more than once; names identify saved "
                       "state across a restart and must be unique.", definition.name);
        }
 
        PetscCall(ParseStatisticsWindowSchedule(window_index, &definition));
        PetscCall(ParseStatisticsFields(window_index, &definition));
        PetscCall(ParseStatisticsCovariances(window_index, &definition));
        PetscCall(PicurvWindowInit(&simCtx->fieldStatisticsWindows[window_index], &definition));
        PetscCall(LogResolvedWindow(&simCtx->fieldStatisticsWindows[window_index].definition));
    }
 
    LOG_ALLOW(GLOBAL, LOG_INFO, "Field statistics resolved %d window(s).\n", (int)window_count);
    PROFILE_FUNCTION_END;
    PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

◆ DestroyFieldStatisticsConfig()

PetscErrorCode DestroyFieldStatisticsConfig ( SimCtx * simCtx )

Releases the window definitions resolved by ParseFieldStatisticsConfig().