PICurv 0.1.0
A Parallel Particle-In-Cell Solver for Curvilinear LES
 
Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Enumerations | Functions
statistics_window.h File Reference

Window lifecycle, scheduling, and weighting for the field-statistics pipeline. More...

#include <petscsys.h>
Include dependency graph for statistics_window.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  PicurvWindowFieldRequest
 One field a window accumulates. More...
 
struct  PicurvWindowCovarianceRequest
 One cross-field covariance a window accumulates. More...
 
struct  PicurvWindowDefinition
 The scientifically immutable definition of one window. More...
 
struct  PicurvWindow
 Runtime state of one window. More...
 

Macros

#define PICURV_WINDOW_NAME_LENGTH   64
 Maximum stored length of a window name, including the terminator.
 
#define PICURV_WINDOW_MAX_REQUESTS   16
 Maximum fields or covariance pairs one window may request.
 
#define PICURV_WINDOW_HASH_GROUP_COUNT   8
 Number of independently hashed property groups in a window definition.
 
#define PICURV_WINDOW_HASH_GROUP_LENGTH   17
 Stored length of one truncated group digest, including the terminator.
 

Typedefs

typedef struct PicurvWindow PicurvWindow
 Runtime state of one window.
 

Enumerations

enum  PicurvWindowState { PICURV_WINDOW_PENDING = 0 , PICURV_WINDOW_ACTIVE , PICURV_WINDOW_COMPLETE }
 Lifecycle state of one window. More...
 
enum  PicurvWeighting { PICURV_WEIGHTING_SAMPLE = 0 , PICURV_WEIGHTING_PHYSICAL_TIME }
 How an accepted state's weight is determined. More...
 
enum  PicurvCadenceKind { PICURV_CADENCE_STEP = 0 , PICURV_CADENCE_TIME }
 Which schedule selects due states. More...
 

Functions

PetscErrorCode PicurvWindowInit (PicurvWindow *window, const PicurvWindowDefinition *definition)
 Validates a definition and initializes a window to the pending state.
 
PetscErrorCode PicurvWindowOfferState (PicurvWindow *window, PetscInt step, PetscReal time, PetscBool *accepted, PetscReal *weight)
 Offers one completed state to a window and reports the decision.
 
PetscErrorCode PicurvWindowComputeHash (const PicurvWindowDefinition *definition, char digest_hex[65], char group_digest_hex[][17])
 Computes the resolved identity hash of one window definition.
 
PetscErrorCode PicurvWindowFirstHashDifference (const PicurvWindowDefinition *definition, const char *saved_group_digests, PetscInt *group)
 Reports which hashed property group first differs from saved group digests.
 
const char * PicurvWindowHashGroupName (PetscInt group)
 Returns the stable name of one hashed property group.
 
PetscReal PicurvWindowProgress (const PicurvWindow *window)
 Reports the fraction of a bounded window's span that has been represented.
 
const char * PicurvWindowStateName (PicurvWindowState state)
 Returns a stable human-readable name for a window state.
 
PetscBool FieldStatisticsIsActive (const struct SimCtx *simCtx)
 Reports whether this run has live field-statistics state.
 
PetscBool FieldStatisticsNeedsWorkspace (const struct SimCtx *simCtx)
 Reports whether this process derives field statistics of any kind.
 
PetscErrorCode FieldStatisticsUpdateWindows (struct SimCtx *simCtx, PetscInt step, PetscReal time)
 Offers one completed state to every configured window.
 

Detailed Description

Window lifecycle, scheduling, and weighting for the field-statistics pipeline.

Implements the window semantics described in 2. Windows and 3. Weighting and Quadrature — right-rectangle weighting, final-interval clipping, and the rule that a state representing a zero-length interval is not a sample.

This module decides whether a completed state is accepted and what weight it carries. It holds no PETSc objects and performs no field accumulation; the caller applies the returned weight through the moment kernels.

