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,688 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Helpers for `xarray` / `DataTree` exports of structured result payloads."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from collections.abc import Mapping, Sequence
9
+ from typing import TYPE_CHECKING, cast
10
+
11
+ import numpy as np
12
+
13
+ from .....exceptions import InvalidConfigurationError, UnsupportedExportError
14
+ from ....artifacts import (
15
+ ComputationalCosts,
16
+ Eigenvalues,
17
+ PostprocessCollection,
18
+ )
19
+ from .grouped import (
20
+ _common_ordered_child_names,
21
+ _GroupedPostprocessTensor,
22
+ _split_structured_payload,
23
+ _stack_batch_grouped_tensors,
24
+ _StructuredPayloadParts,
25
+ grouped_tensor_to_xarray_dataset,
26
+ postprocess_payload_to_grouped_tensor,
27
+ )
28
+ from .headers import (
29
+ _append_stacked_header_data_variable,
30
+ _flatten_header_fields,
31
+ _header_payload_to_dataset,
32
+ )
33
+ from .runtime import (
34
+ _create_data_tree,
35
+ _DataTreeModule,
36
+ _load_datatree_module,
37
+ _load_xarray_module,
38
+ _XarrayModule,
39
+ )
40
+ from .shared import (
41
+ _build_batch_coord_variable,
42
+ _ensure_generated_companion_dim_coords,
43
+ )
44
+ from .tabular import (
45
+ _BatchIndexedKeys,
46
+ _stack_batch_tabular_tables,
47
+ _TabularXarrayTable,
48
+ tabular_payload_to_xarray_table,
49
+ tabular_table_to_xarray_dataset,
50
+ )
51
+ from .types import XarrayDataset, XarrayDataTree
52
+
53
+ if TYPE_CHECKING:
54
+ from ....artifacts import PostprocessRecord
55
+ from ...models.batch import BatchExportRecord
56
+
57
+
58
+ def batch_keys_to_xarray_dataset(
59
+ records: Sequence["BatchExportRecord"],
60
+ ) -> XarrayDataTree:
61
+ """Convert batch key metadata to a strict root-only `DataTree`."""
62
+
63
+ xarray_module: _XarrayModule = _load_xarray_module()
64
+ datatree_module: _DataTreeModule = _load_datatree_module()
65
+ key_names: tuple[str, ...] = _strict_batch_key_names(records)
66
+ data_vars: dict[str, object] = {}
67
+ key_name: str
68
+ for key_name in key_names:
69
+ values: list[object] = [record.keys[key_name] for record in records]
70
+ data_vars[key_name] = (
71
+ ("batch_index",),
72
+ _strict_batch_key_values(key_name, values),
73
+ )
74
+ dataset: XarrayDataset = xarray_module.Dataset(
75
+ data_vars=data_vars,
76
+ coords={"batch_index": [record.index for record in records]},
77
+ )
78
+ return _create_data_tree(datatree_module=datatree_module, dataset=dataset)
79
+
80
+
81
+ def batch_costs_to_xarray_dataset(
82
+ records: Sequence["BatchExportRecord"],
83
+ ) -> XarrayDataTree:
84
+ """Convert batch computational-cost tables into one `DataTree`."""
85
+
86
+ xarray_module: _XarrayModule = _load_xarray_module()
87
+ datatree_module: _DataTreeModule = _load_datatree_module()
88
+ tables: list[_TabularXarrayTable | None] = [
89
+ (
90
+ tabular_payload_to_xarray_table(
91
+ cast(ComputationalCosts, record.payload).table,
92
+ payload_name="Computational-cost payload",
93
+ )
94
+ if record.payload is not None
95
+ else None
96
+ )
97
+ for record in records
98
+ ]
99
+ dataset: XarrayDataset = _stack_batch_tabular_tables(
100
+ records,
101
+ tables,
102
+ xarray_module=xarray_module,
103
+ batch_axis_name="batch_index",
104
+ )
105
+ dataset.attrs.pop("header", None)
106
+ return _create_data_tree(datatree_module=datatree_module, dataset=dataset)
107
+
108
+
109
+ def _strict_batch_key_names(
110
+ records: Sequence["BatchExportRecord"],
111
+ ) -> tuple[str, ...]:
112
+ """Validate and return the common key-name set for strict export."""
113
+
114
+ if not records:
115
+ return ()
116
+ first_names: set[str] = set(records[0].keys)
117
+ record: BatchExportRecord
118
+ for record in records[1:]:
119
+ if set(record.keys) != first_names:
120
+ raise InvalidConfigurationError(
121
+ "Batch key payloads must have the same key names for direct "
122
+ "xarray export."
123
+ )
124
+ if "index" in first_names:
125
+ raise InvalidConfigurationError(
126
+ "Batch key name 'index' conflicts with the xarray batch index "
127
+ "coordinate."
128
+ )
129
+ return tuple(sorted(first_names))
130
+
131
+
132
+ def _strict_batch_key_values(key_name: str, values: Sequence[object]) -> np.ndarray:
133
+ """Validate scalar key values without applying shape coercion."""
134
+
135
+ categories: set[str] = set()
136
+ value: object
137
+ for value in values:
138
+ if value is None or not np.isscalar(value):
139
+ raise InvalidConfigurationError(
140
+ f"Batch key {key_name!r} is not directly representable in "
141
+ "xarray without coercion."
142
+ )
143
+ categories.add(_batch_key_scalar_category(value))
144
+ if len(categories) > 1:
145
+ raise InvalidConfigurationError(
146
+ f"Batch key {key_name!r} has incompatible scalar types for direct "
147
+ "xarray export."
148
+ )
149
+ return np.asarray(values)
150
+
151
+
152
+ def _batch_key_scalar_category(value: object) -> str:
153
+ """Return the strict xarray scalar category for one key value."""
154
+
155
+ if isinstance(value, (bool, np.bool_)):
156
+ return "bool"
157
+ if isinstance(value, (int, np.integer)):
158
+ return "integer"
159
+ if isinstance(value, (float, np.floating)):
160
+ return "floating"
161
+ if isinstance(value, (complex, np.complexfloating)):
162
+ return "complex"
163
+ if isinstance(value, str):
164
+ return "string"
165
+ if isinstance(value, (bytes, np.bytes_)):
166
+ return "bytes"
167
+ raise InvalidConfigurationError(
168
+ "Batch key value is not directly representable in xarray without " "coercion."
169
+ )
170
+
171
+
172
+ def postprocess_payload_to_xarray_dataset(
173
+ payload: object,
174
+ *,
175
+ postprocess_title: str | None,
176
+ source_file: object,
177
+ ) -> XarrayDataTree:
178
+ """Convert one supported postprocess payload into a `DataTree`."""
179
+
180
+ xarray_module: _XarrayModule = _load_xarray_module()
181
+ datatree_module: _DataTreeModule = _load_datatree_module()
182
+ if isinstance(payload, Mapping):
183
+ return _postprocess_mapping_to_data_tree(
184
+ payload,
185
+ postprocess_title=postprocess_title,
186
+ source_file=source_file,
187
+ xarray_module=xarray_module,
188
+ datatree_module=datatree_module,
189
+ )
190
+ raise InvalidConfigurationError(
191
+ "Postprocess payload is not mapping-like and cannot be exported via to_xarray()."
192
+ )
193
+
194
+
195
+ def eigenvalues_payload_to_xarray_dataset(payload: object) -> XarrayDataTree:
196
+ """Convert one tabular eigenvalue payload into a root-only `DataTree`."""
197
+
198
+ xarray_module: _XarrayModule = _load_xarray_module()
199
+ datatree_module: _DataTreeModule = _load_datatree_module()
200
+ normalized_payload: object = payload
201
+ title_value: object | None = None
202
+ if isinstance(payload, Mapping):
203
+ normalized_payload = dict(payload)
204
+ title_value = normalized_payload.pop("title", None)
205
+ table: _TabularXarrayTable = tabular_payload_to_xarray_table(
206
+ normalized_payload,
207
+ payload_name="Eigenvalue payload",
208
+ )
209
+ if title_value is not None:
210
+ table.attrs["title"] = title_value
211
+ dataset: XarrayDataset = tabular_table_to_xarray_dataset(
212
+ table, xarray_module=xarray_module
213
+ )
214
+ return _create_data_tree(datatree_module=datatree_module, dataset=dataset)
215
+
216
+
217
+ def header_payload_to_xarray_dataset(payload: object) -> XarrayDataTree:
218
+ """Convert one postprocess header payload into a root-only `DataTree`."""
219
+
220
+ if not isinstance(payload, Mapping):
221
+ raise InvalidConfigurationError(
222
+ "Postprocess header payload is not mapping-like and cannot be exported via to_xarray()."
223
+ )
224
+ xarray_module: _XarrayModule = _load_xarray_module()
225
+ datatree_module: _DataTreeModule = _load_datatree_module()
226
+ dataset: XarrayDataset = _header_payload_to_dataset(
227
+ payload,
228
+ xarray_module=xarray_module,
229
+ )
230
+ return _create_data_tree(datatree_module=datatree_module, dataset=dataset)
231
+
232
+
233
+ def batch_selected_postprocess_headers_to_xarray_dataset(
234
+ entries: Sequence["BatchExportRecord"],
235
+ *,
236
+ index: int,
237
+ ) -> XarrayDataTree:
238
+ """Convert one selected batch postprocess header stream into a `DataTree`."""
239
+
240
+ xarray_module: _XarrayModule = _load_xarray_module()
241
+ datatree_module: _DataTreeModule = _load_datatree_module()
242
+ selected_entries: list[BatchExportRecord] = []
243
+ header_payloads: list[Mapping[object, object] | None] = []
244
+ entry: BatchExportRecord
245
+ for entry in entries:
246
+ if not isinstance(entry.payload, PostprocessCollection):
247
+ continue
248
+ record = _select_batch_postprocess_record(entry, index=index)
249
+ selected_entries.append(entry)
250
+ header_payloads.append(None if record.header is None else record.header.table)
251
+
252
+ dataset: XarrayDataset = _stack_batch_header_payloads(
253
+ selected_entries,
254
+ header_payloads,
255
+ xarray_module=xarray_module,
256
+ )
257
+ return _create_data_tree(datatree_module=datatree_module, dataset=dataset)
258
+
259
+
260
+ def batch_selected_postprocesses_to_xarray_dataset(
261
+ entries: Sequence["BatchExportRecord"],
262
+ *,
263
+ index: int,
264
+ ) -> XarrayDataTree:
265
+ """Convert one selected batch postprocess stream into a stacked `DataTree`."""
266
+
267
+ xarray_module: _XarrayModule = _load_xarray_module()
268
+ datatree_module: _DataTreeModule = _load_datatree_module()
269
+ selected_entries: list[BatchExportRecord] = []
270
+ payloads: list[Mapping[object, object]] = []
271
+ selected_title: str | None = None
272
+ entry: BatchExportRecord
273
+ for entry in entries:
274
+ if not isinstance(entry.payload, PostprocessCollection):
275
+ continue
276
+ record = _select_batch_postprocess_record(entry, index=index)
277
+ if selected_title is None:
278
+ selected_title = record.title
279
+ payload_object: object = _record_xarray_payload(record)
280
+ if not isinstance(payload_object, Mapping):
281
+ raise InvalidConfigurationError(
282
+ "Postprocess payload is not mapping-like and cannot be exported via to_xarray()."
283
+ )
284
+ payloads.append(payload_object)
285
+ selected_entries.append(entry)
286
+
287
+ if not payloads:
288
+ raise InvalidConfigurationError(
289
+ "No successful batch entries with the selected postprocess payload are available for to_xarray()."
290
+ )
291
+
292
+ return _stack_batch_postprocess_payloads_to_data_tree(
293
+ selected_entries,
294
+ payloads,
295
+ index=index,
296
+ title=selected_title,
297
+ xarray_module=xarray_module,
298
+ datatree_module=datatree_module,
299
+ )
300
+
301
+
302
+ def batch_eigenvalues_to_xarray_dataset(
303
+ records: Sequence["BatchExportRecord"],
304
+ ) -> XarrayDataTree:
305
+ """Convert batch eigenvalue tables into one stacked root-only `DataTree`."""
306
+
307
+ xarray_module: _XarrayModule = _load_xarray_module()
308
+ datatree_module: _DataTreeModule = _load_datatree_module()
309
+ tables: list[_TabularXarrayTable | None] = []
310
+ record: BatchExportRecord
311
+ for record in records:
312
+ if not isinstance(record.payload, Eigenvalues):
313
+ tables.append(None)
314
+ continue
315
+ table: _TabularXarrayTable = tabular_payload_to_xarray_table(
316
+ record.payload.table,
317
+ payload_name="Eigenvalue payload",
318
+ )
319
+ tables.append(table)
320
+
321
+ if not any(table is not None for table in tables):
322
+ raise InvalidConfigurationError(
323
+ "No successful batch entries with eigenvalue payloads are available for to_xarray()."
324
+ )
325
+
326
+ dataset: XarrayDataset = _stack_batch_tabular_tables(
327
+ records,
328
+ tables,
329
+ xarray_module=xarray_module,
330
+ batch_axis_name="batch_index",
331
+ )
332
+ return _create_data_tree(datatree_module=datatree_module, dataset=dataset)
333
+
334
+
335
+ def _postprocess_mapping_to_data_tree(
336
+ payload: Mapping[object, object],
337
+ *,
338
+ postprocess_title: str | None,
339
+ source_file: object,
340
+ xarray_module: _XarrayModule,
341
+ datatree_module: _DataTreeModule,
342
+ node_name: str | None = None,
343
+ ) -> XarrayDataTree:
344
+ """Convert one structured mapping payload into a `DataTree`."""
345
+
346
+ payload_parts: _StructuredPayloadParts = _split_structured_payload(payload)
347
+ root_dataset: XarrayDataset = _current_postprocess_level_to_dataset(
348
+ payload_parts,
349
+ postprocess_title=postprocess_title,
350
+ source_file=source_file,
351
+ xarray_module=xarray_module,
352
+ )
353
+ children: dict[str, XarrayDataTree] = {}
354
+ child_name: str
355
+ child_payload: Mapping[object, object]
356
+ for child_name, child_payload in payload_parts.nested_fields.items():
357
+ children[child_name] = _postprocess_mapping_to_data_tree(
358
+ child_payload,
359
+ postprocess_title=postprocess_title,
360
+ source_file=source_file,
361
+ xarray_module=xarray_module,
362
+ datatree_module=datatree_module,
363
+ node_name=child_name,
364
+ )
365
+ return _create_data_tree(
366
+ datatree_module=datatree_module,
367
+ dataset=root_dataset,
368
+ children=children,
369
+ name=node_name,
370
+ )
371
+
372
+
373
+ def _stack_batch_header_payloads(
374
+ entries: Sequence[_BatchIndexedKeys],
375
+ payloads: Sequence[Mapping[object, object] | None],
376
+ *,
377
+ xarray_module: _XarrayModule,
378
+ ) -> XarrayDataset:
379
+ """Stack selected header payloads across a batch `index` axis."""
380
+
381
+ flattened_payloads: list[dict[str, object]] = []
382
+ payload: Mapping[object, object] | None
383
+ for payload in payloads:
384
+ flattened_fields: dict[str, object] = {}
385
+ if payload is not None:
386
+ _flatten_header_fields(
387
+ payload,
388
+ flattened_fields=flattened_fields,
389
+ field_prefix="",
390
+ )
391
+ flattened_payloads.append(flattened_fields)
392
+
393
+ data_vars: dict[str, object] = {}
394
+ coords: dict[str, object] = {"index": [entry.index for entry in entries]}
395
+ attrs: dict[str, object] = {}
396
+ if entries:
397
+ _append_batch_key_coords(
398
+ coords=coords,
399
+ attrs=attrs,
400
+ keys_by_entry=[entry.keys for entry in entries],
401
+ key_names=sorted(entries[0].keys),
402
+ )
403
+
404
+ all_field_names: set[str] = set()
405
+ flattened_payload: dict[str, object]
406
+ for flattened_payload in flattened_payloads:
407
+ all_field_names.update(flattened_payload)
408
+
409
+ field_name: str
410
+ for field_name in sorted(all_field_names):
411
+ values: list[object | None] = [
412
+ flattened_fields.get(field_name) for flattened_fields in flattened_payloads
413
+ ]
414
+ present_values: list[object] = [value for value in values if value is not None]
415
+ if not present_values:
416
+ continue
417
+ if all(isinstance(value, str) for value in present_values):
418
+ first_value: str = cast(str, present_values[0])
419
+ if all(cast(str, value) == first_value for value in present_values[1:]):
420
+ attrs[field_name] = first_value
421
+ continue
422
+ _append_stacked_header_data_variable(
423
+ data_vars=data_vars,
424
+ coords=coords,
425
+ field_name=field_name,
426
+ values=values,
427
+ )
428
+
429
+ return xarray_module.Dataset(
430
+ data_vars=data_vars,
431
+ coords=coords or None,
432
+ attrs=attrs or None,
433
+ )
434
+
435
+
436
+ def _stack_batch_postprocess_payloads_to_data_tree(
437
+ entries: Sequence[_BatchIndexedKeys],
438
+ payloads: Sequence[Mapping[object, object]],
439
+ *,
440
+ index: int | None,
441
+ title: str | None,
442
+ xarray_module: _XarrayModule,
443
+ datatree_module: _DataTreeModule,
444
+ node_name: str | None = None,
445
+ batch_axis_name: str = "index",
446
+ available: Sequence[bool] | None = None,
447
+ ) -> XarrayDataTree:
448
+ """Convert structured batch-selected payloads into a stacked `DataTree`."""
449
+
450
+ payload_parts_list: list[_StructuredPayloadParts] = [
451
+ _split_structured_payload(payload) for payload in payloads
452
+ ]
453
+ root_dataset: XarrayDataset = _stack_batch_postprocess_level_to_dataset(
454
+ entries,
455
+ payload_parts_list,
456
+ index=index,
457
+ title=title,
458
+ xarray_module=xarray_module,
459
+ batch_axis_name=batch_axis_name,
460
+ available=available,
461
+ )
462
+ common_child_names: tuple[str, ...] = _common_ordered_child_names(
463
+ payload_parts_list
464
+ )
465
+ children: dict[str, XarrayDataTree] = {}
466
+ child_name: str
467
+ for child_name in common_child_names:
468
+ child_payloads: list[Mapping[object, object]] = [
469
+ payload_parts.nested_fields[child_name]
470
+ for payload_parts in payload_parts_list
471
+ ]
472
+ children[child_name] = _stack_batch_postprocess_payloads_to_data_tree(
473
+ entries,
474
+ child_payloads,
475
+ index=index,
476
+ title=title,
477
+ xarray_module=xarray_module,
478
+ datatree_module=datatree_module,
479
+ node_name=child_name,
480
+ batch_axis_name=batch_axis_name,
481
+ available=available,
482
+ )
483
+ return _create_data_tree(
484
+ datatree_module=datatree_module,
485
+ dataset=root_dataset,
486
+ children=children,
487
+ name=node_name,
488
+ )
489
+
490
+
491
+ def _current_postprocess_level_to_dataset(
492
+ payload_parts: _StructuredPayloadParts,
493
+ *,
494
+ postprocess_title: str | None,
495
+ source_file: object,
496
+ xarray_module: _XarrayModule,
497
+ ) -> XarrayDataset:
498
+ """Build one dataset for the current postprocess tree node."""
499
+
500
+ if payload_parts.grouped_fields:
501
+ tensor: _GroupedPostprocessTensor = postprocess_payload_to_grouped_tensor(
502
+ payload_parts,
503
+ postprocess_title=postprocess_title,
504
+ source_file=source_file,
505
+ )
506
+ return grouped_tensor_to_xarray_dataset(tensor, xarray_module=xarray_module)
507
+
508
+ if payload_parts.companion_fields:
509
+ table: _TabularXarrayTable = tabular_payload_to_xarray_table(
510
+ payload_parts.companion_fields,
511
+ payload_name="Postprocess payload",
512
+ )
513
+ table_attrs: dict[str, object] = dict(table.attrs)
514
+ table_attrs["postprocess_title"] = postprocess_title
515
+ table_attrs["source_file"] = None if source_file is None else str(source_file)
516
+ return tabular_table_to_xarray_dataset(
517
+ _TabularXarrayTable(
518
+ row_count=table.row_count,
519
+ column_names=table.column_names,
520
+ column_arrays=table.column_arrays,
521
+ column_dims=table.column_dims,
522
+ attrs=table_attrs,
523
+ ),
524
+ xarray_module=xarray_module,
525
+ )
526
+
527
+ return xarray_module.Dataset(
528
+ data_vars={},
529
+ coords={},
530
+ attrs={
531
+ "postprocess_title": postprocess_title,
532
+ "source_file": None if source_file is None else str(source_file),
533
+ },
534
+ )
535
+
536
+
537
+ def _stack_batch_postprocess_level_to_dataset(
538
+ entries: Sequence[_BatchIndexedKeys],
539
+ payload_parts_list: Sequence[_StructuredPayloadParts],
540
+ *,
541
+ index: int | None,
542
+ title: str | None,
543
+ xarray_module: _XarrayModule,
544
+ batch_axis_name: str = "index",
545
+ available: Sequence[bool] | None = None,
546
+ ) -> XarrayDataset:
547
+ """Build one stacked dataset for the current batch postprocess tree node."""
548
+
549
+ first_parts: _StructuredPayloadParts = payload_parts_list[0]
550
+ inferred_postprocess_title: str | None = title
551
+ if inferred_postprocess_title is None:
552
+ raw_title: object | None = first_parts.companion_fields.get("title")
553
+ if isinstance(raw_title, str):
554
+ inferred_postprocess_title = raw_title
555
+ if any(
556
+ tuple(parts.grouped_fields.keys()) != tuple(first_parts.grouped_fields.keys())
557
+ or tuple(parts.companion_fields.keys())
558
+ != tuple(first_parts.companion_fields.keys())
559
+ for parts in payload_parts_list[1:]
560
+ ):
561
+ raise InvalidConfigurationError(
562
+ "Selected batch postprocess stream mixes incompatible structured payload node shapes and cannot be stacked via to_xarray()."
563
+ )
564
+
565
+ if first_parts.grouped_fields:
566
+ tensors: list[_GroupedPostprocessTensor] = [
567
+ postprocess_payload_to_grouped_tensor(
568
+ parts,
569
+ postprocess_title=inferred_postprocess_title,
570
+ source_file=None,
571
+ )
572
+ for parts in payload_parts_list
573
+ ]
574
+ return _stack_batch_grouped_tensors(
575
+ entries,
576
+ tensors,
577
+ index=index,
578
+ title=title,
579
+ xarray_module=xarray_module,
580
+ batch_axis_name=batch_axis_name,
581
+ available=available,
582
+ )
583
+
584
+ if first_parts.companion_fields:
585
+ tables: list[_TabularXarrayTable] = [
586
+ tabular_payload_to_xarray_table(
587
+ parts.companion_fields,
588
+ payload_name="Postprocess payload",
589
+ )
590
+ for parts in payload_parts_list
591
+ ]
592
+ return _stack_batch_tabular_tables(
593
+ entries,
594
+ tables,
595
+ xarray_module=xarray_module,
596
+ batch_axis_name=batch_axis_name,
597
+ valid_entries=available,
598
+ )
599
+
600
+ coords: dict[str, object] = {batch_axis_name: [entry.index for entry in entries]}
601
+ attrs: dict[str, object] = {}
602
+ common_key_names: set[str] = set(entries[0].keys)
603
+ entry: _BatchIndexedKeys
604
+ for entry in entries[1:]:
605
+ common_key_names &= set(entry.keys)
606
+ _append_batch_key_coords(
607
+ coords=coords,
608
+ attrs=attrs,
609
+ keys_by_entry=[entry.keys for entry in entries],
610
+ key_names=sorted(common_key_names),
611
+ )
612
+ data_vars: dict[str, object] = {}
613
+ if available is not None:
614
+ data_vars["is_valid"] = (
615
+ (batch_axis_name,),
616
+ np.asarray(available, dtype=bool),
617
+ )
618
+ return xarray_module.Dataset(
619
+ data_vars=data_vars, coords=coords, attrs=attrs or None
620
+ )
621
+
622
+
623
+ def _append_batch_key_coords(
624
+ *,
625
+ coords: dict[str, object],
626
+ attrs: dict[str, object],
627
+ keys_by_entry: Sequence[Mapping[str, object]],
628
+ key_names: Sequence[str],
629
+ ) -> None:
630
+ """Append supported batch key coords and note keys that were skipped."""
631
+
632
+ dropped_key_names: list[str] = []
633
+ key_name: str
634
+ for key_name in key_names:
635
+ coord_variable: tuple[tuple[str, ...], np.ndarray] | None = (
636
+ _build_batch_coord_variable(
637
+ key_name,
638
+ [entry_keys.get(key_name) for entry_keys in keys_by_entry],
639
+ )
640
+ )
641
+ if coord_variable is None:
642
+ dropped_key_names.append(key_name)
643
+ continue
644
+ coord_dims: tuple[str, ...]
645
+ coord_array: np.ndarray
646
+ coord_dims, coord_array = coord_variable
647
+ coords[key_name] = (coord_dims, coord_array)
648
+ if len(coord_dims) > 1:
649
+ _ensure_generated_companion_dim_coords(
650
+ coords,
651
+ coord_dims=coord_dims,
652
+ coord_array=coord_array,
653
+ )
654
+ if dropped_key_names:
655
+ attrs["dropped_batch_key_coords"] = tuple(dropped_key_names)
656
+
657
+
658
+ def _select_batch_postprocess_record(
659
+ entry: "BatchExportRecord",
660
+ *,
661
+ index: int,
662
+ ) -> "PostprocessRecord":
663
+ """Select one postprocess record from one successful batch entry."""
664
+
665
+ if not isinstance(entry.payload, PostprocessCollection):
666
+ raise InvalidConfigurationError(
667
+ f"Batch entry {entry.index} has no solve result for xarray export."
668
+ )
669
+ if index < 0 or index >= len(entry.payload):
670
+ raise InvalidConfigurationError(
671
+ f"Selected postprocess index {index!r} is missing for batch entry {entry.index}."
672
+ )
673
+ record: PostprocessRecord | None = entry.payload[index]
674
+ if record is None:
675
+ raise InvalidConfigurationError(
676
+ f"Selected postprocess index {index!r} is unavailable for batch entry {entry.index}."
677
+ )
678
+ return record
679
+
680
+
681
+ def _record_xarray_payload(record: "PostprocessRecord") -> object:
682
+ """Return the exact payload object used for record-level xarray export."""
683
+
684
+ try:
685
+ payload_object: object = record.to_dict()
686
+ except UnsupportedExportError:
687
+ payload_object = record._raw
688
+ return payload_object