5@file check_statistics_nodal_consistency.py
6@brief Cross-check derived statistics VTK output against the convergence-history CSV.
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.
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.
19check_statistics_nodal_consistency.py RUN_DIR WINDOW_NAME
24USAGE =
"usage: check_statistics_nodal_consistency.py RUN_DIR WINDOW_NAME"
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.
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)))
47 f
"expected exactly one recipe directory under {root}, found {entries}."
49 return os.path.join(root, entries[0])
54 @brief Import NumPy, which this checker needs to read the binary VTK payload.
55 @return Imported NumPy module.
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.
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)
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")
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)
81 for match
in re.finditer(
82 r'Name="([^"]+)" NumberOfComponents="(\d+)" format="appended" offset="(\d+)"', head
84 name, ncomp, offset = match.group(1), int(match.group(2)), int(match.group(3))
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
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.
98 for root, _dirs, files
in os.walk(os.path.join(run_dir,
"output")):
99 if "checkpoint.meta" not in files:
101 with open(os.path.join(root,
"checkpoint.meta"),
"r", encoding=
"utf-8")
as 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)
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.
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))
123 raise ValueError(f
"no derived statistics VTK output for window '{window}' in {viz_dir}.")
129 @brief Verify every derived array wraps across each periodic layout boundary.
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.
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.
142 for name, values
in sorted(arrays.items()):
143 if name ==
"Position":
145 ncomp = values.shape[1]
if values.ndim > 1
else 1
146 field = values.reshape(nodes[2], nodes[1], nodes[0], ncomp)
148 for flag, axis, label
in zip(periodic, (2, 1, 0), (
"i",
"j",
"k")):
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)
159 print(f
"[INFO] periodic layout boundary wraps verified on {checked} array/direction pair(s).")
165 @brief Run the consistency check.
166 @param[in] argv Optional argument override for tests.
167 @return Process exit code.
170 args =
list(sys.argv[1:]
if argv
is None else argv)
172 print(USAGE, file=sys.stderr)
174 run_dir, window = args
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"))
186 if periodic
and any(periodic):
190 tke_name = next((n
for n
in arrays
if n.endswith(
"_tke")),
None)
192 print(f
"[SKIP] {os.path.basename(vts_path)} carries no turbulent kinetic energy field.")
194 field = arrays[tke_name].reshape(nodes[2], nodes[1], nodes[0])
197 (os.path.join(stats_dir, n)
for n
in sorted(os.listdir(stats_dir))
198 if n.endswith(f
"_statistics_{window}.csv")),
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.")
206 reference = float(rows[-1][
"mean_tke"])
208 print(f
"[SKIP] window '{window}' has no accumulated energy to compare.")
213 interior = field[1:-1, 1:-1, 1:-1].mean()
214 deviation = abs(interior / reference - 1.0)
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:
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().",
228 if periodic
and all(periodic):
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:
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().",
246 print(
"[PASS] derived statistics VTK is consistent with the convergence CSV.")
248 except Exception
as exc:
249 print(f
"[ERROR] statistics nodal consistency check failed: {exc}", file=sys.stderr)
253if __name__ ==
"__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.
main(argv=None)
Run the consistency check.
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.