Per-window PETSc accumulator storage and pointwise application. More...
Go to the source code of this file.
Data Structures | |
| struct | PicurvWindowStorage |
| Independent accumulator state for one window on one block. More... | |
| struct | PicurvStatisticsPayload |
| One checkpointable accumulator vector, resolved by enumeration index. More... | |
| struct | PicurvDerivedField |
| One derived output field, resolved by enumeration index. More... | |
Macros | |
| #define | PICURV_STATISTICS_PAYLOAD_NAME_LENGTH 96 |
| Maximum stored length of a payload name, including the terminator. | |
| #define | PICURV_STATISTICS_VARIANCE_FLOOR 1.0e-12 |
| Tolerance within which a negative variance is treated as floating-point noise. | |
Typedefs | |
| typedef struct PicurvWindowStorage | PicurvWindowStorage |
| Independent accumulator state for one window on one block. | |
Functions | |
| PetscErrorCode | PicurvWindowStoragePayloadCount (const PicurvWindowStorage *storage, PetscInt *count) |
| Reports how many checkpointable vectors one window's storage holds. | |
| PetscErrorCode | PicurvWindowStoragePayload (UserCtx *user, const PicurvWindowDefinition *definition, const PicurvWindowStorage *storage, PetscInt index, PicurvStatisticsPayload *payload) |
| Resolves one enumerated payload of a window's storage. | |
| PetscErrorCode | PicurvStatisticsComponentDM (UserCtx *user, PetscInt components, DM *dm) |
| Resolves the DM carrying a given number of accumulator components. | |
| PetscErrorCode | PicurvProductComponentCount (PetscInt dof, PetscInt *count) |
| Reports how many symmetric product components a field's second moment needs. | |
| PetscErrorCode | PicurvCovarianceComponentCount (PetscInt dof_a, PetscInt dof_b, PetscInt *count) |
| Reports how many components a covariance between two fields needs. | |
| PetscErrorCode | PicurvWindowStorageCreate (UserCtx *user, const PicurvWindowDefinition *definition, PicurvWindowStorage *storage) |
| Allocates the accumulator state one window owns on one block. | |
| PetscErrorCode | PicurvWindowStorageDestroy (PicurvWindowStorage *storage) |
| Releases accumulator state previously created for one window. | |
| PetscErrorCode | PicurvWindowDerivedCount (const PicurvWindowDefinition *definition, const PicurvWindowStorage *storage, const char *outputs, PetscInt *count) |
| Reports how many derived fields a requested output set produces. | |
| PetscErrorCode | PicurvWindowDerive (UserCtx *user, const PicurvWindowDefinition *definition, const PicurvWindowStorage *storage, const char *outputs, PetscInt index, Vec scalar_target, Vec vector_target, PicurvDerivedField *field) |
| Derives one output field from centered accumulator state. | |
| PetscErrorCode | PicurvWindowSpatialMean (UserCtx *user, const PicurvWindowDefinition *definition, const PicurvWindowStorage *storage, Vec field, PetscReal *mean) |
| Reports the spatial mean of a derived field over the points a window sampled. | |
| 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. | |
| PetscErrorCode | PicurvWindowStorageFromParticles (UserCtx *user, const PicurvWindowDefinition *definition, PicurvWindowStorage *storage) |
| Fills a window's storage from the particles sampling each cell at one instant. | |
| PetscErrorCode | PicurvWindowStorageReduce (UserCtx *user, const PicurvWindowDefinition *definition, const PicurvWindowStorage *storage, const PetscBool average_direction[3], PicurvWindowStorage *reduced) |
| Merges a window's pointwise state over homogeneous directions. | |
Per-window PETSc accumulator storage and pointwise application.
Holds the independent state each named window owns, and applies one accepted completed state to it, per 4. Accumulated State and Component Order.
Storage is allocated once by the vector factory and released once at teardown. Application is strictly pointwise: it reads a source field value at an owned point and updates that point's accumulator, so it performs no halo exchange and allocates nothing.
Definition in file statistics_accumulator.h.
| struct PicurvWindowStorage |
Independent accumulator state for one window on one block.
Per-point occupancy is tracked separately from the field moments because the fluid mask can move: a point contributes only to the states in which it was valid, so its own count and weight are what normalize its moments.
A particle-sampled field (FIELD_CAPABILITY_PARTICLE_SAMPLED) is a measurement only in the states in which its cell held particles, so it is accumulated over a second sample set, the occupied states, with occupancy of its own. A covariance pairing it with an ordinary field is taken over the occupied states too, and needs the ordinary member's mean over those same states; that mean is kept beside the member's own. A window requesting no particle-sampled field holds none of this.
Every product is one vector carrying all of its components, not one vector per component. A symmetric second-order tensor is a single object: splitting it would cost six memory streams in the per-step accumulation loop instead of one cache line, and six collective gathers per checkpoint instead of one. Component counts that neither da nor fda provides are carried by a DM mirroring the block decomposition at that degree of freedom.
Definition at line 41 of file statistics_accumulator.h.
| struct PicurvStatisticsPayload |
One checkpointable accumulator vector, resolved by enumeration index.
The enumeration order is the persistence contract: the manifest inventory, the checkpoint writer, and the restart reader all walk it identically, so a payload lands in the vector it came from without a separate lookup table.
Definition at line 69 of file statistics_accumulator.h.
| struct PicurvDerivedField |
One derived output field, resolved by enumeration index.
Definition at line 159 of file statistics_accumulator.h.
| #define PICURV_STATISTICS_PAYLOAD_NAME_LENGTH 96 |
Maximum stored length of a payload name, including the terminator.
Definition at line 60 of file statistics_accumulator.h.
| #define PICURV_STATISTICS_VARIANCE_FLOOR 1.0e-12 |
Tolerance within which a negative variance is treated as floating-point noise.
Definition at line 156 of file statistics_accumulator.h.
| typedef struct PicurvWindowStorage PicurvWindowStorage |
Independent accumulator state for one window on one block.
Per-point occupancy is tracked separately from the field moments because the fluid mask can move: a point contributes only to the states in which it was valid, so its own count and weight are what normalize its moments.
A particle-sampled field (FIELD_CAPABILITY_PARTICLE_SAMPLED) is a measurement only in the states in which its cell held particles, so it is accumulated over a second sample set, the occupied states, with occupancy of its own. A covariance pairing it with an ordinary field is taken over the occupied states too, and needs the ordinary member's mean over those same states; that mean is kept beside the member's own. A window requesting no particle-sampled field holds none of this.
Every product is one vector carrying all of its components, not one vector per component. A symmetric second-order tensor is a single object: splitting it would cost six memory streams in the per-step accumulation loop instead of one cache line, and six collective gathers per checkpoint instead of one. Component counts that neither da nor fda provides are carried by a DM mirroring the block decomposition at that degree of freedom.
| PetscErrorCode PicurvWindowStoragePayloadCount | ( | const PicurvWindowStorage * | storage, |
| PetscInt * | count | ||
| ) |
Reports how many checkpointable vectors one window's storage holds.
| [in] | storage | Storage to measure. |
| [out] | count | Payload count, including the three occupancy vectors. |
PETSC_ERR_ARG_NULL for a null argument.Reports how many checkpointable vectors one window's storage holds.
Definition at line 386 of file statistics_accumulator.c.
| PetscErrorCode PicurvWindowStoragePayload | ( | UserCtx * | user, |
| const PicurvWindowDefinition * | definition, | ||
| const PicurvWindowStorage * | storage, | ||
| PetscInt | index, | ||
| PicurvStatisticsPayload * | payload | ||
| ) |
Resolves one enumerated payload of a window's storage.
Names are derived from catalogued field names and fixed component suffixes, so they are stable across runs, rank counts, and configuration reorderings.
| [in] | user | Block context the storage belongs to. |
| [in] | definition | Window definition naming the accumulated fields and pairs. |
| [in] | storage | Storage to enumerate. |
| [in] | index | Payload index in [0, count). |
| [out] | payload | Resolved payload; the vector is borrowed, not duplicated. |
PETSC_ERR_ARG_OUTOFRANGE for an index outside the range.Resolves one enumerated payload of a window's storage.
Definition at line 409 of file statistics_accumulator.c.
| PetscErrorCode PicurvStatisticsComponentDM | ( | UserCtx * | user, |
| PetscInt | components, | ||
| DM * | dm | ||
| ) |
Resolves the DM carrying a given number of accumulator components.
Component counts of one and three reuse the DMs the block already owns; six is carried by the symmetric-tensor DM created alongside them. Every one of these mirrors the block decomposition exactly, so a pointwise loop can read a source field and write an accumulator at the same index.
| [in] | user | Block context owning the DMs. |
| [in] | components | Component count to place. |
| [out] | dm | Resolved DM; borrowed, never destroyed by the caller. |
PETSC_ERR_ARG_OUTOFRANGE for an unsupported count.Resolves the DM carrying a given number of accumulator components.
Definition at line 126 of file statistics_accumulator.c.
| PetscErrorCode PicurvProductComponentCount | ( | PetscInt | dof, |
| PetscInt * | count | ||
| ) |
Reports how many symmetric product components a field's second moment needs.
| [in] | dof | Degree of freedom of the field. |
| [out] | count | Component count: one for a scalar, six for a three-vector. |
PETSC_ERR_ARG_OUTOFRANGE for an unsupported dof.Reports how many symmetric product components a field's second moment needs.
Definition at line 90 of file statistics_accumulator.c.
| PetscErrorCode PicurvCovarianceComponentCount | ( | PetscInt | dof_a, |
| PetscInt | dof_b, | ||
| PetscInt * | count | ||
| ) |
Reports how many components a covariance between two fields needs.
| [in] | dof_a | Degree of freedom of the first member. |
| [in] | dof_b | Degree of freedom of the second member. |
| [out] | count | Component count. |
PETSC_ERR_ARG_OUTOFRANGE for an unsupported pairing.Reports how many components a covariance between two fields needs.
Definition at line 106 of file statistics_accumulator.c.
| PetscErrorCode PicurvWindowStorageCreate | ( | UserCtx * | user, |
| const PicurvWindowDefinition * | definition, | ||
| PicurvWindowStorage * | storage | ||
| ) |
Allocates the accumulator state one window owns on one block.
Every vector is duplicated from one the factory already built, so no new DM or layout decision is introduced.
| [in] | user | Block context supplying the source fields. |
| [in] | definition | Window definition naming the requested fields and pairs. |
| [out] | storage | Storage to populate; zeroed on entry. |
Allocates the accumulator state one window owns on one block.
Definition at line 223 of file statistics_accumulator.c.
| PetscErrorCode PicurvWindowStorageDestroy | ( | PicurvWindowStorage * | storage | ) |
Releases accumulator state previously created for one window.
| [in,out] | storage | Storage to release; safe to call on zeroed storage. |
Releases accumulator state previously created for one window.
Definition at line 328 of file statistics_accumulator.c.
| PetscErrorCode PicurvWindowDerivedCount | ( | const PicurvWindowDefinition * | definition, |
| const PicurvWindowStorage * | storage, | ||
| const char * | outputs, | ||
| PetscInt * | count | ||
| ) |
Reports how many derived fields a requested output set produces.
| [in] | definition | Window definition naming the accumulated fields and pairs. |
| [in] | storage | Accumulator state the outputs are derived from. |
| [in] | outputs | Comma-separated output kinds: mean, reynolds_stress, rms, tke, flux, point_variance. |
| [out] | count | Number of derived fields. |
PETSC_ERR_ARG_WRONG for an unknown output kind.Reports how many derived fields a requested output set produces.
Definition at line 654 of file statistics_accumulator.c.
| PetscErrorCode PicurvWindowDerive | ( | UserCtx * | user, |
| const PicurvWindowDefinition * | definition, | ||
| const PicurvWindowStorage * | storage, | ||
| const char * | outputs, | ||
| PetscInt | index, | ||
| Vec | scalar_target, | ||
| Vec | vector_target, | ||
| PicurvDerivedField * | field | ||
| ) |
Derives one output field from centered accumulator state.
Normalizes in exactly one place: R_ij = C_ij / W, RMS_i = sqrt(R_ii), k = (R_xx + R_yy + R_zz) / 2, and a flux is the co-moment over the same weight. Each uses the moment kernels rather than repeating the division, so the online and offline halves of the pipeline cannot disagree about what centered state means.
A variance that comes out slightly negative through floating-point cancellation is clamped only where a square root would otherwise fail, and only within PICURV_STATISTICS_VARIANCE_FLOOR. Stored state is never modified.
Points the window never sampled are left at zero rather than divided by a zero weight; the valid-fraction range reports how much of the domain that covers.
| [in] | user | Block context supplying the target domain. |
| [in] | definition | Window definition. |
| [in] | storage | Accumulator state to read. |
| [in] | outputs | Comma-separated output kinds. |
| [in] | index | Derived field index in [0, count). |
| [out] | scalar_target | Scalar destination, used when the field has one component. |
| [out] | vector_target | Vector destination, used when the field has three. |
| [out] | field | Resolved name and component count of the derived field. |
Derives one output field from centered accumulator state.
Definition at line 735 of file statistics_accumulator.c.
| PetscErrorCode PicurvWindowSpatialMean | ( | UserCtx * | user, |
| const PicurvWindowDefinition * | definition, | ||
| const PicurvWindowStorage * | storage, | ||
| Vec | field, | ||
| PetscReal * | mean | ||
| ) |
Reports the spatial mean of a derived field over the points a window sampled.
The average is taken over targeted points that actually accumulated weight, not over the whole vector. A derived field is zero everywhere outside the target domain and at any point the mask never admitted, and those zeros are absences rather than measurements: including them would scale the answer down by the fraction of the vector the window never covered.
Performs a collective reduction, so callers use it for reporting rather than per point.
| [in] | user | Block context supplying the target domain. |
| [in] | definition | Window definition naming the accumulated fields. |
| [in] | storage | Accumulator state supplying per-point occupancy. |
| [in] | field | Derived field to average, on the cell-centred scalar DM. |
| [out] | mean | Spatial mean; zero when the window sampled no point. |
Reports the spatial mean of a derived field over the points a window sampled.
Definition at line 961 of file statistics_accumulator.c.
| 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.
A point contributes only to the states in which the mask accepted it, so with a moving immersed body different points carry different sample counts. The ratio of a point's own count to the window's accepted-sample count is its valid fraction, and the range of that ratio is the window's mask-health indicator: a minimum of one means every point saw every state, and a minimum of zero means some point contributed nothing at all.
Performs a collective reduction, so callers gate it on an already-active reporting path rather than calling it every step.
| [in] | user | Block context supplying the target domain and mask. |
| [in] | definition | Window definition naming the accumulated fields. |
| [in] | storage | Accumulator state to inspect. |
| [in] | sample_count | Accepted states the window has recorded. |
| [out] | minimum | Smallest valid fraction; one when no point is targeted. |
| [out] | maximum | Largest valid fraction; zero when no point is targeted. |
Reports the range of per-point valid fraction across a window's domain.
Definition at line 994 of file statistics_accumulator.c.
| PetscErrorCode PicurvWindowAccumulate | ( | UserCtx * | user, |
| const PicurvWindowDefinition * | definition, | ||
| PicurvWindowStorage * | storage, | ||
| PetscReal | weight | ||
| ) |
Applies one accepted completed state to a window's accumulators.
Iterates the pointwise target domain, skipping points the mask rejects, and updates each point's occupancy and every requested moment and co-moment through the centered kernels.
| [in] | user | Block context supplying the source fields. |
| [in] | definition | Window definition. |
| [in,out] | storage | Accumulator state to update. |
| [in] | weight | Weight the window assigned to this state; must be positive. |
Applies one accepted completed state to a window's accumulators.
Definition at line 1048 of file statistics_accumulator.c.
| PetscErrorCode PicurvWindowStorageFromParticles | ( | UserCtx * | user, |
| const PicurvWindowDefinition * | definition, | ||
| PicurvWindowStorage * | storage | ||
| ) |
Fills a window's storage from the particles sampling each cell at one instant.
The particles a cell holds are that cell's samples, each of unit weight, so the stored state is the cell's particle ensemble: its count, the ensemble mean of every requested field, and the centred sums of every requested self-product and covariance. Each field is identified by its Eulerian scatter target, which fixes its layout and the names its derived outputs carry.
The runtime accumulator streams states it sees once, so it updates running means sample by sample. A snapshot holds every sample at once, which admits the two-pass form instead: the means first, through the same particle sum the runtime scatter uses, then the centred products about them. That is the more accurate of the two, needs no division per sample, and does not depend on particle order. Both produce the same stored state, so derivation and output treat the two alike.
A particle contributes wherever its cell lies in this rank's ghosted patch, and the patch sums are added onto their owners, so a particle need not sit on the rank that owns its cell. One outside the patch is skipped, as in the scatter.
| [in] | user | Block context supplying the swarm and the grid. |
| [in] | definition | Fields and pairs to accumulate, by Eulerian scatter target. |
| [in,out] | storage | Freshly created storage for definition; overwritten. |
Fills a window's storage from the particles sampling each cell at one instant.
Definition at line 1357 of file statistics_accumulator.c.
| PetscErrorCode PicurvWindowStorageReduce | ( | UserCtx * | user, |
| const PicurvWindowDefinition * | definition, | ||
| const PicurvWindowStorage * | storage, | ||
| const PetscBool | average_direction[3], | ||
| PicurvWindowStorage * | reduced | ||
| ) |
Merges a window's pointwise state over homogeneous directions.
Every point of a retained slot is combined into one state through the weighted merge: the slot mean is the weight-averaged point mean, and the slot co-moment adds to the point co-moments the spread of the point means about it, \(C = \sum_p [C_p + W_p (\mu_{a,p} - \mu_a)(\mu_{b,p} - \mu_b)] / \sum_p W_p\). It is the moment of the slot's whole sample set, which an average of the point statistics is not.
The result is written back at every point of its slot, as a state of unit weight holding the merged mean and the merged co-moments already divided by the merged weight. The derivation therefore applies to it unchanged, and a point carries weight only where its slot was sampled. Its occupancy totals are not the slot's.
| [in] | user | Block context supplying the target domain and mask. |
| [in] | definition | Window definition. |
| [in] | storage | Pointwise state to merge. |
| [in] | average_direction | Directions to merge over, in (i, j, k) order. |
| [out] | reduced | Storage created for definition; overwritten. |
Merges a window's pointwise state over homogeneous directions.
Definition at line 1467 of file statistics_accumulator.c.