PICurv 0.1.0
A Parallel Particle-In-Cell Solver for Curvilinear LES
 
Loading...
Searching...
No Matches
check_statistics_nodal_consistency.py
Go to the documentation of this file.
1#!/usr/bin/env python3
2# -*- coding: utf-8 -*-
3
4"""!
5@file check_statistics_nodal_consistency.py
6@brief Cross-check derived statistics VTK output against the convergence-history CSV.
7
8The two are produced by paths that share no code: the CSV mean comes from
9`PicurvWindowSpatialMean`, which reduces the cell-centred accumulators over the
10resolved spatial target, while the VTK field comes from `ComputeNodalAverage`
11interpolating the derived staging buffer onto grid nodes. Agreement between them
12is therefore a real check rather than a restatement.
13
14It catches the specific failure this check was written for: an interior-only
15producer leaving structural zeros on the layout boundary, which halves every
16boundary node and biases a whole-domain mean without any other symptom.
17
18@code
19check_statistics_nodal_consistency.py RUN_DIR WINDOW_NAME
20@endcode
21"""
22
23#: Usage line reported when the arguments do not parse.
24USAGE = "usage: check_statistics_nodal_consistency.py RUN_DIR WINDOW_NAME"
25
26import csv
27import os
28import re
29import sys
30
31
32def sole_recipe_dir(run_dir: str, canonical_relative: str) -> str:
33 """!
34 @brief Resolve the one per-recipe subdirectory beneath a canonical output home.
35 @param[in] run_dir Run directory being inspected.
36 @param[in] canonical_relative Run-relative canonical home, such as output/visualization.
37 @return Absolute path to the single recipe subdirectory.
38 @throws ValueError when the home is absent or holds anything but one recipe.
39 """
40 root = os.path.join(run_dir, canonical_relative)
41 if not os.path.isdir(root):
42 raise ValueError(f"{canonical_relative} does not exist under {run_dir}.")
43 entries = sorted(name for name in os.listdir(root)
44 if os.path.isdir(os.path.join(root, name)))
45 if len(entries) != 1:
46 raise ValueError(
47 f"expected exactly one recipe directory under {root}, found {entries}."
48 )
49 return os.path.join(root, entries[0])
50
51
53 """!
54 @brief Import NumPy, which this checker needs to read the binary VTK payload.
55 @return Imported NumPy module.
56 """
57 import numpy
58 return numpy
59
60
62 """!
63 @brief Read appended raw Float64 point arrays from a PICurv `.vts`.
64 @param[in] path VTK structured-grid file path.
65 @return Tuple of the node extent per direction and a name-to-array mapping.
66 """
67 numpy = require_numpy()
68 raw = open(path, "rb").read()
69 head = raw[:8192].decode("utf-8", "replace")
70 extent = re.search(r'WholeExtent="0 (\d+) 0 (\d+) 0 (\d+)"', head)
71 if not extent:
72 raise ValueError(f"{path}: no WholeExtent in header.")
73 nodes = tuple(int(extent.group(i)) + 1 for i in (1, 2, 3))
74 marker = raw.find(b"<AppendedData")
75 if marker < 0:
76 raise ValueError(f"{path}: no appended data section.")
77 start = raw.find(b"_", marker) + 1
78 wide = 'header_type="UInt64"' in head
79 count_type, count_bytes = ("<u8", 8) if wide else ("<u4", 4)
80 arrays = {}
81 for match in re.finditer(
82 r'Name="([^"]+)" NumberOfComponents="(\d+)" format="appended" offset="(\d+)"', head
83 ):
84 name, ncomp, offset = match.group(1), int(match.group(2)), int(match.group(3))
85 base = start + offset
86 nbytes = int(numpy.frombuffer(raw, dtype=count_type, count=1, offset=base)[0])
87 values = numpy.frombuffer(raw, dtype="<f8", count=nbytes // 8, offset=base + count_bytes)
88 arrays[name] = values.reshape(-1, ncomp) if ncomp > 1 else values
89 return nodes, arrays
90
91
93 """!
94 @brief Read the periodicity the solver recorded in any committed checkpoint.
95 @param[in] run_dir Run directory to search.
96 @return Tuple of three booleans for i, j, k, or None when no checkpoint is present.
97 """
98 for root, _dirs, files in os.walk(os.path.join(run_dir, "output")):
99 if "checkpoint.meta" not in files:
100 continue
101 with open(os.path.join(root, "checkpoint.meta"), "r", encoding="utf-8") as stream:
102 for line in stream:
103 if line.startswith("-checkpoint_periodic "):
104 flags = line.split(None, 1)[1].strip().split(",")
105 return tuple(token.strip() == "1" for token in flags)
106 return None
107
108
109def newest_window_vts(viz_dir, window):
110 """!
111 @brief Locate the highest-step derived statistics file for one window.
112 @param[in] viz_dir Directory holding the post-processing output.
113 @param[in] window Window name.
114 @return Path to the selected file.
115 """
116 pattern = re.compile(rf"_statistics_{re.escape(window)}_(\d+)\.vts$")
117 best, best_step = None, -1
118 for name in sorted(os.listdir(viz_dir)):
119 match = pattern.search(name)
120 if match and int(match.group(1)) > best_step:
121 best, best_step = os.path.join(viz_dir, name), int(match.group(1))
122 if best is None:
123 raise ValueError(f"no derived statistics VTK output for window '{window}' in {viz_dir}.")
124 return best
125
126
127def check_periodic_wrap(arrays, nodes, periodic):
128 """!
129 @brief Verify every derived array wraps across each periodic layout boundary.
130
131 @details Independent of whether the flow is turbulent, so a steady case still guards
132 the layout boundary. An interior-only producer leaves the two boundary
133 planes holding different partial averages, which this detects directly.
134
135 @param[in] arrays Name-to-array mapping from `read_vts_point_arrays()`.
136 @param[in] nodes Node extent per direction, in i, j, k order.
137 @param[in] periodic Per-direction periodicity in i, j, k order.
138 @return Zero when every array wraps, or one on the first disagreement.
139 """
140 numpy = require_numpy()
141 checked = 0
142 for name, values in sorted(arrays.items()):
143 if name == "Position":
144 continue
145 ncomp = values.shape[1] if values.ndim > 1 else 1
146 field = values.reshape(nodes[2], nodes[1], nodes[0], ncomp)
147 # checkpoint_periodic is recorded in i, j, k order; the array is k, j, i.
148 for flag, axis, label in zip(periodic, (2, 1, 0), ("i", "j", "k")):
149 if not flag:
150 continue
151 low = numpy.take(field, 0, axis=axis)
152 high = numpy.take(field, field.shape[axis] - 1, axis=axis)
153 if not numpy.allclose(low, high):
154 print(f"[FAIL] '{name}': the two layout boundary planes in the periodic "
155 f"{label} direction differ, so the wrap was not applied. See "
156 f"SynchronizePeriodicCellFields().", file=sys.stderr)
157 return 1
158 checked += 1
159 print(f"[INFO] periodic layout boundary wraps verified on {checked} array/direction pair(s).")
160 return 0
161
162
163def main(argv=None):
164 """!
165 @brief Run the consistency check.
166 @param[in] argv Optional argument override for tests.
167 @return Process exit code.
168 """
169 numpy = require_numpy()
170 args = list(sys.argv[1:] if argv is None else argv)
171 if len(args) != 2:
172 print(USAGE, file=sys.stderr)
173 return 2
174 run_dir, window = args
175 # The two artifacts no longer share a directory: derived VTK lands in the run's
176 # visualization home and the convergence history in its statistics home, each
177 # under the producing recipe's own identity.
178 viz_dir = sole_recipe_dir(run_dir, os.path.join("output", "visualization"))
179 stats_dir = sole_recipe_dir(run_dir, os.path.join("output", "analysis", "statistics"))
180
181 try:
182 vts_path = newest_window_vts(viz_dir, window)
183 nodes, arrays = read_vts_point_arrays(vts_path)
184
185 periodic = read_checkpoint_periodicity(run_dir)
186 if periodic and any(periodic):
187 if check_periodic_wrap(arrays, nodes, periodic) != 0:
188 return 1
189
190 tke_name = next((n for n in arrays if n.endswith("_tke")), None)
191 if tke_name is None:
192 print(f"[SKIP] {os.path.basename(vts_path)} carries no turbulent kinetic energy field.")
193 return 0
194 field = arrays[tke_name].reshape(nodes[2], nodes[1], nodes[0])
195
196 csv_path = next(
197 (os.path.join(stats_dir, n) for n in sorted(os.listdir(stats_dir))
198 if n.endswith(f"_statistics_{window}.csv")), None
199 )
200 if csv_path is None:
201 raise ValueError(f"no convergence-history CSV for window '{window}' in {stats_dir}.")
202 rows = list(csv.DictReader(open(csv_path, "r", encoding="utf-8")))
203 if not rows or "mean_tke" not in rows[0]:
204 print(f"[SKIP] {os.path.basename(csv_path)} records no mean_tke column.")
205 return 0
206 reference = float(rows[-1]["mean_tke"])
207 if reference <= 0.0:
208 print(f"[SKIP] window '{window}' has no accumulated energy to compare.")
209 return 0
210
211 # Interior nodes only: the outermost node layer is a periodic duplicate of the
212 # opposite face, so counting it weights that plane twice.
213 interior = field[1:-1, 1:-1, 1:-1].mean()
214 deviation = abs(interior / reference - 1.0)
215 tolerance = 0.05
216 print(f"[INFO] {window}: nodal interior mean {interior:.6e} vs CSV mean_tke "
217 f"{reference:.6e} ({100*deviation:+.2f}%)")
218 if deviation > tolerance:
219 print(
220 f"[FAIL] derived statistics VTK and convergence CSV disagree by "
221 f"{100*deviation:.2f}%, above the {100*tolerance:.0f}% interpolation "
222 f"allowance. A layout boundary left unwritten by an interior-only "
223 f"producer is the usual cause; see SynchronizePeriodicCellFields().",
224 file=sys.stderr,
225 )
226 return 1
227
228 if periodic and all(periodic):
229 # On a fully periodic layout every boundary node is defined, so the whole
230 # domain must also agree. This is the assertion that catches an unwritten
231 # layout boundary: the interior stays correct either way, so an
232 # interior-only comparison would pass straight through the defect.
233 whole = field.mean()
234 whole_deviation = abs(whole / reference - 1.0)
235 print(f"[INFO] {window}: whole-domain nodal mean {whole:.6e} "
236 f"({100*whole_deviation:+.2f}%)")
237 if whole_deviation > tolerance:
238 print(
239 f"[FAIL] every boundary node is defined on a fully periodic layout, "
240 f"but the whole-domain nodal mean is off by {100*whole_deviation:.2f}%. "
241 f"The layout boundary was left unwritten; see SynchronizePeriodicCellFields().",
242 file=sys.stderr,
243 )
244 return 1
245
246 print("[PASS] derived statistics VTK is consistent with the convergence CSV.")
247 return 0
248 except Exception as exc: # noqa: BLE001 - a check reports rather than raises
249 print(f"[ERROR] statistics nodal consistency check failed: {exc}", file=sys.stderr)
250 return 1
251
252
253if __name__ == "__main__":
254 sys.exit(main())
check_periodic_wrap(arrays, nodes, periodic)
Verify every derived array wraps across each periodic layout boundary.
read_vts_point_arrays(path)
Read appended raw Float64 point arrays from a PICurv .vts.
require_numpy()
Import NumPy, which this checker needs to read the binary VTK payload.
newest_window_vts(viz_dir, window)
Locate the highest-step derived statistics file for one window.
str sole_recipe_dir(str run_dir, str canonical_relative)
Resolve the one per-recipe subdirectory beneath a canonical output home.
read_checkpoint_periodicity(run_dir)
Read the periodicity the solver recorded in any committed checkpoint.
Head of a generic C-style linked list.
Definition variables.h:504