Definition in file statistics_window.h.


Data Structure Documentation

◆ PicurvWindowFieldRequest

struct PicurvWindowFieldRequest

One field a window accumulates.

The first moment is always kept.

Definition at line 47 of file statistics_window.h.

Data Fields
PetscInt field_id Catalogued Eulerian field identity.
PetscBool want_second Also keep the centered second moment.

◆ PicurvWindowCovarianceRequest

struct PicurvWindowCovarianceRequest

One cross-field covariance a window accumulates.

Definition at line 53 of file statistics_window.h.

Data Fields
PetscInt first First member; must also appear in the field list.
PetscInt second Second member; must also appear in the field list.

◆ PicurvWindowDefinition

struct PicurvWindowDefinition

The scientifically immutable definition of one window.

Definition at line 59 of file statistics_window.h.

Collaboration diagram for PicurvWindowDefinition:
[legend]
Data Fields
char name[64]
PetscReal start_time Requested start.
PetscReal end_time Requested end; ignored when bounded is false.
PetscBool bounded False for an open-ended window.
PicurvWeighting weighting
PicurvCadenceKind cadence_kind
PetscInt step_cadence Used when cadence_kind is step; must be positive.
PetscReal time_cadence Used when cadence_kind is time; must be positive.
PetscInt field_count
PicurvWindowFieldRequest fields[16]
PetscInt covariance_count
PicurvWindowCovarianceRequest covariances[16]

◆ PicurvWindow

struct PicurvWindow

Runtime state of one window.

Definition at line 75 of file statistics_window.h.

Collaboration diagram for PicurvWindow:
[legend]
Data Fields
PicurvWindowDefinition definition
PicurvWindowState state
PetscReal effective_start Origin of the first represented interval.
PetscReal effective_end End of the last represented interval.
PetscReal last_accepted_time Right edge of the last represented interval.
PetscInt sample_count
PetscReal total_weight
PetscReal represented_time Physical time the window covers.
PetscInt activation_step Step at which the window became active.
PetscInt last_event_step Guards against a step being offered twice.
PetscInt next_time_target k in effective_start + k*time_cadence.
PetscInt restart_count Restart segments this state descends from.

Macro Definition Documentation

◆ PICURV_WINDOW_NAME_LENGTH

#define PICURV_WINDOW_NAME_LENGTH   64

Maximum stored length of a window name, including the terminator.

Definition at line 22 of file statistics_window.h.

◆ PICURV_WINDOW_MAX_REQUESTS

#define PICURV_WINDOW_MAX_REQUESTS   16

Maximum fields or covariance pairs one window may request.

Definition at line 44 of file statistics_window.h.

◆ PICURV_WINDOW_HASH_GROUP_COUNT

#define PICURV_WINDOW_HASH_GROUP_COUNT   8

Number of independently hashed property groups in a window definition.

Definition at line 125 of file statistics_window.h.

◆ PICURV_WINDOW_HASH_GROUP_LENGTH

#define PICURV_WINDOW_HASH_GROUP_LENGTH   17

Stored length of one truncated group digest, including the terminator.

Definition at line 128 of file statistics_window.h.

Typedef Documentation

◆ PicurvWindow

typedef struct PicurvWindow PicurvWindow

Runtime state of one window.

Enumeration Type Documentation

◆ PicurvWindowState

Lifecycle state of one window.

Enumerator
PICURV_WINDOW_PENDING 

Requested start not yet reached.

PICURV_WINDOW_ACTIVE 

Accepting due states.

PICURV_WINDOW_COMPLETE 

Bounded end reached; accepts nothing further.

Definition at line 25 of file statistics_window.h.

