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,806 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Typed result-file discovery and access models."""
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
12
+
13
+ from ..exceptions import InvalidConfigurationError, UnsupportedExportError
14
+ from ..loaders import load_cartesian_fields, load_table
15
+ from .internal.export.common import materialize_rows, rows_to_dataframe
16
+ from .internal.export.pandas.payload import (
17
+ payload_to_tabular_rows,
18
+ postprocess_header_to_long_rows,
19
+ )
20
+ from .payloads import (
21
+ DictionaryExportMixin,
22
+ MetadataPayload,
23
+ Source,
24
+ TablePayload,
25
+ )
26
+
27
+ if TYPE_CHECKING:
28
+ import pandas as pd # pyright: ignore[reportMissingImports]
29
+
30
+ from .discovery import load_postprocess_payload, project_postprocess_output_files
31
+ from .postprocess import PostprocessCollection as PostprocessCollection
32
+ from .postprocess_payloads import payload_mapping as _payload_mapping_helper
33
+ from .postprocess_record import PostprocessRecord as PostprocessRecord
34
+
35
+ if TYPE_CHECKING:
36
+ from .internal.export.xarray.types import XarrayDataTree
37
+
38
+
39
+ @dataclass(slots=True, frozen=True, repr=False)
40
+ class ComputationalCosts(TablePayload):
41
+ """Store and export computational-cost data.
42
+
43
+ Parameters
44
+ ----------
45
+ table : Mapping[object, object]
46
+ Dictionary read from `computational_costs.jcm`.
47
+ source : str | Path | None, optional
48
+ Source file or storage origin for the computational-cost data.
49
+ """
50
+
51
+ table: Mapping[object, object]
52
+ source: Source = None # pyright: ignore
53
+
54
+ @property
55
+ def _raw(self) -> Mapping[object, object]:
56
+ """Return the original computational-cost payload."""
57
+
58
+ return self.table
59
+
60
+ @property
61
+ def title(self) -> str | None:
62
+ """Return the table title.
63
+
64
+ Returns
65
+ -------
66
+ str | None
67
+ Table title, or `None` if the table has no title.
68
+ """
69
+
70
+ title_object: object | None = self.table.get("title")
71
+ if isinstance(title_object, str):
72
+ return title_object
73
+ return None
74
+
75
+ @property
76
+ def header(self) -> "ComputationalCostsHeader | None":
77
+ """Return the table header.
78
+
79
+ Returns
80
+ -------
81
+ ComputationalCostsHeader | None
82
+ Header information, or `None` if no header is available.
83
+ """
84
+
85
+ header_object: object | None = self.table.get("header")
86
+ if isinstance(header_object, Mapping):
87
+ return ComputationalCostsHeader(table=header_object, source=self.source)
88
+ return None
89
+
90
+ def to_dict(self) -> Mapping[object, object]:
91
+ """Return the computational-cost data as a dictionary.
92
+
93
+ Returns
94
+ -------
95
+ Mapping[object, object]
96
+ Computational-cost values and header information.
97
+ """
98
+
99
+ return dict(self.table)
100
+
101
+ def _value_mapping(self) -> Mapping[object, object]:
102
+ """Return computational values without title or header metadata."""
103
+
104
+ normalized_mapping: dict[object, object] = dict(self.table)
105
+ normalized_mapping.pop("title", None)
106
+ normalized_mapping.pop("header", None)
107
+ return normalized_mapping
108
+
109
+ def _to_df_wide(self) -> "pd.DataFrame":
110
+ """Return a DataFrame with one column for each cost value.
111
+
112
+ Returns
113
+ -------
114
+ pandas.DataFrame
115
+ Wide computational-cost table.
116
+ """
117
+
118
+ payload: object = self._value_mapping()
119
+ rows: list[dict[str, object]] | None = payload_to_tabular_rows(payload)
120
+ if rows is None:
121
+ raise InvalidConfigurationError(
122
+ "Computational-cost payload is not tabular."
123
+ )
124
+ indexed_rows: list[dict[str, object]] = materialize_rows(
125
+ rows,
126
+ row_index_key="row_index",
127
+ )
128
+ return rows_to_dataframe(indexed_rows)
129
+
130
+ def _to_df_long(self) -> "pd.DataFrame":
131
+ """Return a DataFrame with one row for each cost value.
132
+
133
+ Returns
134
+ -------
135
+ pandas.DataFrame
136
+ Long-form computational-cost table.
137
+ """
138
+
139
+ from .internal.export.pandas.payload import postprocess_payload_to_long_rows
140
+
141
+ rows: list[dict[str, object]] | None = postprocess_payload_to_long_rows(
142
+ self._value_mapping()
143
+ )
144
+ if rows is None:
145
+ raise InvalidConfigurationError(
146
+ "Computational-cost payload is not tabular."
147
+ )
148
+ return rows_to_dataframe(materialize_rows(rows, row_index_key="row_index"))
149
+
150
+ def to_xarray(self) -> XarrayDataTree:
151
+ """Return the computational-cost data as an xarray `DataTree`.
152
+
153
+ The root node contains the cost values.
154
+
155
+ Returns
156
+ -------
157
+ xarray.DataTree
158
+ Computational-cost data in the root node.
159
+ """
160
+
161
+ from .internal.export.xarray.runtime import (
162
+ _create_data_tree,
163
+ _load_datatree_module,
164
+ _load_xarray_module,
165
+ )
166
+ from .internal.export.xarray.tabular import (
167
+ tabular_payload_to_xarray_table,
168
+ tabular_table_to_xarray_dataset,
169
+ )
170
+
171
+ xarray_module = _load_xarray_module()
172
+ datatree_module = _load_datatree_module()
173
+ payload_object: object = self._value_mapping()
174
+ tabular_table = tabular_payload_to_xarray_table(
175
+ payload_object,
176
+ payload_name="Computational-cost payload",
177
+ )
178
+ dataset = tabular_table_to_xarray_dataset(
179
+ tabular_table,
180
+ xarray_module=xarray_module,
181
+ )
182
+ if self.title is not None:
183
+ dataset.attrs["title"] = self.title
184
+ return _create_data_tree(datatree_module=datatree_module, dataset=dataset)
185
+
186
+
187
+ @dataclass(slots=True, frozen=True, repr=False)
188
+ class ComputationalCostsHeader(MetadataPayload, Mapping[object, object]):
189
+ """Store and export information from a computational-cost header.
190
+
191
+ Parameters
192
+ ----------
193
+ table : Mapping[object, object]
194
+ Header information from `computational_costs.jcm`.
195
+ source : str | Path | None, optional
196
+ Source file or storage origin for the computational-cost header.
197
+ """
198
+
199
+ table: Mapping[object, object]
200
+ source: Source = None # pyright: ignore
201
+
202
+ @property
203
+ def _raw(self) -> Mapping[object, object]:
204
+ """Return the original computational-cost header payload."""
205
+
206
+ return self.table
207
+
208
+ def to_dict(self) -> Mapping[object, object]:
209
+ """Return the header information as a dictionary.
210
+
211
+ Returns
212
+ -------
213
+ Mapping[object, object]
214
+ Copy of the computational-cost header.
215
+ """
216
+
217
+ return dict(self.table)
218
+
219
+ def __getitem__(self, key: object) -> object:
220
+
221
+ return self.table[key]
222
+
223
+ def __iter__(self) -> Iterator[object]:
224
+
225
+ return iter(self.table)
226
+
227
+ def __len__(self) -> int:
228
+
229
+ return len(self.table)
230
+
231
+ def _to_df_long(self) -> "pd.DataFrame":
232
+ """Return one DataFrame row for each header value.
233
+
234
+ Returns
235
+ -------
236
+ pandas.DataFrame
237
+ Long-form computational-cost header.
238
+ """
239
+
240
+ header_rows: list[dict[str, object]] | None = postprocess_header_to_long_rows(
241
+ self.table
242
+ )
243
+ if header_rows is None:
244
+ raise InvalidConfigurationError(
245
+ "Computational-cost header payload is not tabular and cannot be exported via to_df()."
246
+ )
247
+ return rows_to_dataframe(header_rows)
248
+
249
+ def _to_df_wide(self) -> "pd.DataFrame":
250
+ """Reject wide export for general header metadata."""
251
+
252
+ raise UnsupportedExportError(
253
+ "Computational-cost header metadata only supports long DataFrame export."
254
+ )
255
+
256
+ def to_df(self, orient: str | None = None) -> "pd.DataFrame":
257
+ """Return header metadata in the requested DataFrame orientation.
258
+
259
+ Parameters
260
+ ----------
261
+ orient : {None, "long"}, optional
262
+ Select the table layout. Header metadata supports only long form.
263
+
264
+ Returns
265
+ -------
266
+ pandas.DataFrame
267
+ Long-form computational-cost header.
268
+
269
+ Raises
270
+ ------
271
+ UnsupportedExportError
272
+ If `orient` is `"wide"`.
273
+ ValueError
274
+ If `orient` is not `None`, `"wide"`, or `"long"`.
275
+ """
276
+
277
+ if orient is None or orient == "long":
278
+ return self._to_df_long()
279
+ if orient == "wide":
280
+ return self._to_df_wide()
281
+ raise ValueError("orient must be None, 'wide', or 'long'")
282
+
283
+ def to_xarray(self) -> XarrayDataTree:
284
+ """Return the header information as an xarray `DataTree`.
285
+
286
+ The root node contains the header values.
287
+
288
+ Returns
289
+ -------
290
+ xarray.DataTree
291
+ Header information in the root node.
292
+ """
293
+
294
+ from .internal.export.xarray.export import header_payload_to_xarray_dataset
295
+
296
+ return header_payload_to_xarray_dataset(self.table)
297
+
298
+
299
+ @dataclass(slots=True, frozen=True, repr=False)
300
+ class Eigenvalues(TablePayload):
301
+ """Store and export eigenvalue data.
302
+
303
+ Parameters
304
+ ----------
305
+ table : Mapping[object, object]
306
+ Dictionary read from `eigenvalues.jcm`.
307
+ source : str | Path | None, optional
308
+ Source file or storage origin for the eigenvalue data.
309
+ """
310
+
311
+ table: Mapping[object, object]
312
+ source: Source = None # pyright: ignore
313
+
314
+ @property
315
+ def _raw(self) -> Mapping[object, object]:
316
+ """Return the original eigenvalue payload."""
317
+
318
+ return self.table
319
+
320
+ def to_dict(self) -> Mapping[object, object]:
321
+ """Return the eigenvalue data as a dictionary.
322
+
323
+ Returns
324
+ -------
325
+ Mapping[object, object]
326
+ Eigenvalue values and table information.
327
+ """
328
+
329
+ return dict(self.table)
330
+
331
+ def _value_mapping(self) -> Mapping[object, object]:
332
+ """Return eigenvalue values without title metadata."""
333
+
334
+ normalized_mapping: dict[object, object] = dict(self.table)
335
+ normalized_mapping.pop("title", None)
336
+ return normalized_mapping
337
+
338
+ def __getitem__(self, key: object) -> object:
339
+
340
+ return self.table[key]
341
+
342
+ def __iter__(self) -> Iterator[object]:
343
+
344
+ return iter(self.table)
345
+
346
+ def __len__(self) -> int:
347
+
348
+ return len(self.table)
349
+
350
+ def _to_df_wide(self) -> "pd.DataFrame":
351
+ """Return a DataFrame with one column for each eigenvalue property.
352
+
353
+ Returns
354
+ -------
355
+ pandas.DataFrame
356
+ Wide eigenvalue table.
357
+ """
358
+
359
+ rows: list[dict[str, object]] | None = payload_to_tabular_rows(
360
+ self._value_mapping()
361
+ )
362
+ if rows is None:
363
+ raise InvalidConfigurationError("Eigenvalue payload is not tabular.")
364
+ indexed_rows: list[dict[str, object]] = materialize_rows(
365
+ rows,
366
+ row_index_key="row_index",
367
+ )
368
+ return rows_to_dataframe(indexed_rows)
369
+
370
+ def _to_df_long(self) -> "pd.DataFrame":
371
+ """Return a DataFrame with one row for each eigenvalue property.
372
+
373
+ Returns
374
+ -------
375
+ pandas.DataFrame
376
+ Long-form eigenvalue table.
377
+ """
378
+
379
+ from .internal.export.pandas.payload import postprocess_payload_to_long_rows
380
+
381
+ rows: list[dict[str, object]] | None = postprocess_payload_to_long_rows(
382
+ self._value_mapping()
383
+ )
384
+ if rows is None:
385
+ raise InvalidConfigurationError("Eigenvalue payload is not tabular.")
386
+ return rows_to_dataframe(materialize_rows(rows, row_index_key="row_index"))
387
+
388
+ def to_xarray(self) -> XarrayDataTree:
389
+ """Return the eigenvalue data as an xarray `DataTree`.
390
+
391
+ Returns
392
+ -------
393
+ xarray.DataTree
394
+ Tree with all eigenvalue data in the root node. The `row_index`
395
+ coordinate identifies each eigenvalue row.
396
+
397
+ Raises
398
+ ------
399
+ InvalidConfigurationError
400
+ If the eigenvalue data cannot form a table.
401
+ """
402
+
403
+ from .internal.export.xarray.export import eigenvalues_payload_to_xarray_dataset
404
+
405
+ return eigenvalues_payload_to_xarray_dataset(self.table)
406
+
407
+
408
+ @dataclass(slots=True, frozen=True, repr=False)
409
+ class PostprocessHeader(DictionaryExportMixin, Mapping[object, object]):
410
+ """Store and export information from a postprocess header.
411
+
412
+ Parameters
413
+ ----------
414
+ table : Mapping[object, object]
415
+ Header information from a postprocess result.
416
+ """
417
+
418
+ table: Mapping[object, object]
419
+
420
+ @property
421
+ def _raw(self) -> Mapping[object, object]:
422
+ """Return the original postprocess header payload."""
423
+
424
+ return self.table
425
+
426
+ def to_dict(self) -> Mapping[object, object]:
427
+ """Return the header information as a dictionary.
428
+
429
+ Returns
430
+ -------
431
+ Mapping[object, object]
432
+ Copy of the postprocess header.
433
+ """
434
+
435
+ return dict(self.table)
436
+
437
+ def _preview(self) -> str:
438
+ """Return internal bounded one-row header preview text.
439
+
440
+ Returns
441
+ -------
442
+ str
443
+ A text table containing at most six header fields.
444
+ """
445
+
446
+ from .internal.export.preview import format_mapping_preview
447
+
448
+ return format_mapping_preview(self.to_dict())
449
+
450
+ def __repr__(self) -> str:
451
+ """Return the header class name with its bounded data preview."""
452
+
453
+ return f"PostprocessHeader(\n preview=\n{self._preview()}\n)"
454
+
455
+ @property
456
+ def title(self) -> str | None:
457
+ """Return the postprocess title stored in the header payload."""
458
+
459
+ title_object: object | None = self.table.get("title")
460
+ if isinstance(title_object, str):
461
+ return title_object
462
+ return None
463
+
464
+ def __getitem__(self, key: object) -> object:
465
+
466
+ return self.table[key]
467
+
468
+ def __iter__(self) -> Iterator[object]:
469
+
470
+ return iter(self.table)
471
+
472
+ def __len__(self) -> int:
473
+
474
+ return len(self.table)
475
+
476
+ def to_df(self, orient: str | None = None) -> "pd.DataFrame":
477
+ """Return one DataFrame row for each header value.
478
+
479
+ Parameters
480
+ ----------
481
+ orient : {None, "long"}, optional
482
+ Select the table layout. Postprocess headers support only long form.
483
+
484
+ Returns
485
+ -------
486
+ pandas.DataFrame
487
+ Long-form postprocess header.
488
+
489
+ Raises
490
+ ------
491
+ InvalidConfigurationError
492
+ If the postprocess header is not tabular.
493
+ UnsupportedExportError
494
+ If `orient` is `"wide"`.
495
+ ValueError
496
+ If `orient` is not `None`, `"wide"`, or `"long"`.
497
+ """
498
+
499
+ if orient not in (None, "long"):
500
+ if orient == "wide":
501
+ raise UnsupportedExportError(
502
+ "Postprocess header metadata only supports long DataFrame export."
503
+ )
504
+ raise ValueError("orient must be None, 'wide', or 'long'")
505
+ header_rows: list[dict[str, object]] | None = postprocess_header_to_long_rows(
506
+ self.table
507
+ )
508
+ if header_rows is None:
509
+ raise InvalidConfigurationError(
510
+ "Postprocess header payload is not tabular and cannot be exported via to_df()."
511
+ )
512
+ return rows_to_dataframe(header_rows)
513
+
514
+ def to_xarray(self) -> XarrayDataTree:
515
+ """Return the header information as an xarray `DataTree`.
516
+
517
+ The root node contains the header values.
518
+
519
+ Returns
520
+ -------
521
+ xarray.DataTree
522
+ Header information in the root node.
523
+ """
524
+
525
+ from .internal.export.xarray.export import header_payload_to_xarray_dataset
526
+
527
+ return header_payload_to_xarray_dataset(self.table)
528
+
529
+
530
+ @dataclass(slots=True, frozen=True)
531
+ class DiscoveredArtifacts:
532
+ """Store result files and data found for one project.
533
+
534
+ Attributes
535
+ ----------
536
+ file : Path | None
537
+ Solution fieldbag file, if available.
538
+ costs : ComputationalCosts | None
539
+ Computational-cost data, if available.
540
+ eigenvalues : Eigenvalues | None
541
+ Eigenvalue data, if available.
542
+ postprocesses : PostprocessCollection
543
+ Available postprocess results in project file order.
544
+ """
545
+
546
+ file: Path | None
547
+ costs: ComputationalCosts | None
548
+ eigenvalues: Eigenvalues | None
549
+ postprocesses: PostprocessCollection
550
+
551
+
552
+ def discover_artifacts_from_project(project_file: Path) -> DiscoveredArtifacts:
553
+ """Find and load result data for one project file.
554
+
555
+ Parameters
556
+ ----------
557
+ project_file : Path
558
+ Path to the rendered project file.
559
+
560
+ Returns
561
+ -------
562
+ DiscoveredArtifacts
563
+ Solution fieldbag file and the available computational-cost,
564
+ eigenvalue, and postprocess data.
565
+ """
566
+
567
+ result_dir: Path = project_file.parent / f"{project_file.stem}_results"
568
+ ordered_output_files: tuple[Path, ...] = _project_postprocess_output_files(
569
+ project_file=project_file,
570
+ result_dir=result_dir,
571
+ )
572
+ return _discover_artifacts(
573
+ result_dir=result_dir,
574
+ ordered_output_files=ordered_output_files,
575
+ allow_result_dir_scan=False,
576
+ )
577
+
578
+
579
+ def discover_artifacts_from_result_dir(result_dir: Path) -> DiscoveredArtifacts:
580
+ """Find and load result data from a project result directory.
581
+
582
+ Parameters
583
+ ----------
584
+ result_dir : Path
585
+ Path to the ``*_results`` directory.
586
+
587
+ Returns
588
+ -------
589
+ DiscoveredArtifacts
590
+ Solution fieldbag file and the available computational-cost,
591
+ eigenvalue, and postprocess data.
592
+ """
593
+
594
+ return _discover_artifacts(
595
+ result_dir=result_dir,
596
+ ordered_output_files=(),
597
+ allow_result_dir_scan=True,
598
+ )
599
+
600
+
601
+ def _discover_artifacts(
602
+ *,
603
+ result_dir: Path,
604
+ ordered_output_files: tuple[Path, ...],
605
+ allow_result_dir_scan: bool,
606
+ ) -> DiscoveredArtifacts:
607
+ """Discover result files from one result directory with optional ordering."""
608
+
609
+ resolved_result_dir: Path = result_dir.expanduser().resolve()
610
+ fieldbag_file: Path = resolved_result_dir / "fieldbag.jcm"
611
+ costs_file: Path = resolved_result_dir / "computational_costs.jcm"
612
+ eigenvalues_file: Path = resolved_result_dir / "eigenvalues.jcm"
613
+
614
+ solution_file: Path | None = (
615
+ fieldbag_file.resolve() if fieldbag_file.is_file() else None
616
+ )
617
+
618
+ computational_costs: ComputationalCosts | None = None
619
+ costs_payload: object
620
+ if costs_file.is_file():
621
+ try:
622
+ costs_payload = load_table(costs_file)
623
+ except Exception:
624
+ costs_payload = None
625
+ costs_mapping: Mapping[object, object] | None = _payload_mapping_helper(
626
+ costs_payload
627
+ )
628
+ if costs_mapping is not None:
629
+ computational_costs = ComputationalCosts(
630
+ table=costs_mapping,
631
+ source=costs_file,
632
+ )
633
+
634
+ eigenvalues: Eigenvalues | None = None
635
+ eigen_payload: object
636
+ if eigenvalues_file.is_file():
637
+ try:
638
+ eigen_payload = load_table(eigenvalues_file)
639
+ except Exception:
640
+ eigen_payload = None
641
+ eigen_mapping: Mapping[object, object] | None = _payload_mapping_helper(
642
+ eigen_payload
643
+ )
644
+ if eigen_mapping is not None:
645
+ eigenvalues = Eigenvalues(
646
+ table=eigen_mapping,
647
+ source=eigenvalues_file,
648
+ )
649
+
650
+ postprocess_records: list[PostprocessRecord] = []
651
+ reserved_result_names: set[str] = {
652
+ "fieldbag.jcm",
653
+ "computational_costs.jcm",
654
+ "eigenvalues.jcm",
655
+ }
656
+ ordered_result_files: list[Path] = []
657
+ seen_output_files: set[Path] = set()
658
+ ordered_output: Path
659
+ for ordered_output in ordered_output_files:
660
+ resolved_output: Path = ordered_output.expanduser().resolve()
661
+ if resolved_output in seen_output_files:
662
+ continue
663
+ seen_output_files.add(resolved_output)
664
+ # Preserve project-declared postprocess outputs even when the backing
665
+ # file never materialized as a loadable `.jcm` artifact (for example
666
+ # Pinboard-formatted outputs). Those entries surface as empty records.
667
+ ordered_result_files.append(resolved_output)
668
+ if allow_result_dir_scan:
669
+ discovered_result_files: list[Path] = sorted(
670
+ (
671
+ []
672
+ if not resolved_result_dir.is_dir()
673
+ else [
674
+ candidate.resolve()
675
+ for candidate in resolved_result_dir.glob("*.jcm")
676
+ if candidate.is_file()
677
+ and candidate.name not in reserved_result_names
678
+ ]
679
+ ),
680
+ key=lambda file_path: file_path.name.lower(),
681
+ )
682
+ fallback_output: Path
683
+ for fallback_output in discovered_result_files:
684
+ if fallback_output not in seen_output_files:
685
+ ordered_result_files.append(fallback_output)
686
+
687
+ ordered_result_file: Path
688
+ for ordered_result_file in ordered_result_files:
689
+ try:
690
+ payload: object | None = _load_postprocess_payload(ordered_result_file)
691
+ except InvalidConfigurationError as exc:
692
+ postprocess_records.append(
693
+ PostprocessRecord(
694
+ source_file=ordered_result_file,
695
+ _raw=None,
696
+ title=ordered_result_file.stem,
697
+ available=False,
698
+ failure_message=str(exc),
699
+ )
700
+ )
701
+ continue
702
+ payload_title: str | None = _extract_payload_title(payload)
703
+ if payload_title is None:
704
+ payload_title = ordered_result_file.stem
705
+ if payload is None:
706
+ postprocess_records.append(
707
+ PostprocessRecord(
708
+ source_file=ordered_result_file,
709
+ _raw=None,
710
+ title=payload_title,
711
+ available=False,
712
+ failure_message="Postprocess output file is missing.",
713
+ )
714
+ )
715
+ continue
716
+ postprocess_records.append(
717
+ PostprocessRecord(
718
+ source_file=ordered_result_file,
719
+ _raw=payload,
720
+ title=payload_title,
721
+ )
722
+ )
723
+ postprocess_collection: PostprocessCollection = PostprocessCollection(
724
+ records=tuple(postprocess_records)
725
+ )
726
+ return DiscoveredArtifacts(
727
+ file=solution_file,
728
+ costs=computational_costs,
729
+ eigenvalues=eigenvalues,
730
+ postprocesses=postprocess_collection,
731
+ )
732
+
733
+
734
+ def _project_postprocess_output_files(
735
+ *,
736
+ project_file: Path,
737
+ result_dir: Path,
738
+ ) -> tuple[Path, ...]:
739
+ """Return postprocess output files in project-definition order.
740
+
741
+ Notes
742
+ -----
743
+ Internal API: this helper preserves the legacy `OutputFileName` ordering
744
+ contract for project-backed result discovery. Raw result-dir opening still
745
+ falls back to filesystem order when no project file is available.
746
+ """
747
+
748
+ return project_postprocess_output_files(
749
+ project_file=project_file,
750
+ result_dir=result_dir,
751
+ )
752
+
753
+
754
+ def _load_postprocess_payload(output_path: Path) -> object | None:
755
+ """Load postprocess payload.
756
+
757
+ Parameters
758
+ ----------
759
+ output_path : Path
760
+ Filesystem path supplied via `output_path`.
761
+
762
+ Returns
763
+ -------
764
+ object | None
765
+ Computed ``object | None`` value.
766
+
767
+ Notes
768
+ -----
769
+ Internal API: this helper is an implementation detail and may change
770
+ without notice.
771
+ """
772
+
773
+ return load_postprocess_payload(
774
+ output_path,
775
+ load_table=load_table,
776
+ load_cartesian_fields=load_cartesian_fields,
777
+ )
778
+
779
+
780
+ def _extract_payload_title(payload: object | None) -> str | None:
781
+ """Extract payload title.
782
+
783
+ Parameters
784
+ ----------
785
+ payload : object | None
786
+ Internal structured data supplied via `payload`.
787
+
788
+ Returns
789
+ -------
790
+ str | None
791
+ Computed optional string output.
792
+
793
+ Notes
794
+ -----
795
+ Internal API: this helper is an implementation detail and may change
796
+ without notice.
797
+ """
798
+
799
+ if payload is None:
800
+ return None
801
+ payload_mapping: Mapping[object, object] | None = _payload_mapping_helper(payload)
802
+ if payload_mapping is not None:
803
+ title_object: object | None = payload_mapping.get("title")
804
+ if isinstance(title_object, str):
805
+ return title_object
806
+ return None