PICurv 0.1.0
A Parallel Particle-In-Cell Solver for Curvilinear LES
 
Loading...
Searching...
No Matches
Functions | Variables
check_statistics_nodal_consistency Namespace Reference

Functions

str sole_recipe_dir (str run_dir, str canonical_relative)
 Resolve the one per-recipe subdirectory beneath a canonical output home.
 
 require_numpy ()
 Import NumPy, which this checker needs to read the binary VTK payload.
 
 read_vts_point_arrays (path)
 Read appended raw Float64 point arrays from a PICurv .vts.
 
 read_checkpoint_periodicity (run_dir)
 Read the periodicity the solver recorded in any committed checkpoint.
 
 newest_window_vts (viz_dir, window)
 Locate the highest-step derived statistics file for one window.
 
 check_periodic_wrap (arrays, nodes, periodic)
 Verify every derived array wraps across each periodic layout boundary.
 
 main (argv=None)
 Run the consistency check.
 

Variables

str USAGE = "usage: check_statistics_nodal_consistency.py RUN_DIR WINDOW_NAME"
 

Function Documentation

◆ sole_recipe_dir()

str check_statistics_nodal_consistency.sole_recipe_dir ( str  run_dir,
str  canonical_relative 
)

Resolve the one per-recipe subdirectory beneath a canonical output home.

Parameters
[in]run_dirRun directory being inspected.
[in]canonical_relativeRun-relative canonical home, such as output/visualization.
Returns
Absolute path to the single recipe subdirectory.
Exceptions
ValueErrorwhen the home is absent or holds anything but one recipe.

Definition at line 32 of file check_statistics_nodal_consistency.py.

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
Here is the caller graph for this function:

◆ require_numpy()

check_statistics_nodal_consistency.require_numpy ( )

Import NumPy, which this checker needs to read the binary VTK payload.

Returns
Imported NumPy module.

Definition at line 52 of file check_statistics_nodal_consistency.py.

52def require_numpy():
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
Here is the caller graph for this function:

◆ read_vts_point_arrays()

check_statistics_nodal_consistency.read_vts_point_arrays (   path)

Read appended raw Float64 point arrays from a PICurv .vts.

Parameters
[in]pathVTK structured-grid file path.
Returns
Tuple of the node extent per direction and a name-to-array mapping.

Definition at line 61 of file check_statistics_nodal_consistency.py.

61def read_vts_point_arrays(path):
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
Here is the call graph for this function:
Here is the caller graph for this function:

◆ read_checkpoint_periodicity()

check_statistics_nodal_consistency.read_checkpoint_periodicity (   run_dir)

Read the periodicity the solver recorded in any committed checkpoint.

Parameters
[in]run_dirRun directory to search.
Returns
Tuple of three booleans for i, j, k, or None when no checkpoint is present.

Definition at line 92 of file check_statistics_nodal_consistency.py.

92def read_checkpoint_periodicity(run_dir):
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
Here is the caller graph for this function:

◆ newest_window_vts()

check_statistics_nodal_consistency.newest_window_vts (   viz_dir,
  window 
)

Locate the highest-step derived statistics file for one window.

Parameters
[in]viz_dirDirectory holding the post-processing output.
[in]windowWindow name.
Returns
Path to the selected file.

Definition at line 109 of file check_statistics_nodal_consistency.py.

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
Here is the caller graph for this function:

◆ check_periodic_wrap()

check_statistics_nodal_consistency.check_periodic_wrap (   arrays,
  nodes,
  periodic 
)

Verify every derived array wraps across each periodic layout boundary.

Independent of whether the flow is turbulent, so a steady case still guards the layout boundary. An interior-only producer leaves the two boundary planes holding different partial averages, which this detects directly.

Parameters
[in]arraysName-to-array mapping from read_vts_point_arrays().
[in]nodesNode extent per direction, in i, j, k order.
[in]periodicPer-direction periodicity in i, j, k order.
Returns
Zero when every array wraps, or one on the first disagreement.

Definition at line 127 of file check_statistics_nodal_consistency.py.

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
Here is the call graph for this function:
Here is the caller graph for this function:

◆ main()

check_statistics_nodal_consistency.main (   argv = None)

Run the consistency check.

Parameters
[in]argvOptional argument override for tests.
Returns
Process exit code.

Definition at line 163 of file check_statistics_nodal_consistency.py.

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
int main(int argc, char **argv)
Entry point for the postprocessor executable.
Head of a generic C-style linked list.
Definition variables.h:504
Here is the call graph for this function:
Here is the caller graph for this function:

Variable Documentation

◆ USAGE

str check_statistics_nodal_consistency.USAGE = "usage: check_statistics_nodal_consistency.py RUN_DIR WINDOW_NAME"

Definition at line 24 of file check_statistics_nodal_consistency.py.