25 {
26 PICURV_WINDOW_PENDING = 0, /**< Requested start not yet reached. */
27 PICURV_WINDOW_ACTIVE, /**< Accepting due states. */
28 PICURV_WINDOW_COMPLETE /**< Bounded end reached; accepts nothing further. */
PicurvWindowState
Lifecycle state of one window.
@ PICURV_WINDOW_PENDING
Requested start not yet reached.
@ PICURV_WINDOW_COMPLETE
Bounded end reached; accepts nothing further.
@ PICURV_WINDOW_ACTIVE
Accepting due states.

◆ PicurvWeighting

How an accepted state's weight is determined.

Enumerator
PICURV_WEIGHTING_SAMPLE 

Equal weight per accepted state.

PICURV_WEIGHTING_PHYSICAL_TIME 

Weight is the represented interval.

Definition at line 32 of file statistics_window.h.

32 {
33 PICURV_WEIGHTING_SAMPLE = 0, /**< Equal weight per accepted state. */
34 PICURV_WEIGHTING_PHYSICAL_TIME /**< Weight is the represented interval. */
PicurvWeighting
How an accepted state's weight is determined.
@ PICURV_WEIGHTING_PHYSICAL_TIME
Weight is the represented interval.
@ PICURV_WEIGHTING_SAMPLE
Equal weight per accepted state.

◆ PicurvCadenceKind

Which schedule selects due states.

Exactly one is used.

Enumerator
PICURV_CADENCE_STEP 

Every n completed steps from activation.

PICURV_CADENCE_TIME 

First state at or past each nominal time target.

Definition at line 38 of file statistics_window.h.

38 {
39 PICURV_CADENCE_STEP = 0, /**< Every n completed steps from activation. */
40 PICURV_CADENCE_TIME /**< First state at or past each nominal time target. */
PicurvCadenceKind
Which schedule selects due states.
@ PICURV_CADENCE_TIME
First state at or past each nominal time target.
@ PICURV_CADENCE_STEP
Every n completed steps from activation.

Function Documentation

◆ PicurvWindowInit()

PetscErrorCode PicurvWindowInit ( PicurvWindow *  window,
const PicurvWindowDefinition *  definition 
)

Validates a definition and initializes a window to the pending state.

Parameters
[out]windowWindow to initialize.
[in]definitionRequested definition; copied into the window.
Returns
Zero on success, or PETSC_ERR_ARG_OUTOFRANGE for a non-positive cadence, an empty name, or a bounded window whose end does not exceed its start.

Validates a definition and initializes a window to the pending state.

See also
PicurvWindowInit()

Definition at line 39 of file statistics_window.c.

40{
41 PetscFunctionBeginUser;
43 PetscCheck(window != NULL && definition != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
44 "Window and definition are required.");
45 PetscCheck(definition->name[0] != '\0', PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE,
46 "Window name must not be empty.");
47 if (definition->cadence_kind == PICURV_CADENCE_STEP) {
48 PetscCheck(definition->step_cadence > 0, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE,
49 "Window '%s' needs a positive step cadence, got %" PetscInt_FMT ".",
50 definition->name, definition->step_cadence);
51 } else {
52 PetscCheck(definition->time_cadence > 0.0, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE,
53 "Window '%s' needs a positive time cadence, got %g.",
54 definition->name, (double)definition->time_cadence);
55 }
56 PetscCheck(!definition->bounded || definition->end_time > definition->start_time,
57 PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE,
58 "Window '%s' must end after it starts.", definition->name);
59
60 PetscCall(PetscMemzero(window, sizeof(*window)));
61 window->definition = *definition;
63 /* Anchoring the interval origin at the requested start, rather than at the
64 * first accepted state, is what lets the first sample represent the interval
65 * back to the requested bound instead of silently dropping it. */
66 window->effective_start = definition->start_time;
67 window->effective_end = definition->start_time;
68 window->last_accepted_time = definition->start_time;
69 window->activation_step = -1;
70 window->last_event_step = PETSC_MIN_INT;
71 window->next_time_target = 0;
73 PetscFunctionReturn(0);
74}
#define PROFILE_FUNCTION_END
Marks the end of a profiled code block.
Definition logging.h:1029
#define PROFILE_FUNCTION_BEGIN
Marks the beginning of a profiled function: an always-on aggregate timer.
Definition logging.h:1000
PetscInt last_event_step
Guards against a step being offered twice.
PetscReal effective_start
Origin of the first represented interval.
PetscReal last_accepted_time
Right edge of the last represented interval.
PicurvWindowState state
PetscReal time_cadence
Used when cadence_kind is time; must be positive.
PetscReal effective_end
End of the last represented interval.
PetscReal end_time
Requested end; ignored when bounded is false.
PicurvCadenceKind cadence_kind
PetscInt step_cadence
Used when cadence_kind is step; must be positive.
PetscBool bounded
False for an open-ended window.
PicurvWindowDefinition definition
PetscInt next_time_target
k in effective_start + k*time_cadence.
PetscReal start_time
Requested start.
PetscInt activation_step
Step at which the window became active.
Here is the caller graph for this function:

◆ PicurvWindowOfferState()

PetscErrorCode PicurvWindowOfferState ( PicurvWindow *  window,
PetscInt  step,
PetscReal  time,
PetscBool *  accepted,
PetscReal *  weight 
)

Offers one completed state to a window and reports the decision.

Applies the interval convention in full: the state carries the interval ending at it, measured from the previous accepted state or from the effective start; a zero-length interval is not a sample; and a bounded window clips its final interval to the requested end and then completes.

When accepted is returned true the window's bookkeeping has already been advanced, and the caller applies weight through the moment kernels. When it is false the window is scientifically unchanged.

Offering the same step twice is rejected, so a completed state cannot be counted more than once.

Parameters
[in,out]windowWindow to offer the state to.
[in]stepCompleted step number.
[in]timePhysical time of the completed state.
[out]acceptedWhether the state became a sample.
[out]weightWeight to apply; zero when not accepted.
Returns
Zero on success, or a PETSc error for a null argument.

Offers one completed state to a window and reports the decision.

See also
PicurvWindowOfferState()

Definition at line 123 of file statistics_window.c.

125{
126 PetscReal interval = 0.0;
127 PetscReal right_edge = 0.0;
128 PetscBool closes = PETSC_FALSE;
129
130 PetscFunctionBeginUser;
132 PetscCheck(window != NULL && accepted != NULL && weight != NULL,
133 PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
134 "Window, acceptance flag, and weight output are required.");
135 *accepted = PETSC_FALSE;
136 *weight = 0.0;
137
138 if (window->state == PICURV_WINDOW_COMPLETE) { PROFILE_FUNCTION_END; PetscFunctionReturn(0); }
139 /* A completed state is accepted at most once, so a step already seen is
140 * rejected outright rather than double counted. */
141 if (step == window->last_event_step) { PROFILE_FUNCTION_END; PetscFunctionReturn(0); }
142 if (time < window->definition.start_time - WINDOW_TIME_EPSILON) { PROFILE_FUNCTION_END; PetscFunctionReturn(0); }
143
144 /* First observation: a window resumed later than its requested start cannot
145 * claim represented time it never saw, so the origin moves forward. */
146 if (window->state == PICURV_WINDOW_PENDING) {
147 if (time > window->definition.start_time + WINDOW_TIME_EPSILON) {
148 window->effective_start = time;
149 window->last_accepted_time = time;
150 }
151 window->state = PICURV_WINDOW_ACTIVE;
152 window->activation_step = step;
153 window->effective_end = window->effective_start;
154 window->next_time_target = 0;
156 }
157
158 if (!WindowStateIsDue(window, step, time)) {
159 /* An active off-schedule state changes no scientific state. */
161 PetscFunctionReturn(0);
162 }
163 window->last_event_step = step;
164
165 /* Clip the final represented interval to the requested bound. */
166 right_edge = time;
167 if (window->definition.bounded && time >= window->definition.end_time - WINDOW_TIME_EPSILON) {
168 right_edge = window->definition.end_time;
169 closes = PETSC_TRUE;
170 }
171
172 interval = right_edge - window->last_accepted_time;
173 WindowAdvanceTimeTarget(window, time);
174
175 if (interval <= WINDOW_TIME_EPSILON) {
176 /* A zero-length interval is not a sample. It still anchors the origin, which
177 * is what makes initial-state handling identical under both weightings. */
178 window->last_accepted_time = right_edge;
179 window->effective_end = right_edge;
180 if (closes) window->state = PICURV_WINDOW_COMPLETE;
182 PetscFunctionReturn(0);
183 }
184
185 *weight = (window->definition.weighting == PICURV_WEIGHTING_SAMPLE) ? 1.0 : interval;
186 *accepted = PETSC_TRUE;
187
188 window->last_accepted_time = right_edge;
189 window->effective_end = right_edge;
190 window->sample_count += 1;
191 window->total_weight += *weight;
192 window->represented_time += interval;
193 if (closes) window->state = PICURV_WINDOW_COMPLETE;
195 PetscFunctionReturn(0);
196}
#define WINDOW_TIME_EPSILON
Tolerance for treating two physical times as the same instant.
static void WindowAdvanceTimeTarget(PicurvWindow *window, PetscReal time)
Internal helper: advances the time-cadence target past the accepted time.
static PetscBool WindowStateIsDue(const PicurvWindow *window, PetscInt step, PetscReal time)
Internal helper: reports whether a state is due under the window's schedule.
PetscInt sample_count
PetscReal total_weight
PetscReal represented_time
Physical time the window covers.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ PicurvWindowComputeHash()

PetscErrorCode PicurvWindowComputeHash ( const PicurvWindowDefinition *  definition,
char  digest_hex[65],
char  group_digest_hex[][17] 
)

Computes the resolved identity hash of one window definition.

Hashes the canonical serialization defined in 6. Window Identity and What May Change, in that fixed order, so a saved window can be matched against a resolved one without storing the definition itself.

end_time and the enabled flag are deliberately excluded, which is what lets a bounded window be extended forward and lets statistics be switched off and on without invalidating saved state.

Field and covariance entries are serialized in catalog order rather than the order the user listed them, so a reordered but otherwise identical configuration continues rather than being rejected.

Each property group is additionally hashed on its own. A restart that finds a mismatched full digest compares the group digests to name the first differing property, which a single digest could not do.

Parameters
[in]definitionWindow definition to hash.
[out]digest_hexFull 64-character digest plus terminator.
[out]group_digest_hexOptional per-group truncated digests; pass NULL to skip.
Returns
Zero on success, or a PETSc error for a null argument or unknown field.
Here is the caller graph for this function:

◆ PicurvWindowFirstHashDifference()

PetscErrorCode PicurvWindowFirstHashDifference ( const PicurvWindowDefinition *  definition,
const char *  saved_group_digests,
PetscInt *  group 
)

Reports which hashed property group first differs from saved group digests.

A checkpoint stores the group digests but never the definition itself, so this is what turns "two hashes differ" into a message naming the property that changed.

Parameters
[in]definitionResolved definition to compare against.
[in]saved_group_digestsComma-separated group digests from a checkpoint.
[out]groupFirst differing group index, or -1 when the saved digests match or are too malformed to compare.
Returns
Zero on success, or a PETSc error for a null argument or unknown field.

Reports which hashed property group first differs from saved group digests.

See also
PicurvWindowFirstHashDifference()

Definition at line 398 of file statistics_window.c.

401{
402 char digest[65];
404 const char *cursor = saved_group_digests;
405
406 PetscFunctionBeginUser;
408 PetscCheck(definition != NULL && group != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
409 "Definition and group output are required.");
410 *group = -1;
411 if (!saved_group_digests) { PROFILE_HELPER_END; PetscFunctionReturn(0); }
412 PetscCall(PicurvWindowComputeHash(definition, digest, current));
413
414 for (PetscInt index = 0; index < PICURV_WINDOW_HASH_GROUP_COUNT; ++index) {
415 const char *comma = strchr(cursor, ',');
416 const size_t length = comma ? (size_t)(comma - cursor) : strlen(cursor);
417 size_t expected = 0;
418
419 PetscCall(PetscStrlen(current[index], &expected));
420 /* Every well-formed digest is fixed width, so a short segment means the
421 * saved list is malformed rather than that this property changed. A
422 * malformed list localizes to nothing: reporting the wrong property would
423 * be worse than reporting none. */
424 if (length != expected) { PROFILE_HELPER_END; PetscFunctionReturn(0); }
425 if (strncmp(cursor, current[index], length)) {
426 *group = index;
428 PetscFunctionReturn(0);
429 }
430 if (!comma) { PROFILE_HELPER_END; PetscFunctionReturn(0); }
431 cursor = comma + 1;
432 }
434 PetscFunctionReturn(0);
435}
#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
PetscErrorCode PicurvWindowComputeHash(const PicurvWindowDefinition *definition, char digest_hex[65], char group_digest_hex[][PICURV_WINDOW_HASH_GROUP_LENGTH])
Implementation of PicurvWindowComputeHash().
#define PICURV_WINDOW_HASH_GROUP_COUNT
Number of independently hashed property groups in a window definition.
#define PICURV_WINDOW_HASH_GROUP_LENGTH
Stored length of one truncated group digest, including the terminator.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ PicurvWindowHashGroupName()

const char * PicurvWindowHashGroupName ( PetscInt  group)

Returns the stable name of one hashed property group.

Parameters
[in]groupGroup index in [0, PICURV_WINDOW_HASH_GROUP_COUNT).
Returns
Static string; "unknown" for an out-of-range index, never NULL.

Returns the stable name of one hashed property group.

See also
PicurvWindowHashGroupName()

Definition at line 207 of file statistics_window.c.

208{
210 if (group < 0 || group >= PICURV_WINDOW_HASH_GROUP_COUNT) { PROFILE_HELPER_END; return "unknown"; }
212 return kHashGroupNames[group];
213}
static const char *const kHashGroupNames[PICURV_WINDOW_HASH_GROUP_COUNT]
Stable names of the hashed property groups, in serialization order.
Here is the caller graph for this function:

◆ PicurvWindowProgress()

PetscReal PicurvWindowProgress ( const PicurvWindow *  window)

Reports the fraction of a bounded window's span that has been represented.

Parameters
[in]windowWindow to query.
Returns
Value in [0,1] for a bounded window, or zero for an open one.

Reports the fraction of a bounded window's span that has been represented.

See also
PicurvWindowProgress()

Definition at line 441 of file statistics_window.c.

442{
444 PetscReal span = 0.0;
445
446 if (window == NULL || !window->definition.bounded) { PROFILE_HELPER_END; return 0.0; }
447 span = window->definition.end_time - window->effective_start;
448 if (span <= 0.0) { PROFILE_HELPER_END; return 0.0; }
450 return PetscMin(1.0, window->represented_time / span);
451}
Here is the caller graph for this function:

◆ PicurvWindowStateName()

const char * PicurvWindowStateName ( PicurvWindowState  state)

Returns a stable human-readable name for a window state.

Parameters
[in]stateWindow lifecycle state.
Returns
Static string; never NULL.

Returns a stable human-readable name for a window state.

See also
PicurvWindowStateName()

Definition at line 23 of file statistics_window.c.

24{
26 switch (state) {
27 case PICURV_WINDOW_PENDING: PROFILE_FUNCTION_END; return "pending";
28 case PICURV_WINDOW_ACTIVE: PROFILE_FUNCTION_END; return "active";
29 case PICURV_WINDOW_COMPLETE: PROFILE_FUNCTION_END; return "complete";
30 default: PROFILE_FUNCTION_END; return "unknown";
31 }
33}
Here is the caller graph for this function:

◆ FieldStatisticsIsActive()

PetscBool FieldStatisticsIsActive ( const struct SimCtx *  simCtx)

Reports whether this run has live field-statistics state.

The subsystem is active only when it is enabled, at least one window is configured, and the window array exists. Every caller that touches window or accumulator state asks this rather than restating the condition, so the three parts cannot drift apart between the runloop, the checkpoint writer, and the console monitor.

Parameters
[in]simCtxSimulation context; may be NULL.
Returns
PETSC_TRUE when window state exists and may be touched.
Here is the caller graph for this function:

◆ FieldStatisticsNeedsWorkspace()

PetscBool FieldStatisticsNeedsWorkspace ( const struct SimCtx *  simCtx)

Reports whether this process derives field statistics of any kind.

True when run windows are active or the post-processing recipe defines ensembles. It gates the workspace both share: the symmetric-tensor DM their products live on and the staging fields their derived outputs pass through.

Parameters
[in]simCtxSimulation context; may be NULL.
Returns
PETSC_TRUE when the statistics workspace is needed.
Here is the caller graph for this function:

◆ FieldStatisticsUpdateWindows()

PetscErrorCode FieldStatisticsUpdateWindows ( SimCtx *  simCtx,
PetscInt  step,
PetscReal  time 
)

Offers one completed state to every configured window.

Called once per completed step from the runloop. Each due window advances its own bookkeeping independently; windows share the source state but never share accumulator state. Does nothing when field statistics are disabled or no window is configured, which is the case until configuration ingress exists.

Parameters
[in,out]simCtxSimulation context carrying the window array.
[in]stepCompleted step number.
[in]timePhysical time of the completed state.
Returns
Zero on success, or a PETSc error propagated from a window update.

Offers one completed state to every configured window.

See also
FieldStatisticsUpdateWindows()

Definition at line 482 of file statistics_window.c.

483{
484 PetscFunctionBeginUser;
486 PetscCheck(simCtx != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "SimCtx cannot be NULL.");
487 if (!FieldStatisticsIsActive(simCtx)) { PROFILE_FUNCTION_END; PetscFunctionReturn(0); }
488
489 for (PetscInt window_index = 0; window_index < simCtx->fieldStatisticsWindowCount; ++window_index) {
490 PicurvWindow *window = &simCtx->fieldStatisticsWindows[window_index];
491 const PicurvWindowState before = window->state;
492 PetscBool accepted = PETSC_FALSE;
493 PetscReal weight = 0.0;
494
495 PetscCall(PicurvWindowOfferState(window, step, time, &accepted, &weight));
496
497 if (before == PICURV_WINDOW_PENDING && window->state == PICURV_WINDOW_ACTIVE) {
499 "Statistics window '%s' active from t=%.6g.\n",
500 window->definition.name, (double)window->effective_start);
501 }
502 if (accepted) {
503 /* Apply the accepted weight to every block's accumulators. Windows share
504 * the source state but own independent accumulator state. */
505 for (PetscInt bi = 0; bi < simCtx->block_number; ++bi) {
506 UserCtx *user = &simCtx->usermg.mgctx[simCtx->usermg.mglevels - 1].user[bi];
507 if (!user->fieldStatisticsStorage) continue;
508 PetscCall(PicurvWindowAccumulate(user, &window->definition,
509 &user->fieldStatisticsStorage[window_index], weight));
510 }
512 "Statistics window '%s' accepted step %" PetscInt_FMT " at t=%.6g with weight %.6g "
513 "(samples=%" PetscInt_FMT ", represented=%.6g).\n",
514 window->definition.name, step, (double)time, (double)weight,
515 window->sample_count, (double)window->represented_time);
516 } else if (window->state == PICURV_WINDOW_ACTIVE) {
517 /* An active window that took nothing was either off schedule or offered a
518 * zero-length interval. Both are expected, so this is the level that
519 * explains a sample count without implying anything is wrong. */
521 "Statistics window '%s' did not sample step %" PetscInt_FMT " at t=%.6g "
522 "(last accepted t=%.6g, samples=%" PetscInt_FMT ").\n",
523 window->definition.name, step, (double)time,
524 (double)window->last_accepted_time, window->sample_count);
525 }
526 if (before != PICURV_WINDOW_COMPLETE && window->state == PICURV_WINDOW_COMPLETE) {
528 "Statistics window '%s' complete: %" PetscInt_FMT " sample(s), total weight %.6g, "
529 "represented time %.6g.\n",
530 window->definition.name, window->sample_count,
531 (double)window->total_weight, (double)window->represented_time);
532 if (window->sample_count == 0) {
534 "Statistics window '%s' completed without accepting any sample.\n",
535 window->definition.name);
536 } else {
537 UserCtx *user = simCtx->usermg.mgctx[simCtx->usermg.mglevels - 1].user;
538
539 /* A point that was never valid carries no average at all, which a
540 * reader of the mean field cannot see. Report it once, at the only
541 * moment the final coverage is known. The reduction is collective and
542 * runs once per window, not per step. */
543 if (user && user->fieldStatisticsStorage) {
544 PetscReal lowest = 1.0, highest = 0.0;
545
546 PetscCall(PicurvWindowValidFractionRange(user, &window->definition,
547 &user->fieldStatisticsStorage[window_index],
548 window->sample_count, &lowest, &highest));
549 if (lowest <= 0.0) {
551 "Statistics window '%s' completed with points that were never "
552 "valid; their mean and moments are undefined.\n",
553 window->definition.name);
554 } else {
556 "Statistics window '%s' per-point valid fraction spans [%.3f, %.3f].\n",
557 window->definition.name, (double)lowest, (double)highest);
558 }
559 }
560 }
561 }
562 }
564 PetscFunctionReturn(0);
565}
#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
@ LOG_INFO
Informational messages about program execution.
Definition logging.h:31
@ LOG_WARNING
Non-critical issues that warrant attention.
Definition logging.h:30
@ LOG_DEBUG
Detailed debugging information.
Definition logging.h:32
PetscErrorCode PicurvWindowValidFractionRange(UserCtx *user, const PicurvWindowDefinition *definition, const PicurvWindowStorage *storage, PetscInt sample_count, PetscReal *minimum, PetscReal *maximum)
Reports the range of per-point valid fraction across a window's domain.
PetscErrorCode PicurvWindowAccumulate(UserCtx *user, const PicurvWindowDefinition *definition, PicurvWindowStorage *storage, PetscReal weight)
Applies one accepted completed state to a window's accumulators.
PetscBool FieldStatisticsIsActive(const SimCtx *simCtx)
Implementation of FieldStatisticsIsActive().
PetscErrorCode PicurvWindowOfferState(PicurvWindow *window, PetscInt step, PetscReal time, PetscBool *accepted, PetscReal *weight)
Implementation of PicurvWindowOfferState().
Runtime state of one window.
PetscInt fieldStatisticsWindowCount
Definition variables.h:989
UserCtx * user
Definition variables.h:768
PetscInt block_number
Definition variables.h:1009
UserMG usermg
Definition variables.h:1082
struct PicurvWindow * fieldStatisticsWindows
Definition variables.h:990
PetscInt mglevels
Definition variables.h:775
struct PicurvWindowStorage * fieldStatisticsStorage
Definition variables.h:1222
MGCtx * mgctx
Definition variables.h:778
User-defined context containing data specific to a single computational grid level.
Definition variables.h:1157
Here is the call graph for this function:
Here is the caller graph for this function: