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,757 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Typed payload adapters used by single-result postprocess records."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from collections.abc import Iterator, Mapping
9
+ from dataclasses import dataclass
10
+ from pathlib import Path
11
+ from typing import TYPE_CHECKING, cast
12
+
13
+ import numpy as np
14
+
15
+ from ..exceptions import InvalidConfigurationError
16
+ from ..loaders.table import TableCollection
17
+ from .field_exports import FieldExportPayload
18
+ from .internal.export.common import materialize_rows, rows_to_dataframe
19
+ from .internal.export.pandas.payload import (
20
+ flatten_payload,
21
+ is_numeric_key_mapping,
22
+ payload_to_tabular_rows,
23
+ postprocess_payload_to_long_rows,
24
+ )
25
+ from .payloads import (
26
+ DictionaryExportMixin,
27
+ PostprocessRecordPayload,
28
+ Source,
29
+ StructuredPayload,
30
+ TableCollectionPayload,
31
+ TablePayload,
32
+ )
33
+
34
+ if TYPE_CHECKING:
35
+ import pandas as pd
36
+
37
+ from .internal.export.xarray.types import XarrayDataTree
38
+
39
+
40
+ @dataclass(slots=True, frozen=True)
41
+ class _TableRecordPayload(TablePayload):
42
+ """Typed table payload adapter for one discovered postprocess record."""
43
+
44
+ table: Mapping[object, object]
45
+ source: Source = None # pyright: ignore
46
+
47
+ def to_dict(self) -> Mapping[object, object]:
48
+ return dict(self.table)
49
+
50
+ def _value_mapping(self) -> Mapping[object, object]:
51
+ values: dict[object, object] = dict(self.table)
52
+ values.pop("title", None)
53
+ values.pop("header", None)
54
+ return values
55
+
56
+ def _to_df_wide(self) -> "pd.DataFrame":
57
+ rows: list[dict[str, object]] | None = payload_to_tabular_rows(
58
+ self._value_mapping()
59
+ )
60
+ if rows is None:
61
+ raise InvalidConfigurationError("Postprocess payload is not tabular.")
62
+ return rows_to_dataframe(materialize_rows(rows, row_index_key="row_index"))
63
+
64
+ def _to_df_long(self) -> "pd.DataFrame":
65
+ rows: list[dict[str, object]] | None = postprocess_payload_to_long_rows(
66
+ self._value_mapping()
67
+ )
68
+ if rows is None:
69
+ raise InvalidConfigurationError("Postprocess payload is not tabular.")
70
+ return rows_to_dataframe(materialize_rows(rows, row_index_key="row_index"))
71
+
72
+ def to_xarray(self) -> "XarrayDataTree":
73
+ from .internal.export.xarray.export import postprocess_payload_to_xarray_dataset
74
+
75
+ title_object: object | None = self.table.get("title")
76
+ title: str | None = title_object if isinstance(title_object, str) else None
77
+ return postprocess_payload_to_xarray_dataset(
78
+ self._value_mapping(), postprocess_title=title, source_file=self.source
79
+ )
80
+
81
+
82
+ @dataclass(slots=True, frozen=True)
83
+ class _StructuredRecordPayload(StructuredPayload):
84
+ """Typed structured payload adapter for restored postprocess records."""
85
+
86
+ mapping: Mapping[object, object]
87
+ source: Source = None # pyright: ignore
88
+
89
+ def _value_mapping(self) -> Mapping[object, object]:
90
+ values: dict[object, object] = dict(self.mapping)
91
+ values.pop("title", None)
92
+ values.pop("header", None)
93
+ return values
94
+
95
+ def to_dict(self) -> Mapping[object, object]:
96
+ return dict(self.mapping)
97
+
98
+ def _to_df_long(self) -> "pd.DataFrame":
99
+ rows: list[dict[str, object]] = [
100
+ {"path": path, "value": value}
101
+ for path, value in flatten_payload(self._value_mapping(), path_prefix="")
102
+ ]
103
+ return rows_to_dataframe(rows)
104
+
105
+ def to_xarray(self) -> "XarrayDataTree":
106
+ from .internal.export.xarray.export import postprocess_payload_to_xarray_dataset
107
+
108
+ title_object: object | None = self.mapping.get("title")
109
+ title: str | None = title_object if isinstance(title_object, str) else None
110
+ return postprocess_payload_to_xarray_dataset(
111
+ self._value_mapping(), postprocess_title=title, source_file=self.source
112
+ )
113
+
114
+
115
+ @dataclass(slots=True, frozen=True)
116
+ class _TableCollectionRecordPayload(TableCollectionPayload):
117
+ """Typed table-collection payload adapter for one discovered record."""
118
+
119
+ collection: TableCollection
120
+ source: Source = None # pyright: ignore
121
+
122
+ def to_dict(self) -> Mapping[object, object]:
123
+ names: tuple[str, ...] = self.collection.table_names()
124
+ result: dict[str, object] = {}
125
+ for name, table in zip(names, self.collection, strict=True):
126
+ if not isinstance(table, Mapping):
127
+ raise InvalidConfigurationError(
128
+ "Table-collection mapping export requires named table payloads."
129
+ )
130
+ result[name] = dict(table)
131
+ return cast(Mapping[object, object], result)
132
+
133
+ def _to_df_long(self) -> "pd.DataFrame":
134
+ return self.collection.to_df()
135
+
136
+ def to_xarray(self) -> "XarrayDataTree":
137
+ return self.collection.to_xarray()
138
+
139
+
140
+ class _StandaloneTablePayload(TablePayload, Mapping[object, object]):
141
+ """Standalone named table payload."""
142
+
143
+ def __init__(self, table: Mapping[object, object], *, source: Source) -> None:
144
+ self._delegate = _TableRecordPayload(table=table, source=source)
145
+
146
+ @property
147
+ def source(self) -> Source:
148
+ return self._delegate.source
149
+
150
+ def to_dict(self) -> Mapping[object, object]:
151
+ return self._delegate.to_dict()
152
+
153
+ def __getitem__(self, key: object) -> object:
154
+ return self.to_dict()[key]
155
+
156
+ def __iter__(self) -> Iterator[object]:
157
+ return iter(self.to_dict())
158
+
159
+ def __len__(self) -> int:
160
+ return len(self.to_dict())
161
+
162
+ def _to_df_wide(self) -> "pd.DataFrame":
163
+ return self._delegate._to_df_wide()
164
+
165
+ def _to_df_long(self) -> "pd.DataFrame":
166
+ return self._delegate._to_df_long()
167
+
168
+ def to_xarray(self) -> "XarrayDataTree":
169
+ return self._delegate.to_xarray()
170
+
171
+
172
+ class _StandaloneTableCollectionPayload(TableCollectionPayload):
173
+ """Standalone named table collection payload."""
174
+
175
+ def __init__(self, collection: TableCollection) -> None:
176
+ self._delegate = _TableCollectionRecordPayload(
177
+ collection=collection, source=collection.source_file
178
+ )
179
+
180
+ @property
181
+ def source(self) -> Source:
182
+ return self._delegate.source
183
+
184
+ def to_dict(self) -> Mapping[object, object]:
185
+ return self._delegate.to_dict()
186
+
187
+ def __getitem__(self, index: int) -> Mapping[object, object]:
188
+ table: object = self._delegate.collection[index]
189
+ if not isinstance(table, Mapping):
190
+ raise InvalidConfigurationError(
191
+ "Table-collection payload contains a non-mapping table."
192
+ )
193
+ return cast(Mapping[object, object], table)
194
+
195
+ def __iter__(self) -> Iterator[Mapping[object, object]]:
196
+ return (
197
+ cast(Mapping[object, object], table) for table in self._delegate.collection
198
+ )
199
+
200
+ def __len__(self) -> int:
201
+ return len(self._delegate.collection)
202
+
203
+ def _to_df_long(self) -> "pd.DataFrame":
204
+ return self._delegate._to_df_long()
205
+
206
+ def to_xarray(self) -> "XarrayDataTree":
207
+ return self._delegate.to_xarray()
208
+
209
+
210
+ class TableDerivativeCollection:
211
+ """Select solver derivatives from one canonical table payload."""
212
+
213
+ def __init__(
214
+ self,
215
+ payload: TablePayload,
216
+ *,
217
+ root: Mapping[object, object] | None = None,
218
+ parameter: str | None = None,
219
+ depth: int = 0,
220
+ ) -> None:
221
+ self._payload: TablePayload = payload
222
+ self._root: Mapping[object, object] = (
223
+ payload.to_dict() if root is None else root
224
+ )
225
+ self._parameter: str | None = parameter
226
+ self._depth: int = depth
227
+
228
+ def keys(self) -> tuple[str, ...]:
229
+ """Return the solver parameter names available for derivative selection.
230
+
231
+ On a postprocess record's derivative collection, the names select first
232
+ derivatives. After selecting a first derivative, the names select its
233
+ available second derivatives. These are solver parameter names, not
234
+ Torch project keys.
235
+
236
+ Returns
237
+ -------
238
+ tuple[str, ...]
239
+ Available parameter names in table traversal order. The tuple is
240
+ empty if no further derivative is available, including after a
241
+ second derivative has been selected.
242
+ """
243
+
244
+ if self._depth >= 2:
245
+ return ()
246
+ names: dict[str, None] = {}
247
+ if self._parameter is None:
248
+ branches: Mapping[object, object] = self._root
249
+ for key, value in branches.items():
250
+ if (
251
+ isinstance(key, str)
252
+ and key.startswith("d_")
253
+ and isinstance(value, Mapping)
254
+ ):
255
+ names[key[2:]] = None
256
+ else:
257
+ current_branch: object = self._root.get(f"d_{self._parameter}")
258
+ if isinstance(current_branch, Mapping):
259
+ for key, value in current_branch.items():
260
+ if (
261
+ isinstance(key, str)
262
+ and key.startswith("d_")
263
+ and isinstance(value, Mapping)
264
+ ):
265
+ names[key[2:]] = None
266
+ # Some parsed second-order schemas store the same unordered pair
267
+ # beneath the other first-derivative branch. Expose that pair in
268
+ # both traversal orders without splitting parameter labels.
269
+ for key, value in self._root.items():
270
+ if (
271
+ not isinstance(key, str)
272
+ or not key.startswith("d_")
273
+ or not isinstance(value, Mapping)
274
+ ):
275
+ continue
276
+ reverse: object = value.get(f"d_{self._parameter}")
277
+ if isinstance(reverse, Mapping):
278
+ names[key[2:]] = None
279
+ return tuple(names)
280
+
281
+ def __getitem__(self, name: str) -> "TableDerivativeView":
282
+ """Select one derivative by solver parameter name."""
283
+
284
+ if not isinstance(name, str):
285
+ raise TypeError("Derivative names must be strings.")
286
+ if self._depth >= 2:
287
+ raise KeyError(f"derivatives[{self._parameter!r}].derivatives[{name!r}]")
288
+ branch: str = f"d_{name}"
289
+ if self._parameter is None:
290
+ selected: object = self._root.get(branch)
291
+ expected_base: dict[object, object] = {
292
+ key: value
293
+ for key, value in self._root.items()
294
+ if key not in {"title", "header"}
295
+ and not (
296
+ isinstance(key, str)
297
+ and key.startswith("d_")
298
+ and isinstance(value, Mapping)
299
+ )
300
+ }
301
+ if isinstance(selected, Mapping) and not _compatible_numeric_shapes(
302
+ selected, expected_base
303
+ ):
304
+ raise InvalidConfigurationError(
305
+ f"Incompatible shapes for derivative path derivatives[{name!r}]."
306
+ )
307
+ else:
308
+ current: object = self._root.get(f"d_{self._parameter}")
309
+ direct: object = (
310
+ current.get(branch) if isinstance(current, Mapping) else None
311
+ )
312
+ reverse_parent: object = self._root.get(branch)
313
+ reverse: object = (
314
+ reverse_parent.get(f"d_{self._parameter}")
315
+ if isinstance(reverse_parent, Mapping)
316
+ else None
317
+ )
318
+ if isinstance(direct, Mapping) and isinstance(reverse, Mapping):
319
+ if not _equivalent_derivative_payloads(direct, reverse):
320
+ message: str = (
321
+ f"Conflicting table derivative paths d_{self._parameter}.{branch} "
322
+ f"and {branch}.d_{self._parameter}."
323
+ )
324
+ if not _compatible_numeric_shapes(direct, reverse):
325
+ message = (
326
+ f"Incompatible shapes for table derivative paths "
327
+ f"d_{self._parameter}.{branch} and {branch}.d_{self._parameter}."
328
+ )
329
+ raise InvalidConfigurationError(message)
330
+ selected = direct if isinstance(direct, Mapping) else reverse
331
+ expected: object = current
332
+ if isinstance(selected, Mapping) and isinstance(expected, Mapping):
333
+ if not _compatible_numeric_shapes(selected, expected):
334
+ raise InvalidConfigurationError(
335
+ f"Incompatible shapes for derivative path "
336
+ f"derivatives[{self._parameter!r}].derivatives[{name!r}]."
337
+ )
338
+ if not isinstance(selected, Mapping):
339
+ path: str = (
340
+ f"derivatives[{self._parameter!r}].derivatives[{name!r}]"
341
+ if self._parameter is not None
342
+ else f"derivatives[{name!r}]"
343
+ )
344
+ raise KeyError(path)
345
+ return TableDerivativeView(
346
+ cast(Mapping[object, object], selected),
347
+ source=self._payload.source,
348
+ root=self._root,
349
+ parameter=name,
350
+ depth=self._depth + 1,
351
+ )
352
+
353
+
354
+ class TableDerivativeView(TablePayload):
355
+ """Table-shaped export of a selected first- or higher-order derivative."""
356
+
357
+ def __init__(
358
+ self,
359
+ values: Mapping[object, object],
360
+ *,
361
+ source: Source,
362
+ root: Mapping[object, object],
363
+ parameter: str,
364
+ depth: int,
365
+ ) -> None:
366
+ self._delegate: _TableRecordPayload = _TableRecordPayload(
367
+ table=values, source=source
368
+ )
369
+ self._root: Mapping[object, object] = root
370
+ self._parameter: str = parameter
371
+ self._depth: int = depth
372
+ export_values: dict[object, object] = {
373
+ key: value
374
+ for key, value in values.items()
375
+ if not (
376
+ isinstance(key, str)
377
+ and key.startswith("d_")
378
+ and isinstance(value, Mapping)
379
+ )
380
+ }
381
+ for metadata_key in ("title", "header"):
382
+ if metadata_key in root and metadata_key not in export_values:
383
+ export_values[metadata_key] = root[metadata_key]
384
+ self._export_delegate: _TableRecordPayload = _TableRecordPayload(
385
+ table=export_values, source=source
386
+ )
387
+
388
+ @property
389
+ def source(self) -> Source:
390
+ return self._delegate.source
391
+
392
+ @property
393
+ def derivatives(self) -> TableDerivativeCollection:
394
+ return TableDerivativeCollection(
395
+ self,
396
+ root=self._root,
397
+ parameter=self._parameter,
398
+ depth=self._depth,
399
+ )
400
+
401
+ def to_dict(self) -> Mapping[object, object]:
402
+ return self._export_delegate.to_dict()
403
+
404
+ def _to_df_wide(self) -> "pd.DataFrame":
405
+ return self._export_delegate._to_df_wide()
406
+
407
+ def _to_df_long(self) -> "pd.DataFrame":
408
+ return self._export_delegate._to_df_long()
409
+
410
+ def to_xarray(self) -> "XarrayDataTree":
411
+ return self._export_delegate.to_xarray()
412
+
413
+
414
+ class TableCollectionDerivativeCollection:
415
+ """Select derivative directions without changing table member identity."""
416
+
417
+ def __init__(
418
+ self,
419
+ payload: TableCollectionPayload,
420
+ *,
421
+ roots: Mapping[str, Mapping[object, object]] | None = None,
422
+ parameter: str | None = None,
423
+ depth: int = 0,
424
+ ) -> None:
425
+ self._payload: TableCollectionPayload = payload
426
+ raw: Mapping[object, object] = payload.to_dict()
427
+ self._roots: dict[str, Mapping[object, object]] = (
428
+ {
429
+ str(name): cast(Mapping[object, object], table)
430
+ for name, table in raw.items()
431
+ if isinstance(table, Mapping)
432
+ }
433
+ if roots is None
434
+ else dict(roots)
435
+ )
436
+ self._parameter: str | None = parameter
437
+ self._depth: int = depth
438
+
439
+ def keys(self) -> tuple[str, ...]:
440
+ """Return solver parameter names available in at least one table.
441
+
442
+ On a postprocess record's derivative collection, the names select first
443
+ derivatives. After selecting a first derivative, the names select its
444
+ available second derivatives. A name need not be available in every
445
+ table; selecting it includes only the tables that provide it.
446
+
447
+ Returns
448
+ -------
449
+ tuple[str, ...]
450
+ Unique parameter names in first-encounter order across the tables.
451
+ The tuple is empty if no further derivative is available, including
452
+ after a second derivative has been selected.
453
+ """
454
+
455
+ if self._depth >= 2:
456
+ return ()
457
+ names: dict[str, None] = {}
458
+ for root in self._roots.values():
459
+ table: _TableRecordPayload = _TableRecordPayload(
460
+ table=root, source=self._payload.source
461
+ )
462
+ collection: TableDerivativeCollection = TableDerivativeCollection(
463
+ table, root=root, parameter=self._parameter, depth=self._depth
464
+ )
465
+ names.update(dict.fromkeys(collection.keys()))
466
+ return tuple(names)
467
+
468
+ def __getitem__(self, name: str) -> "TableCollectionDerivativeView":
469
+ """Select an available derivative from each matching collection member."""
470
+
471
+ if not isinstance(name, str):
472
+ raise TypeError("Derivative names must be strings.")
473
+ selected: dict[str, TableDerivativeView] = {}
474
+ for member, root in self._roots.items():
475
+ table: _TableRecordPayload = _TableRecordPayload(
476
+ table=root, source=self._payload.source
477
+ )
478
+ derivatives: TableDerivativeCollection = TableDerivativeCollection(
479
+ table, root=root, parameter=self._parameter, depth=self._depth
480
+ )
481
+ if name in derivatives.keys():
482
+ selected[member] = derivatives[name]
483
+ if not selected:
484
+ path: str = (
485
+ f"derivatives[{self._parameter!r}].derivatives[{name!r}]"
486
+ if self._parameter is not None
487
+ else f"derivatives[{name!r}]"
488
+ )
489
+ raise KeyError(path)
490
+ selected_roots: dict[str, Mapping[object, object]] = {
491
+ member: self._roots[member] for member in selected
492
+ }
493
+ return TableCollectionDerivativeView(
494
+ payload=self._payload,
495
+ members=selected,
496
+ roots=selected_roots,
497
+ parameter=name,
498
+ depth=self._depth + 1,
499
+ )
500
+
501
+
502
+ class TableCollectionDerivativeView(TableCollectionPayload):
503
+ """Collection export containing only members with the selected derivative."""
504
+
505
+ def __init__(
506
+ self,
507
+ *,
508
+ payload: TableCollectionPayload,
509
+ members: Mapping[str, TableDerivativeView],
510
+ roots: Mapping[str, Mapping[object, object]],
511
+ parameter: str,
512
+ depth: int,
513
+ ) -> None:
514
+ self._payload: TableCollectionPayload = payload
515
+ self._members: dict[str, TableDerivativeView] = dict(members)
516
+ self._roots: dict[str, Mapping[object, object]] = dict(roots)
517
+ self._parameter: str = parameter
518
+ self._depth: int = depth
519
+
520
+ @property
521
+ def source(self) -> Source:
522
+ return self._payload.source
523
+
524
+ @property
525
+ def derivatives(self) -> TableCollectionDerivativeCollection:
526
+ return TableCollectionDerivativeCollection(
527
+ self._payload,
528
+ roots=self._roots,
529
+ parameter=self._parameter,
530
+ depth=self._depth,
531
+ )
532
+
533
+ def to_dict(self) -> Mapping[object, object]:
534
+ return {name: view.to_dict() for name, view in self._members.items()}
535
+
536
+ def _collection(self) -> TableCollection:
537
+ tables: list[dict[str | int, object]] = [
538
+ cast(dict[str | int, object], dict(view.to_dict()))
539
+ for view in self._members.values()
540
+ ]
541
+ source_file: Path | None = (
542
+ Path(self.source) if isinstance(self.source, str) else self.source
543
+ )
544
+ return _NamedDerivativeTableCollection(
545
+ tables,
546
+ names=tuple(self._members),
547
+ source_file=source_file,
548
+ )
549
+
550
+ def _to_df_long(self) -> "pd.DataFrame":
551
+ return self._collection().to_df()
552
+
553
+ def to_xarray(self) -> "XarrayDataTree":
554
+ return self._collection().to_xarray()
555
+
556
+
557
+ class _NamedDerivativeTableCollection(TableCollection):
558
+ """Export selected tables under their original collection member names."""
559
+
560
+ def __init__(
561
+ self,
562
+ tables: list[dict[str | int, object]],
563
+ *,
564
+ names: tuple[str, ...],
565
+ source_file: Path | None,
566
+ ) -> None:
567
+ super().__init__(tables, source_file=source_file)
568
+ self._member_names: tuple[str, ...] = names
569
+
570
+ def table_names(self) -> tuple[str, ...]:
571
+ """Return the member identifiers retained from the source collection."""
572
+
573
+ return self._member_names
574
+
575
+
576
+ def format_postprocess_payload_preview(payload: PostprocessRecordPayload) -> str:
577
+ """Return the bounded preview appropriate for one postprocess payload."""
578
+
579
+ if isinstance(payload, TablePayload):
580
+ return payload._preview()
581
+ if isinstance(payload, _StructuredRecordPayload):
582
+ paths: list[tuple[str, object]] = flatten_payload(
583
+ payload.to_dict(), path_prefix=""
584
+ )
585
+ values: dict[object, object] = {
586
+ "path": tuple(path for path, _ in paths),
587
+ "value": tuple(value for _, value in paths),
588
+ }
589
+ from .internal.export.preview import format_table_preview
590
+
591
+ return format_table_preview(values, quote_strings=False)
592
+ if isinstance(payload, TableCollectionPayload):
593
+ table_names: tuple[str, ...] = tuple(str(name) for name in payload.to_dict())
594
+ table_values: dict[object, object] = {
595
+ "index": tuple(range(len(table_names))),
596
+ "table": table_names,
597
+ }
598
+ from .internal.export.preview import format_table_preview
599
+
600
+ return format_table_preview(
601
+ table_values, include_row_index=False, quote_strings=False
602
+ )
603
+ if isinstance(payload, FieldExportPayload):
604
+ return payload._preview()
605
+ return " <unsupported payload>"
606
+
607
+
608
+ def payload_mapping(raw: object | None) -> Mapping[object, object] | None:
609
+ """Return mapping data from a raw mapping or typed payload."""
610
+
611
+ if isinstance(raw, Mapping):
612
+ return cast(Mapping[object, object], raw)
613
+ if isinstance(raw, DictionaryExportMixin):
614
+ return raw.to_dict()
615
+ return None
616
+
617
+
618
+ def is_field_export_mapping(payload_object: object | None, title: str | None) -> bool:
619
+ """Return whether raw payload metadata identifies a field export."""
620
+
621
+ if isinstance(payload_object, Mapping):
622
+ if any(str(mapping_key).lower() == "field" for mapping_key in payload_object):
623
+ return True
624
+ return title is not None and title.lower() in {
625
+ "field",
626
+ "fields",
627
+ "fieldexport",
628
+ "field_export",
629
+ }
630
+
631
+
632
+ def _has_structured_branch(payload: Mapping[object, object]) -> bool:
633
+ value: object
634
+ for value in payload.values():
635
+ if isinstance(value, Mapping):
636
+ if not is_numeric_key_mapping(value) or _has_structured_branch(value):
637
+ return True
638
+ return False
639
+
640
+
641
+ def _compatible_numeric_shapes(
642
+ values: Mapping[object, object], expected: Mapping[object, object]
643
+ ) -> bool:
644
+ """Compare numeric leaf shapes where both tables expose the same path."""
645
+
646
+ matched_numeric_leaf: bool = False
647
+ for key, value in values.items():
648
+ expected_value: object = expected.get(key)
649
+ if isinstance(value, (np.ndarray, list, tuple)) and isinstance(
650
+ expected_value, (np.ndarray, list, tuple)
651
+ ):
652
+ matched_numeric_leaf = True
653
+ if np.shape(value) != np.shape(expected_value):
654
+ return False
655
+ elif isinstance(value, Mapping) and isinstance(expected_value, Mapping):
656
+ if not _compatible_numeric_shapes(value, expected_value):
657
+ return False
658
+ matched_numeric_leaf = True
659
+ return matched_numeric_leaf
660
+
661
+
662
+ def _equivalent_derivative_payloads(
663
+ first: Mapping[object, object], second: Mapping[object, object]
664
+ ) -> bool:
665
+ """Return whether two parsed representations contain the same pair values."""
666
+
667
+ if first.keys() != second.keys():
668
+ return False
669
+ for key, first_value in first.items():
670
+ second_value: object = second[key]
671
+ if isinstance(first_value, Mapping) and isinstance(second_value, Mapping):
672
+ if not _equivalent_derivative_payloads(first_value, second_value):
673
+ return False
674
+ elif isinstance(first_value, np.ndarray) or isinstance(
675
+ second_value, np.ndarray
676
+ ):
677
+ if not isinstance(first_value, np.ndarray) or not isinstance(
678
+ second_value, np.ndarray
679
+ ):
680
+ return False
681
+ if first_value.shape != second_value.shape:
682
+ return False
683
+ try:
684
+ equal_values: bool = bool(
685
+ np.array_equal(first_value, second_value, equal_nan=True)
686
+ )
687
+ except TypeError:
688
+ equal_values = bool(np.array_equal(first_value, second_value))
689
+ if not equal_values:
690
+ return False
691
+ elif isinstance(first_value, (list, tuple)) or isinstance(
692
+ second_value, (list, tuple)
693
+ ):
694
+ if not isinstance(first_value, (list, tuple)) or not isinstance(
695
+ second_value, type(first_value)
696
+ ):
697
+ return False
698
+ if not _equivalent_derivative_sequences(first_value, second_value):
699
+ return False
700
+ elif first_value != second_value:
701
+ return False
702
+ return True
703
+
704
+
705
+ def _equivalent_derivative_sequences(
706
+ first: list[object] | tuple[object, ...], second: list[object] | tuple[object, ...]
707
+ ) -> bool:
708
+ if len(first) != len(second):
709
+ return False
710
+ for first_value, second_value in zip(first, second, strict=True):
711
+ if isinstance(first_value, Mapping) and isinstance(second_value, Mapping):
712
+ if not _equivalent_derivative_payloads(first_value, second_value):
713
+ return False
714
+ elif isinstance(first_value, np.ndarray) or isinstance(
715
+ second_value, np.ndarray
716
+ ):
717
+ if not _equivalent_derivative_payloads(
718
+ {"value": first_value}, {"value": second_value}
719
+ ):
720
+ return False
721
+ elif isinstance(first_value, (list, tuple)) or isinstance(
722
+ second_value, (list, tuple)
723
+ ):
724
+ if not isinstance(first_value, (list, tuple)) or not isinstance(
725
+ second_value, type(first_value)
726
+ ):
727
+ return False
728
+ if not _equivalent_derivative_sequences(first_value, second_value):
729
+ return False
730
+ elif first_value != second_value:
731
+ return False
732
+ return True
733
+
734
+
735
+ def classify_payload(
736
+ *, raw: object | None, source: Source, title: str | None
737
+ ) -> PostprocessRecordPayload | None:
738
+ """Create one typed payload from a discovered raw result value."""
739
+
740
+ if isinstance(raw, PostprocessRecordPayload):
741
+ return raw
742
+ if isinstance(raw, TableCollection):
743
+ return _TableCollectionRecordPayload(collection=raw, source=source)
744
+ if not isinstance(raw, Mapping):
745
+ return None
746
+ from .field_payloads import is_field_export_payload
747
+
748
+ if is_field_export_mapping(raw, title) and is_field_export_payload(raw):
749
+ return FieldExportPayload(mapping=raw, source=source)
750
+ normalized_mapping: dict[object, object] = dict(raw)
751
+ normalized_mapping.pop("title", None)
752
+ normalized_mapping.pop("header", None)
753
+ if payload_to_tabular_rows(
754
+ normalized_mapping
755
+ ) is not None and not _has_structured_branch(normalized_mapping):
756
+ return _TableRecordPayload(table=raw, source=source)
757
+ return _StructuredRecordPayload(mapping=raw, source=source)