PICurv 0.1.0
A Parallel Particle-In-Cell Solver for Curvilinear LES
 
Loading...
Searching...
No Matches
statistics_target.c
Go to the documentation of this file.
1/**
2 * @file statistics_target.c
3 * @brief Spatial target resolution for the field-statistics pipeline.
4 *
5 * Full API contract is documented with the declarations in
6 * `include/statistics_target.h`.
7 */
8
9#include "statistics_target.h"
10#include "logging.h"
11
12/**
13 * @brief Implementation of \ref PicurvLayoutDimensionIsNodeLike().
14 * @see PicurvLayoutDimensionIsNodeLike()
15 */
16PetscErrorCode PicurvLayoutDimensionIsNodeLike(FieldLayout layout, PetscInt dim, PetscBool *node_like)
17{
18 PetscFunctionBeginUser;
20 PetscCheck(node_like != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
21 "Classification output is required.");
22 PetscCheck(dim >= 0 && dim < 3, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE,
23 "Dimension must be 0, 1, or 2; got %" PetscInt_FMT ".", dim);
24
25 switch (layout) {
27 *node_like = PETSC_TRUE;
28 break;
30 *node_like = PETSC_FALSE;
31 break;
33 *node_like = (PetscBool)(dim == 0);
34 break;
36 *node_like = (PetscBool)(dim == 1);
37 break;
39 *node_like = (PetscBool)(dim == 2);
40 break;
42 /* x, y, and z live on I-, J-, and K-faces respectively, so no single
43 * classification describes the packed vector. */
44 SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE,
45 "Component-staggered layout has no single per-dimension classification.");
46 default:
47 SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE,
48 "Unknown field layout %d.", (int)layout);
49 }
51 PetscFunctionReturn(0);
52}
53
54/**
55 * @brief Internal helper: resolves the layout-valid index span for one dimension.
56 * @details Local to this translation unit.
57 *
58 * The DMDA carries one extra high-side slot beyond the physical grid, and the
59 * solver's shifted convention places boundary/dummy values at index zero. Under
60 * periodicity the repair algorithms in `Boundaries.c` write index `0` and index
61 * `size-1` from the opposite side, so both are dependent duplicates and the
62 * independent span starts at one in every layout.
63 */
64static void ResolveLayoutSpan(PetscBool node_like, PetscBool periodic, PetscInt size,
65 PetscInt *lo, PetscInt *hi_exclusive)
66{
68 /* Node-like and non-periodic is the only case whose first physical entry
69 * sits at index zero; everywhere else index zero is a boundary, dummy, or
70 * periodic duplicate. */
71 *lo = (node_like && !periodic) ? 0 : 1;
72 /* The final slot is the DMDA's extra non-physical entry under every layout. */
73 *hi_exclusive = size - 1;
75}
76
77/**
78 * @brief Implementation of \ref SpatialTargetPlanCreate().
79 * @see SpatialTargetPlanCreate()
80 */
81PetscErrorCode SpatialTargetPlanCreate(UserCtx *user, FieldId field_id,
83{
84 const FieldDescriptor *descriptor = NULL;
85 const DMDALocalInfo *info = NULL;
86 SimCtx *simCtx = NULL;
87 PetscInt owned_start[3];
88 PetscInt owned_end[3];
89 PetscInt global_size[3];
90 PetscBool periodic[3];
91
92 PetscFunctionBeginUser;
94 PetscCheck(user != NULL && plan != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
95 "Block context and plan output are required.");
96 PetscCheck(mask == PICURV_STATISTICS_MASK_FLUID, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE,
97 "Only the fluid mask is implemented.");
98 simCtx = user->simCtx;
99 PetscCheck(simCtx != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE,
100 "Block context must carry a simulation context.");
101
102 PetscCall(FieldGetDescriptor(field_id, &descriptor));
103 PetscCheck(descriptor->layout != FIELD_LAYOUT_COMPONENT_STAGGERED,
104 PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE,
105 "Field '%s' is component-staggered; its components live on different face "
106 "families and cannot share one pointwise target domain.",
107 descriptor->canonical_name);
108
109 info = &user->info;
110 owned_start[0] = info->xs; owned_end[0] = info->xs + info->xm; global_size[0] = info->mx;
111 owned_start[1] = info->ys; owned_end[1] = info->ys + info->ym; global_size[1] = info->my;
112 owned_start[2] = info->zs; owned_end[2] = info->zs + info->zm; global_size[2] = info->mz;
113 GetPeriodicAxes(simCtx, periodic);
114
116 plan->mask = mask;
117 plan->descriptor = descriptor;
118
119 for (PetscInt dim = 0; dim < 3; ++dim) {
120 PetscBool node_like = PETSC_FALSE;
121 PetscInt layout_lo = 0;
122 PetscInt layout_hi = 0;
123
124 PetscCall(PicurvLayoutDimensionIsNodeLike(descriptor->layout, dim, &node_like));
125 ResolveLayoutSpan(node_like, periodic[dim], global_size[dim], &layout_lo, &layout_hi);
126
127 /* Intersect the layout-valid span with this rank's owned range: the
128 * first exclusion removes solver-layout indices, the second removes
129 * PETSc halo storage. */
130 plan->start[dim] = PetscMax(owned_start[dim], layout_lo);
131 plan->end[dim] = PetscMin(owned_end[dim], layout_hi);
132 if (plan->end[dim] < plan->start[dim]) plan->end[dim] = plan->start[dim];
133 }
135 PetscFunctionReturn(0);
136}
137
138/**
139 * @brief Implementation of \ref SpatialTargetPlanLocalPointCount().
140 * @see SpatialTargetPlanLocalPointCount()
141 */
142PetscErrorCode SpatialTargetPlanLocalPointCount(const SpatialTargetPlan *plan, PetscInt *count)
143{
144 PetscInt total = 1;
145
146 PetscFunctionBeginUser;
148 PetscCheck(plan != NULL && count != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
149 "Plan and count output are required.");
150 for (PetscInt dim = 0; dim < 3; ++dim) {
151 const PetscInt extent = plan->end[dim] - plan->start[dim];
152 if (extent <= 0) { *count = 0; PROFILE_FUNCTION_END; PetscFunctionReturn(0); }
153 total *= extent;
154 }
155 *count = total;
157 PetscFunctionReturn(0);
158}
159
160/**
161 * @brief Implementation of \ref SpatialTargetPlanGlobalPointCount().
162 * @see SpatialTargetPlanGlobalPointCount()
163 */
164PetscErrorCode SpatialTargetPlanGlobalPointCount(const SpatialTargetPlan *plan, MPI_Comm comm, PetscInt *count)
165{
166 PetscInt local = 0;
167
168 PetscFunctionBeginUser;
170 PetscCheck(plan != NULL && count != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
171 "Plan and count output are required.");
172 PetscCall(SpatialTargetPlanLocalPointCount(plan, &local));
173 PetscCallMPI(MPI_Allreduce(&local, count, 1, MPIU_INT, MPI_SUM, comm));
175 PetscFunctionReturn(0);
176}
177
178/**
179 * @brief Implementation of \ref SpatialTargetPlanMaskAllows().
180 * @see SpatialTargetPlanMaskAllows()
181 */
182PetscBool SpatialTargetPlanMaskAllows(const SpatialTargetPlan *plan, PetscReal nvert_value)
183{
184 if (plan == NULL) return PETSC_FALSE;
185 return (PetscBool)(nvert_value < PICURV_STATISTICS_FLUID_THRESHOLD);
186}
187
188/**
189 * @brief Flattens the retained global indices of one point into a reduction slot.
190 *
191 * A direction being averaged over collapses to a single entry, so the buffer is
192 * indexed only by the directions left out.
193 */
194static PetscInt SpatialAverageSlot(const PetscBool average_direction[3],
195 const PetscInt retained_extent[3],
196 PetscInt i, PetscInt j, PetscInt k)
197{
198 return (average_direction[0] ? 0 : i) +
199 retained_extent[0] * ((average_direction[1] ? 0 : j) +
200 retained_extent[1] * (average_direction[2] ? 0 : k));
201}
202
203/**
204 * @brief Implementation of \ref PicurvSpatialRatioAverage().
205 * @see PicurvSpatialRatioAverage()
206 */
207PetscErrorCode PicurvSpatialRatioAverage(UserCtx *user, const SpatialTargetPlan *plan,
208 Vec numerator, Vec denominator, Vec inclusion,
209 const PetscBool average_direction[3], MPI_Comm comm,
210 Vec ratio, PetscReal *reduced)
211{
212 DM da = NULL, numerator_dm = NULL;
213 DMDALocalInfo info;
214 PetscInt retained_extent[3];
215 PetscInt buffer_size = 1;
216 PetscInt averaged_count = 0;
217 PetscInt dof = 1;
218 PetscReal ***den = NULL, ***inc = NULL, ***nvert = NULL;
219 PetscScalar ****num = NULL, ****out = NULL;
220 PetscReal *num_sum = NULL, *den_sum = NULL;
221
222 PetscFunctionBeginUser;
224 PetscCheck(user != NULL && plan != NULL && numerator != NULL && average_direction != NULL,
225 PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
226 "Context, plan, numerator, and direction selector are required.");
227
228 da = user->da;
229 info = user->info;
230 /* The numerator's own DM supplies its component count; every component shares the
231 * scalar denominator, inclusion mask and solid mask. */
232 PetscCall(VecGetDM(numerator, &numerator_dm));
233 PetscCheck(numerator_dm != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG,
234 "The numerator must carry the DMDA it was created from.");
235 PetscCall(DMDAGetInfo(numerator_dm, NULL, NULL, NULL, NULL, NULL, NULL, NULL, &dof,
236 NULL, NULL, NULL, NULL, NULL));
237
238 retained_extent[0] = average_direction[0] ? 1 : info.mx;
239 retained_extent[1] = average_direction[1] ? 1 : info.my;
240 retained_extent[2] = average_direction[2] ? 1 : info.mz;
241 for (PetscInt axis = 0; axis < 3; axis++) {
242 if (average_direction[axis]) averaged_count++;
243 buffer_size *= retained_extent[axis];
244 }
245 PetscCheck(reduced == NULL || averaged_count > 0, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE,
246 "Reduced values exist only when at least one direction is averaged over.");
247
248 PetscCall(DMDAVecGetArrayDOFRead(numerator_dm, numerator, &num));
249 if (denominator) PetscCall(DMDAVecGetArrayRead(da, denominator, &den));
250 if (inclusion) PetscCall(DMDAVecGetArrayRead(da, inclusion, &inc));
251 if (ratio) PetscCall(DMDAVecGetArrayDOF(numerator_dm, ratio, &out));
252 PetscCall(DMDAVecGetArrayRead(da, user->lNvert, &nvert));
253
254 if (averaged_count == 0) {
255 /* Pointwise: the empty averaging set, which is a legitimate request rather
256 * than a degenerate one. It is what a local formulation asks for. The masks
257 * mean the same thing here as they do for an averaged set - a point they
258 * exclude contributes nothing and receives nothing - so that a caller can
259 * switch between the two without its exclusions quietly changing meaning. */
260 for (PetscInt k = plan->start[2]; k < plan->end[2]; k++)
261 for (PetscInt j = plan->start[1]; j < plan->end[1]; j++)
262 for (PetscInt i = plan->start[0]; i < plan->end[0]; i++) {
263 const PetscReal divisor = denominator ? den[k][j][i] : 1.0;
264 const PetscBool admitted = (PetscBool)(SpatialTargetPlanMaskAllows(plan, nvert[k][j][i]) &&
265 !(inc && inc[k][j][i] <= 0.0));
266
267 for (PetscInt c = 0; c < dof; c++) {
268 out[k][j][i][c] = (admitted && PetscAbsReal(divisor) > 0.0)
269 ? (num[k][j][i][c] / divisor) : 0.0;
270 }
271 }
272 } else {
273 PetscCheck(buffer_size * dof <= PICURV_SPATIAL_AVERAGE_MAX_BUFFER, PETSC_COMM_SELF,
274 PETSC_ERR_ARG_OUTOFRANGE,
275 "Averaging over %" PetscInt_FMT " direction(s) would need a reduction buffer "
276 "of %" PetscInt_FMT " entries, above the %d entry limit. Average over more "
277 "directions.", averaged_count, buffer_size * dof, PICURV_SPATIAL_AVERAGE_MAX_BUFFER);
278
279 PetscCall(PetscCalloc2(buffer_size * dof, &num_sum, buffer_size, &den_sum));
280
281 for (PetscInt k = plan->start[2]; k < plan->end[2]; k++)
282 for (PetscInt j = plan->start[1]; j < plan->end[1]; j++)
283 for (PetscInt i = plan->start[0]; i < plan->end[0]; i++) {
284 PetscInt slot;
285
286 if (!SpatialTargetPlanMaskAllows(plan, nvert[k][j][i])) continue;
287 /* A point the caller marks unmeasured holds a zero that means absence, not
288 * a measurement; counting it would scale the answer toward zero. */
289 if (inc && inc[k][j][i] <= 0.0) continue;
290
291 slot = SpatialAverageSlot(average_direction, retained_extent, i, j, k);
292 for (PetscInt c = 0; c < dof; c++) num_sum[slot * dof + c] += num[k][j][i][c];
293 den_sum[slot] += denominator ? den[k][j][i] : 1.0;
294 }
295
296 PetscCallMPI(MPI_Allreduce(MPI_IN_PLACE, num_sum, (PetscMPIInt)(buffer_size * dof),
297 MPIU_REAL, MPI_SUM, comm));
298 PetscCallMPI(MPI_Allreduce(MPI_IN_PLACE, den_sum, (PetscMPIInt)buffer_size,
299 MPIU_REAL, MPI_SUM, comm));
300 for (PetscInt slot = 0; slot < buffer_size; slot++) {
301 for (PetscInt c = 0; c < dof; c++) {
302 num_sum[slot * dof + c] = (PetscAbsReal(den_sum[slot]) > 0.0)
303 ? (num_sum[slot * dof + c] / den_sum[slot]) : 0.0;
304 }
305 }
306
307 if (out) {
308 for (PetscInt k = plan->start[2]; k < plan->end[2]; k++)
309 for (PetscInt j = plan->start[1]; j < plan->end[1]; j++)
310 for (PetscInt i = plan->start[0]; i < plan->end[0]; i++) {
311 const PetscInt slot = SpatialAverageSlot(average_direction, retained_extent, i, j, k);
312
313 for (PetscInt c = 0; c < dof; c++) out[k][j][i][c] = num_sum[slot * dof + c];
314 }
315 }
316 if (reduced) PetscCall(PetscArraycpy(reduced, num_sum, buffer_size * dof));
317
318 PetscCall(PetscFree2(num_sum, den_sum));
319 }
320
321 PetscCall(DMDAVecRestoreArrayDOFRead(numerator_dm, numerator, &num));
322 if (denominator) PetscCall(DMDAVecRestoreArrayRead(da, denominator, &den));
323 if (inclusion) PetscCall(DMDAVecRestoreArrayRead(da, inclusion, &inc));
324 if (ratio) PetscCall(DMDAVecRestoreArrayDOF(numerator_dm, ratio, &out));
325 PetscCall(DMDAVecRestoreArrayRead(da, user->lNvert, &nvert));
326
328 PetscFunctionReturn(0);
329}
FieldLayout layout
FieldLayout
Logical storage topology of a field.
@ FIELD_LAYOUT_K_FACE
@ FIELD_LAYOUT_I_FACE
@ FIELD_LAYOUT_CELL_CENTERED
@ FIELD_LAYOUT_COMPONENT_STAGGERED
@ FIELD_LAYOUT_NODE_CENTERED
@ FIELD_LAYOUT_J_FACE
const char * canonical_name
PetscErrorCode FieldGetDescriptor(FieldId field_id, const FieldDescriptor **descriptor)
Return immutable metadata for a valid field identifier.
FieldId
Compile-time identity for a catalogued Eulerian field.
Immutable metadata for one field identity.
Logging utilities and macros for PETSc-based applications.
#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
static void GetPeriodicAxes(const SimCtx *simCtx, PetscBool periodic[3])
Which grid axes are periodic.
Definition setup.h:361
PetscBool SpatialTargetPlanMaskAllows(const SpatialTargetPlan *plan, PetscReal nvert_value)
Implementation of SpatialTargetPlanMaskAllows().
static void ResolveLayoutSpan(PetscBool node_like, PetscBool periodic, PetscInt size, PetscInt *lo, PetscInt *hi_exclusive)
Internal helper: resolves the layout-valid index span for one dimension.
PetscErrorCode SpatialTargetPlanLocalPointCount(const SpatialTargetPlan *plan, PetscInt *count)
Implementation of SpatialTargetPlanLocalPointCount().
PetscErrorCode SpatialTargetPlanGlobalPointCount(const SpatialTargetPlan *plan, MPI_Comm comm, PetscInt *count)
Implementation of SpatialTargetPlanGlobalPointCount().
PetscErrorCode SpatialTargetPlanCreate(UserCtx *user, FieldId field_id, PicurvStatisticsMask mask, SpatialTargetPlan *plan)
Implementation of SpatialTargetPlanCreate().
PetscErrorCode PicurvLayoutDimensionIsNodeLike(FieldLayout layout, PetscInt dim, PetscBool *node_like)
Implementation of PicurvLayoutDimensionIsNodeLike().
PetscErrorCode PicurvSpatialRatioAverage(UserCtx *user, const SpatialTargetPlan *plan, Vec numerator, Vec denominator, Vec inclusion, const PetscBool average_direction[3], MPI_Comm comm, Vec ratio, PetscReal *reduced)
Implementation of PicurvSpatialRatioAverage().
static PetscInt SpatialAverageSlot(const PetscBool average_direction[3], const PetscInt retained_extent[3], PetscInt i, PetscInt j, PetscInt k)
Flattens the retained global indices of one point into a reduction slot.
Spatial target resolution for the field-statistics pipeline.
#define PICURV_STATISTICS_FLUID_THRESHOLD
Threshold below which a cell counts as fluid for the default mask.
PicurvTargetKind kind
Spatial mapping; always pointwise.
@ PICURV_TARGET_POINTWISE
PicurvStatisticsMask
Point-eligibility mask.
@ PICURV_STATISTICS_MASK_FLUID
PetscInt end[3]
Exclusive end per dimension (i, j, k).
PetscInt start[3]
Inclusive start per dimension (i, j, k).
const FieldDescriptor * descriptor
Catalog metadata for the targeted field.
PicurvStatisticsMask mask
Point-eligibility mask.
#define PICURV_SPATIAL_AVERAGE_MAX_BUFFER
Largest reduction buffer a directional average will allocate, in entries.
Resolved iteration domain for one field on one block.
Vec lNvert
Definition variables.h:1197
SimCtx * simCtx
Back-pointer to the master simulation context.
Definition variables.h:1160
DMDALocalInfo info
Definition variables.h:1169
The master context for the entire simulation.
Definition variables.h:916
User-defined context containing data specific to a single computational grid level.
Definition variables.h:1157