PICurv 0.1.0
A Parallel Particle-In-Cell Solver for Curvilinear LES
 
Loading...
Searching...
No Matches
Functions
statistics_config.h File Reference

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:

Go to the source code of this file.

Functions

PetscErrorCode ParseFieldStatisticsConfig (SimCtx *simCtx)
 Resolves field-statistics configuration from the control file.
 
PetscErrorCode ParsePostStatisticsEnsembles (SimCtx *simCtx)
 Resolves the statistics ensembles a post-processing recipe defines.
 
PetscErrorCode DestroyFieldStatisticsConfig (SimCtx *simCtx)
 Releases the window definitions resolved by ParseFieldStatisticsConfig() and the ensembles resolved by ParsePostStatisticsEnsembles().
 

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]simCtxSimulation 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 393 of file statistics_config.c.

394{
395 PetscInt window_count = 0;
396 PetscBool found = PETSC_FALSE;
397
398 PetscFunctionBeginUser;
400 PetscCheck(simCtx != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "SimCtx cannot be NULL.");
401
402 PetscCall(PetscOptionsGetInt(NULL, NULL, "-statistics_console_output_freq",
403 &simCtx->statisticsConsoleOutputFreq, NULL));
404 PetscCall(PetscOptionsGetBool(NULL, NULL, "-field_statistics_enabled",
405 &simCtx->fieldStatisticsEnabled, NULL));
406 if (!simCtx->fieldStatisticsEnabled) {
407 LOG_ALLOW(GLOBAL, LOG_DEBUG, "Field statistics are disabled.\n");
409 PetscFunctionReturn(0);
410 }
411
412 PetscCall(PetscOptionsGetInt(NULL, NULL, "-field_statistics_window_count", &window_count, &found));
413 PetscCheck(found && window_count > 0, PETSC_COMM_WORLD, PETSC_ERR_ARG_WRONG,
414 "Field statistics are enabled but no window is configured.");
415 PetscCall(PetscCalloc1((size_t)window_count, &simCtx->fieldStatisticsWindows));
416 simCtx->fieldStatisticsWindowCount = window_count;
417
418 for (PetscInt window_index = 0; window_index < window_count; ++window_index) {
419 PicurvWindowDefinition definition;
420 char option_name[STATISTICS_OPTION_NAME_LENGTH];
421
422 PetscCall(PetscMemzero(&definition, sizeof(definition)));
423 PetscCall(PetscSNPrintf(option_name, sizeof(option_name),
424 "-field_statistics_window_%" PetscInt_FMT "_name", window_index));
425 PetscCall(PetscOptionsGetString(NULL, NULL, option_name, definition.name,
426 sizeof(definition.name), &found));
427 PetscCheck(found && definition.name[0] != '\0', PETSC_COMM_WORLD, PETSC_ERR_ARG_WRONG,
428 "Statistics window %" PetscInt_FMT " has no name.", window_index);
429
430 /* A duplicate name would make two windows indistinguishable in the
431 * checkpoint, where window state is matched by name on restart. */
432 for (PetscInt prior = 0; prior < window_index; ++prior) {
433 PetscBool clash = PETSC_FALSE;
434
435 PetscCall(PetscStrcmp(simCtx->fieldStatisticsWindows[prior].definition.name,
436 definition.name, &clash));
437 PetscCheck(!clash, PETSC_COMM_WORLD, PETSC_ERR_ARG_WRONG,
438 "Statistics window name '%s' is used more than once; names identify saved "
439 "state across a restart and must be unique.", definition.name);
440 }
441
442 PetscCall(ParseStatisticsWindowSchedule(window_index, &definition));
443 PetscCall(ParseStatisticsFields("window", window_index, PETSC_FALSE, &definition));
444 PetscCall(ParseStatisticsCovariances("window", window_index, PETSC_FALSE, &definition));
445 PetscCall(PicurvWindowInit(&simCtx->fieldStatisticsWindows[window_index], &definition));
446 PetscCall(LogResolvedWindow(&simCtx->fieldStatisticsWindows[window_index].definition));
447 }
448
449 LOG_ALLOW(GLOBAL, LOG_INFO, "Field statistics resolved %d window(s).\n", (int)window_count);
451 PetscFunctionReturn(0);
452}
#define GLOBAL
Scope for global logging across all processes.
Definition logging.h:46
#define LOG_ALLOW(scope, level, fmt,...)
Logging macro that checks both the log level and whether the calling function is in the allowed-funct...
Definition logging.h:214
#define PROFILE_FUNCTION_END
Marks the end of a profiled code block.
Definition logging.h:1029
@ LOG_INFO
Informational messages about program execution.
Definition logging.h:31
@ LOG_DEBUG
Detailed debugging information.
Definition logging.h:32
#define PROFILE_FUNCTION_BEGIN
Marks the beginning of a profiled function: an always-on aggregate timer.
Definition logging.h:1000
#define STATISTICS_OPTION_NAME_LENGTH
Longest constructed option name this module builds.
static PetscErrorCode LogResolvedWindow(const PicurvWindowDefinition *definition)
Internal helper: reports one resolved window definition to the log.
static PetscErrorCode ParseStatisticsFields(const char *kind, PetscInt window, PetscBool particle_source, PicurvWindowDefinition *definition)
Internal helper: reads one window's field list into its definition.
static PetscErrorCode ParseStatisticsWindowSchedule(PetscInt window, PicurvWindowDefinition *definition)
Internal helper: reads one window's scheduling and weighting properties.
static PetscErrorCode ParseStatisticsCovariances(const char *kind, PetscInt window, PetscBool particle_source, PicurvWindowDefinition *definition)
Internal helper: reads one window's covariance list into its definition.
PetscErrorCode PicurvWindowInit(PicurvWindow *window, const PicurvWindowDefinition *definition)
Validates a definition and initializes a window to the pending state.
PicurvWindowDefinition definition
The scientifically immutable definition of one window.
PetscInt fieldStatisticsWindowCount
Definition variables.h:989
PetscInt statisticsConsoleOutputFreq
Definition variables.h:991
PetscBool fieldStatisticsEnabled
Definition variables.h:988
struct PicurvWindow * fieldStatisticsWindows
Definition variables.h:990
Here is the call graph for this function:
Here is the caller graph for this function:

◆ ParsePostStatisticsEnsembles()

PetscErrorCode ParsePostStatisticsEnsembles ( SimCtx *  simCtx)

Resolves the statistics ensembles a post-processing recipe defines.

An ensemble is a window over one instant instead of over time: its samples are the particles in each cell (source particles) or the single state of each cell (source eulerian) at the step being processed. Its fields and covariances use the run windows' option families under the ensemble kind, which the recipe parser forwards from the post-processing file. A particle field is named by its particle name and resolved to the Eulerian field it scatters to.

Parameters
[in,out]simCtxContext whose post-processing parameters receive the ensembles; run windows must already be resolved, since names may not clash.
Returns
Zero on success, or a PETSc error for a malformed definition.

Resolves the statistics ensembles a post-processing recipe defines.

See also
ParsePostStatisticsEnsembles()

Definition at line 317 of file statistics_config.c.

318{
319 PostProcessParams *pps = NULL;
320 PetscInt count = 0;
321 PetscBool found = PETSC_FALSE;
322
323 PetscFunctionBeginUser;
325 PetscCheck(simCtx != NULL && simCtx->pps != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
326 "SimCtx and its post-processing parameters are required.");
327 pps = simCtx->pps;
328 PetscCall(PetscOptionsGetInt(NULL, NULL, "-field_statistics_ensemble_count", &count, &found));
329 if (!found || count <= 0) { PROFILE_FUNCTION_END; PetscFunctionReturn(0); }
330 PetscCall(PetscCalloc2((size_t)count, &pps->field_statistics_ensembles,
331 (size_t)count, &pps->field_statistics_ensemble_from_particles));
333
334 for (PetscInt index = 0; index < count; ++index) {
335 PicurvWindowDefinition definition;
336 char option_name[STATISTICS_OPTION_NAME_LENGTH];
338 PetscBool from_particles = PETSC_FALSE;
339
340 PetscCall(PetscMemzero(&definition, sizeof(definition)));
341 PetscCall(PetscSNPrintf(option_name, sizeof(option_name),
342 "-field_statistics_ensemble_%" PetscInt_FMT "_name", index));
343 PetscCall(PetscOptionsGetString(NULL, NULL, option_name, definition.name,
344 sizeof(definition.name), &found));
345 PetscCheck(found && definition.name[0] != '\0', PETSC_COMM_WORLD, PETSC_ERR_ARG_WRONG,
346 "Statistics ensemble %" PetscInt_FMT " has no name.", index);
347 /* Ensembles and run windows write to the same file names. */
348 for (PetscInt w = 0; w < simCtx->fieldStatisticsWindowCount; ++w) {
349 PetscBool clash = PETSC_FALSE;
350
351 PetscCall(PetscStrcmp(simCtx->fieldStatisticsWindows[w].definition.name, definition.name, &clash));
352 PetscCheck(!clash, PETSC_COMM_WORLD, PETSC_ERR_ARG_WRONG,
353 "Statistics ensemble '%s' has the name of a run window.", definition.name);
354 }
355 for (PetscInt prior = 0; prior < index; ++prior) {
356 PetscBool clash = PETSC_FALSE;
357
358 PetscCall(PetscStrcmp(pps->field_statistics_ensembles[prior].definition.name, definition.name, &clash));
359 PetscCheck(!clash, PETSC_COMM_WORLD, PETSC_ERR_ARG_WRONG,
360 "Statistics ensemble name '%s' is used more than once.", definition.name);
361 }
362
363 PetscCall(PetscSNPrintf(option_name, sizeof(option_name),
364 "-field_statistics_ensemble_%" PetscInt_FMT "_source", index));
365 PetscCall(PetscOptionsGetString(NULL, NULL, option_name, source, sizeof(source), &found));
366 PetscCheck(found && (!strcmp(source, "particles") || !strcmp(source, "eulerian")),
367 PETSC_COMM_WORLD, PETSC_ERR_ARG_WRONG,
368 "Statistics ensemble '%s' needs source 'particles' or 'eulerian'.", definition.name);
369 from_particles = (PetscBool)!strcmp(source, "particles");
370
371 /* An ensemble is one instant, so it has no schedule of its own; the unit step
372 * cadence only satisfies the window validation it shares. */
375 definition.step_cadence = 1;
376 PetscCall(ParseStatisticsFields("ensemble", index, from_particles, &definition));
377 PetscCall(ParseStatisticsCovariances("ensemble", index, from_particles, &definition));
378 PetscCall(PicurvWindowInit(&pps->field_statistics_ensembles[index], &definition));
379 pps->field_statistics_ensemble_from_particles[index] = from_particles;
380 LOG_ALLOW(GLOBAL, LOG_INFO, "Statistics ensemble '%s' from %s: %d field(s), %d covariance(s).\n",
381 definition.name, source, (int)definition.field_count, (int)definition.covariance_count);
382 }
384 PetscFunctionReturn(0);
385}
#define STATISTICS_OPTION_VALUE_LENGTH
Longest option value this module reads, sized for a moment or pair list.
PicurvCadenceKind cadence_kind
PetscInt step_cadence
Used when cadence_kind is step; must be positive.
@ PICURV_WEIGHTING_SAMPLE
Equal weight per accepted state.
@ PICURV_CADENCE_STEP
Every n completed steps from activation.
struct PicurvWindow * field_statistics_ensembles
Definition variables.h:835
PetscBool * field_statistics_ensemble_from_particles
Whether each ensemble samples the particles in a cell rather than the cell's state.
Definition variables.h:837
PetscInt field_statistics_ensemble_count
Recipe-defined single-instant windows, derived at every processed step.
Definition variables.h:834
PostProcessParams * pps
Definition variables.h:1131
Holds all configuration parameters for a post-processing run.
Definition variables.h:793
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() and the ensembles resolved by ParsePostStatisticsEnsembles().

