cfdbender 0.4.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. cfdbender/__init__.py +7 -0
  2. cfdbender/_pyfs.py +92 -0
  3. cfdbender/core/__init__.py +13 -0
  4. cfdbender/core/adapter.py +148 -0
  5. cfdbender/core/executables.py +157 -0
  6. cfdbender/core/flight.py +346 -0
  7. cfdbender/core/matrix.py +354 -0
  8. cfdbender/core/naming.py +172 -0
  9. cfdbender/core/plan.py +463 -0
  10. cfdbender/core/registry.py +735 -0
  11. cfdbender/core/results.py +117 -0
  12. cfdbender/core/run.py +150 -0
  13. cfdbender/core/settings.py +92 -0
  14. cfdbender/core/workspace.py +93 -0
  15. cfdbender/geometry/__init__.py +1 -0
  16. cfdbender/geometry/blade_slicing.py +355 -0
  17. cfdbender/hpc/__init__.py +21 -0
  18. cfdbender/hpc/_plan.py +266 -0
  19. cfdbender/hpc/_profiles.py +305 -0
  20. cfdbender/hpc/_render.py +271 -0
  21. cfdbender/hpc/_submit.py +96 -0
  22. cfdbender/hpc/_walltime.py +301 -0
  23. cfdbender/matrix/__init__.py +1 -0
  24. cfdbender/matrix/cli.py +228 -0
  25. cfdbender/matrix/collection.py +251 -0
  26. cfdbender/matrix/exports.py +122 -0
  27. cfdbender/matrix/rerun.py +126 -0
  28. cfdbender/matrix/selection.py +62 -0
  29. cfdbender/matrix/submission.py +272 -0
  30. cfdbender/solvers/__init__.py +47 -0
  31. cfdbender/solvers/_host/__init__.py +1 -0
  32. cfdbender/solvers/_host/_config.py +10 -0
  33. cfdbender/solvers/_host/_execute.py +52 -0
  34. cfdbender/solvers/_host/_mesh.py +62 -0
  35. cfdbender/solvers/_host/_ram.py +69 -0
  36. cfdbender/solvers/_host/_single.py +63 -0
  37. cfdbender/solvers/flightstream/__init__.py +114 -0
  38. cfdbender/solvers/flightstream/reader.py +191 -0
  39. cfdbender/solvers/mock/__init__.py +273 -0
  40. cfdbender/solvers/openfoam/__init__.py +201 -0
  41. cfdbender/solvers/openfoam/_config.py +410 -0
  42. cfdbender/solvers/openfoam/_execute.py +162 -0
  43. cfdbender/solvers/openfoam/_history.py +158 -0
  44. cfdbender/solvers/pyfr/__init__.py +118 -0
  45. cfdbender/solvers/pyfr/_config.py +196 -0
  46. cfdbender/solvers/pyfr/_execute.py +127 -0
  47. cfdbender/solvers/pyfr/_history.py +88 -0
  48. cfdbender/solvers/qprop/__init__.py +303 -0
  49. cfdbender/solvers/qprop/_config.py +259 -0
  50. cfdbender/solvers/qprop/_execute.py +269 -0
  51. cfdbender/solvers/qprop/_output.py +64 -0
  52. cfdbender/solvers/qprop/_polar.py +98 -0
  53. cfdbender/solvers/qprop/_prop.py +81 -0
  54. cfdbender/solvers/qprop/_sections.py +193 -0
  55. cfdbender/solvers/su2/__init__.py +210 -0
  56. cfdbender/solvers/su2/_config.py +290 -0
  57. cfdbender/solvers/su2/_execute.py +196 -0
  58. cfdbender/solvers/su2/_history.py +117 -0
  59. cfdbender/solvers/su2/_pysu2_worker.py +25 -0
  60. cfdbender/solvers/su2/_ram.py +13 -0
  61. cfdbender/solvers/su2/_reference.py +79 -0
  62. cfdbender/solvers/su2/_single.py +3 -0
  63. cfdbender/solvers/su2/routes.py +61 -0
  64. cfdbender/solvers/xfoil/__init__.py +171 -0
  65. cfdbender/solvers/xfoil/_config.py +144 -0
  66. cfdbender/solvers/xfoil/_execute.py +227 -0
  67. cfdbender/solvers/xfoil/_polar.py +88 -0
  68. cfdbender/testing/__init__.py +301 -0
  69. cfdbender/workspace/__init__.py +1 -0
  70. cfdbender/workspace/cli.py +99 -0
  71. cfdbender/workspace/planning.py +38 -0
  72. cfdbender-0.4.2.dist-info/METADATA +57 -0
  73. cfdbender-0.4.2.dist-info/RECORD +77 -0
  74. cfdbender-0.4.2.dist-info/WHEEL +5 -0
  75. cfdbender-0.4.2.dist-info/entry_points.txt +3 -0
  76. cfdbender-0.4.2.dist-info/licenses/LICENSE +21 -0
  77. cfdbender-0.4.2.dist-info/top_level.txt +1 -0
@@ -0,0 +1,172 @@
1
+ """Name a datapoint folder from the point's flight condition.
2
+
3
+ The rule is the one pyflightstream writes, so a cfdbender workspace and a
4
+ pyflightstream workspace name the same operating point the same way: the
5
+ folder is ``DP-<point name>`` and the point name is every FLIGHT_CONDITION
6
+ variable of the row, in the row's order, each written as a code, the value
7
+ times a scale, rounded, and zero padded to a fixed width.
8
+
9
+ ======== ====== ===== ====== =======================================
10
+ Key Code Scale Width Example
11
+ ======== ====== ===== ====== =======================================
12
+ MACH M 1000 3 0.144 -> M144
13
+ TASmps V 10 4 34 -> V0340
14
+ REmi RE 100 3 4.38 -> RE438
15
+ ALTFT ALT 1 5 5000 -> ALT05000
16
+ dISA DT 10 4 sign 10 -> DT+100
17
+ RHOkgm3 RHO 10000 5 1.225 -> RHO12250
18
+ MUPas MU 1e9 5 1.8e-5 -> MU18000
19
+ ASMPS A 10 4 340 -> A3400
20
+ TK T 10 4 290 -> T2900
21
+ PPA PS 1 6 100000 -> PS100000
22
+ ALPHA AL 10 4 sign -2 -> AL-020
23
+ BETA BE 10 4 sign 4 -> BE+040
24
+ ADVANCE_RATIO J 100 4 sign 0.8 -> J+080 (``J`` is accepted)
25
+ RPM RPM 1 5 800 -> RPM00800 (a magnitude)
26
+ roll_rate P 10 4 sign as ALPHA
27
+ pitch_rate Q 10 4 sign as ALPHA
28
+ yaw_rate R 10 4 sign as ALPHA
29
+ ======== ====== ===== ====== =======================================
30
+
31
+ A signed field counts its sign in the width. An unsigned field refuses a
32
+ negative value, and RPM, a magnitude, refuses a negative value too. Rounding
33
+ is Python's ``round`` on the scaled value, as pyflightstream does.
34
+
35
+ A key that pyflightstream has no code for (the native keys of a solver row,
36
+ for example QPROP's ``V``, ``BETA07`` or ``RHO``) is written as its upper case
37
+ name followed by the value in Python's general format, such as ``V20`` or
38
+ ``RHO1.2``, so every row stays nameable. Two points of one row that write the
39
+ same name are refused when the plan is built, naming both points.
40
+ """
41
+
42
+ from __future__ import annotations
43
+
44
+ import math
45
+ import re
46
+ from collections.abc import Mapping, Sequence
47
+ from dataclasses import dataclass
48
+
49
+ from cfdbender.core.settings import WorkspaceError
50
+
51
+ DATAPOINT_PREFIX = "DP-"
52
+
53
+ #: The name of a point whose row states no FLIGHT_CONDITION.
54
+ NO_CONDITION = "NOCOND"
55
+
56
+
57
+ class PointNameError(WorkspaceError):
58
+ """A flight condition cannot be written as a point name."""
59
+
60
+
61
+ @dataclass(frozen=True)
62
+ class NameField:
63
+ """How one variable is written: code, then the scaled value, padded to width."""
64
+
65
+ code: str
66
+ scale: float
67
+ width: int
68
+ signed: bool
69
+ magnitude: bool = False
70
+
71
+
72
+ POINT_NAME_FIELDS: dict[str, NameField] = {
73
+ "MACH": NameField("M", 1000.0, 3, False),
74
+ "TASmps": NameField("V", 10.0, 4, False),
75
+ "REmi": NameField("RE", 100.0, 3, False),
76
+ "ALTFT": NameField("ALT", 1.0, 5, False),
77
+ "dISA": NameField("DT", 10.0, 4, True),
78
+ "RHOkgm3": NameField("RHO", 10000.0, 5, False),
79
+ "MUPas": NameField("MU", 1e9, 5, False),
80
+ "ASMPS": NameField("A", 10.0, 4, False),
81
+ "TK": NameField("T", 10.0, 4, False),
82
+ "PPA": NameField("PS", 1.0, 6, False),
83
+ "ALPHA": NameField("AL", 10.0, 4, True),
84
+ "BETA": NameField("BE", 10.0, 4, True),
85
+ "ADVANCE_RATIO": NameField("J", 100.0, 4, True),
86
+ "RPM": NameField("RPM", 1.0, 5, False, magnitude=True),
87
+ "roll_rate": NameField("P", 10.0, 4, True),
88
+ "pitch_rate": NameField("Q", 10.0, 4, True),
89
+ "yaw_rate": NameField("R", 10.0, 4, True),
90
+ }
91
+
92
+ #: Spellings that name a coded key, so QPROP's own ``J`` is written like ADVANCE_RATIO.
93
+ _ALIASES = {"J": "ADVANCE_RATIO"}
94
+
95
+ _PORTABLE = re.compile(r"[A-Za-z0-9._+-]+")
96
+
97
+
98
+ def name_field(key: str, value: float) -> str:
99
+ """Write one variable the way a point name carries it, for example ``M144``.
100
+
101
+ Parameters
102
+ ----------
103
+ key : str
104
+ A FLIGHT_CONDITION key. A key with no code is written as its upper case
105
+ name and the value in general format.
106
+ value : float
107
+ The variable's value on the point.
108
+
109
+ Returns
110
+ -------
111
+ str
112
+ The field text.
113
+
114
+ Raises
115
+ ------
116
+ PointNameError
117
+ If the value is not finite, or a negative value meets an unsigned or
118
+ magnitude field.
119
+ """
120
+ number = float(value)
121
+ if not math.isfinite(number):
122
+ raise PointNameError(f"{key} is {value!r}, which a point name cannot write")
123
+ field = POINT_NAME_FIELDS.get(_ALIASES.get(key, key))
124
+ if field is None:
125
+ return f"{key.upper()}{format(0.0 if number == 0 else number, 'g')}"
126
+ if field.magnitude and number < 0.0:
127
+ raise PointNameError(
128
+ f"{key} is {value!r}; a rotor speed is a magnitude, so write it positive"
129
+ )
130
+ scaled = round(number * field.scale)
131
+ if field.signed:
132
+ return f"{field.code}{scaled:+0{field.width}d}"
133
+ if number < 0.0:
134
+ raise PointNameError(
135
+ f"{key} is {value!r}, and a point name writes {key} without a sign; "
136
+ "the name cannot carry a negative value"
137
+ )
138
+ return f"{field.code}{scaled:0{field.width}d}"
139
+
140
+
141
+ def point_name(order: Sequence[str], condition: Mapping[str, float]) -> str:
142
+ """Return a point's name: its keys in the row's order, each as :func:`name_field`.
143
+
144
+ Parameters
145
+ ----------
146
+ order : sequence of str
147
+ The FLIGHT_CONDITION keys in the order the row declares them. Keys of
148
+ ``condition`` the order does not list follow, in the condition's order.
149
+ condition : mapping of str to float
150
+ The point's resolved values, the swept key at the point's own value.
151
+
152
+ Returns
153
+ -------
154
+ str
155
+ The point name, such as ``M120RE009AL+000BE+000J+100``.
156
+
157
+ Raises
158
+ ------
159
+ PointNameError
160
+ If a field cannot be written or the name is not portable.
161
+ """
162
+ keys = [key for key in order if key in condition]
163
+ keys.extend(key for key in condition if key not in keys)
164
+ name = "".join(name_field(key, condition[key]) for key in keys) or NO_CONDITION
165
+ if _PORTABLE.fullmatch(name) is None:
166
+ raise PointNameError(f"{name!r} is not a portable point name")
167
+ return name
168
+
169
+
170
+ def datapoint_dir_name(name: str) -> str:
171
+ """Return the folder a point's outputs go to: ``DP-<point name>``."""
172
+ return f"{DATAPOINT_PREFIX}{name}"
cfdbender/core/plan.py ADDED
@@ -0,0 +1,463 @@
1
+ """Expand matrix rows into a read-only plan through an injected solver hook.
2
+
3
+ Adapters implement validate_row(row, inputs) -> RowRequirements. They inspect
4
+ inputs.setup, inputs.reference and inputs.post, and read any additional files
5
+ through inputs.read_bytes/read_toml so every byte read is included in provenance.
6
+ The hook validates and describes actions; it must not run a solver or write files.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import hashlib
12
+ import re
13
+ import tomllib
14
+ from collections.abc import Mapping
15
+ from dataclasses import dataclass, field
16
+ from pathlib import Path
17
+ from types import MappingProxyType
18
+ from typing import Protocol
19
+
20
+ from cfdbender.core.matrix import MatrixRow, parse_matrix
21
+ from cfdbender.core.naming import PointNameError, datapoint_dir_name, point_name
22
+ from cfdbender.core.settings import WorkspaceError, _validate
23
+
24
+
25
+ def _empty() -> Mapping[str, object]:
26
+ return MappingProxyType({})
27
+
28
+
29
+ class PlanError(WorkspaceError):
30
+ """A workspace input, solver validation or output claim prevents planning."""
31
+
32
+
33
+ def workspace_path(root: Path, name: str) -> Path:
34
+ """Resolve a workspace-relative path, refusing escapes and ambiguous separators.
35
+
36
+ Parameters
37
+ ----------
38
+ root : Path
39
+ Resolved workspace root.
40
+ name : str
41
+ Relative POSIX path.
42
+
43
+ Returns
44
+ -------
45
+ Path
46
+ Contained absolute path, including symlink resolution.
47
+ """
48
+ path = checked_relative(name)
49
+ target = (root / path).resolve()
50
+ if not target.is_relative_to(root) or target == root:
51
+ raise PlanError(f"{name!r}: path outside workspace")
52
+ return target
53
+
54
+
55
+ def checked_relative(name: str) -> Path:
56
+ """Refuse a workspace path that escapes or is ambiguous on Windows, without resolving it.
57
+
58
+ Parameters
59
+ ----------
60
+ name : str
61
+ Relative POSIX path.
62
+
63
+ Returns
64
+ -------
65
+ Path
66
+ The unresolved relative path.
67
+ """
68
+ path = Path(name)
69
+ if not name or chr(92) in name or ":" in name or path.is_absolute() or ".." in path.parts:
70
+ raise PlanError(f"{name!r}: path outside workspace or not a relative POSIX path")
71
+ for part in path.parts:
72
+ stem = part.split(".", 1)[0].upper()
73
+ if (
74
+ part.endswith((".", " "))
75
+ or re.search(r"~[0-9]+(?:[.]|$)", part, re.IGNORECASE)
76
+ or stem in {"CON", "PRN", "AUX", "NUL"}
77
+ or re.fullmatch(r"(?:COM|LPT)[1-9]", stem)
78
+ or any(ord(c) < 32 or c in '<>"|?*' for c in part)
79
+ ):
80
+ raise PlanError(f"{name!r}: ambiguous or invalid Windows path component")
81
+ return path
82
+
83
+
84
+ class InputFiles:
85
+ """Read byte snapshots once, tracking workspace-relative SHA-256 keys."""
86
+
87
+ def __init__(self, root: Path) -> None:
88
+ self.root = root
89
+ self._bytes: dict[str, bytes] = {}
90
+
91
+ def read_bytes(self, name: str) -> bytes:
92
+ """Read and memoize an input, refusing a path outside this workspace.
93
+
94
+ Parameters
95
+ ----------
96
+ name : str
97
+ Workspace-relative input path, using forward slashes.
98
+
99
+ Returns
100
+ -------
101
+ bytes
102
+ Exact first-read bytes, also used for the recorded digest.
103
+ """
104
+ path = workspace_path(self.root, name)
105
+ key = path.relative_to(self.root).as_posix()
106
+ if key not in self._bytes:
107
+ try:
108
+ self._bytes[key] = path.read_bytes()
109
+ except OSError as error:
110
+ raise PlanError(f"{name}: cannot read: {error}") from error
111
+ return self._bytes[key]
112
+
113
+ def read_toml(self, name: str) -> Mapping[str, object]:
114
+ """Read TOML from the same byte snapshot used for its digest.
115
+
116
+ Parameters
117
+ ----------
118
+ name : str
119
+ Workspace-relative TOML input path.
120
+
121
+ Returns
122
+ -------
123
+ Mapping
124
+ Parsed TOML fields. Solver-specific schema validation belongs to the hook.
125
+ """
126
+ data = self.read_bytes(name)
127
+ try:
128
+ return tomllib.loads(data.decode("utf-8"))
129
+ except (UnicodeError, tomllib.TOMLDecodeError) as error:
130
+ raise PlanError(f"{name}: invalid TOML: {error}") from error
131
+
132
+ def digests(self) -> Mapping[str, str]:
133
+ """Return a sorted, immutable digest snapshot of every file read."""
134
+ return MappingProxyType(
135
+ {k: hashlib.sha256(v).hexdigest() for k, v in sorted(self._bytes.items())}
136
+ )
137
+
138
+
139
+ GEOMETRY_FOLDERS = ("inputs/geometries", "inputs/geometry")
140
+
141
+
142
+ def apply_variables(
143
+ setup: Mapping[str, object], variables: Mapping[str, object]
144
+ ) -> Mapping[str, object]:
145
+ """Return the setup with a row's VAR_NAMES_VALUES overrides applied.
146
+
147
+ Parameters
148
+ ----------
149
+ setup : Mapping
150
+ Parsed setup file.
151
+ variables : Mapping
152
+ Row overrides; a dotted key such as ``solver.threads`` sets a key of a table.
153
+
154
+ Returns
155
+ -------
156
+ Mapping
157
+ A new mapping; the parsed setup is not modified.
158
+ """
159
+ result: dict[str, object] = dict(setup)
160
+ for key, value in variables.items():
161
+ *tables, name = key.split(".")
162
+ target = result
163
+ for part in tables:
164
+ inner = target.get(part, {})
165
+ if not isinstance(inner, Mapping):
166
+ raise ValueError(f"VAR_NAMES_VALUES {key}: setup key {part} is not a table")
167
+ copied = dict(inner)
168
+ target[part] = copied
169
+ target = copied
170
+ target[name] = value
171
+ return result
172
+
173
+
174
+ def resolve_geometry(root: Path, cell: str | None) -> str | None:
175
+ """Resolve a GEOMETRY cell to a workspace-relative file, without reading it.
176
+
177
+ Parameters
178
+ ----------
179
+ root : Path
180
+ Resolved workspace root.
181
+ cell : str or None
182
+ A file name in inputs/geometries/ (or inputs/geometry/), a stem naming
183
+ exactly one file there, or a workspace-relative path containing ``/``.
184
+
185
+ Returns
186
+ -------
187
+ str or None
188
+ The workspace-relative POSIX path, or None when the row states none.
189
+ """
190
+ if cell is None:
191
+ return None
192
+ if "/" in cell:
193
+ candidates = [cell]
194
+ else:
195
+ candidates = [f"{folder}/{cell}" for folder in GEOMETRY_FOLDERS]
196
+ found = [name for name in candidates if workspace_path(root, name).is_file()]
197
+ if not found and "/" not in cell:
198
+ found = [
199
+ path.relative_to(root).as_posix()
200
+ for folder in GEOMETRY_FOLDERS
201
+ if (root / folder).is_dir()
202
+ for path in sorted((root / folder).glob(f"{cell}.*"))
203
+ if path.is_file()
204
+ ]
205
+ if len(found) != 1:
206
+ raise ValueError(
207
+ f"GEOMETRY {cell!r} names "
208
+ + (f"several files: {', '.join(found)}" if found else "no file")
209
+ + "; name one file of inputs/geometries/ (with its extension when stems repeat)"
210
+ )
211
+ return found[0]
212
+
213
+
214
+ class RowInputs(InputFiles):
215
+ """One row's s/r/p tables plus tracked access to further workspace inputs.
216
+
217
+ ``setup`` carries the row's VAR_NAMES_VALUES overrides. ``geometry`` is the
218
+ resolved GEOMETRY file, or None; an adapter reads it through read_bytes.
219
+ """
220
+
221
+ def __init__(self, root: Path, row: MatrixRow, common: InputFiles) -> None:
222
+ super().__init__(root)
223
+ self._bytes.update(common._bytes)
224
+ self.setup = apply_variables(
225
+ self.read_toml(f"inputs/setups/{row.setup_id}.toml"), row.variables
226
+ )
227
+ self.reference = self.read_toml(f"inputs/references/{row.reference_id}.toml")
228
+ self.post = self.read_toml(f"inputs/pproc/{row.post_id}.toml")
229
+ self.geometry = resolve_geometry(root, row.geometry)
230
+
231
+
232
+ @dataclass(frozen=True)
233
+ class RowRequirements:
234
+ """Solver hook response: actions and workspace-relative output templates.
235
+
236
+ Templates may use {pol} and {point}. The point token is a stable DP name.
237
+ Example: sims/sim_{pol}/datapoints/{point}/history.csv. No file is created.
238
+ """
239
+
240
+ actions: tuple[str, ...]
241
+ outputs: tuple[str, ...]
242
+
243
+
244
+ class RowValidator(Protocol):
245
+ """The solver-independent callable interface supplied by a composing layer."""
246
+
247
+ def __call__(self, row: MatrixRow, inputs: RowInputs) -> RowRequirements:
248
+ """Validate one row, read tracked inputs and describe the proposed work.
249
+
250
+ Parameters
251
+ ----------
252
+ row : MatrixRow
253
+ Matrix data and its input ids.
254
+ inputs : RowInputs
255
+ Parsed s/r/p and tracked readers for further inputs.
256
+
257
+ Returns
258
+ -------
259
+ RowRequirements
260
+ Actions and output paths. Raise ValueError to refuse the row.
261
+ """
262
+ ...
263
+
264
+
265
+ @dataclass(frozen=True)
266
+ class Point:
267
+ """One stable point with all inputs, proposed actions and claimed output paths."""
268
+
269
+ point_id: str
270
+ pol: str
271
+ setup_id: str
272
+ reference_id: str
273
+ post_id: str
274
+ condition: Mapping[str, float]
275
+ walltime: str | None
276
+ directory: str
277
+ actions: tuple[str, ...]
278
+ outputs: tuple[str, ...]
279
+ inputs_sha256: Mapping[str, str]
280
+ geometry: str | None = None
281
+ variables: Mapping[str, object] = field(default_factory=_empty)
282
+ ncpus: int | None = None
283
+ solver_build: str | None = None
284
+ description: str = ""
285
+ aircraft: str = ""
286
+ configuration: str = ""
287
+ hidden: bool = False
288
+
289
+
290
+ #: Point fields beyond the original record, with the value an older record implies.
291
+ POINT_EXTRAS: Mapping[str, object] = MappingProxyType(
292
+ {
293
+ "geometry": None,
294
+ "variables": {},
295
+ "ncpus": None,
296
+ "solver_build": None,
297
+ "description": "",
298
+ "aircraft": "",
299
+ "configuration": "",
300
+ "hidden": False,
301
+ }
302
+ )
303
+
304
+
305
+ @dataclass(frozen=True)
306
+ class RunPlan:
307
+ """An in-memory, solver-named plan; creating it writes no workspace files."""
308
+
309
+ root: Path
310
+ matrix: str
311
+ solver: str
312
+ points: tuple[Point, ...]
313
+
314
+
315
+ def _points(root: Path, row: MatrixRow, inputs: RowInputs, needs: RowRequirements) -> list[Point]:
316
+ if not needs.actions or any(not isinstance(a, str) or not a.strip() for a in needs.actions):
317
+ raise PlanError("solver validation must describe at least one non-empty action")
318
+ if not needs.outputs:
319
+ raise PlanError("solver validation must declare output paths")
320
+ points: list[Point] = []
321
+ names: dict[str, float | None] = {}
322
+ for value in row.sweep_values if row.sweep_key else (None,):
323
+ condition = dict(row.condition)
324
+ if row.sweep_key is not None and value is not None:
325
+ condition[row.sweep_key] = value
326
+ try:
327
+ name = point_name(row.condition_order, condition)
328
+ except PointNameError as error:
329
+ raise PlanError(f"POL {row.pol}: {error}") from error
330
+ if name in names:
331
+ raise PlanError(
332
+ f"POL {row.pol}: sweep values {names[name]!r} and {value!r} of "
333
+ f"{row.sweep_key} round to the same point name {name}; a datapoint folder "
334
+ "is named from its flight condition, so give the values distinct names "
335
+ "(for example further apart)"
336
+ )
337
+ names[name] = value
338
+ tag = datapoint_dir_name(name)
339
+ directory = f"sims/sim_{row.pol}/datapoints/{tag}"
340
+ outputs: list[str] = []
341
+ for template in needs.outputs:
342
+ try:
343
+ output = template.format(pol=row.pol, point=tag)
344
+ except (KeyError, IndexError, ValueError) as error:
345
+ raise PlanError(f"invalid output template {template!r}: {error}") from error
346
+ # A staged mesh output may already exist as a link to inputs/geometry: judge the
347
+ # output by its folder and name, never by what the link points at.
348
+ checked_relative(output)
349
+ parent, _, leaf = output.rpartition("/")
350
+ folder = workspace_path(root, parent) if parent else root
351
+ normalized = f"{folder.relative_to(root).as_posix()}/{leaf}" if parent else leaf
352
+ path = folder / leaf
353
+ if not parent or not normalized.startswith(("sims/", "post/")):
354
+ raise PlanError(f"{output}: output must be under sims/ or post/")
355
+ if path.is_dir():
356
+ raise PlanError(f"{output}: output is a directory")
357
+ outputs.append(normalized)
358
+ points.append(
359
+ Point(
360
+ point_id=f"{row.pol}/{tag}",
361
+ pol=row.pol,
362
+ setup_id=row.setup_id,
363
+ reference_id=row.reference_id,
364
+ post_id=row.post_id,
365
+ condition=MappingProxyType(condition),
366
+ walltime=row.walltime,
367
+ directory=directory,
368
+ actions=tuple(needs.actions),
369
+ outputs=tuple(outputs),
370
+ inputs_sha256=inputs.digests(),
371
+ geometry=inputs.geometry,
372
+ variables=row.variables,
373
+ ncpus=row.ncpus,
374
+ solver_build=row.solver_build,
375
+ description=row.description,
376
+ aircraft=row.aircraft,
377
+ configuration=row.configuration,
378
+ hidden=row.hidden,
379
+ )
380
+ )
381
+ return points
382
+
383
+
384
+ def check_claims(points: tuple[Point, ...]) -> None:
385
+ """Refuse duplicate point ids, overlapping directories and output path claims.
386
+
387
+ Parameters
388
+ ----------
389
+ points : tuple of Point
390
+ All points sharing a workspace, including any existing run records.
391
+ """
392
+ ids: set[str] = set()
393
+ claims: list[tuple[str, str, bool]] = []
394
+ for point in points:
395
+ if point.point_id.casefold() in ids:
396
+ raise PlanError(f"point {point.point_id!r} is recorded or planned twice")
397
+ ids.add(point.point_id.casefold())
398
+ for name, is_directory in [(point.directory, True), *((p, False) for p in point.outputs)]:
399
+ folded = name.casefold().rstrip("/")
400
+ for previous, owner, previous_dir in claims:
401
+ equal = folded == previous
402
+ overlaps = folded.startswith(previous + "/") or previous.startswith(folded + "/")
403
+ own_file_in_directory = owner == point.point_id and (
404
+ (previous_dir and folded.startswith(previous + "/"))
405
+ or (is_directory and previous.startswith(folded + "/"))
406
+ )
407
+ if (equal or overlaps) and not own_file_in_directory:
408
+ raise PlanError(
409
+ f"{name}: point {point.point_id!r} and point {owner!r} "
410
+ "would write the same path; choose distinct output paths"
411
+ )
412
+ claims.append((folded, point.point_id, is_directory))
413
+
414
+
415
+ def plan_matrix(root: str | Path, name: str, *, validators: Mapping[str, RowValidator]) -> RunPlan:
416
+ """Plan a named inputs/matrices/<name>.fs without writing or executing anything.
417
+
418
+ Parameters
419
+ ----------
420
+ root : str or Path
421
+ Workspace root containing init.toml.
422
+ name : str
423
+ Matrix filename or stem, without directory components.
424
+ validators : Mapping of str to RowValidator
425
+ Solver name to hook, supplied by the application. Core imports no adapters.
426
+
427
+ Returns
428
+ -------
429
+ RunPlan
430
+ Stable points, actions, path claims and SHA-256 of exact input bytes.
431
+
432
+ Raises
433
+ ------
434
+ PlanError
435
+ Missing input, malformed TOML, hook refusal or colliding output claims.
436
+ """
437
+ target = Path(root).resolve()
438
+ common = InputFiles(target)
439
+ try:
440
+ config = _validate(common.read_toml("init.toml"), target / "init.toml", validators.keys())
441
+ except WorkspaceError as error:
442
+ raise PlanError(str(error)) from error
443
+ stem = name.removesuffix(".fs")
444
+ if re.fullmatch("[A-Za-z0-9][A-Za-z0-9_-]*", stem) is None:
445
+ raise PlanError(f"{name!r}: name a .fs matrix in inputs/matrices/")
446
+ matrix = f"inputs/matrices/{stem}.fs"
447
+ rows = parse_matrix(common.read_bytes(matrix), Path(matrix))
448
+ points: list[Point] = []
449
+ for row in rows:
450
+ try:
451
+ inputs = RowInputs(target, row, common)
452
+ needs = validators[config.solver](row, inputs)
453
+ if inputs.geometry is not None and inputs.geometry not in inputs.digests():
454
+ raise PlanError(
455
+ f"solver {config.solver!r} does not read the GEOMETRY column; "
456
+ "name the geometry where its setup documents it and write - in the cell"
457
+ )
458
+ points.extend(_points(target, row, inputs, needs))
459
+ except (ValueError, OSError) as error:
460
+ raise PlanError(f"data row {row.row_number}, POL {row.pol}: {error}") from error
461
+ result = tuple(points)
462
+ check_claims(result)
463
+ return RunPlan(target, matrix, config.solver, result)