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,1081 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Batch solve result models and view helpers."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from abc import ABC
9
+ from collections.abc import Iterator, Mapping
10
+ from dataclasses import dataclass, field
11
+ from pathlib import Path
12
+ from typing import TYPE_CHECKING, Callable, Literal, Self, cast, overload
13
+
14
+ from ....exceptions import UnsupportedExportError
15
+ from ...artifacts import (
16
+ ComputationalCosts,
17
+ Eigenvalues,
18
+ )
19
+ from ...field_exports import FieldExportView
20
+ from ...payloads import (
21
+ DataFrameLongExportMixin,
22
+ DictionaryExportMixin,
23
+ Source,
24
+ TablePayload,
25
+ XarrayExportMixin,
26
+ )
27
+ from ..export.pandas.payload import payload_to_tabular_rows, value_mapping
28
+ from ..export.xarray.types import XarrayDataTree
29
+ from .core import SolveExecutionLog, SolveResult
30
+
31
+ if TYPE_CHECKING:
32
+ import pandas as pd # pyright: ignore[reportMissingImports]
33
+
34
+ from .batch_postprocess import BatchPostprocessCollection
35
+
36
+
37
+ @dataclass(slots=True, frozen=True)
38
+ class BatchSolveFailure:
39
+ """Describe one failed entry in a `BatchSolveResult`.
40
+
41
+ Parameters
42
+ ----------
43
+ index : int
44
+ Position in the batched project keys.
45
+ keys : dict[str, object]
46
+ project keys for the failed entry.
47
+ exception_type : type[Exception]
48
+ Exception class raised while processing the item.
49
+ message : str
50
+ Message from the exception.
51
+ """
52
+
53
+ index: int
54
+ keys: dict[str, object]
55
+ exception_type: type[Exception]
56
+ message: str
57
+
58
+
59
+ @dataclass(slots=True, frozen=True)
60
+ class BatchSolveEntry:
61
+ """Store one ordered entry in a `BatchSolveResult`.
62
+
63
+ Parameters
64
+ ----------
65
+ index : int
66
+ Position in the batched project keys.
67
+ keys : dict[str, object]
68
+ project keys used for this solve entry.
69
+ result : SolveResult | None
70
+ Solve result if this entry succeeded.
71
+ failure : BatchSolveFailure | None
72
+ Failure information if this entry did not succeed and `on_error` was
73
+ `"collect"`.
74
+ _log : SolveExecutionLog | None, optional
75
+ Stored execution log for a failed entry. Application code usually
76
+ reads the public `log` property instead of setting this value.
77
+ """
78
+
79
+ index: int
80
+ """Position in the batched project keys."""
81
+ keys: dict[str, object]
82
+ """Project keys used for this solve entry."""
83
+ result: SolveResult | None
84
+ """Solve result if this entry succeeded."""
85
+ failure: BatchSolveFailure | None
86
+ """Failure information if this entry did not succeed."""
87
+ _log: SolveExecutionLog | None = field(default=None, repr=False)
88
+
89
+ @property
90
+ def log(self) -> SolveExecutionLog | None:
91
+ """Return the execution log for this batch entry.
92
+
93
+ Returns
94
+ -------
95
+ SolveExecutionLog | None
96
+ Log from `result.log` for a successful entry, or the stored failure
97
+ log. Returns `None` if no log is available.
98
+ """
99
+
100
+ if self.result is not None and self.result.log is not None:
101
+ return self.result.log
102
+ return self._log
103
+
104
+
105
+ @dataclass(slots=True, frozen=True)
106
+ class BatchExportRecord:
107
+ """Aligned batch record used by metadata and result-data export views."""
108
+
109
+ index: int
110
+ keys: dict[str, object]
111
+ payload: object | None = None
112
+ source: Source = None
113
+
114
+
115
+ class BatchExportablePayload(ABC):
116
+ """Independent base for aligned batch payload provenance."""
117
+
118
+ _sources: tuple[Source, ...]
119
+
120
+ def __init__(self, sources: tuple[Source, ...]) -> None:
121
+ object.__setattr__(self, "_sources", tuple(sources))
122
+
123
+ @property
124
+ def sources(self) -> tuple[Source, ...]:
125
+ """Return one source file for each batch entry.
126
+
127
+ An unavailable source file is `None`. The order matches the current
128
+ batch entries.
129
+
130
+ Returns
131
+ -------
132
+ tuple[Path | None, ...]
133
+ Source files in batched project keys order.
134
+ """
135
+
136
+ return self._sources
137
+
138
+
139
+ class BatchMetadataPayload(
140
+ BatchExportablePayload,
141
+ DictionaryExportMixin,
142
+ DataFrameLongExportMixin,
143
+ XarrayExportMixin,
144
+ ABC,
145
+ ):
146
+ """Store and export named information for a batch."""
147
+
148
+ def __init__(self, records: tuple[BatchExportRecord, ...]) -> None:
149
+ super().__init__(tuple(record.source for record in records))
150
+ self._records: tuple[BatchExportRecord, ...] = records
151
+
152
+ @property
153
+ def records(self) -> tuple[BatchExportRecord, ...]:
154
+ """Return aligned metadata records."""
155
+
156
+ return self._records
157
+
158
+ def to_dict(self) -> Mapping[object, object]:
159
+ """Return one information dictionary for each original batch position.
160
+
161
+ Returns
162
+ -------
163
+ Mapping[object, object]
164
+ Information dictionaries indexed by original batch position.
165
+ """
166
+
167
+ return {record.index: dict(record.keys) for record in self.records}
168
+
169
+ def _to_df_long(self) -> "pd.DataFrame":
170
+ """Return one DataFrame row for each named value in each batch entry.
171
+
172
+ The `batch_index` column contains the original batch position.
173
+
174
+ Returns
175
+ -------
176
+ pandas.DataFrame
177
+ Long-form table of the batch information.
178
+ """
179
+
180
+ from ...pandas_export import batch_keys_to_df_long
181
+
182
+ return batch_keys_to_df_long(self.records)
183
+
184
+ def to_df(self, orient: str | None = None) -> "pd.DataFrame":
185
+ """Return batch table data as a long-form pandas `DataFrame`.
186
+
187
+ Parameters
188
+ ----------
189
+ orient : {None, "long"}, optional
190
+ Select the table layout. Batch table data does not support the wide
191
+ layout.
192
+
193
+ Returns
194
+ -------
195
+ pandas.DataFrame
196
+ Batch metadata in long form.
197
+
198
+ Raises
199
+ ------
200
+ UnsupportedExportError
201
+ If `orient` is `"wide"`.
202
+ ValueError
203
+ If `orient` is not `None` or `"long"`.
204
+ """
205
+
206
+ if orient is None or orient == "long":
207
+ return self._to_df_long()
208
+ if orient == "wide":
209
+ raise UnsupportedExportError(
210
+ "to_df is not supported for wide batch metadata."
211
+ )
212
+ raise ValueError("orient must be None, 'wide', or 'long'")
213
+
214
+ def to_xarray(self) -> XarrayDataTree:
215
+ """Return the information as an xarray `DataTree`.
216
+
217
+ The `batch_index` coordinate contains the original batch positions.
218
+
219
+ Returns
220
+ -------
221
+ xarray.DataTree
222
+ Batch information in the root node.
223
+ """
224
+
225
+ from ..export.xarray.export import batch_keys_to_xarray_dataset
226
+
227
+ return batch_keys_to_xarray_dataset(self.records)
228
+
229
+ def _preview(self) -> str:
230
+ """Return a bounded long-form preview of aligned metadata."""
231
+
232
+ from ..export.preview import format_table_preview
233
+
234
+ rows: list[dict[str, object]] = []
235
+ record: BatchExportRecord
236
+ for record in self.records:
237
+ if not record.keys:
238
+ rows.append({"batch_index": record.index, "name": None, "value": None})
239
+ continue
240
+ for name, value in record.keys.items():
241
+ rows.append({"batch_index": record.index, "name": name, "value": value})
242
+ columns: dict[object, object] = {
243
+ name: [row[name] for row in rows]
244
+ for name in ("batch_index", "name", "value")
245
+ }
246
+ return format_table_preview(columns, compact_values=False)
247
+
248
+ def __repr__(self) -> str:
249
+ """Return the payload class name with its bounded metadata preview."""
250
+
251
+ return f"{type(self).__name__}(\n preview=\n{self._preview()}\n)"
252
+
253
+
254
+ class BatchSolveKeys(BatchMetadataPayload):
255
+ """Store and export batched project keys with their original positions."""
256
+
257
+ def _preview(self) -> str:
258
+ """Return a bounded table preview of the batch project keys."""
259
+
260
+ from ..export.preview import format_table_preview
261
+
262
+ key_names: list[str] = []
263
+ for record in self.records:
264
+ for key_name in record.keys:
265
+ if key_name not in key_names:
266
+ key_names.append(key_name)
267
+ columns: dict[object, object] = {
268
+ "batch_index": [record.index for record in self.records]
269
+ }
270
+ for key_name in key_names:
271
+ columns[key_name] = [record.keys.get(key_name) for record in self.records]
272
+ return format_table_preview(
273
+ columns,
274
+ compact_values=False,
275
+ )
276
+
277
+ def __repr__(self) -> str:
278
+ """Return the payload class name with its bounded data preview."""
279
+
280
+ return f"BatchSolveKeys(\n preview=\n{self._preview()}\n)"
281
+
282
+
283
+ class BatchTablePayload(
284
+ BatchExportablePayload,
285
+ DictionaryExportMixin,
286
+ DataFrameLongExportMixin,
287
+ XarrayExportMixin,
288
+ ABC,
289
+ ):
290
+ """Base capability family for batch table payloads."""
291
+
292
+ records: tuple[BatchExportRecord, ...]
293
+
294
+ def to_df(self, orient: str | None = None) -> "pd.DataFrame":
295
+ """Return batch table data as a long-form pandas `DataFrame`.
296
+
297
+ Parameters
298
+ ----------
299
+ orient : {None, "long"}, optional
300
+ Select the table layout. Batch table data does not support the wide
301
+ layout.
302
+
303
+ Returns
304
+ -------
305
+ pandas.DataFrame
306
+ Batch table data in long form.
307
+
308
+ Raises
309
+ ------
310
+ UnsupportedExportError
311
+ If `orient` is `"wide"`.
312
+ ValueError
313
+ If `orient` is not `None` or `"long"`.
314
+ """
315
+
316
+ if orient is None or orient == "long":
317
+ return self._to_df_long()
318
+ if orient == "wide":
319
+ raise UnsupportedExportError(
320
+ "to_df is not supported for wide batch tables."
321
+ )
322
+ raise ValueError("orient must be None, 'wide', or 'long'")
323
+
324
+ def _preview(self) -> str:
325
+ """Return a bounded preview for the aligned batch tables."""
326
+
327
+ from ..export.preview import format_table_preview
328
+
329
+ records: tuple[BatchExportRecord, ...] = self.records
330
+ rows: list[dict[str, object]] = []
331
+ record: BatchExportRecord
332
+ for record in records:
333
+ if not isinstance(record.payload, TablePayload):
334
+ rows.append({"batch_index": record.index, "row_index": None})
335
+ continue
336
+ payload_rows: list[dict[str, object]] | None = payload_to_tabular_rows(
337
+ value_mapping(record.payload.to_dict())
338
+ )
339
+ if payload_rows is None:
340
+ rows.append({"batch_index": record.index, "row_index": None})
341
+ continue
342
+ for row_index, payload_row in enumerate(payload_rows):
343
+ row: dict[str, object] = {
344
+ "batch_index": record.index,
345
+ "row_index": row_index,
346
+ }
347
+ row.update(payload_row)
348
+ rows.append(row)
349
+
350
+ column_names: list[str] = []
351
+ for row in rows:
352
+ for column_name in row:
353
+ if column_name not in column_names:
354
+ column_names.append(column_name)
355
+ columns: dict[object, object] = {
356
+ column_name: [row.get(column_name) for row in rows]
357
+ for column_name in column_names
358
+ }
359
+ return format_table_preview(columns)
360
+
361
+ def __repr__(self) -> str:
362
+ """Return the payload class name with its bounded table preview."""
363
+
364
+ return f"{type(self).__name__}(\n preview=\n{self._preview()}\n)"
365
+
366
+
367
+ class BatchStructuredPayload(
368
+ BatchExportablePayload,
369
+ DictionaryExportMixin,
370
+ DataFrameLongExportMixin,
371
+ XarrayExportMixin,
372
+ ABC,
373
+ ):
374
+ """Base capability family for batch structured payloads."""
375
+
376
+ def to_df(self, orient: str | None = None) -> "pd.DataFrame":
377
+ """Return batch structured data as path/value rows.
378
+
379
+ Parameters
380
+ ----------
381
+ orient : str | None, optional
382
+ DataFrame orientation. Use `None` or `"long"`; `"wide"` is not
383
+ supported for batch structured data.
384
+
385
+ Returns
386
+ -------
387
+ pandas.DataFrame
388
+ Batch structured data in path/value rows.
389
+ """
390
+
391
+ if orient is None or orient == "long":
392
+ return self._to_df_long()
393
+ if orient == "wide":
394
+ raise UnsupportedExportError(
395
+ "to_df is not supported for wide batch structured payloads."
396
+ )
397
+ raise ValueError("orient must be None, 'wide', or 'long'")
398
+
399
+
400
+ class BatchTableCollectionPayload(
401
+ BatchExportablePayload,
402
+ DictionaryExportMixin,
403
+ DataFrameLongExportMixin,
404
+ XarrayExportMixin,
405
+ ABC,
406
+ ):
407
+ """Base capability family for batch collections of named tables."""
408
+
409
+ def to_df(self, orient: str | None = None) -> "pd.DataFrame":
410
+ """Return batch table collections as path/value rows.
411
+
412
+ Parameters
413
+ ----------
414
+ orient : str | None, optional
415
+ DataFrame orientation. Use `None` or `"long"`; `"wide"` is not
416
+ supported for batch table collections.
417
+
418
+ Returns
419
+ -------
420
+ pandas.DataFrame
421
+ Batch table collections in path/value rows.
422
+ """
423
+
424
+ if orient is None or orient == "long":
425
+ return self._to_df_long()
426
+ if orient == "wide":
427
+ raise UnsupportedExportError(
428
+ "to_df is not supported for wide batch table collections."
429
+ )
430
+ raise ValueError("orient must be None, 'wide', or 'long'")
431
+
432
+
433
+ class BatchFieldPayloadBase(
434
+ BatchExportablePayload,
435
+ DictionaryExportMixin,
436
+ XarrayExportMixin,
437
+ ABC,
438
+ ):
439
+ """Base capability family for non-tabular batch field payloads."""
440
+
441
+ records: tuple[BatchExportRecord, ...]
442
+
443
+ @property
444
+ def base(self) -> Self:
445
+ """Return only the base fields from available batch entries.
446
+
447
+ Returns
448
+ -------
449
+ BatchFieldExportPayload
450
+ New batch field selection that excludes derivatives.
451
+ """
452
+
453
+ return self._project_fields(lambda field: field.base)
454
+
455
+ @property
456
+ def derivatives(self) -> Self:
457
+ """Return all field derivatives from available batch entries.
458
+
459
+ Returns
460
+ -------
461
+ BatchFieldExportPayload
462
+ New batch selection that contains available derivatives.
463
+ """
464
+
465
+ return self._project_fields(lambda field: field.derivatives)
466
+
467
+ def keys(self) -> tuple[str, ...]:
468
+ """Return the available derivative names in source-file order.
469
+
470
+ Returns
471
+ -------
472
+ tuple[str, ...]
473
+ Derivative names from the first available batch entry.
474
+ """
475
+
476
+ for record in self.records:
477
+ if isinstance(record.payload, FieldExportView):
478
+ return record.payload.keys()
479
+ return ()
480
+
481
+ def __getitem__(self, name: str) -> Self:
482
+ """Select one derivative by name from all available batch entries.
483
+
484
+ Parameters
485
+ ----------
486
+ name : str
487
+ Derivative name.
488
+
489
+ Returns
490
+ -------
491
+ BatchFieldExportPayload
492
+ New batch field selection for the derivative.
493
+
494
+ Raises
495
+ ------
496
+ TypeError
497
+ If `name` is not a string.
498
+ KeyError
499
+ If the derivative is not available.
500
+ """
501
+
502
+ if not isinstance(name, str):
503
+ raise TypeError("Derivative names must be strings.")
504
+ if name not in self.keys():
505
+ raise KeyError(name)
506
+ return self._project_fields(lambda field: field[name])
507
+
508
+ @property
509
+ def indices(self) -> tuple[int, ...]:
510
+ """Return the positions of the selected fields in source-file order.
511
+
512
+ Returns
513
+ -------
514
+ tuple[int, ...]
515
+ Selected field positions from the first available batch entry.
516
+ """
517
+
518
+ for record in self.records:
519
+ if isinstance(record.payload, FieldExportView):
520
+ return record.payload.indices
521
+ return ()
522
+
523
+ def select(self, index: int | None = None) -> Self:
524
+ """Select one field position from all available batch entries.
525
+
526
+ If `index` is `None`, select all field positions.
527
+
528
+ Parameters
529
+ ----------
530
+ index : int | None, optional
531
+ Field position. `None` selects all fields.
532
+
533
+ Returns
534
+ -------
535
+ BatchFieldExportPayload
536
+ New batch field selection.
537
+
538
+ Raises
539
+ ------
540
+ IndexError
541
+ If the field position is not available.
542
+ """
543
+
544
+ return self._project_fields(lambda field: field.select(index))
545
+
546
+ def _project_fields(
547
+ self, projection: Callable[[FieldExportView], FieldExportView]
548
+ ) -> Self:
549
+ """Apply one field projection while retaining batch record alignment."""
550
+
551
+ raise NotImplementedError
552
+
553
+ def _preview(self) -> str:
554
+ """Return batch availability and field-navigation state."""
555
+
556
+ available_records: tuple[BatchExportRecord, ...] = tuple(
557
+ record
558
+ for record in self.records
559
+ if isinstance(record.payload, FieldExportView)
560
+ )
561
+ available_indices: tuple[int, ...] = tuple(
562
+ record.index for record in available_records
563
+ )
564
+ lines: list[str] = [
565
+ f" entries: {len(self.records)}",
566
+ f" available: {len(available_records)}",
567
+ f" missing: {len(self.records) - len(available_records)}",
568
+ f" batch_indices: {available_indices}",
569
+ ]
570
+ if available_records:
571
+ field_preview: str = cast(
572
+ FieldExportView, available_records[0].payload
573
+ )._preview()
574
+ lines.extend(field_preview.splitlines())
575
+ return "\n".join(lines)
576
+
577
+ def __repr__(self) -> str:
578
+ """Return field navigation state without numerical field values."""
579
+
580
+ return f"{type(self).__name__}(\n{self._preview()}\n)"
581
+
582
+
583
+ def _batch_export_records(
584
+ entries: tuple[BatchSolveEntry, ...],
585
+ ) -> tuple[BatchExportRecord, ...]:
586
+ """Copy batch indices and keys while selecting no result-data payload."""
587
+
588
+ return tuple(
589
+ BatchExportRecord(
590
+ index=entry.index,
591
+ keys=dict(entry.keys),
592
+ source=(None if entry.result is None else entry.result.project_file),
593
+ )
594
+ for entry in entries
595
+ )
596
+
597
+
598
+ def _batch_artifact_records(
599
+ entries: tuple[BatchSolveEntry, ...],
600
+ artifact: Literal["costs", "eigenvalues"],
601
+ ) -> tuple[BatchExportRecord, ...]:
602
+ """Copy batch metadata and one selected result-data payload."""
603
+
604
+ records: list[BatchExportRecord] = []
605
+ entry: BatchSolveEntry
606
+ for entry in entries:
607
+ payload: TablePayload | None = None
608
+ if entry.result is not None:
609
+ payload_object: object = getattr(entry.result, artifact)
610
+ if isinstance(payload_object, TablePayload):
611
+ payload = payload_object
612
+ records.append(
613
+ BatchExportRecord(
614
+ index=entry.index,
615
+ keys=dict(entry.keys),
616
+ payload=payload,
617
+ source=(
618
+ None
619
+ if entry.result is None
620
+ else (
621
+ entry.result.project_file
622
+ if payload is None or payload.source is None
623
+ else payload.source
624
+ )
625
+ ),
626
+ )
627
+ )
628
+ return tuple(records)
629
+
630
+
631
+ def _batch_postprocess_records(
632
+ entries: tuple[BatchSolveEntry, ...],
633
+ ) -> tuple[BatchExportRecord, ...]:
634
+ """Copy batch metadata and each successful postprocess collection."""
635
+
636
+ return tuple(
637
+ BatchExportRecord(
638
+ index=entry.index,
639
+ keys=dict(entry.keys),
640
+ payload=(None if entry.result is None else entry.result.postprocesses),
641
+ source=_postprocess_source(entry.result),
642
+ )
643
+ for entry in entries
644
+ )
645
+
646
+
647
+ def _postprocess_source(result: SolveResult | None) -> Source:
648
+ """Return the source marker from the first available postprocess record."""
649
+
650
+ if result is None:
651
+ return None
652
+ records = result.postprocesses
653
+ if len(records) == 0:
654
+ return result.project_file
655
+ return records[0].source_file
656
+
657
+
658
+ @dataclass(slots=True)
659
+ class BatchSolveResult:
660
+ """Provide ordered results for batched project keys.
661
+
662
+ Parameters
663
+ ----------
664
+ entries : tuple[BatchSolveEntry, ...]
665
+ Results in batched project keys order.
666
+
667
+ Notes
668
+ -----
669
+ `result[index]` returns one `BatchSolveEntry`. `result[start:stop]` returns
670
+ a new `BatchSolveResult`. Iteration yields entries in batched project keys
671
+ order.
672
+ """
673
+
674
+ entries: tuple[BatchSolveEntry, ...]
675
+
676
+ @property
677
+ def project_file(self) -> Path | None:
678
+ """Return the first available project file.
679
+
680
+ Returns
681
+ -------
682
+ pathlib.Path | None
683
+ project file from the first successful entry, or `None` if the
684
+ batch contains no successful result.
685
+ """
686
+
687
+ entry: BatchSolveEntry
688
+ for entry in self.entries:
689
+ if entry.result is not None and entry.result.project_file is not None:
690
+ return entry.result.project_file
691
+ return None
692
+
693
+ def __len__(self) -> int:
694
+ """Return the number of batch entries.
695
+
696
+ Returns
697
+ -------
698
+ int
699
+ Number of entries.
700
+ """
701
+
702
+ return len(self.entries)
703
+
704
+ def __iter__(self) -> Iterator[BatchSolveEntry]:
705
+ """Iterate over entries in batched project keys order.
706
+
707
+ Returns
708
+ -------
709
+ Iterator[BatchSolveEntry]
710
+ Iterator over the batch entries.
711
+ """
712
+
713
+ return iter(self.entries)
714
+
715
+ @overload
716
+ def __getitem__(self, index: int) -> BatchSolveEntry: ...
717
+
718
+ @overload
719
+ def __getitem__(self, index: slice) -> BatchSolveResult: ...
720
+
721
+ def __getitem__(
722
+ self,
723
+ index: int | slice,
724
+ ) -> BatchSolveEntry | BatchSolveResult:
725
+ """Return one entry or a new batch selected by a slice.
726
+
727
+ Parameters
728
+ ----------
729
+ index : int | slice
730
+ Entry position or standard Python slice. Negative positions count
731
+ from the end of the batch.
732
+
733
+ Returns
734
+ -------
735
+ BatchSolveEntry | BatchSolveResult
736
+ One entry for an integer position, or a new batch for a slice.
737
+
738
+ Raises
739
+ ------
740
+ TypeError
741
+ If `index` is not an integer or slice.
742
+ IndexError
743
+ If an integer position is outside the batch.
744
+ """
745
+
746
+ if isinstance(index, slice):
747
+ return BatchSolveResult(entries=self.entries[index])
748
+ if isinstance(index, bool) or not isinstance(index, int):
749
+ raise TypeError("BatchSolveResult indexing requires an integer or slice.")
750
+ return self.entries[index]
751
+
752
+ @property
753
+ def success_indices(self) -> tuple[int, ...]:
754
+ """Return the original positions of successful batch entries.
755
+
756
+ Returns
757
+ -------
758
+ tuple[int, ...]
759
+ Original batch positions in input order.
760
+ """
761
+
762
+ return tuple(entry.index for entry in self.entries if entry.result is not None)
763
+
764
+ @property
765
+ def failure_indices(self) -> tuple[int, ...]:
766
+ """Return the original positions of failed batch entries.
767
+
768
+ Returns
769
+ -------
770
+ tuple[int, ...]
771
+ Original batch positions in input order.
772
+ """
773
+
774
+ return tuple(entry.index for entry in self.entries if entry.result is None)
775
+
776
+ @property
777
+ def costs(self) -> BatchComputationalCosts:
778
+ """Return computational-cost data for all batch entries.
779
+
780
+ Returns
781
+ -------
782
+ BatchComputationalCosts
783
+ Computational-cost data in batched project keys order.
784
+ """
785
+
786
+ return BatchComputationalCosts(
787
+ records=_batch_artifact_records(self.entries, "costs")
788
+ )
789
+
790
+ @property
791
+ def eigenvalues(self) -> BatchEigenvalues:
792
+ """Return eigenvalue data for all batch entries.
793
+
794
+ Returns
795
+ -------
796
+ BatchEigenvalues
797
+ Eigenvalue data in batched project keys order.
798
+ """
799
+
800
+ return BatchEigenvalues(
801
+ records=_batch_artifact_records(self.entries, "eigenvalues")
802
+ )
803
+
804
+ @property
805
+ def postprocesses(self) -> BatchPostprocessCollection:
806
+ """Return the batch postprocess collection.
807
+
808
+ Returns
809
+ -------
810
+ BatchPostprocessCollection
811
+ Postprocess results in batched project keys order.
812
+ """
813
+
814
+ from .batch_postprocess import BatchPostprocessCollection
815
+
816
+ return BatchPostprocessCollection(
817
+ records=_batch_postprocess_records(self.entries)
818
+ )
819
+
820
+ @property
821
+ def keys(self) -> BatchSolveKeys:
822
+ """Return the batched project keys and their original positions.
823
+
824
+ Returns
825
+ -------
826
+ BatchSolveKeys
827
+ project keys in their original batch order.
828
+ """
829
+
830
+ return BatchSolveKeys(records=_batch_export_records(self.entries))
831
+
832
+
833
+ @dataclass(slots=True, frozen=True)
834
+ class BatchComputationalCosts(BatchTablePayload):
835
+ """Store and export computational-cost data for a batch.
836
+
837
+ Parameters
838
+ ----------
839
+ records : tuple[BatchExportRecord, ...]
840
+ Computational-cost data in batch order.
841
+ """
842
+
843
+ records: tuple[BatchExportRecord, ...]
844
+
845
+ def __post_init__(self) -> None:
846
+ BatchTablePayload.__init__(
847
+ self, tuple(record.source for record in self.records)
848
+ )
849
+
850
+ @property
851
+ def count(self) -> int:
852
+ """Return the total number of batch entries.
853
+
854
+ Returns
855
+ -------
856
+ int
857
+ Number of batch entries.
858
+ """
859
+
860
+ return len(self.records)
861
+
862
+ @property
863
+ def available_count(self) -> int:
864
+ """Return the number of entries with computational-cost data.
865
+
866
+ Returns
867
+ -------
868
+ int
869
+ Number of available computational-cost results.
870
+ """
871
+
872
+ return sum(
873
+ 1
874
+ for record in self.records
875
+ if isinstance(record.payload, ComputationalCosts)
876
+ )
877
+
878
+ @property
879
+ def missing_count(self) -> int:
880
+ """Return the number of entries without computational-cost data.
881
+
882
+ Returns
883
+ -------
884
+ int
885
+ Number of missing computational-cost results.
886
+ """
887
+
888
+ return self.count - self.available_count
889
+
890
+ def to_dict(self) -> Mapping[object, object]:
891
+ """Return one cost dictionary for each available batch entry.
892
+
893
+ Returns
894
+ -------
895
+ Mapping[object, object]
896
+ Cost dictionaries indexed by their original batch positions.
897
+ """
898
+
899
+ return {
900
+ record.index: dict(record.payload.to_dict())
901
+ for record in self.records
902
+ if isinstance(record.payload, ComputationalCosts)
903
+ }
904
+
905
+ def __repr__(self) -> str:
906
+ """Return a compact summary with a bounded cost-data preview."""
907
+
908
+ return (
909
+ f"{self.__class__.__name__}(entries={self.count}, "
910
+ f"available={self.available_count}, missing={self.missing_count},\n"
911
+ f" preview=\n{self._preview()}\n)"
912
+ )
913
+
914
+ def _to_df_long(self) -> "pd.DataFrame":
915
+ """Return one DataFrame row for each cost value in each batch entry.
916
+
917
+ Returns
918
+ -------
919
+ pandas.DataFrame
920
+ Long-form batch computational-cost table.
921
+ """
922
+
923
+ from ...pandas_export import batch_costs_to_df
924
+
925
+ return batch_costs_to_df(self.records)
926
+
927
+ def to_xarray(self) -> XarrayDataTree:
928
+ """Return the batch computational costs as an xarray `DataTree`.
929
+
930
+ Returns
931
+ -------
932
+ xarray.DataTree
933
+ Computational-cost data in batched project keys order.
934
+ """
935
+
936
+ from ..export.xarray.export import batch_costs_to_xarray_dataset
937
+
938
+ return batch_costs_to_xarray_dataset(self.records)
939
+
940
+ @property
941
+ def header(self) -> BatchMetadataPayload:
942
+ """Return header information for all batch entries.
943
+
944
+ Returns
945
+ -------
946
+ BatchMetadataPayload
947
+ Header information in batched project keys order.
948
+ """
949
+
950
+ header_records: tuple[BatchExportRecord, ...] = tuple(
951
+ BatchExportRecord(
952
+ index=record.index,
953
+ keys=(
954
+ {}
955
+ if not isinstance(record.payload, ComputationalCosts)
956
+ or record.payload.header is None
957
+ else {
958
+ str(key): value
959
+ for key, value in record.payload.header.to_dict().items()
960
+ }
961
+ ),
962
+ source=record.source,
963
+ )
964
+ for record in self.records
965
+ )
966
+ return BatchMetadataPayload(header_records)
967
+
968
+
969
+ @dataclass(slots=True, frozen=True)
970
+ class BatchEigenvalues(BatchTablePayload):
971
+ """Store and export eigenvalue data for a batch.
972
+
973
+ Parameters
974
+ ----------
975
+ records : tuple[BatchExportRecord, ...]
976
+ Eigenvalue data in batch order.
977
+ """
978
+
979
+ records: tuple[BatchExportRecord, ...]
980
+
981
+ def __post_init__(self) -> None:
982
+ BatchTablePayload.__init__(
983
+ self, tuple(record.source for record in self.records)
984
+ )
985
+
986
+ @property
987
+ def count(self) -> int:
988
+ """Return the total number of batch entries.
989
+
990
+ Returns
991
+ -------
992
+ int
993
+ Number of batch entries.
994
+ """
995
+
996
+ return len(self.records)
997
+
998
+ def to_dict(self) -> Mapping[object, object]:
999
+ """Return one eigenvalue dictionary for each available batch entry.
1000
+
1001
+ Returns
1002
+ -------
1003
+ Mapping[object, object]
1004
+ Eigenvalue dictionaries indexed by their original batch positions.
1005
+ """
1006
+
1007
+ return {
1008
+ record.index: dict(record.payload.to_dict())
1009
+ for record in self.records
1010
+ if isinstance(record.payload, Eigenvalues)
1011
+ }
1012
+
1013
+ @property
1014
+ def available_count(self) -> int:
1015
+ """Return the number of entries with eigenvalue data.
1016
+
1017
+ Returns
1018
+ -------
1019
+ int
1020
+ Number of available eigenvalue results.
1021
+ """
1022
+
1023
+ return sum(
1024
+ 1 for record in self.records if isinstance(record.payload, Eigenvalues)
1025
+ )
1026
+
1027
+ @property
1028
+ def missing_count(self) -> int:
1029
+ """Return the number of entries without eigenvalue data.
1030
+
1031
+ Returns
1032
+ -------
1033
+ int
1034
+ Number of missing eigenvalue results.
1035
+ """
1036
+
1037
+ return self.count - self.available_count
1038
+
1039
+ def __repr__(self) -> str:
1040
+ """Return a compact summary with a bounded eigenvalue preview."""
1041
+
1042
+ return (
1043
+ f"{self.__class__.__name__}(entries={self.count}, "
1044
+ f"available={self.available_count}, missing={self.missing_count},\n"
1045
+ f" preview=\n{self._preview()}\n)"
1046
+ )
1047
+
1048
+ def _to_df_long(self) -> "pd.DataFrame":
1049
+ """Return one DataFrame row for each eigenvalue property in each entry.
1050
+
1051
+ Returns
1052
+ -------
1053
+ pandas.DataFrame
1054
+ Long-form batch eigenvalue table.
1055
+ """
1056
+
1057
+ from ...pandas_export import batch_eigenvalues_to_df
1058
+
1059
+ return batch_eigenvalues_to_df(self.records)
1060
+
1061
+ def to_xarray(self) -> XarrayDataTree:
1062
+ """Return the batch eigenvalues as an xarray `DataTree`.
1063
+
1064
+ Returns
1065
+ -------
1066
+ xarray.DataTree
1067
+ Tree with all data in the root node. `batch_index` contains the
1068
+ original batch positions. `row_index` identifies table rows.
1069
+ `is_valid` identifies source values. `is_padded` identifies values
1070
+ added to make all batch tables the same length.
1071
+
1072
+ Raises
1073
+ ------
1074
+ InvalidConfigurationError
1075
+ If no eigenvalue data is available or the tables cannot be
1076
+ combined.
1077
+ """
1078
+
1079
+ from ..export.xarray.export import batch_eigenvalues_to_xarray_dataset
1080
+
1081
+ return batch_eigenvalues_to_xarray_dataset(self.records)