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.
- jcmsuite/__init__.py +22 -0
- jcmsuite/_build_info.py +4 -0
- jcmsuite/context/__init__.py +44 -0
- jcmsuite/context/interface_metadata.py +158 -0
- jcmsuite/context/models.py +213 -0
- jcmsuite/context/scope.py +210 -0
- jcmsuite/context/solver_context.py +569 -0
- jcmsuite/context/subprocess_tools.py +172 -0
- jcmsuite/contract.py +47 -0
- jcmsuite/daemon/__init__.py +19 -0
- jcmsuite/daemon/handler.py +925 -0
- jcmsuite/daemon/internal/__init__.py +4 -0
- jcmsuite/daemon/internal/bundle_protocol.py +64 -0
- jcmsuite/daemon/internal/handler_helpers.py +368 -0
- jcmsuite/daemon/internal/handler_resource_jobs.py +227 -0
- jcmsuite/daemon/internal/handler_wait.py +564 -0
- jcmsuite/daemon/models.py +349 -0
- jcmsuite/daemon/namespaces.py +250 -0
- jcmsuite/daemon/protocol.py +801 -0
- jcmsuite/daemon/resources.py +407 -0
- jcmsuite/daemon/scope.py +53 -0
- jcmsuite/daemon/transport.py +223 -0
- jcmsuite/editing/__init__.py +10 -0
- jcmsuite/editing/editor.py +274 -0
- jcmsuite/exceptions/__init__.py +32 -0
- jcmsuite/exceptions/errors.py +173 -0
- jcmsuite/geo/__init__.py +10 -0
- jcmsuite/geo/mesh.py +302 -0
- jcmsuite/info/__init__.py +10 -0
- jcmsuite/info/runtime_info.py +45 -0
- jcmsuite/internal/__init__.py +2 -0
- jcmsuite/internal/diagnostics.py +74 -0
- jcmsuite/internal/progress.py +80 -0
- jcmsuite/loaders/__init__.py +18 -0
- jcmsuite/loaders/blob_header.py +315 -0
- jcmsuite/loaders/cartesian_field_reader.py +249 -0
- jcmsuite/loaders/cartesian_fields.py +324 -0
- jcmsuite/loaders/nested_mapping.py +69 -0
- jcmsuite/loaders/powerflux.py +136 -0
- jcmsuite/loaders/table.py +637 -0
- jcmsuite/logging/__init__.py +22 -0
- jcmsuite/logging/runtime.py +210 -0
- jcmsuite/results/__init__.py +126 -0
- jcmsuite/results/artifacts.py +806 -0
- jcmsuite/results/discovery.py +82 -0
- jcmsuite/results/field_exports.py +1062 -0
- jcmsuite/results/field_payloads.py +453 -0
- jcmsuite/results/internal/__init__.py +4 -0
- jcmsuite/results/internal/export/__init__.py +4 -0
- jcmsuite/results/internal/export/common.py +56 -0
- jcmsuite/results/internal/export/pandas/__init__.py +4 -0
- jcmsuite/results/internal/export/pandas/common.py +165 -0
- jcmsuite/results/internal/export/pandas/payload.py +480 -0
- jcmsuite/results/internal/export/pandas/rows.py +484 -0
- jcmsuite/results/internal/export/preview.py +178 -0
- jcmsuite/results/internal/export/xarray/__init__.py +4 -0
- jcmsuite/results/internal/export/xarray/export.py +688 -0
- jcmsuite/results/internal/export/xarray/grouped.py +608 -0
- jcmsuite/results/internal/export/xarray/headers.py +290 -0
- jcmsuite/results/internal/export/xarray/runtime.py +99 -0
- jcmsuite/results/internal/export/xarray/shared.py +246 -0
- jcmsuite/results/internal/export/xarray/tabular.py +304 -0
- jcmsuite/results/internal/export/xarray/types.py +28 -0
- jcmsuite/results/internal/models/__init__.py +4 -0
- jcmsuite/results/internal/models/batch.py +1081 -0
- jcmsuite/results/internal/models/batch_postprocess.py +1728 -0
- jcmsuite/results/internal/models/bundle.py +343 -0
- jcmsuite/results/internal/models/core.py +556 -0
- jcmsuite/results/internal/models/submission.py +1157 -0
- jcmsuite/results/internal/resultbag/__init__.py +4 -0
- jcmsuite/results/internal/resultbag/access.py +489 -0
- jcmsuite/results/internal/resultbag/iteration.py +199 -0
- jcmsuite/results/internal/resultbag/query.py +226 -0
- jcmsuite/results/internal/resultbag/raw.py +407 -0
- jcmsuite/results/internal/resultbag/source_files.py +142 -0
- jcmsuite/results/internal/resultbag/store.py +881 -0
- jcmsuite/results/internal/resultbag/utils.py +258 -0
- jcmsuite/results/models.py +76 -0
- jcmsuite/results/opening.py +55 -0
- jcmsuite/results/pandas_export.py +325 -0
- jcmsuite/results/payloads.py +478 -0
- jcmsuite/results/postprocess.py +97 -0
- jcmsuite/results/postprocess_payloads.py +757 -0
- jcmsuite/results/postprocess_record.py +418 -0
- jcmsuite/results/resultbag.py +279 -0
- jcmsuite/results/resultbag_management.py +433 -0
- jcmsuite/results/structured_derivatives.py +387 -0
- jcmsuite/solve/__init__.py +10 -0
- jcmsuite/solve/daemon_bundle_staging.py +100 -0
- jcmsuite/solve/daemon_bundle_wait.py +89 -0
- jcmsuite/solve/orchestration.py +1576 -0
- jcmsuite/solve/orchestration_execution.py +180 -0
- jcmsuite/solve/orchestration_routing.py +128 -0
- jcmsuite/solve/orchestration_support.py +323 -0
- jcmsuite/solve/path_resolution.py +98 -0
- jcmsuite/solve/progress.py +20 -0
- jcmsuite/solve/solver.py +709 -0
- jcmsuite/solve/staging.py +264 -0
- jcmsuite/solve/types.py +25 -0
- jcmsuite/solve/working_dirs.py +227 -0
- jcmsuite/templates/__init__.py +11 -0
- jcmsuite/templates/converter.py +71 -0
- jcmsuite/templates/formatting.py +335 -0
- jcmsuite/templates/formatting_cli.py +47 -0
- jcmsuite/templates/rendering.py +666 -0
- jcmsuite/torch/__init__.py +25 -0
- jcmsuite/torch/autograd.py +488 -0
- jcmsuite/torch/coordinate_policy.py +82 -0
- jcmsuite/torch/core.py +312 -0
- jcmsuite/torch/results/__init__.py +51 -0
- jcmsuite/torch/types.py +84 -0
- jcmsuite/torch/validation.py +208 -0
- jcmsuite/torch/wrappers.py +4332 -0
- jcmsuite/view/__init__.py +10 -0
- jcmsuite/view/viewer.py +122 -0
- jcmsuite-7.4.2.dist-info/METADATA +180 -0
- jcmsuite-7.4.2.dist-info/RECORD +119 -0
- jcmsuite-7.4.2.dist-info/WHEEL +4 -0
- jcmsuite-7.4.2.dist-info/entry_points.txt +3 -0
|
@@ -0,0 +1,418 @@
|
|
|
1
|
+
# SPDX-License-Identifier: MIT
|
|
2
|
+
# Copyright (c) 2001-2026 JCMwave GmbH
|
|
3
|
+
|
|
4
|
+
"""Single-result postprocess record façade."""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
import warnings
|
|
9
|
+
from collections.abc import Mapping
|
|
10
|
+
from dataclasses import dataclass, field
|
|
11
|
+
from typing import TYPE_CHECKING, cast
|
|
12
|
+
|
|
13
|
+
from ..exceptions import InvalidConfigurationError, UnsupportedExportError
|
|
14
|
+
from ..loaders import convert_to_powerflux
|
|
15
|
+
from .field_exports import FieldExportPayload
|
|
16
|
+
from .internal.export.common import materialize_rows, rows_to_dataframe
|
|
17
|
+
from .internal.export.pandas.payload import (
|
|
18
|
+
flatten_payload,
|
|
19
|
+
postprocess_payload_to_long_rows,
|
|
20
|
+
)
|
|
21
|
+
from .payloads import (
|
|
22
|
+
DictionaryExportMixin,
|
|
23
|
+
PostprocessRecordPayload,
|
|
24
|
+
Source,
|
|
25
|
+
TableCollectionPayload,
|
|
26
|
+
TablePayload,
|
|
27
|
+
XarrayExportMixin,
|
|
28
|
+
)
|
|
29
|
+
from .postprocess_payloads import (
|
|
30
|
+
_StructuredRecordPayload,
|
|
31
|
+
classify_payload,
|
|
32
|
+
format_postprocess_payload_preview,
|
|
33
|
+
is_field_export_mapping,
|
|
34
|
+
payload_mapping,
|
|
35
|
+
)
|
|
36
|
+
|
|
37
|
+
if TYPE_CHECKING:
|
|
38
|
+
import pandas as pd
|
|
39
|
+
|
|
40
|
+
from .artifacts import PostprocessHeader
|
|
41
|
+
from .internal.export.xarray.types import XarrayDataTree
|
|
42
|
+
from .postprocess_payloads import (
|
|
43
|
+
TableCollectionDerivativeCollection,
|
|
44
|
+
TableDerivativeCollection,
|
|
45
|
+
)
|
|
46
|
+
from .structured_derivatives import StructuredDerivativeCollection
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
@dataclass(slots=True, frozen=True, repr=False)
|
|
50
|
+
class PostprocessRecord(DictionaryExportMixin):
|
|
51
|
+
"""Store and export one postprocess result."""
|
|
52
|
+
|
|
53
|
+
source_file: Source
|
|
54
|
+
_raw: object | None = field(repr=False)
|
|
55
|
+
title: str | None
|
|
56
|
+
payload: PostprocessRecordPayload | None = field(default=None, repr=False)
|
|
57
|
+
available: bool = True
|
|
58
|
+
failure_message: str | None = None
|
|
59
|
+
|
|
60
|
+
def __repr__(self) -> str:
|
|
61
|
+
status: str = (
|
|
62
|
+
"available"
|
|
63
|
+
if self.available
|
|
64
|
+
else (
|
|
65
|
+
"unavailable"
|
|
66
|
+
if self.failure_message is None
|
|
67
|
+
else f"unavailable: {self.failure_message}"
|
|
68
|
+
)
|
|
69
|
+
)
|
|
70
|
+
lines: list[str] = [
|
|
71
|
+
"PostprocessRecord(",
|
|
72
|
+
f" source_file: {self.source_file}",
|
|
73
|
+
f" title: {self.title if self.title is not None else '<untitled>'}",
|
|
74
|
+
f" status: {status}",
|
|
75
|
+
]
|
|
76
|
+
if self.available and self.payload is not None:
|
|
77
|
+
lines.append(" preview:")
|
|
78
|
+
lines.extend(
|
|
79
|
+
f" {line}"
|
|
80
|
+
for line in format_postprocess_payload_preview(
|
|
81
|
+
self.payload
|
|
82
|
+
).splitlines()
|
|
83
|
+
)
|
|
84
|
+
return "\n".join((*lines, ")"))
|
|
85
|
+
|
|
86
|
+
def __post_init__(self) -> None:
|
|
87
|
+
if self.payload is None:
|
|
88
|
+
typed_payload: PostprocessRecordPayload | None = classify_payload(
|
|
89
|
+
raw=self._raw, source=self.source_file, title=self.title
|
|
90
|
+
)
|
|
91
|
+
if typed_payload is not None:
|
|
92
|
+
object.__setattr__(self, "payload", typed_payload)
|
|
93
|
+
|
|
94
|
+
@property
|
|
95
|
+
def is_empty(self) -> bool:
|
|
96
|
+
return self._raw is None or not self.available
|
|
97
|
+
|
|
98
|
+
def _require_available(self) -> None:
|
|
99
|
+
if self.available:
|
|
100
|
+
return
|
|
101
|
+
record_label: str = (
|
|
102
|
+
str(self.source_file)
|
|
103
|
+
if self.title is None
|
|
104
|
+
else f"{self.title} ({self.source_file})"
|
|
105
|
+
)
|
|
106
|
+
warnings.warn(
|
|
107
|
+
(
|
|
108
|
+
f"Accessing unavailable postprocess output {record_label}"
|
|
109
|
+
if self.failure_message is None
|
|
110
|
+
else (
|
|
111
|
+
f"Accessing unavailable postprocess output {record_label}: "
|
|
112
|
+
f"{self.failure_message}"
|
|
113
|
+
)
|
|
114
|
+
),
|
|
115
|
+
stacklevel=2,
|
|
116
|
+
)
|
|
117
|
+
message: str = (
|
|
118
|
+
"Postprocess output is unavailable and cannot be accessed."
|
|
119
|
+
if self.failure_message is None
|
|
120
|
+
else f"Postprocess output is unavailable and cannot be accessed: {self.failure_message}"
|
|
121
|
+
)
|
|
122
|
+
raise InvalidConfigurationError(message)
|
|
123
|
+
|
|
124
|
+
def __setstate__(self, state: object) -> None:
|
|
125
|
+
values: dict[str, object] = {
|
|
126
|
+
"source_file": None,
|
|
127
|
+
"_raw": None,
|
|
128
|
+
"title": None,
|
|
129
|
+
"payload": None,
|
|
130
|
+
"available": True,
|
|
131
|
+
"failure_message": None,
|
|
132
|
+
}
|
|
133
|
+
if isinstance(state, dict):
|
|
134
|
+
for name, value in state.items():
|
|
135
|
+
if name in values:
|
|
136
|
+
values[name] = value
|
|
137
|
+
elif isinstance(state, (tuple, list)):
|
|
138
|
+
state_values: tuple[object, ...] = tuple(state)
|
|
139
|
+
names: tuple[str, ...] = (
|
|
140
|
+
"source_file",
|
|
141
|
+
"_raw",
|
|
142
|
+
"title",
|
|
143
|
+
"available",
|
|
144
|
+
"failure_message",
|
|
145
|
+
)
|
|
146
|
+
for index, name in enumerate(names):
|
|
147
|
+
if index < len(state_values):
|
|
148
|
+
values[name] = state_values[index]
|
|
149
|
+
else:
|
|
150
|
+
raise TypeError(
|
|
151
|
+
f"Unsupported pickled state for PostprocessRecord: {type(state)!r}"
|
|
152
|
+
)
|
|
153
|
+
for name, value in values.items():
|
|
154
|
+
object.__setattr__(self, name, value)
|
|
155
|
+
if values["payload"] is None:
|
|
156
|
+
restored: PostprocessRecordPayload | None = classify_payload(
|
|
157
|
+
raw=values["_raw"],
|
|
158
|
+
source=cast(Source, values["source_file"]),
|
|
159
|
+
title=cast(str | None, values["title"]),
|
|
160
|
+
)
|
|
161
|
+
if restored is not None:
|
|
162
|
+
object.__setattr__(self, "payload", restored)
|
|
163
|
+
|
|
164
|
+
def _unsupported(self, operation: str) -> UnsupportedExportError:
|
|
165
|
+
payload_name: str = (
|
|
166
|
+
type(self.payload).__name__
|
|
167
|
+
if self.payload is not None
|
|
168
|
+
else type(self._raw).__name__
|
|
169
|
+
)
|
|
170
|
+
return UnsupportedExportError(
|
|
171
|
+
f"{operation} is not supported for `{payload_name}`."
|
|
172
|
+
)
|
|
173
|
+
|
|
174
|
+
def to_dict(self) -> Mapping[object, object]:
|
|
175
|
+
"""Return the postprocess data as a dictionary.
|
|
176
|
+
|
|
177
|
+
Returns
|
|
178
|
+
-------
|
|
179
|
+
Mapping[object, object]
|
|
180
|
+
Postprocess data as a dictionary that keeps the original field names.
|
|
181
|
+
"""
|
|
182
|
+
|
|
183
|
+
self._require_available()
|
|
184
|
+
if self.payload is None:
|
|
185
|
+
raise self._unsupported("to_dict")
|
|
186
|
+
return cast(DictionaryExportMixin, self.payload).to_dict()
|
|
187
|
+
|
|
188
|
+
@property
|
|
189
|
+
def header(self) -> "PostprocessHeader | None":
|
|
190
|
+
"""Return the optional header associated with this postprocess result.
|
|
191
|
+
|
|
192
|
+
Returns
|
|
193
|
+
-------
|
|
194
|
+
PostprocessHeader | None
|
|
195
|
+
Header data when the result contains a header. Otherwise, `None`.
|
|
196
|
+
"""
|
|
197
|
+
|
|
198
|
+
self._require_available()
|
|
199
|
+
raw_mapping: Mapping[object, object] | None = payload_mapping(self._raw)
|
|
200
|
+
if raw_mapping is None or not isinstance(raw_mapping.get("header"), Mapping):
|
|
201
|
+
return None
|
|
202
|
+
from .artifacts import PostprocessHeader
|
|
203
|
+
|
|
204
|
+
return PostprocessHeader(
|
|
205
|
+
table=cast(Mapping[object, object], raw_mapping["header"])
|
|
206
|
+
)
|
|
207
|
+
|
|
208
|
+
def is_field_export(self) -> bool:
|
|
209
|
+
"""Return whether this record contains a Cartesian field export.
|
|
210
|
+
|
|
211
|
+
Returns
|
|
212
|
+
-------
|
|
213
|
+
bool
|
|
214
|
+
`True` when the record contains field data. Otherwise, `False`.
|
|
215
|
+
"""
|
|
216
|
+
|
|
217
|
+
return is_field_export_mapping(payload_mapping(self._raw), self.title)
|
|
218
|
+
|
|
219
|
+
@property
|
|
220
|
+
def fields(self) -> FieldExportPayload:
|
|
221
|
+
"""Return the field-export interface for this record.
|
|
222
|
+
|
|
223
|
+
Returns
|
|
224
|
+
-------
|
|
225
|
+
FieldExportPayload
|
|
226
|
+
Field data and field-navigation operations.
|
|
227
|
+
|
|
228
|
+
Raises
|
|
229
|
+
------
|
|
230
|
+
UnsupportedExportError
|
|
231
|
+
If the record does not contain field data.
|
|
232
|
+
"""
|
|
233
|
+
|
|
234
|
+
self._require_available()
|
|
235
|
+
if not isinstance(self.payload, FieldExportPayload):
|
|
236
|
+
raise self._unsupported("fields")
|
|
237
|
+
return self.payload
|
|
238
|
+
|
|
239
|
+
@property
|
|
240
|
+
def derivatives(
|
|
241
|
+
self,
|
|
242
|
+
) -> "TableDerivativeCollection | TableCollectionDerivativeCollection | StructuredDerivativeCollection":
|
|
243
|
+
"""Return parameter-derivative navigation for numeric postprocess data.
|
|
244
|
+
|
|
245
|
+
Returns
|
|
246
|
+
-------
|
|
247
|
+
TableDerivativeCollection | TableCollectionDerivativeCollection | StructuredDerivativeCollection
|
|
248
|
+
Name-based selection for canonical table or structured payloads.
|
|
249
|
+
"""
|
|
250
|
+
|
|
251
|
+
self._require_available()
|
|
252
|
+
if isinstance(self.payload, TablePayload):
|
|
253
|
+
return self.payload.derivatives
|
|
254
|
+
if isinstance(self.payload, TableCollectionPayload):
|
|
255
|
+
return self.payload.derivatives
|
|
256
|
+
if not isinstance(self.payload, _StructuredRecordPayload):
|
|
257
|
+
raise AttributeError("derivatives")
|
|
258
|
+
values: Mapping[object, object] = self.payload._value_mapping()
|
|
259
|
+
# Preserve established dynamic access for a user quantity named
|
|
260
|
+
# `derivatives` instead of shadowing it with the navigation view.
|
|
261
|
+
if "derivatives" in values:
|
|
262
|
+
raise AttributeError("derivatives")
|
|
263
|
+
from .structured_derivatives import (
|
|
264
|
+
StructuredDerivativeCollection,
|
|
265
|
+
_base_values,
|
|
266
|
+
_has_selected_numeric,
|
|
267
|
+
_parameter_branches,
|
|
268
|
+
)
|
|
269
|
+
|
|
270
|
+
base: Mapping[object, object] = _base_values(values)
|
|
271
|
+
branches: Mapping[str, Mapping[object, object]] = _parameter_branches(values)
|
|
272
|
+
return StructuredDerivativeCollection(
|
|
273
|
+
_branches={
|
|
274
|
+
name: branch
|
|
275
|
+
for name, branch in branches.items()
|
|
276
|
+
if _has_selected_numeric(branch, base)
|
|
277
|
+
},
|
|
278
|
+
_source=self.source_file,
|
|
279
|
+
_title=self.title,
|
|
280
|
+
_root=values,
|
|
281
|
+
)
|
|
282
|
+
|
|
283
|
+
def to_df(self, orient: str | None = None) -> "pd.DataFrame":
|
|
284
|
+
"""Return tabular postprocess data as a pandas `DataFrame`.
|
|
285
|
+
|
|
286
|
+
Parameters
|
|
287
|
+
----------
|
|
288
|
+
orient : {None, "wide", "long"}, optional
|
|
289
|
+
Select the table layout. Structured and table-collection payloads
|
|
290
|
+
support only the long layout.
|
|
291
|
+
|
|
292
|
+
Raises
|
|
293
|
+
------
|
|
294
|
+
InvalidConfigurationError
|
|
295
|
+
If the record is unavailable or does not contain tabular data.
|
|
296
|
+
UnsupportedExportError
|
|
297
|
+
If the payload does not support the requested layout.
|
|
298
|
+
|
|
299
|
+
Returns
|
|
300
|
+
-------
|
|
301
|
+
pandas.DataFrame
|
|
302
|
+
Postprocess data in the selected layout.
|
|
303
|
+
"""
|
|
304
|
+
|
|
305
|
+
if orient not in {None, "wide", "long"}:
|
|
306
|
+
raise ValueError("orient must be None, 'wide', or 'long'")
|
|
307
|
+
self._require_available()
|
|
308
|
+
if isinstance(self.payload, TableCollectionPayload):
|
|
309
|
+
if orient == "wide":
|
|
310
|
+
raise self._unsupported("to_df")
|
|
311
|
+
return self.payload.to_df(orient=orient)
|
|
312
|
+
if self.is_field_export():
|
|
313
|
+
raise self._unsupported("to_df")
|
|
314
|
+
if isinstance(self.payload, _StructuredRecordPayload):
|
|
315
|
+
if orient == "wide":
|
|
316
|
+
raise self._unsupported("to_df")
|
|
317
|
+
rows: list[dict[str, object]] = [
|
|
318
|
+
{"path": path, "value": value}
|
|
319
|
+
for path, value in flatten_payload(
|
|
320
|
+
self.payload._value_mapping(), path_prefix=""
|
|
321
|
+
)
|
|
322
|
+
]
|
|
323
|
+
return rows_to_dataframe(
|
|
324
|
+
materialize_rows(
|
|
325
|
+
rows,
|
|
326
|
+
prefix={
|
|
327
|
+
"postprocess_title": self.title,
|
|
328
|
+
"source_file": str(self.source_file),
|
|
329
|
+
},
|
|
330
|
+
)
|
|
331
|
+
)
|
|
332
|
+
if not isinstance(self.payload, TablePayload):
|
|
333
|
+
raise self._unsupported("to_df")
|
|
334
|
+
if orient in (None, "wide"):
|
|
335
|
+
return self.payload.to_df(orient=orient)
|
|
336
|
+
values: dict[object, object] = dict(self.payload.to_dict())
|
|
337
|
+
values.pop("title", None)
|
|
338
|
+
values.pop("header", None)
|
|
339
|
+
table_rows: list[dict[str, object]] | None = postprocess_payload_to_long_rows(
|
|
340
|
+
values
|
|
341
|
+
)
|
|
342
|
+
if table_rows is None:
|
|
343
|
+
raise InvalidConfigurationError("Postprocess payload is not tabular.")
|
|
344
|
+
return rows_to_dataframe(
|
|
345
|
+
materialize_rows(
|
|
346
|
+
table_rows,
|
|
347
|
+
prefix={
|
|
348
|
+
"postprocess_title": self.title,
|
|
349
|
+
"source_file": str(self.source_file),
|
|
350
|
+
},
|
|
351
|
+
)
|
|
352
|
+
)
|
|
353
|
+
|
|
354
|
+
def to_xarray(self) -> "XarrayDataTree":
|
|
355
|
+
"""Return postprocess data as an xarray `DataTree`.
|
|
356
|
+
|
|
357
|
+
Returns
|
|
358
|
+
-------
|
|
359
|
+
xarray.DataTree
|
|
360
|
+
Postprocess data in an xarray tree.
|
|
361
|
+
"""
|
|
362
|
+
|
|
363
|
+
self._require_available()
|
|
364
|
+
if self.is_field_export():
|
|
365
|
+
return self.fields.to_xarray()
|
|
366
|
+
if isinstance(self.payload, TableCollectionPayload):
|
|
367
|
+
return self.payload.to_xarray()
|
|
368
|
+
if self.payload is None:
|
|
369
|
+
if self._raw is None:
|
|
370
|
+
raise InvalidConfigurationError(
|
|
371
|
+
"Postprocess payload is unavailable and cannot be exported via to_xarray()."
|
|
372
|
+
)
|
|
373
|
+
raise self._unsupported("to_xarray")
|
|
374
|
+
return cast(XarrayExportMixin, self.payload).to_xarray()
|
|
375
|
+
|
|
376
|
+
def to_powerflux(self) -> PostprocessRecord:
|
|
377
|
+
"""Return a new record with field data converted to power flux.
|
|
378
|
+
|
|
379
|
+
Returns
|
|
380
|
+
-------
|
|
381
|
+
PostprocessRecord
|
|
382
|
+
New record containing converted postprocess data.
|
|
383
|
+
|
|
384
|
+
Raises
|
|
385
|
+
------
|
|
386
|
+
InvalidConfigurationError
|
|
387
|
+
If the postprocess data is not stored as named values.
|
|
388
|
+
"""
|
|
389
|
+
|
|
390
|
+
self._require_available()
|
|
391
|
+
raw_mapping: Mapping[object, object] | None = payload_mapping(self._raw)
|
|
392
|
+
if raw_mapping is None:
|
|
393
|
+
raise InvalidConfigurationError(
|
|
394
|
+
"Postprocess payload is not mapping-like and cannot be converted to power flux."
|
|
395
|
+
)
|
|
396
|
+
converted: dict[str, object] = convert_to_powerflux(
|
|
397
|
+
cast(Mapping[str, object], raw_mapping)
|
|
398
|
+
)
|
|
399
|
+
title_object: object | None = converted.get("title")
|
|
400
|
+
return PostprocessRecord(
|
|
401
|
+
source_file=self.source_file,
|
|
402
|
+
_raw=converted,
|
|
403
|
+
title=title_object if isinstance(title_object, str) else self.title,
|
|
404
|
+
)
|
|
405
|
+
|
|
406
|
+
def __getattr__(self, name: str) -> object:
|
|
407
|
+
self._require_available()
|
|
408
|
+
values: Mapping[object, object] = self.to_dict()
|
|
409
|
+
if name in values:
|
|
410
|
+
return values[name]
|
|
411
|
+
raise AttributeError(f"Postprocess mapping has no key {name!r}.")
|
|
412
|
+
|
|
413
|
+
def _field_payload_mapping(self, *, error_message: str) -> Mapping[object, object]:
|
|
414
|
+
self._require_available()
|
|
415
|
+
values: Mapping[object, object] | None = payload_mapping(self._raw)
|
|
416
|
+
if values is None:
|
|
417
|
+
raise InvalidConfigurationError(error_message)
|
|
418
|
+
return values
|
|
@@ -0,0 +1,279 @@
|
|
|
1
|
+
# SPDX-License-Identifier: MIT
|
|
2
|
+
# Copyright (c) 2001-2026 JCMwave GmbH
|
|
3
|
+
|
|
4
|
+
"""Persistent Resultbag storage for solve/result workflows."""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
import sqlite3
|
|
9
|
+
from collections.abc import Iterator, Mapping, Sequence
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
|
|
12
|
+
from .internal.resultbag.access import ResultbagEntry, ResultbagKeys, ResultbagView
|
|
13
|
+
from .internal.resultbag.query import ResultbagQuery
|
|
14
|
+
from .internal.resultbag.store import _ResultbagStore
|
|
15
|
+
from .internal.resultbag.utils import FilterInput, between
|
|
16
|
+
from .resultbag_management import ResultbagManagement
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class Resultbag:
|
|
20
|
+
"""Store and query solve results in a persistent Resultbag.
|
|
21
|
+
|
|
22
|
+
.. warning::
|
|
23
|
+
Open Resultbag files only from trusted sources. Loading stored results
|
|
24
|
+
or logs uses Python pickle and can execute code from the file.
|
|
25
|
+
|
|
26
|
+
Parameters
|
|
27
|
+
----------
|
|
28
|
+
filepath : str | Path
|
|
29
|
+
Resultbag storage path. When the path has no suffix, `.jcmrb` is
|
|
30
|
+
appended automatically.
|
|
31
|
+
keys : Mapping[str, object] | Sequence[str] | None, optional
|
|
32
|
+
project keys or a sequence of project key names that defines the
|
|
33
|
+
stored fields. When you reopen a Resultbag, `None` preserves its
|
|
34
|
+
existing fields. If stored data exists, call
|
|
35
|
+
`resultbag.management.reset()` before you change the fields.
|
|
36
|
+
|
|
37
|
+
Notes
|
|
38
|
+
-----
|
|
39
|
+
Use one Resultbag for one logical project and one set of source files.
|
|
40
|
+
Source-file checks determine whether stored results can be reused.
|
|
41
|
+
"""
|
|
42
|
+
|
|
43
|
+
management: ResultbagManagement
|
|
44
|
+
"""Provide advanced Resultbag maintenance and solve integration.
|
|
45
|
+
|
|
46
|
+
Use this namespace to add, inspect, remove, or reset stored entries, manage
|
|
47
|
+
attempt logs, and connect daemon submissions to Resultbag storage. These
|
|
48
|
+
operations access persisted data directly. Use `Resultbag.get_results(...)`
|
|
49
|
+
for normal result selection and the current typed result interfaces.
|
|
50
|
+
"""
|
|
51
|
+
|
|
52
|
+
def __init__(
|
|
53
|
+
self,
|
|
54
|
+
filepath: str | Path,
|
|
55
|
+
keys: Mapping[str, object] | Sequence[str] | None = None,
|
|
56
|
+
) -> None:
|
|
57
|
+
"""Open or create a Resultbag.
|
|
58
|
+
|
|
59
|
+
Parameters
|
|
60
|
+
----------
|
|
61
|
+
filepath : str | Path
|
|
62
|
+
Resultbag storage path. When the path has no suffix, `.jcmrb` is
|
|
63
|
+
appended automatically.
|
|
64
|
+
keys : Mapping[str, object] | Sequence[str] | None, optional
|
|
65
|
+
project keys or a sequence of project key names that defines the
|
|
66
|
+
stored fields. When you reopen a Resultbag, `None` preserves its
|
|
67
|
+
existing fields. If stored data exists, call
|
|
68
|
+
`resultbag.management.reset()` before you change the fields.
|
|
69
|
+
|
|
70
|
+
Raises
|
|
71
|
+
------
|
|
72
|
+
InvalidConfigurationError
|
|
73
|
+
If the parent directory does not exist, or if stored data exists
|
|
74
|
+
and the requested project key fields differ.
|
|
75
|
+
"""
|
|
76
|
+
|
|
77
|
+
self._store: _ResultbagStore = _ResultbagStore(filepath, keys)
|
|
78
|
+
self.management: ResultbagManagement = ResultbagManagement(self._store)
|
|
79
|
+
|
|
80
|
+
@property
|
|
81
|
+
def _filepath(self) -> Path:
|
|
82
|
+
"""Expose the normalized path for existing internal diagnostics."""
|
|
83
|
+
|
|
84
|
+
return self._store._filepath
|
|
85
|
+
|
|
86
|
+
@property
|
|
87
|
+
def _connection(self) -> sqlite3.Connection:
|
|
88
|
+
"""Expose the connection for existing internal diagnostics."""
|
|
89
|
+
|
|
90
|
+
return self._store._connection
|
|
91
|
+
|
|
92
|
+
@property
|
|
93
|
+
def _closed(self) -> bool:
|
|
94
|
+
"""Expose closure state for existing internal diagnostics."""
|
|
95
|
+
|
|
96
|
+
return self._store._closed
|
|
97
|
+
|
|
98
|
+
@classmethod
|
|
99
|
+
def _close_open_instances_for_exit(cls) -> None:
|
|
100
|
+
"""Close still-open Resultbag stores during process teardown."""
|
|
101
|
+
|
|
102
|
+
_ResultbagStore._close_open_instances_for_exit()
|
|
103
|
+
|
|
104
|
+
def close(self) -> None:
|
|
105
|
+
"""Close the Resultbag file.
|
|
106
|
+
|
|
107
|
+
Repeated calls have no effect.
|
|
108
|
+
"""
|
|
109
|
+
|
|
110
|
+
self._store.close()
|
|
111
|
+
|
|
112
|
+
def __enter__(self) -> Resultbag:
|
|
113
|
+
"""Return this Resultbag for context-managed usage.
|
|
114
|
+
|
|
115
|
+
Returns
|
|
116
|
+
-------
|
|
117
|
+
Resultbag
|
|
118
|
+
This Resultbag instance.
|
|
119
|
+
"""
|
|
120
|
+
|
|
121
|
+
return self
|
|
122
|
+
|
|
123
|
+
def __exit__(
|
|
124
|
+
self,
|
|
125
|
+
exc_type: type[BaseException] | None,
|
|
126
|
+
exc: BaseException | None,
|
|
127
|
+
tb: object | None,
|
|
128
|
+
) -> None:
|
|
129
|
+
"""Close the Resultbag when the context-managed block exits.
|
|
130
|
+
|
|
131
|
+
Parameters
|
|
132
|
+
----------
|
|
133
|
+
exc_type : type[BaseException] | None
|
|
134
|
+
Exception type raised in the managed block, if any.
|
|
135
|
+
exc : BaseException | None
|
|
136
|
+
Exception instance raised in the managed block, if any.
|
|
137
|
+
tb : object | None
|
|
138
|
+
Traceback object associated with `exc`, if any.
|
|
139
|
+
"""
|
|
140
|
+
|
|
141
|
+
del exc_type, exc, tb
|
|
142
|
+
self.close()
|
|
143
|
+
|
|
144
|
+
@property
|
|
145
|
+
def keys(self) -> ResultbagKeys:
|
|
146
|
+
"""Return stored project keys without loading result payloads.
|
|
147
|
+
|
|
148
|
+
Returns
|
|
149
|
+
-------
|
|
150
|
+
ResultbagKeys
|
|
151
|
+
project keys in stable order. The collection cannot be changed.
|
|
152
|
+
"""
|
|
153
|
+
|
|
154
|
+
return self._store.keys
|
|
155
|
+
|
|
156
|
+
@property
|
|
157
|
+
def suffixes(self) -> tuple[str | None, ...]:
|
|
158
|
+
"""Return stored suffix patterns in stable order.
|
|
159
|
+
|
|
160
|
+
Returns
|
|
161
|
+
-------
|
|
162
|
+
tuple[str | None, ...]
|
|
163
|
+
Available suffix patterns. `None` identifies entries without a
|
|
164
|
+
suffix pattern.
|
|
165
|
+
"""
|
|
166
|
+
|
|
167
|
+
return self._store.suffixes
|
|
168
|
+
|
|
169
|
+
def items(self) -> Iterator[tuple[dict[str, object], object]]:
|
|
170
|
+
"""Iterate over stored project keys and result payloads.
|
|
171
|
+
|
|
172
|
+
Returns
|
|
173
|
+
-------
|
|
174
|
+
Iterator[tuple[dict[str, object], object]]
|
|
175
|
+
project keys and stored raw result pairs in storage order.
|
|
176
|
+
|
|
177
|
+
Notes
|
|
178
|
+
-----
|
|
179
|
+
Only iterate over a Resultbag file that you trust. This method loads
|
|
180
|
+
serialized raw result data.
|
|
181
|
+
"""
|
|
182
|
+
|
|
183
|
+
yield from self._store.items()
|
|
184
|
+
|
|
185
|
+
def filter(
|
|
186
|
+
self,
|
|
187
|
+
key: str | None = None,
|
|
188
|
+
filter_value: FilterInput | None = None,
|
|
189
|
+
/,
|
|
190
|
+
**criteria: FilterInput,
|
|
191
|
+
) -> ResultbagQuery:
|
|
192
|
+
"""Return a read-only view filtered by project keys.
|
|
193
|
+
|
|
194
|
+
Parameters
|
|
195
|
+
----------
|
|
196
|
+
key : str | None, optional
|
|
197
|
+
project key name for a positional filter.
|
|
198
|
+
filter_value : FilterInput | None, optional
|
|
199
|
+
Exact value or an inclusive range created by `between(...)`.
|
|
200
|
+
**criteria : FilterInput
|
|
201
|
+
project key filters. An entry must match all filters.
|
|
202
|
+
|
|
203
|
+
Returns
|
|
204
|
+
-------
|
|
205
|
+
ResultbagQuery
|
|
206
|
+
Read-only access to matching Resultbag entries.
|
|
207
|
+
|
|
208
|
+
Raises
|
|
209
|
+
------
|
|
210
|
+
InvalidConfigurationError
|
|
211
|
+
If the filter is incomplete, empty, duplicated, or cannot compare
|
|
212
|
+
its bounds with a stored value.
|
|
213
|
+
"""
|
|
214
|
+
|
|
215
|
+
return self._store.filter(key, filter_value, **criteria)
|
|
216
|
+
|
|
217
|
+
def get_results(
|
|
218
|
+
self,
|
|
219
|
+
keys: Mapping[str, object] | Sequence[Mapping[str, object]] | None = None,
|
|
220
|
+
*,
|
|
221
|
+
suffix_pattern: str | None = None,
|
|
222
|
+
) -> object:
|
|
223
|
+
"""Load selected entries as their supported solve result shape.
|
|
224
|
+
|
|
225
|
+
Parameters
|
|
226
|
+
----------
|
|
227
|
+
keys : Mapping[str, object] | Sequence[Mapping[str, object]] | None, optional
|
|
228
|
+
One set or a sequence of project keys to load. `None` loads all
|
|
229
|
+
entries in the Resultbag.
|
|
230
|
+
suffix_pattern : str | None, optional
|
|
231
|
+
Suffix pattern to select. `None` selects entries without a suffix
|
|
232
|
+
pattern.
|
|
233
|
+
|
|
234
|
+
Returns
|
|
235
|
+
-------
|
|
236
|
+
SolveResult | BatchSolveResult | BundledSolveResult | BundledBatchSolveResult
|
|
237
|
+
Solve result shape for the selected entries.
|
|
238
|
+
|
|
239
|
+
Raises
|
|
240
|
+
------
|
|
241
|
+
InvalidConfigurationError
|
|
242
|
+
If no entry matches, the selection is ambiguous, the supplied
|
|
243
|
+
project keys are empty, or stored result shapes are incompatible.
|
|
244
|
+
|
|
245
|
+
Notes
|
|
246
|
+
-----
|
|
247
|
+
When project keys are provided, batch positions follow their supplied
|
|
248
|
+
sequence. With no selection, entries retain Resultbag storage order.
|
|
249
|
+
Only load results from a Resultbag file that you trust.
|
|
250
|
+
This method uses Python pickle to load stored results.
|
|
251
|
+
"""
|
|
252
|
+
|
|
253
|
+
return self._store.get_results(keys, suffix_pattern=suffix_pattern)
|
|
254
|
+
|
|
255
|
+
def has_results(self) -> bool:
|
|
256
|
+
"""Return whether at least one stored result exists.
|
|
257
|
+
|
|
258
|
+
Returns
|
|
259
|
+
-------
|
|
260
|
+
bool
|
|
261
|
+
`True` when the Resultbag contains a stored result. Otherwise,
|
|
262
|
+
`False`.
|
|
263
|
+
"""
|
|
264
|
+
|
|
265
|
+
return self._store.has_results()
|
|
266
|
+
|
|
267
|
+
def _iter_access_entries(self) -> Iterator[ResultbagEntry]:
|
|
268
|
+
"""Provide the internal read seam used by filtered views."""
|
|
269
|
+
|
|
270
|
+
yield from self._store._iter_access_entries()
|
|
271
|
+
|
|
272
|
+
|
|
273
|
+
__all__ = [
|
|
274
|
+
"FilterInput",
|
|
275
|
+
"Resultbag",
|
|
276
|
+
"ResultbagQuery",
|
|
277
|
+
"ResultbagView",
|
|
278
|
+
"between",
|
|
279
|
+
]
|