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,453 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Internal payload normalization helpers for field-export access."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from collections.abc import Mapping
9
+ from dataclasses import dataclass, replace
10
+ from pathlib import Path
11
+ from typing import Literal, cast
12
+
13
+ import numpy as np
14
+
15
+ from ..exceptions import InvalidConfigurationError
16
+ from ..loaders import load_cartesian_fields
17
+
18
+
19
+ @dataclass(slots=True, frozen=True)
20
+ class _CoordinateTopology:
21
+ """Store the coordinate system, axes, values, and grid shape."""
22
+
23
+ system: Literal["cartesian", "polar"]
24
+ names: tuple[str, ...]
25
+ values: tuple[np.ndarray, ...]
26
+ grid_shape: tuple[int, ...]
27
+
28
+
29
+ @dataclass(slots=True, frozen=True)
30
+ class _NormalizedFieldData:
31
+ """Store one normalized field tensor and its coordinate topology."""
32
+
33
+ coordinates: _CoordinateTopology
34
+ field: np.ndarray
35
+ component_labels: tuple[str, ...]
36
+ title: str | None
37
+
38
+
39
+ def is_field_export_payload(payload: object) -> bool:
40
+ """Return whether a mapping contains field data and grid coordinates.
41
+
42
+ Parameters
43
+ ----------
44
+ payload : object
45
+ Value to check.
46
+
47
+ Returns
48
+ -------
49
+ bool
50
+ `True` if the value contains field values and Cartesian or polar grid
51
+ coordinates.
52
+ """
53
+
54
+ if not isinstance(payload, Mapping):
55
+ return False
56
+ lower_keys: set[str] = {str(key).lower() for key in payload}
57
+ has_field: bool = "field" in lower_keys
58
+ has_cartesian_grid: bool = any(
59
+ name.lower() in lower_keys for name in ("X", "Y", "Z")
60
+ )
61
+ has_polar_grid: bool = any(
62
+ name.lower() in lower_keys for name in ("R", "Theta", "Phi")
63
+ )
64
+ return has_field and has_cartesian_grid != has_polar_grid
65
+
66
+
67
+ def _build_field_data(
68
+ payload: Mapping[object, object],
69
+ *,
70
+ field_index: int,
71
+ title: str | None,
72
+ include_derivatives: bool,
73
+ ) -> _NormalizedFieldData:
74
+ """Normalize one field payload for internal xarray construction."""
75
+
76
+ field_container: object = payload["field"]
77
+ first_field: object = (
78
+ field_container[0]
79
+ if isinstance(field_container, (list, tuple)) and field_container
80
+ else field_container
81
+ )
82
+ coordinates: _CoordinateTopology = resolve_coordinates(
83
+ payload,
84
+ field_shape=np.asarray(first_field).shape,
85
+ )
86
+ field_tensor: np.ndarray = normalize_field_tensor(
87
+ payload,
88
+ field_index=field_index,
89
+ )
90
+ if all(value.ndim == 1 for value in coordinates.values):
91
+ field_grid_shape: tuple[int, ...] = field_tensor.shape[: len(coordinates.names)]
92
+ if int(np.prod(field_grid_shape)) == int(np.prod(coordinates.grid_shape)):
93
+ coordinates = replace(coordinates, grid_shape=field_grid_shape)
94
+ del include_derivatives
95
+ labels: tuple[str, ...] = component_labels_from_tensor(
96
+ field_tensor,
97
+ grid_rank=len(coordinates.grid_shape),
98
+ )
99
+ resolved_title: str | None = title
100
+ if resolved_title is None:
101
+ title_object: object | None = payload.get("title")
102
+ if isinstance(title_object, str):
103
+ resolved_title = title_object
104
+ return _NormalizedFieldData(
105
+ coordinates=coordinates,
106
+ field=np.asarray(field_tensor),
107
+ component_labels=labels,
108
+ title=resolved_title,
109
+ )
110
+
111
+
112
+ def resolve_field_payload(
113
+ source: Mapping[object, object] | str | Path,
114
+ ) -> Mapping[object, object]:
115
+ """Resolve field payload."""
116
+
117
+ if isinstance(source, Mapping):
118
+ payload_mapping: Mapping[object, object] = source
119
+ else:
120
+ payload_mapping = cast(
121
+ Mapping[object, object],
122
+ load_cartesian_fields(source, format="squeeze"),
123
+ )
124
+ if not is_field_export_payload(payload_mapping):
125
+ raise InvalidConfigurationError(
126
+ "Field payload must provide 'field' with Cartesian or polar grid keys."
127
+ )
128
+ return payload_mapping
129
+
130
+
131
+ def resolve_derivative_payload(
132
+ payload: Mapping[object, object],
133
+ *,
134
+ derivative: str,
135
+ ) -> Mapping[object, object]:
136
+ """Resolve one derivative branch from a field payload."""
137
+
138
+ requested_derivative: str = _normalize_derivative_name(derivative)
139
+ derivative_payloads: dict[str, Mapping[object, object]] = (
140
+ _collect_derivative_payloads(payload)
141
+ )
142
+ if requested_derivative in derivative_payloads:
143
+ return derivative_payloads[requested_derivative]
144
+ raise InvalidConfigurationError(
145
+ "Unknown derivative branch "
146
+ f"{derivative!r}. Available branches: {tuple(sorted(derivative_payloads))}."
147
+ )
148
+
149
+
150
+ def resolve_coordinates(
151
+ payload: Mapping[object, object],
152
+ *,
153
+ field_shape: tuple[int, ...] | None = None,
154
+ ) -> _CoordinateTopology:
155
+ """Resolve the ordered active coordinate axes of a field payload.
156
+
157
+ Parameters
158
+ ----------
159
+ payload : Mapping[object, object]
160
+ Field payload that contains Cartesian or polar coordinate values.
161
+ field_shape : tuple[int, ...] | None, optional
162
+ Shape of one field value. Use the shape to distinguish singleton
163
+ squeezed coordinates from active one-dimensional coordinates.
164
+
165
+ Returns
166
+ -------
167
+ _CoordinateTopology
168
+ Coordinate system, ordered coordinate names, coordinate values, and
169
+ grid shape.
170
+ """
171
+
172
+ coordinate_keys: dict[str, str] = {}
173
+ payload_key: object
174
+ for payload_key in payload:
175
+ if not isinstance(payload_key, str):
176
+ continue
177
+ canonical_key: str = next(
178
+ (
179
+ name
180
+ for name in ("X", "Y", "Z", "R", "Theta", "Phi")
181
+ if name.lower() == payload_key.lower()
182
+ ),
183
+ "",
184
+ )
185
+ if canonical_key:
186
+ if canonical_key in coordinate_keys:
187
+ raise InvalidConfigurationError(
188
+ f"Duplicate coordinate definition for {canonical_key!r}."
189
+ )
190
+ coordinate_keys[canonical_key] = payload_key
191
+
192
+ cartesian_names: tuple[str, ...] = tuple(
193
+ name for name in ("X", "Y", "Z") if name in coordinate_keys
194
+ )
195
+ polar_names: tuple[str, ...] = tuple(
196
+ name for name in ("R", "Theta", "Phi") if name in coordinate_keys
197
+ )
198
+ if cartesian_names and polar_names:
199
+ raise InvalidConfigurationError(
200
+ "Field payload must use either Cartesian or polar coordinates, not both."
201
+ )
202
+ if not cartesian_names and not polar_names:
203
+ raise InvalidConfigurationError(
204
+ "Field payload does not contain supported Cartesian or polar coordinates."
205
+ )
206
+ names: tuple[str, ...] = cartesian_names or polar_names
207
+ values: tuple[np.ndarray, ...] = tuple(
208
+ np.asarray(payload[coordinate_keys[name]]) for name in names
209
+ )
210
+ vector_values: tuple[np.ndarray, ...] = tuple(
211
+ value for value in values if value.ndim == 1
212
+ )
213
+ varying_vector_values: tuple[np.ndarray, ...] = tuple(
214
+ value
215
+ for value in vector_values
216
+ if value.size <= 1 or not np.all(value == value.flat[0])
217
+ )
218
+ preserve_constant_vectors: bool = field_shape is not None and (
219
+ len(field_shape) in {len(vector_values), len(vector_values) + 1}
220
+ )
221
+ if varying_vector_values and not preserve_constant_vectors:
222
+ active_names: tuple[str, ...] = tuple(
223
+ name
224
+ for name, value in zip(names, values, strict=True)
225
+ if value.ndim != 1 or value.size <= 1 or not np.all(value == value.flat[0])
226
+ )
227
+ if active_names:
228
+ names = active_names
229
+ values = tuple(np.asarray(payload[coordinate_keys[name]]) for name in names)
230
+ non_scalar_values: tuple[np.ndarray, ...] = tuple(
231
+ value for value in values if value.ndim > 0
232
+ )
233
+ grid_shape: tuple[int, ...]
234
+ if not non_scalar_values:
235
+ grid_shape = ()
236
+ elif all(value.ndim == 1 for value in non_scalar_values):
237
+ grid_shape = tuple(int(value.size) for value in non_scalar_values)
238
+ else:
239
+ grid_shape = tuple(int(size) for size in non_scalar_values[0].shape)
240
+ if any(value.shape not in {(), grid_shape} for value in non_scalar_values):
241
+ raise InvalidConfigurationError(
242
+ "Field coordinate arrays must share one grid shape."
243
+ )
244
+ if field_shape is not None and len(names) > 1:
245
+ candidate_grid_shapes: tuple[tuple[int, ...], ...] = (field_shape,)
246
+ if field_shape:
247
+ candidate_grid_shapes += (field_shape[:-1],)
248
+ matching_grid_shape: tuple[int, ...] | None = next(
249
+ (
250
+ candidate
251
+ for candidate in candidate_grid_shapes
252
+ if candidate == grid_shape
253
+ ),
254
+ None,
255
+ )
256
+ if matching_grid_shape is not None and len(names) > len(matching_grid_shape):
257
+ varying_names: tuple[str, ...] = tuple(
258
+ name
259
+ for name, value in zip(names, values, strict=True)
260
+ if value.size <= 1 or not np.all(value == value.flat[0])
261
+ )
262
+ if len(varying_names) == len(matching_grid_shape):
263
+ names = varying_names
264
+ values = tuple(
265
+ np.asarray(payload[coordinate_keys[name]]) for name in names
266
+ )
267
+ non_scalar_values = tuple(value for value in values if value.ndim > 0)
268
+ if non_scalar_values and all(
269
+ value.ndim == 1 for value in non_scalar_values
270
+ ):
271
+ grid_shape = tuple(int(value.size) for value in non_scalar_values)
272
+ elif non_scalar_values:
273
+ grid_shape = tuple(int(size) for size in non_scalar_values[0].shape)
274
+ return _CoordinateTopology(
275
+ system="cartesian" if cartesian_names else "polar",
276
+ names=names,
277
+ values=values,
278
+ grid_shape=grid_shape,
279
+ )
280
+
281
+
282
+ def resolve_xy(
283
+ payload: Mapping[object, object],
284
+ ) -> tuple[np.ndarray, np.ndarray, str, str]:
285
+ """Resolve the first two field grid coordinates for legacy callers."""
286
+
287
+ coordinates: _CoordinateTopology = resolve_coordinates(payload)
288
+ if len(coordinates.values) != 2:
289
+ raise InvalidConfigurationError(
290
+ "Field payload does not contain exactly two grid coordinates."
291
+ )
292
+ return (
293
+ coordinates.values[0],
294
+ coordinates.values[1],
295
+ coordinates.names[0],
296
+ coordinates.names[1],
297
+ )
298
+
299
+
300
+ def resolve_field_tensor(
301
+ source: Mapping[object, object] | str | Path,
302
+ *,
303
+ field_index: int,
304
+ ) -> np.ndarray:
305
+ """Resolve one field tensor from a field payload."""
306
+
307
+ payload: Mapping[object, object] = resolve_field_payload(source)
308
+ field_container: object = payload["field"]
309
+ if isinstance(field_container, np.ndarray):
310
+ if field_index != 0:
311
+ raise InvalidConfigurationError(
312
+ f"field_index={field_index} is out of range for a scalar field payload."
313
+ )
314
+ return np.asarray(field_container)
315
+ if not isinstance(field_container, list):
316
+ raise InvalidConfigurationError(
317
+ "Field payload key 'field' must be a list or ndarray."
318
+ )
319
+ if field_index < 0 or field_index >= len(field_container):
320
+ raise InvalidConfigurationError(
321
+ f"field_index={field_index} is out of range for {len(field_container)} fields."
322
+ )
323
+ field_tensor: np.ndarray = np.asarray(field_container[field_index])
324
+ return field_tensor
325
+
326
+
327
+ def component_labels_from_tensor(
328
+ field_tensor: np.ndarray,
329
+ *,
330
+ grid_rank: int | None = None,
331
+ ) -> tuple[str, ...]:
332
+ """Infer component labels from one normalized field tensor.
333
+
334
+ Parameters
335
+ ----------
336
+ field_tensor : numpy.ndarray
337
+ Normalized field values.
338
+ grid_rank : int | None, optional
339
+ Number of spatial grid dimensions. Use `2` when omitted.
340
+
341
+ Returns
342
+ -------
343
+ tuple[str, ...]
344
+ Component labels, or `("value",)` for a scalar field.
345
+ """
346
+
347
+ if grid_rank is None:
348
+ grid_rank = 2
349
+ if field_tensor.ndim <= grid_rank:
350
+ return ("value",)
351
+ component_count: int = int(field_tensor.shape[-1])
352
+ if component_count == 3:
353
+ return ("x", "y", "z")
354
+ labels: list[str] = []
355
+ component_index: int
356
+ for component_index in range(component_count):
357
+ labels.append(f"c{component_index}")
358
+ return tuple(labels)
359
+
360
+
361
+ def normalize_field_tensor(
362
+ payload: Mapping[object, object],
363
+ *,
364
+ field_index: int,
365
+ ) -> np.ndarray:
366
+ """Normalize a field tensor onto its Cartesian or polar grid when needed."""
367
+
368
+ field_tensor: np.ndarray = resolve_field_tensor(
369
+ payload,
370
+ field_index=field_index,
371
+ )
372
+ coordinates: _CoordinateTopology = resolve_coordinates(
373
+ payload,
374
+ field_shape=field_tensor.shape,
375
+ )
376
+ grid_shape: tuple[int, ...] = coordinates.grid_shape
377
+ grid_point_count: int = int(np.prod(grid_shape))
378
+ if field_tensor.ndim == 1 and field_tensor.size == grid_point_count:
379
+ return field_tensor.reshape(grid_shape, order="F")
380
+ if field_tensor.ndim == 2 and field_tensor.shape[0] == grid_point_count:
381
+ if field_tensor.shape[1] == 1:
382
+ return field_tensor.reshape(grid_shape, order="F")
383
+ return field_tensor.reshape((*grid_shape, field_tensor.shape[1]), order="F")
384
+ if field_tensor.shape == grid_shape:
385
+ return field_tensor
386
+ if (
387
+ field_tensor.ndim == len(grid_shape) + 1
388
+ and field_tensor.shape[:-1] == grid_shape
389
+ ):
390
+ return field_tensor
391
+ vector_grid_shape: tuple[int, ...] = tuple(
392
+ int(value.size) for value in coordinates.values if value.ndim == 1
393
+ )
394
+ if len(vector_grid_shape) == len(coordinates.names):
395
+ reversed_grid_shape: tuple[int, ...] = tuple(reversed(vector_grid_shape))
396
+ if field_tensor.shape == reversed_grid_shape:
397
+ return field_tensor
398
+ if (
399
+ field_tensor.ndim == len(reversed_grid_shape) + 1
400
+ and field_tensor.shape[:-1] == reversed_grid_shape
401
+ ):
402
+ return field_tensor
403
+ raise InvalidConfigurationError(
404
+ f"Field shape {field_tensor.shape} does not match grid shape {grid_shape}."
405
+ )
406
+
407
+
408
+ def _collect_derivative_payloads(
409
+ payload: Mapping[object, object],
410
+ ) -> dict[str, Mapping[object, object]]:
411
+ """Collect immediate derivative child payloads from one field payload."""
412
+
413
+ derivative_payloads: dict[str, Mapping[object, object]] = {}
414
+ payload_key: object
415
+ payload_value: object
416
+ for payload_key, payload_value in payload.items():
417
+ if not isinstance(payload_key, str) or not isinstance(payload_value, Mapping):
418
+ continue
419
+ normalized_name: str | None = _normalize_derivative_key(payload_key)
420
+ if normalized_name is None:
421
+ continue
422
+ if normalized_name in derivative_payloads:
423
+ raise InvalidConfigurationError(
424
+ f"Duplicate derivative branch {normalized_name!r} in field payload."
425
+ )
426
+ derivative_payloads[normalized_name] = payload_value
427
+ return derivative_payloads
428
+
429
+
430
+ def _normalize_derivative_key(key: str) -> str | None:
431
+ """Normalize a derivative payload key to a Python-side branch name."""
432
+
433
+ if key.startswith("dd_field_"):
434
+ return key.removeprefix("dd_field_")
435
+ if key.startswith("d_field_"):
436
+ return key.removeprefix("d_field_")
437
+ if key.startswith("dd_"):
438
+ return key.removeprefix("dd_")
439
+ if key.startswith("d_"):
440
+ return key.removeprefix("d_")
441
+ return None
442
+
443
+
444
+ def _normalize_derivative_name(derivative: str) -> str:
445
+ """Normalize a derivative selector to the public branch key."""
446
+
447
+ normalized_derivative: str = derivative.strip()
448
+ if not normalized_derivative:
449
+ raise InvalidConfigurationError("Derivative selector must not be empty.")
450
+ normalized_key: str | None = _normalize_derivative_key(normalized_derivative)
451
+ if normalized_key is not None:
452
+ return normalized_key
453
+ return normalized_derivative
@@ -0,0 +1,4 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Internal results helper modules (non-public API)."""
@@ -0,0 +1,4 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Internal result export helpers grouped by output format."""
@@ -0,0 +1,56 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Shared helpers for SolveResult export surfaces."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from collections.abc import Iterable, Mapping
9
+ from typing import TYPE_CHECKING, Protocol, cast
10
+
11
+ from .pandas.common import normalize_optional_index_columns
12
+
13
+ if TYPE_CHECKING:
14
+ import pandas as pd
15
+
16
+
17
+ class _PandasModule(Protocol):
18
+ """Runtime protocol for the pandas surface used by exports."""
19
+
20
+ DataFrame: type["pd.DataFrame"]
21
+
22
+
23
+ def load_pandas_module() -> _PandasModule:
24
+ """Load pandas lazily for export helpers."""
25
+
26
+ from ...pandas_export import _load_pandas_module
27
+
28
+ return _load_pandas_module()
29
+
30
+
31
+ def materialize_rows(
32
+ rows: Iterable[Mapping[str, object]],
33
+ *,
34
+ prefix: Mapping[str, object] | None = None,
35
+ row_index_key: str | None = None,
36
+ ) -> list[dict[str, object]]:
37
+ """Attach optional metadata and index columns to row dictionaries."""
38
+
39
+ materialized_rows: list[dict[str, object]] = []
40
+ row_index: int
41
+ row_data: Mapping[str, object]
42
+ for row_index, row_data in enumerate(rows):
43
+ merged_row: dict[str, object] = {} if prefix is None else dict(prefix)
44
+ if row_index_key is not None:
45
+ merged_row[row_index_key] = row_index
46
+ merged_row.update(row_data)
47
+ materialized_rows.append(merged_row)
48
+ return materialized_rows
49
+
50
+
51
+ def rows_to_dataframe(rows: Iterable[Mapping[str, object]]) -> "pd.DataFrame":
52
+ """Convert row dictionaries into a normalized pandas DataFrame."""
53
+
54
+ pandas_module: _PandasModule = load_pandas_module()
55
+ dataframe = pandas_module.DataFrame(list(rows))
56
+ return cast("pd.DataFrame", normalize_optional_index_columns(dataframe))
@@ -0,0 +1,4 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Internal pandas export helpers."""
@@ -0,0 +1,165 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Shared helpers for pandas export utilities."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import math
9
+ from collections.abc import Iterable, Iterator, Mapping
10
+ from typing import TYPE_CHECKING, Literal, cast
11
+
12
+ import numpy as np
13
+
14
+ from .....exceptions import InvalidConfigurationError, UnsupportedExportError
15
+
16
+ if TYPE_CHECKING:
17
+ import pandas as pd
18
+
19
+ from ....artifacts import PostprocessRecord
20
+ from ....models import BatchSolveEntry, SolveResult
21
+
22
+ DataFrameDetail = Literal["summary", "long", "values"]
23
+
24
+
25
+ def validate_dataframe_detail(detail: str) -> None:
26
+ """Validate dataframe detail mode."""
27
+
28
+ if detail in {"summary", "long", "values"}:
29
+ return
30
+ raise InvalidConfigurationError(
31
+ f"Unsupported dataframe detail mode: {detail!r}. "
32
+ "Use one of {'summary', 'long', 'values'}."
33
+ )
34
+
35
+
36
+ def entry_key_columns(entry: "BatchSolveEntry") -> dict[str, object]:
37
+ """Expand batch entry keys into dataframe columns."""
38
+
39
+ key_columns: dict[str, object] = {}
40
+ key_name: str
41
+ key_value: object
42
+ for key_name, key_value in sorted(entry.keys.items()):
43
+ key_columns[key_name] = key_value
44
+ return key_columns
45
+
46
+
47
+ def expanded_keys(keys: Mapping[str, object]) -> dict[str, object]:
48
+ """Expand a keys mapping into sorted dataframe columns."""
49
+
50
+ expanded: dict[str, object] = {}
51
+ key_name: str
52
+ key_value: object
53
+ for key_name, key_value in sorted(keys.items()):
54
+ expanded[key_name] = key_value
55
+ return expanded
56
+
57
+
58
+ def iter_resultbag_solve_entries(
59
+ items: Iterable[tuple[dict[str, object], object]],
60
+ ) -> Iterator[tuple[int, dict[str, object], "SolveResult"]]:
61
+ """Iterate over resultbag entries and yield solve-result payloads only."""
62
+
63
+ from ....models import SolveResult
64
+
65
+ item_index: int
66
+ keys: dict[str, object]
67
+ payload: object
68
+ for item_index, (keys, payload) in enumerate(items):
69
+ if isinstance(payload, SolveResult):
70
+ yield item_index, keys, payload
71
+
72
+
73
+ def is_field_postprocess_record(postprocess_record: "PostprocessRecord") -> bool:
74
+ """Return whether a postprocess record describes a field export payload."""
75
+
76
+ try:
77
+ payload_mapping: Mapping[object, object] = postprocess_record.to_dict()
78
+ except UnsupportedExportError:
79
+ return False
80
+ if payload_mapping is not None:
81
+ mapping_key: object
82
+ for mapping_key in payload_mapping:
83
+ if str(mapping_key).lower() == "field":
84
+ return True
85
+ if postprocess_record.title is None:
86
+ return False
87
+ return postprocess_record.title.lower() in {
88
+ "field",
89
+ "fields",
90
+ "fieldexport",
91
+ "field_export",
92
+ }
93
+
94
+
95
+ def postprocess_value_mapping(
96
+ postprocess_record: "PostprocessRecord",
97
+ ) -> Mapping[object, object] | None:
98
+ """Return normalized values through the new record mapping capability."""
99
+
100
+ try:
101
+ payload_mapping: Mapping[object, object] = postprocess_record.to_dict()
102
+ except UnsupportedExportError:
103
+ payload_object: object = postprocess_record._raw
104
+ if not isinstance(payload_object, Mapping):
105
+ return None
106
+ payload_mapping = payload_object
107
+ values: dict[object, object] = dict(payload_mapping)
108
+ values.pop("title", None)
109
+ values.pop("header", None)
110
+ return values
111
+
112
+
113
+ def dataframe_rows(dataframe: object) -> list[dict[str, object]]:
114
+ """Normalize a DataFrame-like object into record rows."""
115
+
116
+ to_dict_method: object | None = getattr(dataframe, "to_dict", None)
117
+ if callable(to_dict_method):
118
+ rows_object: object = to_dict_method(orient="records")
119
+ if isinstance(rows_object, list):
120
+ return [cast(dict[str, object], row) for row in rows_object]
121
+ rows_object = getattr(dataframe, "data", [])
122
+ if isinstance(rows_object, list):
123
+ return [cast(dict[str, object], row) for row in rows_object]
124
+ raise InvalidConfigurationError(
125
+ f"Unsupported DataFrame-like object for export: {type(dataframe)!r}"
126
+ )
127
+
128
+
129
+ def normalize_optional_index_columns(dataframe: object) -> object:
130
+ """Keep optional index-like dataframe columns as `None` instead of `NaN`."""
131
+
132
+ if not hasattr(dataframe, "columns"):
133
+ return dataframe
134
+
135
+ import pandas as pd
136
+
137
+ pandas_dataframe = cast("pd.DataFrame", dataframe)
138
+ candidate_column: str
139
+ for candidate_column in ("field_index", "sample_index"):
140
+ if candidate_column not in pandas_dataframe.columns:
141
+ continue
142
+ series = pandas_dataframe[candidate_column]
143
+ normalized_values: list[object] = [
144
+ _normalize_optional_index_value(value) for value in series.tolist()
145
+ ]
146
+ pandas_dataframe[candidate_column] = pd.Series(
147
+ normalized_values,
148
+ index=series.index,
149
+ dtype=object,
150
+ )
151
+ return pandas_dataframe
152
+
153
+
154
+ def _normalize_optional_index_value(value: object) -> object:
155
+ """Normalize one optional dataframe index value."""
156
+
157
+ if value is None:
158
+ return None
159
+ if isinstance(value, (float, np.floating)) and math.isnan(float(value)):
160
+ return None
161
+ if isinstance(value, (int, np.integer)):
162
+ return int(value)
163
+ if isinstance(value, (float, np.floating)) and float(value).is_integer():
164
+ return int(value)
165
+ return value