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.
- cfdbender/__init__.py +7 -0
- cfdbender/_pyfs.py +92 -0
- cfdbender/core/__init__.py +13 -0
- cfdbender/core/adapter.py +148 -0
- cfdbender/core/executables.py +157 -0
- cfdbender/core/flight.py +346 -0
- cfdbender/core/matrix.py +354 -0
- cfdbender/core/naming.py +172 -0
- cfdbender/core/plan.py +463 -0
- cfdbender/core/registry.py +735 -0
- cfdbender/core/results.py +117 -0
- cfdbender/core/run.py +150 -0
- cfdbender/core/settings.py +92 -0
- cfdbender/core/workspace.py +93 -0
- cfdbender/geometry/__init__.py +1 -0
- cfdbender/geometry/blade_slicing.py +355 -0
- cfdbender/hpc/__init__.py +21 -0
- cfdbender/hpc/_plan.py +266 -0
- cfdbender/hpc/_profiles.py +305 -0
- cfdbender/hpc/_render.py +271 -0
- cfdbender/hpc/_submit.py +96 -0
- cfdbender/hpc/_walltime.py +301 -0
- cfdbender/matrix/__init__.py +1 -0
- cfdbender/matrix/cli.py +228 -0
- cfdbender/matrix/collection.py +251 -0
- cfdbender/matrix/exports.py +122 -0
- cfdbender/matrix/rerun.py +126 -0
- cfdbender/matrix/selection.py +62 -0
- cfdbender/matrix/submission.py +272 -0
- cfdbender/solvers/__init__.py +47 -0
- cfdbender/solvers/_host/__init__.py +1 -0
- cfdbender/solvers/_host/_config.py +10 -0
- cfdbender/solvers/_host/_execute.py +52 -0
- cfdbender/solvers/_host/_mesh.py +62 -0
- cfdbender/solvers/_host/_ram.py +69 -0
- cfdbender/solvers/_host/_single.py +63 -0
- cfdbender/solvers/flightstream/__init__.py +114 -0
- cfdbender/solvers/flightstream/reader.py +191 -0
- cfdbender/solvers/mock/__init__.py +273 -0
- cfdbender/solvers/openfoam/__init__.py +201 -0
- cfdbender/solvers/openfoam/_config.py +410 -0
- cfdbender/solvers/openfoam/_execute.py +162 -0
- cfdbender/solvers/openfoam/_history.py +158 -0
- cfdbender/solvers/pyfr/__init__.py +118 -0
- cfdbender/solvers/pyfr/_config.py +196 -0
- cfdbender/solvers/pyfr/_execute.py +127 -0
- cfdbender/solvers/pyfr/_history.py +88 -0
- cfdbender/solvers/qprop/__init__.py +303 -0
- cfdbender/solvers/qprop/_config.py +259 -0
- cfdbender/solvers/qprop/_execute.py +269 -0
- cfdbender/solvers/qprop/_output.py +64 -0
- cfdbender/solvers/qprop/_polar.py +98 -0
- cfdbender/solvers/qprop/_prop.py +81 -0
- cfdbender/solvers/qprop/_sections.py +193 -0
- cfdbender/solvers/su2/__init__.py +210 -0
- cfdbender/solvers/su2/_config.py +290 -0
- cfdbender/solvers/su2/_execute.py +196 -0
- cfdbender/solvers/su2/_history.py +117 -0
- cfdbender/solvers/su2/_pysu2_worker.py +25 -0
- cfdbender/solvers/su2/_ram.py +13 -0
- cfdbender/solvers/su2/_reference.py +79 -0
- cfdbender/solvers/su2/_single.py +3 -0
- cfdbender/solvers/su2/routes.py +61 -0
- cfdbender/solvers/xfoil/__init__.py +171 -0
- cfdbender/solvers/xfoil/_config.py +144 -0
- cfdbender/solvers/xfoil/_execute.py +227 -0
- cfdbender/solvers/xfoil/_polar.py +88 -0
- cfdbender/testing/__init__.py +301 -0
- cfdbender/workspace/__init__.py +1 -0
- cfdbender/workspace/cli.py +99 -0
- cfdbender/workspace/planning.py +38 -0
- cfdbender-0.4.2.dist-info/METADATA +57 -0
- cfdbender-0.4.2.dist-info/RECORD +77 -0
- cfdbender-0.4.2.dist-info/WHEEL +5 -0
- cfdbender-0.4.2.dist-info/entry_points.txt +3 -0
- cfdbender-0.4.2.dist-info/licenses/LICENSE +21 -0
- cfdbender-0.4.2.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,735 @@
|
|
|
1
|
+
"""Store proposals and execution evidence per point in a workspace's runs.json.
|
|
2
|
+
|
|
3
|
+
Registration is explicit and separate from planning. Records describe proposed
|
|
4
|
+
work, with status PLANNED; RUNNING claims a point and COMPLETED seals evidence.
|
|
5
|
+
Numerical classification is separate from the execution lifecycle.
|
|
6
|
+
An exclusive writer lock and atomic replacement protect the record document.
|
|
7
|
+
|
|
8
|
+
A rerun archives: the document is copied to archive/<stamp>/runs.json, the
|
|
9
|
+
point folder moves to archive/<stamp>/<its directory>, and the record leaves
|
|
10
|
+
the records list for the document's history list, which keeps every archived
|
|
11
|
+
record with its time and archive folder. Nothing is deleted.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
import hashlib
|
|
17
|
+
import json
|
|
18
|
+
import math
|
|
19
|
+
import os
|
|
20
|
+
import re
|
|
21
|
+
import tempfile
|
|
22
|
+
from collections.abc import Mapping
|
|
23
|
+
from dataclasses import dataclass, field, replace
|
|
24
|
+
from datetime import UTC, datetime
|
|
25
|
+
from pathlib import Path
|
|
26
|
+
from types import MappingProxyType
|
|
27
|
+
from typing import Any, cast
|
|
28
|
+
|
|
29
|
+
from cfdbender.core.plan import (
|
|
30
|
+
POINT_EXTRAS,
|
|
31
|
+
PlanError,
|
|
32
|
+
Point,
|
|
33
|
+
RunPlan,
|
|
34
|
+
check_claims,
|
|
35
|
+
workspace_path,
|
|
36
|
+
)
|
|
37
|
+
from cfdbender.core.results import Classification
|
|
38
|
+
from cfdbender.core.settings import WorkspaceError
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class RegistryError(WorkspaceError):
|
|
42
|
+
"""A registry read or write would lose or misidentify point evidence."""
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
@dataclass(frozen=True)
|
|
46
|
+
class RunRecord:
|
|
47
|
+
"""One point's immutable proposal, status and timezone-qualified creation time."""
|
|
48
|
+
|
|
49
|
+
point: Point
|
|
50
|
+
matrix: str
|
|
51
|
+
solver: str
|
|
52
|
+
status: str
|
|
53
|
+
created_at: str
|
|
54
|
+
started_at: str | None = None
|
|
55
|
+
completed_at: str | None = None
|
|
56
|
+
classification: Classification | None = None
|
|
57
|
+
outputs_sha256: Mapping[str, str] = field(default_factory=lambda: MappingProxyType({}))
|
|
58
|
+
error: str | None = None
|
|
59
|
+
submission: Mapping[str, object] | None = None
|
|
60
|
+
|
|
61
|
+
@property
|
|
62
|
+
def point_id(self) -> str:
|
|
63
|
+
"""Return the point's stable identifier."""
|
|
64
|
+
return self.point.point_id
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def _timestamp(value: str) -> str:
|
|
68
|
+
try:
|
|
69
|
+
stamp = datetime.fromisoformat(value)
|
|
70
|
+
except ValueError as error:
|
|
71
|
+
raise RegistryError("created_at must be an ISO 8601 timestamp with a timezone") from error
|
|
72
|
+
if stamp.utcoffset() is None:
|
|
73
|
+
raise RegistryError("created_at must include a timezone")
|
|
74
|
+
return stamp.astimezone(UTC).isoformat()
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def _object(value: object) -> dict[str, object]:
|
|
78
|
+
if not isinstance(value, dict) or any(not isinstance(k, str) for k in value):
|
|
79
|
+
raise RegistryError("expected a JSON object")
|
|
80
|
+
return dict(value)
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def _text(values: dict[str, object], key: str) -> str:
|
|
84
|
+
value = values.get(key)
|
|
85
|
+
if not isinstance(value, str) or not value:
|
|
86
|
+
raise RegistryError(f"{key} must be a non-empty string")
|
|
87
|
+
return value
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def _strings(values: dict[str, object], key: str) -> tuple[str, ...]:
|
|
91
|
+
value = values.get(key)
|
|
92
|
+
if not isinstance(value, list) or not value:
|
|
93
|
+
raise RegistryError(f"{key} must be a non-empty list")
|
|
94
|
+
result = tuple(value)
|
|
95
|
+
if any(not isinstance(v, str) or not v for v in result):
|
|
96
|
+
raise RegistryError(f"{key} must contain non-empty strings")
|
|
97
|
+
return result
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def _submission(raw: object, root: Path, directory: str, started: str) -> Mapping[str, object]:
|
|
101
|
+
values = _object(raw)
|
|
102
|
+
job_outputs = values.pop("job_outputs", None)
|
|
103
|
+
if set(values) != {
|
|
104
|
+
"descriptor",
|
|
105
|
+
"descriptor_sha256",
|
|
106
|
+
"config_path",
|
|
107
|
+
"config_sha256",
|
|
108
|
+
"profile",
|
|
109
|
+
"command",
|
|
110
|
+
"stdout_path",
|
|
111
|
+
"stderr_path",
|
|
112
|
+
"stdout",
|
|
113
|
+
"stderr",
|
|
114
|
+
"started_at",
|
|
115
|
+
"finished_at",
|
|
116
|
+
"return_code",
|
|
117
|
+
"timeout_s",
|
|
118
|
+
"timed_out",
|
|
119
|
+
}:
|
|
120
|
+
raise RegistryError("submission has missing or unknown fields")
|
|
121
|
+
for key in ("descriptor", "config_path", "stdout_path", "stderr_path"):
|
|
122
|
+
name = _text(values, key)
|
|
123
|
+
path = workspace_path(root, name)
|
|
124
|
+
if path.relative_to(root).as_posix() != name or path.parent != root / directory:
|
|
125
|
+
raise RegistryError(f"submission {key} must be in the point directory")
|
|
126
|
+
for key in ("descriptor_sha256", "config_sha256"):
|
|
127
|
+
if re.fullmatch("[0-9a-f]{64}", _text(values, key)) is None:
|
|
128
|
+
raise RegistryError(f"submission {key} must be a SHA-256 hex digest")
|
|
129
|
+
profile = _text(values, "profile")
|
|
130
|
+
if (
|
|
131
|
+
workspace_path(root, profile).relative_to(root).as_posix() != profile
|
|
132
|
+
or not profile.startswith("inputs/hpc/")
|
|
133
|
+
or not profile.endswith(".toml")
|
|
134
|
+
):
|
|
135
|
+
raise RegistryError("submission profile must name inputs/hpc/<NAME>.toml")
|
|
136
|
+
command = values["command"]
|
|
137
|
+
if (
|
|
138
|
+
not isinstance(command, (list, tuple))
|
|
139
|
+
or not command
|
|
140
|
+
or any(not isinstance(part, str) or not part for part in command)
|
|
141
|
+
):
|
|
142
|
+
raise RegistryError("submission command must be a non-empty argv list")
|
|
143
|
+
if any(not isinstance(values[key], str) for key in ("stdout", "stderr")):
|
|
144
|
+
raise RegistryError("submission stdout and stderr must be text")
|
|
145
|
+
timeout = values["timeout_s"]
|
|
146
|
+
if (
|
|
147
|
+
isinstance(timeout, bool)
|
|
148
|
+
or not isinstance(timeout, (int, float))
|
|
149
|
+
or not math.isfinite(timeout)
|
|
150
|
+
or timeout <= 0
|
|
151
|
+
):
|
|
152
|
+
raise RegistryError("submission timeout_s must be finite and positive")
|
|
153
|
+
if type(values["return_code"]) is not int or type(values["timed_out"]) is not bool:
|
|
154
|
+
raise RegistryError("submission requires an integer return_code and boolean timed_out")
|
|
155
|
+
if job_outputs is not None:
|
|
156
|
+
if (
|
|
157
|
+
not isinstance(job_outputs, (list, tuple))
|
|
158
|
+
or not job_outputs
|
|
159
|
+
or any(not isinstance(name, str) or not name for name in job_outputs)
|
|
160
|
+
):
|
|
161
|
+
raise RegistryError("submission job_outputs must be a non-empty list of paths")
|
|
162
|
+
values["job_outputs"] = tuple(job_outputs)
|
|
163
|
+
begin = _timestamp(_text(values, "started_at"))
|
|
164
|
+
finish = _timestamp(_text(values, "finished_at"))
|
|
165
|
+
if (
|
|
166
|
+
not datetime.fromisoformat(started)
|
|
167
|
+
<= datetime.fromisoformat(begin)
|
|
168
|
+
<= datetime.fromisoformat(finish)
|
|
169
|
+
):
|
|
170
|
+
raise RegistryError("submission timestamps precede the run or each other")
|
|
171
|
+
return MappingProxyType(
|
|
172
|
+
{**values, "command": tuple(command), "started_at": begin, "finished_at": finish}
|
|
173
|
+
)
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def _extras(row: Mapping[str, object]) -> dict[str, Any]:
|
|
177
|
+
"""Read the optional row columns a point carries, refusing a wrong type."""
|
|
178
|
+
found: dict[str, Any] = {}
|
|
179
|
+
for key in POINT_EXTRAS:
|
|
180
|
+
if key not in row:
|
|
181
|
+
continue
|
|
182
|
+
value = row[key]
|
|
183
|
+
if key == "variables":
|
|
184
|
+
found[key] = MappingProxyType(dict(_object(value)))
|
|
185
|
+
continue
|
|
186
|
+
if key in {"geometry", "solver_build"}:
|
|
187
|
+
valid = value is None or (isinstance(value, str) and bool(value))
|
|
188
|
+
elif key == "ncpus":
|
|
189
|
+
valid = value is None or (type(value) is int and value > 0)
|
|
190
|
+
elif key == "hidden":
|
|
191
|
+
valid = isinstance(value, bool)
|
|
192
|
+
else:
|
|
193
|
+
valid = isinstance(value, str)
|
|
194
|
+
if not valid:
|
|
195
|
+
raise RegistryError(f"{key} has an invalid value in a run record")
|
|
196
|
+
found[key] = value
|
|
197
|
+
return found
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
def _decode(raw: object, root: Path) -> RunRecord:
|
|
201
|
+
row = _object(raw)
|
|
202
|
+
expected = {
|
|
203
|
+
"point_id",
|
|
204
|
+
"pol",
|
|
205
|
+
"setup_id",
|
|
206
|
+
"reference_id",
|
|
207
|
+
"post_id",
|
|
208
|
+
"condition",
|
|
209
|
+
"walltime",
|
|
210
|
+
"directory",
|
|
211
|
+
"actions",
|
|
212
|
+
"outputs",
|
|
213
|
+
"inputs_sha256",
|
|
214
|
+
"matrix",
|
|
215
|
+
"solver",
|
|
216
|
+
"status",
|
|
217
|
+
"created_at",
|
|
218
|
+
}
|
|
219
|
+
execution = {"started_at", "completed_at", "classification", "outputs_sha256", "error"}
|
|
220
|
+
status = _text(row, "status")
|
|
221
|
+
optional = {"submission"} if "submission" in row and status != "PLANNED" else set()
|
|
222
|
+
optional |= set(row) & set(POINT_EXTRAS)
|
|
223
|
+
if set(row) != expected | (execution if status != "PLANNED" else set()) | optional:
|
|
224
|
+
raise RegistryError("run record has missing or unknown fields")
|
|
225
|
+
condition: dict[str, float] = {}
|
|
226
|
+
for key, value in _object(row["condition"]).items():
|
|
227
|
+
if (
|
|
228
|
+
isinstance(value, bool)
|
|
229
|
+
or not isinstance(value, (int, float))
|
|
230
|
+
or not math.isfinite(value)
|
|
231
|
+
):
|
|
232
|
+
raise RegistryError(f"condition {key} must be finite")
|
|
233
|
+
condition[key] = float(value)
|
|
234
|
+
digests: dict[str, str] = {}
|
|
235
|
+
for key, value in _object(row["inputs_sha256"]).items():
|
|
236
|
+
workspace_path(root, key)
|
|
237
|
+
if not isinstance(value, str) or re.fullmatch("[0-9a-f]{64}", value) is None:
|
|
238
|
+
raise RegistryError(f"inputs_sha256 for {key} must be a SHA-256 hex digest")
|
|
239
|
+
digests[key] = value
|
|
240
|
+
pol = _text(row, "pol")
|
|
241
|
+
point_id = _text(row, "point_id")
|
|
242
|
+
if not point_id.startswith(pol + "/DP-") or re.fullmatch("[A-Za-z0-9_-]+", pol) is None:
|
|
243
|
+
raise RegistryError("point_id must identify POL and its DP name")
|
|
244
|
+
matrix = _text(row, "matrix")
|
|
245
|
+
required_inputs = {
|
|
246
|
+
"init.toml",
|
|
247
|
+
matrix,
|
|
248
|
+
f"inputs/setups/{_text(row, 'setup_id')}.toml",
|
|
249
|
+
f"inputs/references/{_text(row, 'reference_id')}.toml",
|
|
250
|
+
f"inputs/pproc/{_text(row, 'post_id')}.toml",
|
|
251
|
+
}
|
|
252
|
+
if not required_inputs <= set(digests):
|
|
253
|
+
raise RegistryError("inputs_sha256 is missing a matrix, init.toml or s/r/p input")
|
|
254
|
+
directory = _text(row, "directory")
|
|
255
|
+
outputs = _strings(row, "outputs")
|
|
256
|
+
for name in (directory, *outputs):
|
|
257
|
+
# The record names the path, not what it points at: a staged mesh is a link to
|
|
258
|
+
# inputs/geometry, so only the containing folder is resolved, never the file itself.
|
|
259
|
+
parent, _, leaf = name.rpartition("/")
|
|
260
|
+
folder = workspace_path(root, parent) if parent else root
|
|
261
|
+
if (
|
|
262
|
+
not parent
|
|
263
|
+
or not leaf
|
|
264
|
+
or folder.relative_to(root).as_posix() != parent
|
|
265
|
+
or not name.startswith(("sims/", "post/"))
|
|
266
|
+
):
|
|
267
|
+
raise RegistryError(f"{name}: record path must be canonical under sims/ or post/")
|
|
268
|
+
walltime = row["walltime"]
|
|
269
|
+
if walltime is not None and not isinstance(walltime, str):
|
|
270
|
+
raise RegistryError("walltime must be a string or null")
|
|
271
|
+
if status not in ("PLANNED", "RUNNING", "SUBMITTED", "COMPLETED"):
|
|
272
|
+
raise RegistryError(f"unsupported run status {status!r}")
|
|
273
|
+
point = Point(
|
|
274
|
+
point_id=point_id,
|
|
275
|
+
pol=pol,
|
|
276
|
+
setup_id=_text(row, "setup_id"),
|
|
277
|
+
reference_id=_text(row, "reference_id"),
|
|
278
|
+
post_id=_text(row, "post_id"),
|
|
279
|
+
condition=MappingProxyType(condition),
|
|
280
|
+
walltime=walltime,
|
|
281
|
+
directory=directory,
|
|
282
|
+
actions=_strings(row, "actions"),
|
|
283
|
+
outputs=outputs,
|
|
284
|
+
inputs_sha256=MappingProxyType(digests),
|
|
285
|
+
**_extras(row),
|
|
286
|
+
)
|
|
287
|
+
record = RunRecord(
|
|
288
|
+
point, matrix, _text(row, "solver"), status, _timestamp(_text(row, "created_at"))
|
|
289
|
+
)
|
|
290
|
+
if status == "PLANNED":
|
|
291
|
+
return record
|
|
292
|
+
started = _timestamp(_text(row, "started_at"))
|
|
293
|
+
if datetime.fromisoformat(started) < datetime.fromisoformat(record.created_at):
|
|
294
|
+
raise RegistryError("started_at precedes created_at")
|
|
295
|
+
if "submission" in row:
|
|
296
|
+
record = replace(
|
|
297
|
+
record, submission=_submission(row["submission"], root, directory, started)
|
|
298
|
+
)
|
|
299
|
+
if status == "SUBMITTED" and record.submission is None:
|
|
300
|
+
raise RegistryError("SUBMITTED requires submission evidence")
|
|
301
|
+
classification = row["classification"]
|
|
302
|
+
error = row["error"]
|
|
303
|
+
if error is not None and (not isinstance(error, str) or not error.strip()):
|
|
304
|
+
raise RegistryError("error must be a non-empty string or null")
|
|
305
|
+
output_digests: dict[str, str] = {}
|
|
306
|
+
for name, digest in _object(row["outputs_sha256"]).items():
|
|
307
|
+
if (
|
|
308
|
+
name not in outputs
|
|
309
|
+
or not isinstance(digest, str)
|
|
310
|
+
or not re.fullmatch("[0-9a-f]{64}", digest)
|
|
311
|
+
):
|
|
312
|
+
raise RegistryError("outputs_sha256 must name declared outputs with SHA-256 digests")
|
|
313
|
+
output_digests[name] = digest
|
|
314
|
+
if status in ("RUNNING", "SUBMITTED"):
|
|
315
|
+
if classification is not None or row["completed_at"] is not None or output_digests or error:
|
|
316
|
+
raise RegistryError(f"{status} must not carry terminal evidence")
|
|
317
|
+
return replace(record, started_at=started)
|
|
318
|
+
if classification not in ("converged", "iteration_limit", "failed"):
|
|
319
|
+
raise RegistryError("COMPLETED requires a numerical classification")
|
|
320
|
+
completed = _timestamp(_text(row, "completed_at"))
|
|
321
|
+
if datetime.fromisoformat(completed) < datetime.fromisoformat(started):
|
|
322
|
+
raise RegistryError("completed_at precedes started_at")
|
|
323
|
+
# A cluster job writes only its job outputs; files only a local run writes
|
|
324
|
+
# (execution.json) may then be absent.
|
|
325
|
+
required = set(outputs)
|
|
326
|
+
if record.submission is not None and "job_outputs" in record.submission:
|
|
327
|
+
required = set(cast(tuple[str, ...], record.submission["job_outputs"]))
|
|
328
|
+
if not required <= set(outputs):
|
|
329
|
+
raise RegistryError("submission job_outputs must name declared outputs")
|
|
330
|
+
if classification != "failed" and (not required <= set(output_digests) or error):
|
|
331
|
+
raise RegistryError("successful classification requires every output and no error")
|
|
332
|
+
return replace(
|
|
333
|
+
record,
|
|
334
|
+
started_at=started,
|
|
335
|
+
completed_at=completed,
|
|
336
|
+
classification=classification,
|
|
337
|
+
outputs_sha256=MappingProxyType(output_digests),
|
|
338
|
+
error=error,
|
|
339
|
+
)
|
|
340
|
+
|
|
341
|
+
|
|
342
|
+
def _relink(old: Path, new: Path) -> None:
|
|
343
|
+
"""Point relative symbolic links of a moved folder at their original targets."""
|
|
344
|
+
for link in new.rglob("*"):
|
|
345
|
+
if not link.is_symlink():
|
|
346
|
+
continue
|
|
347
|
+
written = os.readlink(link)
|
|
348
|
+
if os.path.isabs(written):
|
|
349
|
+
continue
|
|
350
|
+
original = os.path.normpath(old / link.relative_to(new).parent / written)
|
|
351
|
+
link.unlink()
|
|
352
|
+
link.symlink_to(os.path.relpath(original, link.parent))
|
|
353
|
+
|
|
354
|
+
|
|
355
|
+
def _encode(record: RunRecord) -> dict[str, object]:
|
|
356
|
+
point = record.point
|
|
357
|
+
row: dict[str, object] = {
|
|
358
|
+
"point_id": point.point_id,
|
|
359
|
+
"pol": point.pol,
|
|
360
|
+
"setup_id": point.setup_id,
|
|
361
|
+
"reference_id": point.reference_id,
|
|
362
|
+
"post_id": point.post_id,
|
|
363
|
+
"condition": dict(point.condition),
|
|
364
|
+
"walltime": point.walltime,
|
|
365
|
+
"directory": point.directory,
|
|
366
|
+
"actions": list(point.actions),
|
|
367
|
+
"outputs": list(point.outputs),
|
|
368
|
+
"inputs_sha256": dict(point.inputs_sha256),
|
|
369
|
+
"matrix": record.matrix,
|
|
370
|
+
"solver": record.solver,
|
|
371
|
+
"status": record.status,
|
|
372
|
+
"created_at": record.created_at,
|
|
373
|
+
}
|
|
374
|
+
# Optional columns are written only when a row states them, so a record of
|
|
375
|
+
# a matrix without them keeps its earlier bytes.
|
|
376
|
+
for key, default in POINT_EXTRAS.items():
|
|
377
|
+
value = getattr(point, key)
|
|
378
|
+
if key == "variables":
|
|
379
|
+
value = dict(value)
|
|
380
|
+
if value != default:
|
|
381
|
+
row[key] = value
|
|
382
|
+
if record.status != "PLANNED":
|
|
383
|
+
row.update(
|
|
384
|
+
started_at=record.started_at,
|
|
385
|
+
completed_at=record.completed_at,
|
|
386
|
+
classification=record.classification,
|
|
387
|
+
outputs_sha256=dict(record.outputs_sha256),
|
|
388
|
+
error=record.error,
|
|
389
|
+
)
|
|
390
|
+
if record.submission is not None:
|
|
391
|
+
row["submission"] = dict(record.submission)
|
|
392
|
+
return row
|
|
393
|
+
|
|
394
|
+
|
|
395
|
+
def _unique_pairs(pairs: list[tuple[str, object]]) -> dict[str, object]:
|
|
396
|
+
result: dict[str, object] = {}
|
|
397
|
+
for key, value in pairs:
|
|
398
|
+
if key in result:
|
|
399
|
+
raise RegistryError(f"duplicate JSON field {key!r}")
|
|
400
|
+
result[key] = value
|
|
401
|
+
return result
|
|
402
|
+
|
|
403
|
+
|
|
404
|
+
class RunRegistry:
|
|
405
|
+
"""Read proposals and seal executed points, refusing drift and overlapping claims.
|
|
406
|
+
|
|
407
|
+
No solver is loaded. Writers fail immediately if runs.json.lock exists;
|
|
408
|
+
they never steal or recover a lock. An interrupted writer's lock requires
|
|
409
|
+
the operator to establish that writer has stopped before removing it.
|
|
410
|
+
"""
|
|
411
|
+
|
|
412
|
+
def __init__(self, root: str | Path) -> None:
|
|
413
|
+
self.root = Path(root).resolve()
|
|
414
|
+
self.path = self.root / "runs.json"
|
|
415
|
+
|
|
416
|
+
def _history(self) -> list[object]:
|
|
417
|
+
if not self.path.exists():
|
|
418
|
+
return []
|
|
419
|
+
document = _object(json.loads(self.path.read_bytes(), object_pairs_hook=_unique_pairs))
|
|
420
|
+
history = document.get("history", [])
|
|
421
|
+
if not isinstance(history, list):
|
|
422
|
+
raise RegistryError("history must be a list")
|
|
423
|
+
return history
|
|
424
|
+
|
|
425
|
+
def _replace(self, records: tuple[RunRecord, ...], history: list[object] | None = None) -> None:
|
|
426
|
+
temporary: Path | None = None
|
|
427
|
+
try:
|
|
428
|
+
kept = self._history() if history is None else history
|
|
429
|
+
document: dict[str, object] = {
|
|
430
|
+
"schema_version": 1,
|
|
431
|
+
"records": [_encode(r) for r in records],
|
|
432
|
+
}
|
|
433
|
+
if kept:
|
|
434
|
+
document["history"] = kept
|
|
435
|
+
data = (
|
|
436
|
+
json.dumps(document, indent=2, sort_keys=True, allow_nan=False) + chr(10)
|
|
437
|
+
).encode()
|
|
438
|
+
with tempfile.NamedTemporaryFile(
|
|
439
|
+
dir=self.root, prefix=".runs-", suffix=".tmp", delete=False
|
|
440
|
+
) as stream:
|
|
441
|
+
temporary = Path(stream.name)
|
|
442
|
+
stream.write(data)
|
|
443
|
+
stream.flush()
|
|
444
|
+
os.fsync(stream.fileno())
|
|
445
|
+
os.replace(temporary, self.path)
|
|
446
|
+
temporary = None
|
|
447
|
+
finally:
|
|
448
|
+
if temporary is not None:
|
|
449
|
+
temporary.unlink(missing_ok=True)
|
|
450
|
+
|
|
451
|
+
def transition(
|
|
452
|
+
self,
|
|
453
|
+
point_id: str,
|
|
454
|
+
status: str,
|
|
455
|
+
*,
|
|
456
|
+
timestamp: str | None = None,
|
|
457
|
+
classification: Classification | None = None,
|
|
458
|
+
error: str | None = None,
|
|
459
|
+
submission: Mapping[str, object] | None = None,
|
|
460
|
+
) -> RunRecord:
|
|
461
|
+
"""Claim, submit or seal a point; never rewrite a finished one.
|
|
462
|
+
|
|
463
|
+
Parameters
|
|
464
|
+
----------
|
|
465
|
+
point_id : str
|
|
466
|
+
Exact registered point identity.
|
|
467
|
+
status : str
|
|
468
|
+
RUNNING, SUBMITTED or COMPLETED. Only lifecycle transitions succeed.
|
|
469
|
+
timestamp : str, optional
|
|
470
|
+
Timezone-qualified time, defaulting to UTC now.
|
|
471
|
+
classification : Classification, optional
|
|
472
|
+
Required for COMPLETED; never inferred from process exit.
|
|
473
|
+
error : str, optional
|
|
474
|
+
Failure diagnosis, retained with any partial output digests.
|
|
475
|
+
submission : mapping, optional
|
|
476
|
+
Descriptor/config digests, argv, captured output paths/text and submit
|
|
477
|
+
process timestamps, code, timeout and timed_out evidence, and optional
|
|
478
|
+
job_outputs: the declared outputs the cluster job itself writes. Required
|
|
479
|
+
when moving from RUNNING to SUBMITTED; retained on completion.
|
|
480
|
+
|
|
481
|
+
Returns
|
|
482
|
+
-------
|
|
483
|
+
RunRecord
|
|
484
|
+
Atomically persisted record, preserving the proposal and input digests.
|
|
485
|
+
|
|
486
|
+
Raises
|
|
487
|
+
------
|
|
488
|
+
RegistryError
|
|
489
|
+
Held lock, illegal transition, changed inputs, existing output or bad evidence.
|
|
490
|
+
"""
|
|
491
|
+
stamp = _timestamp(timestamp if timestamp is not None else datetime.now(UTC).isoformat())
|
|
492
|
+
lock = self.root / "runs.json.lock"
|
|
493
|
+
try:
|
|
494
|
+
lease = lock.open("x", encoding="utf-8")
|
|
495
|
+
except FileExistsError as exc:
|
|
496
|
+
raise RegistryError(f"{lock}: registry is locked by another writer") from exc
|
|
497
|
+
try:
|
|
498
|
+
with lease:
|
|
499
|
+
records = self.read()
|
|
500
|
+
for index in range(len(records)):
|
|
501
|
+
previous = records[index]
|
|
502
|
+
if previous.point_id == point_id:
|
|
503
|
+
break
|
|
504
|
+
else:
|
|
505
|
+
raise RegistryError(f"point {point_id!r} has no registered record")
|
|
506
|
+
if (previous.status, status) not in {
|
|
507
|
+
("PLANNED", "RUNNING"),
|
|
508
|
+
("RUNNING", "COMPLETED"),
|
|
509
|
+
("RUNNING", "SUBMITTED"),
|
|
510
|
+
("SUBMITTED", "COMPLETED"),
|
|
511
|
+
}:
|
|
512
|
+
raise RegistryError(
|
|
513
|
+
f"point {point_id!r} already recorded {previous.status}; "
|
|
514
|
+
f"refusing transition to {status}"
|
|
515
|
+
)
|
|
516
|
+
if previous.submission is not None and submission is not None:
|
|
517
|
+
raise RegistryError("submission evidence is immutable")
|
|
518
|
+
if status == "RUNNING":
|
|
519
|
+
for name, digest in previous.point.inputs_sha256.items():
|
|
520
|
+
if (
|
|
521
|
+
hashlib.sha256(workspace_path(self.root, name).read_bytes()).hexdigest()
|
|
522
|
+
!= digest
|
|
523
|
+
):
|
|
524
|
+
raise RegistryError(f"input changed after planning: {name}; plan again")
|
|
525
|
+
for name in (previous.point.directory, *previous.point.outputs):
|
|
526
|
+
if workspace_path(self.root, name).exists():
|
|
527
|
+
raise RegistryError(f"{name}: existing output; refusing overwrite")
|
|
528
|
+
updated = replace(
|
|
529
|
+
previous,
|
|
530
|
+
status=status,
|
|
531
|
+
started_at=stamp,
|
|
532
|
+
classification=classification,
|
|
533
|
+
error=error,
|
|
534
|
+
)
|
|
535
|
+
elif status == "SUBMITTED":
|
|
536
|
+
updated = replace(previous, status=status, submission=submission)
|
|
537
|
+
else:
|
|
538
|
+
digests = {}
|
|
539
|
+
for name in previous.point.outputs:
|
|
540
|
+
path = workspace_path(self.root, name)
|
|
541
|
+
if path.is_file():
|
|
542
|
+
digests[name] = hashlib.sha256(path.read_bytes()).hexdigest()
|
|
543
|
+
updated = replace(
|
|
544
|
+
previous,
|
|
545
|
+
status=status,
|
|
546
|
+
completed_at=stamp,
|
|
547
|
+
classification=classification,
|
|
548
|
+
error=error,
|
|
549
|
+
outputs_sha256=MappingProxyType(digests),
|
|
550
|
+
submission=previous.submission if submission is None else submission,
|
|
551
|
+
)
|
|
552
|
+
updated = _decode(_encode(updated), self.root)
|
|
553
|
+
if submission is not None:
|
|
554
|
+
for name, key in (
|
|
555
|
+
("descriptor", "descriptor_sha256"),
|
|
556
|
+
("config_path", "config_sha256"),
|
|
557
|
+
):
|
|
558
|
+
path = workspace_path(self.root, str(submission[name]))
|
|
559
|
+
if hashlib.sha256(path.read_bytes()).hexdigest() != submission[key]:
|
|
560
|
+
raise RegistryError(f"submission {name} digest differs from file")
|
|
561
|
+
self._replace((*records[:index], updated, *records[index + 1 :]))
|
|
562
|
+
return updated
|
|
563
|
+
except (OSError, ValueError, TypeError) as exc:
|
|
564
|
+
raise RegistryError(f"{self.path}: cannot transition point: {exc}") from exc
|
|
565
|
+
finally:
|
|
566
|
+
lock.unlink(missing_ok=True)
|
|
567
|
+
|
|
568
|
+
def history(self) -> tuple[Mapping[str, object], ...]:
|
|
569
|
+
"""Return archived records, oldest first, each with archived_at and archive.
|
|
570
|
+
|
|
571
|
+
Returns
|
|
572
|
+
-------
|
|
573
|
+
tuple of mapping
|
|
574
|
+
Entries ``{"archived_at", "archive", "record"}``; ``record`` is the
|
|
575
|
+
record as it was in runs.json when it was archived.
|
|
576
|
+
"""
|
|
577
|
+
self.read()
|
|
578
|
+
return tuple(MappingProxyType(_object(entry)) for entry in self._history())
|
|
579
|
+
|
|
580
|
+
def archive(self, point_ids: tuple[str, ...], *, stamp: str | None = None) -> Path:
|
|
581
|
+
"""Move recorded points and their folders to a new archive/<stamp>/ folder.
|
|
582
|
+
|
|
583
|
+
Parameters
|
|
584
|
+
----------
|
|
585
|
+
point_ids : tuple of str
|
|
586
|
+
Recorded points to archive; each may then be registered again.
|
|
587
|
+
stamp : str, optional
|
|
588
|
+
Folder name; defaults to the UTC time as YYYYMMDDTHHMMSSZ, with a
|
|
589
|
+
numeric suffix when that folder exists.
|
|
590
|
+
|
|
591
|
+
Returns
|
|
592
|
+
-------
|
|
593
|
+
Path
|
|
594
|
+
The archive folder, holding runs.json as it was and each point folder
|
|
595
|
+
under its workspace-relative directory.
|
|
596
|
+
|
|
597
|
+
Raises
|
|
598
|
+
------
|
|
599
|
+
RegistryError
|
|
600
|
+
A held lock, an unknown point or a move that cannot be made.
|
|
601
|
+
"""
|
|
602
|
+
now = datetime.now(UTC)
|
|
603
|
+
name = stamp or now.strftime("%Y%m%dT%H%M%SZ")
|
|
604
|
+
target = self.root / "archive" / name
|
|
605
|
+
suffix = 1
|
|
606
|
+
while target.exists():
|
|
607
|
+
target = self.root / "archive" / f"{name}-{suffix}"
|
|
608
|
+
suffix += 1
|
|
609
|
+
lock = self.root / "runs.json.lock"
|
|
610
|
+
try:
|
|
611
|
+
lease = lock.open("x", encoding="utf-8")
|
|
612
|
+
except FileExistsError as error:
|
|
613
|
+
raise RegistryError(f"{lock}: registry is locked by another writer") from error
|
|
614
|
+
try:
|
|
615
|
+
with lease:
|
|
616
|
+
records = self.read()
|
|
617
|
+
chosen = {r.point_id: r for r in records if r.point_id in point_ids}
|
|
618
|
+
if missing := sorted(set(point_ids) - set(chosen)):
|
|
619
|
+
raise RegistryError(f"no recorded point {missing[0]!r} to archive")
|
|
620
|
+
target.mkdir(parents=True)
|
|
621
|
+
(target / "runs.json").write_bytes(self.path.read_bytes())
|
|
622
|
+
history = self._history()
|
|
623
|
+
relative = target.relative_to(self.root).as_posix()
|
|
624
|
+
for record in chosen.values():
|
|
625
|
+
folder = workspace_path(self.root, record.point.directory)
|
|
626
|
+
if folder.exists():
|
|
627
|
+
moved = target / record.point.directory
|
|
628
|
+
moved.parent.mkdir(parents=True, exist_ok=True)
|
|
629
|
+
os.replace(folder, moved)
|
|
630
|
+
_relink(folder, moved)
|
|
631
|
+
history.append(
|
|
632
|
+
{
|
|
633
|
+
"archived_at": now.isoformat(),
|
|
634
|
+
"archive": relative,
|
|
635
|
+
"record": _encode(record),
|
|
636
|
+
}
|
|
637
|
+
)
|
|
638
|
+
kept = tuple(r for r in records if r.point_id not in chosen)
|
|
639
|
+
self._replace(kept, history)
|
|
640
|
+
return target
|
|
641
|
+
except (OSError, ValueError, TypeError) as error:
|
|
642
|
+
raise RegistryError(f"{self.path}: cannot archive points: {error}") from error
|
|
643
|
+
finally:
|
|
644
|
+
lock.unlink(missing_ok=True)
|
|
645
|
+
|
|
646
|
+
def read(self) -> tuple[RunRecord, ...]:
|
|
647
|
+
"""Read validated records, or return an empty tuple when runs.json is absent.
|
|
648
|
+
|
|
649
|
+
Returns
|
|
650
|
+
-------
|
|
651
|
+
tuple of RunRecord
|
|
652
|
+
Records in registration order; input bytes are not re-read here.
|
|
653
|
+
|
|
654
|
+
Raises
|
|
655
|
+
------
|
|
656
|
+
RegistryError
|
|
657
|
+
An unreadable, corrupt or unsupported record document, named in the error.
|
|
658
|
+
"""
|
|
659
|
+
try:
|
|
660
|
+
if self.path.is_symlink():
|
|
661
|
+
raise RegistryError("registry must not be a symlink")
|
|
662
|
+
if not self.path.exists():
|
|
663
|
+
return ()
|
|
664
|
+
document = _object(json.loads(self.path.read_bytes(), object_pairs_hook=_unique_pairs))
|
|
665
|
+
if (
|
|
666
|
+
set(document) - {"history"} != {"schema_version", "records"}
|
|
667
|
+
or not isinstance(document.get("history", []), list)
|
|
668
|
+
or type(document["schema_version"]) is not int
|
|
669
|
+
or document["schema_version"] != 1
|
|
670
|
+
or not isinstance(document["records"], list)
|
|
671
|
+
):
|
|
672
|
+
raise RegistryError("expected schema_version = 1 and records list")
|
|
673
|
+
records = tuple(_decode(raw, self.root) for raw in document["records"])
|
|
674
|
+
check_claims(tuple(r.point for r in records))
|
|
675
|
+
return records
|
|
676
|
+
except (OSError, ValueError, TypeError, OverflowError) as error:
|
|
677
|
+
raise RegistryError(f"{self.path}: cannot read run registry: {error}") from error
|
|
678
|
+
|
|
679
|
+
def record(self, plan: RunPlan, *, created_at: str | None = None) -> tuple[RunRecord, ...]:
|
|
680
|
+
"""Append a plan atomically after checking input bytes and all path claims.
|
|
681
|
+
|
|
682
|
+
Parameters
|
|
683
|
+
----------
|
|
684
|
+
plan : RunPlan
|
|
685
|
+
Validated plan for this registry's workspace.
|
|
686
|
+
created_at : str, optional
|
|
687
|
+
ISO 8601 timestamp with timezone. Defaults to UTC now; pass an explicit
|
|
688
|
+
timestamp for deterministic output.
|
|
689
|
+
|
|
690
|
+
Returns
|
|
691
|
+
-------
|
|
692
|
+
tuple of RunRecord
|
|
693
|
+
Newly appended point records with status PLANNED.
|
|
694
|
+
|
|
695
|
+
Raises
|
|
696
|
+
------
|
|
697
|
+
RegistryError
|
|
698
|
+
A held writer lock, changed input, duplicate point, collision or bad record.
|
|
699
|
+
"""
|
|
700
|
+
if plan.root != self.root:
|
|
701
|
+
raise RegistryError("plan and registry must belong to the same workspace")
|
|
702
|
+
stamp = _timestamp(created_at if created_at is not None else datetime.now(UTC).isoformat())
|
|
703
|
+
lock = self.root / "runs.json.lock"
|
|
704
|
+
try:
|
|
705
|
+
lease = lock.open("x", encoding="utf-8")
|
|
706
|
+
except FileExistsError as error:
|
|
707
|
+
raise RegistryError(f"{lock}: registry is locked by another writer") from error
|
|
708
|
+
try:
|
|
709
|
+
with lease:
|
|
710
|
+
lease.write(str(os.getpid()))
|
|
711
|
+
lease.flush()
|
|
712
|
+
previous = self.read()
|
|
713
|
+
check_claims(tuple(r.point for r in previous) + plan.points)
|
|
714
|
+
records = tuple(
|
|
715
|
+
RunRecord(p, plan.matrix, plan.solver, "PLANNED", stamp) for p in plan.points
|
|
716
|
+
)
|
|
717
|
+
# Validate the same shape that a subsequent read accepts before writing.
|
|
718
|
+
records = tuple(_decode(_encode(r), self.root) for r in records)
|
|
719
|
+
for record in records:
|
|
720
|
+
for name, expected in record.point.inputs_sha256.items():
|
|
721
|
+
path = workspace_path(self.root, name)
|
|
722
|
+
try:
|
|
723
|
+
actual = hashlib.sha256(path.read_bytes()).hexdigest()
|
|
724
|
+
except OSError as error:
|
|
725
|
+
raise RegistryError(
|
|
726
|
+
f"input changed or missing: {name}: {error}"
|
|
727
|
+
) from error
|
|
728
|
+
if actual != expected:
|
|
729
|
+
raise RegistryError(f"input changed after planning: {name}; plan again")
|
|
730
|
+
self._replace((*previous, *records))
|
|
731
|
+
return records
|
|
732
|
+
except (OSError, PlanError, ValueError, TypeError) as error:
|
|
733
|
+
raise RegistryError(f"{self.path}: cannot register plan: {error}") from error
|
|
734
|
+
finally:
|
|
735
|
+
lock.unlink(missing_ok=True)
|