Parameters
[in,out]simCtxSimulation context to clear; safe when nothing was resolved.
Returns
Zero on success.

Releases the window definitions resolved by ParseFieldStatisticsConfig() and the ensembles resolved by ParsePostStatisticsEnsembles().

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

See also
DestroyFieldStatisticsConfig()

Definition at line 460 of file statistics_config.c.

461{
462 PetscFunctionBeginUser;
464 if (!simCtx) { PROFILE_HELPER_END; PetscFunctionReturn(0); }
465 if (simCtx->pps && simCtx->pps->field_statistics_ensembles) {
466 PetscCall(PetscFree2(simCtx->pps->field_statistics_ensembles,
469 }
470 if (!simCtx->fieldStatisticsWindows) { PROFILE_HELPER_END; PetscFunctionReturn(0); }
471 PetscCall(PetscFree(simCtx->fieldStatisticsWindows));
472 simCtx->fieldStatisticsWindows = NULL;
473 simCtx->fieldStatisticsWindowCount = 0;
475 PetscFunctionReturn(0);
476}
#define PROFILE_HELPER_BEGIN
Marks the beginning of a profiled helper: timed only when enabled by name.
Definition logging.h:1014
#define PROFILE_HELPER_END
Alias of PROFILE_FUNCTION_END for a function that began with PROFILE_HELPER_BEGIN.
Definition logging.h:1033
Here is the caller graph for this function: