jcmsuite 7.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.

Potentially problematic release.


This version of jcmsuite might be problematic. Click here for more details.

Files changed (119) hide show
  1. jcmsuite/__init__.py +22 -0
  2. jcmsuite/_build_info.py +4 -0
  3. jcmsuite/context/__init__.py +44 -0
  4. jcmsuite/context/interface_metadata.py +158 -0
  5. jcmsuite/context/models.py +213 -0
  6. jcmsuite/context/scope.py +210 -0
  7. jcmsuite/context/solver_context.py +569 -0
  8. jcmsuite/context/subprocess_tools.py +172 -0
  9. jcmsuite/contract.py +47 -0
  10. jcmsuite/daemon/__init__.py +19 -0
  11. jcmsuite/daemon/handler.py +925 -0
  12. jcmsuite/daemon/internal/__init__.py +4 -0
  13. jcmsuite/daemon/internal/bundle_protocol.py +64 -0
  14. jcmsuite/daemon/internal/handler_helpers.py +368 -0
  15. jcmsuite/daemon/internal/handler_resource_jobs.py +227 -0
  16. jcmsuite/daemon/internal/handler_wait.py +564 -0
  17. jcmsuite/daemon/models.py +349 -0
  18. jcmsuite/daemon/namespaces.py +250 -0
  19. jcmsuite/daemon/protocol.py +801 -0
  20. jcmsuite/daemon/resources.py +407 -0
  21. jcmsuite/daemon/scope.py +53 -0
  22. jcmsuite/daemon/transport.py +223 -0
  23. jcmsuite/editing/__init__.py +10 -0
  24. jcmsuite/editing/editor.py +274 -0
  25. jcmsuite/exceptions/__init__.py +32 -0
  26. jcmsuite/exceptions/errors.py +173 -0
  27. jcmsuite/geo/__init__.py +10 -0
  28. jcmsuite/geo/mesh.py +302 -0
  29. jcmsuite/info/__init__.py +10 -0
  30. jcmsuite/info/runtime_info.py +45 -0
  31. jcmsuite/internal/__init__.py +2 -0
  32. jcmsuite/internal/diagnostics.py +74 -0
  33. jcmsuite/internal/progress.py +80 -0
  34. jcmsuite/loaders/__init__.py +18 -0
  35. jcmsuite/loaders/blob_header.py +315 -0
  36. jcmsuite/loaders/cartesian_field_reader.py +249 -0
  37. jcmsuite/loaders/cartesian_fields.py +324 -0
  38. jcmsuite/loaders/nested_mapping.py +69 -0
  39. jcmsuite/loaders/powerflux.py +136 -0
  40. jcmsuite/loaders/table.py +637 -0
  41. jcmsuite/logging/__init__.py +22 -0
  42. jcmsuite/logging/runtime.py +210 -0
  43. jcmsuite/results/__init__.py +126 -0
  44. jcmsuite/results/artifacts.py +806 -0
  45. jcmsuite/results/discovery.py +82 -0
  46. jcmsuite/results/field_exports.py +1062 -0
  47. jcmsuite/results/field_payloads.py +453 -0
  48. jcmsuite/results/internal/__init__.py +4 -0
  49. jcmsuite/results/internal/export/__init__.py +4 -0
  50. jcmsuite/results/internal/export/common.py +56 -0
  51. jcmsuite/results/internal/export/pandas/__init__.py +4 -0
  52. jcmsuite/results/internal/export/pandas/common.py +165 -0
  53. jcmsuite/results/internal/export/pandas/payload.py +480 -0
  54. jcmsuite/results/internal/export/pandas/rows.py +484 -0
  55. jcmsuite/results/internal/export/preview.py +178 -0
  56. jcmsuite/results/internal/export/xarray/__init__.py +4 -0
  57. jcmsuite/results/internal/export/xarray/export.py +688 -0
  58. jcmsuite/results/internal/export/xarray/grouped.py +608 -0
  59. jcmsuite/results/internal/export/xarray/headers.py +290 -0
  60. jcmsuite/results/internal/export/xarray/runtime.py +99 -0
  61. jcmsuite/results/internal/export/xarray/shared.py +246 -0
  62. jcmsuite/results/internal/export/xarray/tabular.py +304 -0
  63. jcmsuite/results/internal/export/xarray/types.py +28 -0
  64. jcmsuite/results/internal/models/__init__.py +4 -0
  65. jcmsuite/results/internal/models/batch.py +1081 -0
  66. jcmsuite/results/internal/models/batch_postprocess.py +1728 -0
  67. jcmsuite/results/internal/models/bundle.py +343 -0
  68. jcmsuite/results/internal/models/core.py +556 -0
  69. jcmsuite/results/internal/models/submission.py +1157 -0
  70. jcmsuite/results/internal/resultbag/__init__.py +4 -0
  71. jcmsuite/results/internal/resultbag/access.py +489 -0
  72. jcmsuite/results/internal/resultbag/iteration.py +199 -0
  73. jcmsuite/results/internal/resultbag/query.py +226 -0
  74. jcmsuite/results/internal/resultbag/raw.py +407 -0
  75. jcmsuite/results/internal/resultbag/source_files.py +142 -0
  76. jcmsuite/results/internal/resultbag/store.py +881 -0
  77. jcmsuite/results/internal/resultbag/utils.py +258 -0
  78. jcmsuite/results/models.py +76 -0
  79. jcmsuite/results/opening.py +55 -0
  80. jcmsuite/results/pandas_export.py +325 -0
  81. jcmsuite/results/payloads.py +478 -0
  82. jcmsuite/results/postprocess.py +97 -0
  83. jcmsuite/results/postprocess_payloads.py +757 -0
  84. jcmsuite/results/postprocess_record.py +418 -0
  85. jcmsuite/results/resultbag.py +279 -0
  86. jcmsuite/results/resultbag_management.py +433 -0
  87. jcmsuite/results/structured_derivatives.py +387 -0
  88. jcmsuite/solve/__init__.py +10 -0
  89. jcmsuite/solve/daemon_bundle_staging.py +100 -0
  90. jcmsuite/solve/daemon_bundle_wait.py +89 -0
  91. jcmsuite/solve/orchestration.py +1576 -0
  92. jcmsuite/solve/orchestration_execution.py +180 -0
  93. jcmsuite/solve/orchestration_routing.py +128 -0
  94. jcmsuite/solve/orchestration_support.py +323 -0
  95. jcmsuite/solve/path_resolution.py +98 -0
  96. jcmsuite/solve/progress.py +20 -0
  97. jcmsuite/solve/solver.py +709 -0
  98. jcmsuite/solve/staging.py +264 -0
  99. jcmsuite/solve/types.py +25 -0
  100. jcmsuite/solve/working_dirs.py +227 -0
  101. jcmsuite/templates/__init__.py +11 -0
  102. jcmsuite/templates/converter.py +71 -0
  103. jcmsuite/templates/formatting.py +335 -0
  104. jcmsuite/templates/formatting_cli.py +47 -0
  105. jcmsuite/templates/rendering.py +666 -0
  106. jcmsuite/torch/__init__.py +25 -0
  107. jcmsuite/torch/autograd.py +488 -0
  108. jcmsuite/torch/coordinate_policy.py +82 -0
  109. jcmsuite/torch/core.py +312 -0
  110. jcmsuite/torch/results/__init__.py +51 -0
  111. jcmsuite/torch/types.py +84 -0
  112. jcmsuite/torch/validation.py +208 -0
  113. jcmsuite/torch/wrappers.py +4332 -0
  114. jcmsuite/view/__init__.py +10 -0
  115. jcmsuite/view/viewer.py +122 -0
  116. jcmsuite-7.4.2.dist-info/METADATA +180 -0
  117. jcmsuite-7.4.2.dist-info/RECORD +119 -0
  118. jcmsuite-7.4.2.dist-info/WHEEL +4 -0
  119. jcmsuite-7.4.2.dist-info/entry_points.txt +3 -0
@@ -0,0 +1,315 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Blob-header parser used by JCM result loaders."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import array
9
+ import re
10
+ from collections.abc import Mapping
11
+ from typing import BinaryIO, cast
12
+
13
+ import numpy as np
14
+
15
+ from .nested_mapping import PathComponent, nested_get, nested_set
16
+
17
+
18
+ class BlobHeaderReader:
19
+ """Read a JCM blob-header section from an open binary stream.
20
+
21
+ Parameters
22
+ ----------
23
+ stream : BinaryIO
24
+ Open binary file handle positioned at the start of a blob header.
25
+ expected_blob_type : str
26
+ Expected `__BLOBTYPE__` value for validation.
27
+ """
28
+
29
+ def __init__(self, stream: BinaryIO, expected_blob_type: str) -> None:
30
+
31
+ self._stream: BinaryIO = stream
32
+ self._expected_blob_type: str = expected_blob_type
33
+ self._header: dict[PathComponent, object] = {}
34
+ self._last_split_keys: list[PathComponent] = []
35
+ self._last_spatial_index: int = -1
36
+ self._last_component_kind: str | None = None
37
+
38
+ header_start: str = self._read_and_strip_line()
39
+ if header_start.replace(" ", "") != "/*<BLOBHead>":
40
+ raise ValueError("Missing header in opened file.")
41
+
42
+ def read_header(self) -> dict[PathComponent, object]:
43
+ """Parse and return the blob header.
44
+
45
+ Returns
46
+ -------
47
+ dict[str | int, object]
48
+ Parsed blob header structure.
49
+ """
50
+
51
+ while True:
52
+ header_line: str = self._read_and_strip_line()
53
+ if header_line == "*/":
54
+ break
55
+ if header_line.startswith("0"):
56
+ raise ValueError("Missing footer in opened file.")
57
+ self._process_blob_line(header_line)
58
+
59
+ mode: object = self._header.get("__MODE__")
60
+ if mode == "BINARY0":
61
+ zero: array.array[int] = array.array("B")
62
+ zero.fromfile(self._stream, 1)
63
+ if zero[0] != 48: # ASCII '0'
64
+ raise RuntimeError(
65
+ "Header parsed, but binary payload marker is invalid."
66
+ )
67
+ self._header["__MODE__"] = "BINARY"
68
+
69
+ self._header = _collapse_dense_scalar_index_mappings(self._header)
70
+ return self._header
71
+
72
+ def _process_blob_line(self, header_line: str) -> None:
73
+ # Regex structure:
74
+ # 1) optional explicit type prefix `<I>`, `<F>`, `<S>`
75
+ # 2) key content up to `=`
76
+ # 3) value content after `=`
77
+ """Parse one BLOB header line and store the normalized key/value entry.
78
+
79
+ Parameters
80
+ ----------
81
+ header_line : str
82
+ Raw ``KEY=VALUE`` header line from the BLOB header section.
83
+
84
+ Returns
85
+ -------
86
+ None
87
+ Updates ``self._header`` in-place.
88
+
89
+ Notes
90
+ -----
91
+ Internal API: this helper is an implementation detail and may change
92
+ without notice.
93
+ """
94
+
95
+ parsed_header_entry: re.Match[str] | None = re.search(
96
+ r"(<[IFS]>)?(.*)=(.*)",
97
+ header_line,
98
+ )
99
+ if parsed_header_entry is None:
100
+ raise ValueError(f"Invalid header entry: {header_line}")
101
+
102
+ entry_type: str = parsed_header_entry.group(1) or "<S>"
103
+ key: str = parsed_header_entry.group(2)
104
+ raw_value: str = parsed_header_entry.group(3)
105
+
106
+ # Key suffixes like `_12` encode list-like indices. We map them to `:12`
107
+ # so downstream path splitting can uniformly parse both names and indices.
108
+ key = re.sub(r"(_)(\d{1,})", lambda match: f":{match.group(2)}", key)
109
+
110
+ if key == "__BLOBTYPE__" and raw_value != self._expected_blob_type:
111
+ raise TypeError(
112
+ f"Wrong file format. `{self._expected_blob_type}` expected."
113
+ )
114
+
115
+ # Derivative keys (`d(a)_b`) are rewritten with a placeholder separator so
116
+ # nested path splitting can preserve both derivative variable and quantity.
117
+ def derivative_placeholder(match: re.Match[str]) -> str:
118
+ return f"d_{match.group(2)}<DerivativeSep>{match.group(1)}"
119
+
120
+ key = re.sub(r"d\((.*)\)_(.*)", derivative_placeholder, key)
121
+ key = re.sub(r"d\((.*)\)_(.*)", derivative_placeholder, key)
122
+
123
+ split_keys: list[PathComponent] = cast(list[PathComponent], key.split(":"))
124
+ split_index: int
125
+ for split_index in range(len(split_keys)):
126
+ try:
127
+ split_keys[split_index] = int(cast(str, split_keys[split_index])) - 1
128
+ except ValueError:
129
+ pass
130
+
131
+ parsed_value: object
132
+ if entry_type == "<I>":
133
+ float_value: float = float(raw_value)
134
+ int_value: int = int(raw_value)
135
+ if int_value - float_value != 0:
136
+ raise ValueError(f"Value {raw_value} is not an integer.")
137
+ parsed_value = int_value
138
+ elif entry_type == "<F>":
139
+ parsed_value = float(raw_value)
140
+ else:
141
+ parsed_value = raw_value
142
+
143
+ final_key: str = ""
144
+ final_index: int = 0
145
+ reverse_index: int
146
+ for reverse_index in range(len(split_keys) - 1, -1, -1):
147
+ if not isinstance(split_keys[reverse_index], int):
148
+ final_key = cast(str, split_keys[reverse_index])
149
+ final_index = reverse_index
150
+ break
151
+
152
+ spatial_index: int = -1
153
+ if final_key.endswith("X"):
154
+ spatial_index = 0
155
+ elif final_key.endswith("Y"):
156
+ spatial_index = 1
157
+ elif final_key.endswith("Z"):
158
+ spatial_index = 2
159
+ if spatial_index != -1:
160
+ final_key = final_key[:-1]
161
+
162
+ is_complex_component: bool = False
163
+ component_kind: str | None = None
164
+ if entry_type == "<F>":
165
+ if "Real" in final_key:
166
+ final_key = final_key.replace("Real", "")
167
+ is_complex_component = True
168
+ component_kind = "real"
169
+ elif "Imag" in final_key:
170
+ parsed_value = cast(float, parsed_value) * 1j
171
+ final_key = final_key.replace("Imag", "")
172
+ is_complex_component = True
173
+ component_kind = "imag"
174
+ split_keys[final_index] = final_key
175
+
176
+ if (
177
+ self._last_spatial_index != -1
178
+ and split_keys == self._last_split_keys
179
+ and self._last_component_kind == component_kind
180
+ ):
181
+ if spatial_index < self._last_spatial_index:
182
+ raise ValueError(
183
+ f"Suspect wrong ordering of spatial data when processing {header_line}"
184
+ )
185
+ self._last_spatial_index = spatial_index
186
+ self._last_split_keys = split_keys
187
+ self._last_component_kind = component_kind
188
+
189
+ path: list[PathComponent] = []
190
+ path_component: PathComponent
191
+ for path_component in split_keys:
192
+ if isinstance(path_component, str):
193
+ path.extend(path_component.split("<DerivativeSep>"))
194
+ else:
195
+ path.append(path_component)
196
+
197
+ previous_value: object | None = None
198
+ try:
199
+ previous_value = nested_get(self._header, path)
200
+ except KeyError:
201
+ previous_value = None
202
+
203
+ if previous_value is None:
204
+ nested_set(self._header, path, parsed_value)
205
+ return
206
+
207
+ if spatial_index == -1:
208
+ if isinstance(previous_value, str) and isinstance(parsed_value, str):
209
+ accumulated_value: object = previous_value + parsed_value
210
+ else:
211
+ accumulated_value = cast(
212
+ int | float | complex,
213
+ previous_value,
214
+ ) + cast(int | float | complex, parsed_value)
215
+ nested_set(
216
+ self._header,
217
+ path,
218
+ accumulated_value,
219
+ )
220
+ return
221
+
222
+ dtype: str
223
+ if entry_type == "<I>":
224
+ dtype = "int32"
225
+ elif is_complex_component:
226
+ dtype = "complex128"
227
+ else:
228
+ dtype = "float64"
229
+
230
+ if (
231
+ isinstance(previous_value, np.ndarray)
232
+ and previous_value.dtype == "complex128"
233
+ ):
234
+ dtype = "complex128"
235
+
236
+ previous_array: np.ndarray = np.asarray(previous_value, dtype=dtype).reshape(-1)
237
+ previous_length: int = int(previous_array.shape[0])
238
+ new_length: int = max(spatial_index + 1, previous_length)
239
+ merged_value: np.ndarray = np.zeros((new_length,), dtype=dtype)
240
+ merged_value[0:previous_length] = previous_array
241
+ merged_value[spatial_index] += cast(int | float | complex, parsed_value)
242
+ nested_set(self._header, path, merged_value)
243
+
244
+ def _read_and_strip_line(self) -> str:
245
+ """Read and strip line.
246
+
247
+ Parameters
248
+ ----------
249
+ None
250
+ This helper uses internal state only.
251
+
252
+ Returns
253
+ -------
254
+ str
255
+ Normalized string value.
256
+
257
+ Notes
258
+ -----
259
+ Internal API: this helper is an implementation detail and may change
260
+ without notice.
261
+ """
262
+
263
+ line: str = self._stream.readline().decode()
264
+ return line.replace("\r\n", "").replace("\n", "")
265
+
266
+
267
+ def _collapse_dense_scalar_index_mappings(
268
+ value: object,
269
+ ) -> dict[PathComponent, object]:
270
+ """Recursively collapse dense scalar int-key mappings into 1D arrays."""
271
+
272
+ collapsed_value: object = _collapse_dense_scalar_index_mappings_object(value)
273
+ if not isinstance(collapsed_value, dict):
274
+ raise TypeError("Collapsed blob header root must remain a mapping.")
275
+ return cast(dict[PathComponent, object], collapsed_value)
276
+
277
+
278
+ def _collapse_dense_scalar_index_mappings_object(value: object) -> object:
279
+ """Recursively normalize dense scalar int-key mappings in blob headers."""
280
+
281
+ if not isinstance(value, Mapping):
282
+ return value
283
+
284
+ normalized_mapping: dict[PathComponent, object] = {
285
+ key: _collapse_dense_scalar_index_mappings_object(child_value)
286
+ for key, child_value in value.items()
287
+ }
288
+ if not normalized_mapping:
289
+ return normalized_mapping
290
+ if not all(isinstance(key, int) for key in normalized_mapping):
291
+ return normalized_mapping
292
+
293
+ integer_keys: list[int] = sorted(cast(list[int], list(normalized_mapping.keys())))
294
+ expected_keys: list[int] = list(range(len(integer_keys)))
295
+ if integer_keys != expected_keys:
296
+ return normalized_mapping
297
+
298
+ ordered_values: list[object] = [normalized_mapping[key] for key in integer_keys]
299
+ if not all(_is_scalar_header_value(child_value) for child_value in ordered_values):
300
+ return normalized_mapping
301
+
302
+ value_array: np.ndarray = np.asarray(ordered_values)
303
+ if np.issubdtype(value_array.dtype, np.str_):
304
+ return normalized_mapping
305
+ return value_array
306
+
307
+
308
+ def _is_scalar_header_value(value: object) -> bool:
309
+ """Return whether one header value is scalar-like for dense collapse."""
310
+
311
+ if isinstance(value, (bool, int, float, complex, np.generic)):
312
+ return True
313
+ if isinstance(value, np.ndarray):
314
+ return bool(value.ndim == 0)
315
+ return False
@@ -0,0 +1,249 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Internal helpers for reading cartesian fieldbag payload blocks."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from collections.abc import Mapping
9
+ from dataclasses import dataclass
10
+ from typing import BinaryIO, Literal
11
+
12
+ import numpy as np
13
+ import numpy.typing as npt
14
+
15
+ _FieldMode = Literal["BINARY", "TEXT"]
16
+
17
+
18
+ @dataclass(slots=True, frozen=True)
19
+ class _DerivativeSpec:
20
+ """Derivative block metadata from a fieldbag header."""
21
+
22
+ order: int
23
+ parameter_names: tuple[str, ...]
24
+
25
+
26
+ @dataclass(slots=True)
27
+ class _FieldPayloadReader:
28
+ """Read numeric fieldbag payload blocks in binary or text mode."""
29
+
30
+ stream: BinaryIO
31
+ mode: _FieldMode
32
+ text_tokens: tuple[str, ...] = ()
33
+ text_token_index: int = 0
34
+
35
+ @classmethod
36
+ def from_stream(
37
+ cls,
38
+ *,
39
+ stream: BinaryIO,
40
+ mode: _FieldMode,
41
+ ) -> "_FieldPayloadReader":
42
+ """Create a payload reader and preload text tokens when needed."""
43
+
44
+ if mode == "BINARY":
45
+ return cls(stream=stream, mode=mode)
46
+ text_payload: str = stream.read().decode("utf-8")
47
+ filtered_lines: list[str] = []
48
+ line: str
49
+ for line in text_payload.splitlines():
50
+ stripped_line: str = line.strip()
51
+ if not stripped_line or stripped_line.startswith("#"):
52
+ continue
53
+ filtered_lines.append(stripped_line)
54
+ return cls(
55
+ stream=stream,
56
+ mode=mode,
57
+ text_tokens=tuple(" ".join(filtered_lines).split()),
58
+ )
59
+
60
+ def read_numeric_array(
61
+ self,
62
+ *,
63
+ count: int,
64
+ dtype: npt.DTypeLike,
65
+ ) -> np.ndarray:
66
+ """Read one numeric array."""
67
+
68
+ if self.mode == "TEXT":
69
+ token_chunk: tuple[str, ...] = self._consume_text_tokens(count)
70
+ return np.asarray(token_chunk, dtype=dtype)
71
+ return np.asarray(np.fromfile(self.stream, dtype=dtype, count=count))
72
+
73
+ def read_complex_array(
74
+ self,
75
+ *,
76
+ component_count: int,
77
+ point_count: int,
78
+ ) -> np.ndarray:
79
+ """Read one complex-valued field block."""
80
+
81
+ if self.mode == "TEXT":
82
+ raw_values: np.ndarray = self.read_numeric_array(
83
+ count=component_count * 2 * point_count,
84
+ dtype=np.float64,
85
+ )
86
+ if raw_values.size != component_count * 2 * point_count:
87
+ raise RuntimeError("Corrupted file.")
88
+ complex_values: np.ndarray = raw_values[0::2].astype(
89
+ np.float64, copy=False
90
+ ) + 1j * raw_values[1::2].astype(np.float64, copy=False)
91
+ return complex_values.astype(np.complex128, copy=False)
92
+ return np.asarray(
93
+ np.fromfile(
94
+ self.stream,
95
+ dtype=np.complex128,
96
+ count=component_count * point_count,
97
+ )
98
+ )
99
+
100
+ def _consume_text_tokens(self, count: int) -> tuple[str, ...]:
101
+ """Return the next `count` text tokens."""
102
+
103
+ end_index: int = self.text_token_index + count
104
+ if end_index > len(self.text_tokens):
105
+ raise RuntimeError("Corrupted file.")
106
+ token_chunk: tuple[str, ...] = self.text_tokens[
107
+ self.text_token_index : end_index
108
+ ]
109
+ self.text_token_index = end_index
110
+ return token_chunk
111
+
112
+
113
+ def read_parameter_derivatives(
114
+ header: Mapping[str | int, object],
115
+ ) -> _DerivativeSpec:
116
+ """Read derivative order and parameter names from a fieldbag header."""
117
+
118
+ parameter_derivatives_object: object | None = header.get("ParameterDerivatives")
119
+ if not isinstance(parameter_derivatives_object, Mapping):
120
+ return _DerivativeSpec(order=0, parameter_names=())
121
+
122
+ derivative_order: int = _coerce_int(
123
+ parameter_derivatives_object.get("Order"),
124
+ key_name="ParameterDerivatives.Order",
125
+ )
126
+ parameter_names: list[str] = []
127
+ parameter_name_index: int = 1
128
+ while True:
129
+ parameter_key: str = f"ParameterName{parameter_name_index}"
130
+ if parameter_key not in parameter_derivatives_object:
131
+ break
132
+ parameter_value: object = parameter_derivatives_object[parameter_key]
133
+ if not isinstance(parameter_value, str):
134
+ raise RuntimeError("Corrupted file.")
135
+ parameter_names.append(parameter_value)
136
+ parameter_name_index += 1
137
+ if len(parameter_names) != len(set(parameter_names)):
138
+ raise RuntimeError(
139
+ "Corrupted file: ParameterDerivatives contains duplicate parameter names."
140
+ )
141
+ return _DerivativeSpec(
142
+ order=derivative_order, parameter_names=tuple(parameter_names)
143
+ )
144
+
145
+
146
+ def field_block_count(
147
+ *,
148
+ base_field_count: int,
149
+ derivative_spec: _DerivativeSpec,
150
+ ) -> int:
151
+ """Return base plus derivative field block count."""
152
+
153
+ field_count: int = base_field_count
154
+ parameter_count: int = len(derivative_spec.parameter_names)
155
+ if derivative_spec.order > 0:
156
+ field_count += parameter_count * base_field_count
157
+ if derivative_spec.order > 1:
158
+ field_count += ((parameter_count + 1) * parameter_count // 2) * base_field_count
159
+ return field_count
160
+
161
+
162
+ def attach_derivative_branches(
163
+ *,
164
+ fieldbag: dict[str, object],
165
+ field_list: list[np.ndarray],
166
+ base_field_count: int,
167
+ derivative_spec: _DerivativeSpec,
168
+ spatial_shape: tuple[int, ...],
169
+ ) -> list[np.ndarray]:
170
+ """Attach derivative branch payloads and return only base field blocks."""
171
+
172
+ # The block order follows the legacy MATLAB loader: base fields first,
173
+ # then all first derivatives, then all second derivative combinations.
174
+ derivative_field_index: int = base_field_count
175
+ parameter_name: str
176
+ for parameter_name in derivative_spec.parameter_names:
177
+ fieldbag[f"d_field_{parameter_name}"] = _build_derivative_branch_payload(
178
+ fieldbag,
179
+ field_list[
180
+ derivative_field_index : derivative_field_index + base_field_count
181
+ ],
182
+ spatial_shape=spatial_shape,
183
+ title=f"d_field_{parameter_name}",
184
+ )
185
+ derivative_field_index += base_field_count
186
+ if derivative_spec.order > 1:
187
+ parameter_name_index_2: int
188
+ parameter_name_index_1: int
189
+ for parameter_name_index_2 in range(len(derivative_spec.parameter_names)):
190
+ for parameter_name_index_1 in range(parameter_name_index_2 + 1):
191
+ parameter_name_1: str = derivative_spec.parameter_names[
192
+ parameter_name_index_1
193
+ ]
194
+ parameter_name_2: str = derivative_spec.parameter_names[
195
+ parameter_name_index_2
196
+ ]
197
+ branch_name: str = f"dd_field_{parameter_name_1}_{parameter_name_2}"
198
+ if branch_name in fieldbag:
199
+ raise RuntimeError(
200
+ "Corrupted file: ambiguous second-order field branch "
201
+ f"{branch_name!r}."
202
+ )
203
+ fieldbag[branch_name] = _build_derivative_branch_payload(
204
+ fieldbag,
205
+ field_list[
206
+ derivative_field_index : derivative_field_index
207
+ + base_field_count
208
+ ],
209
+ spatial_shape=spatial_shape,
210
+ title=f"dd_field_{parameter_name_1}_{parameter_name_2}",
211
+ )
212
+ derivative_field_index += base_field_count
213
+ return field_list[:base_field_count]
214
+
215
+
216
+ def _build_derivative_branch_payload(
217
+ fieldbag: Mapping[str, object],
218
+ branch_fields: list[np.ndarray],
219
+ *,
220
+ spatial_shape: tuple[int, ...],
221
+ title: str,
222
+ ) -> dict[str, object]:
223
+ """Build one derivative branch payload with shared grid coordinates."""
224
+
225
+ branch_payload: dict[str, object] = {}
226
+ coordinate_key: str
227
+ for coordinate_key in ("X", "Y", "Z", "Theta", "Phi", "R"):
228
+ if coordinate_key in fieldbag:
229
+ branch_payload[coordinate_key] = fieldbag[coordinate_key]
230
+ reshaped_branch_fields: list[np.ndarray] = []
231
+ branch_field: np.ndarray
232
+ for branch_field in branch_fields:
233
+ branch_shape: tuple[int, ...]
234
+ if branch_field.ndim == 2:
235
+ branch_shape = (*spatial_shape, int(branch_field.shape[1]))
236
+ else:
237
+ branch_shape = spatial_shape
238
+ reshaped_branch_fields.append(branch_field.reshape(branch_shape, order="F"))
239
+ branch_payload["field"] = reshaped_branch_fields
240
+ branch_payload["title"] = title
241
+ return branch_payload
242
+
243
+
244
+ def _coerce_int(value: object, *, key_name: str) -> int:
245
+ """Coerce integer to expected type."""
246
+
247
+ if isinstance(value, bool) or not isinstance(value, (int, np.integer)):
248
+ raise RuntimeError(f"Corrupted file: `{key_name}` missing or invalid.")
249
+ return int(value)