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,226 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Filtered Resultbag query view implementation."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import json
9
+ from collections.abc import Iterator, Mapping, Sequence
10
+ from typing import Protocol, cast
11
+
12
+ from .access import (
13
+ ResultbagEntry,
14
+ ResultbagKeys,
15
+ ResultbagReadable,
16
+ ResultbagView,
17
+ )
18
+ from .utils import (
19
+ _build_filter_specs,
20
+ _canonicalize_key_value,
21
+ _FilterSpec,
22
+ )
23
+
24
+
25
+ class ResultbagLike(Protocol):
26
+ """Protocol for Resultbag-like objects consumed by ResultbagQuery."""
27
+
28
+ def items(self) -> Iterator[tuple[dict[str, object], object]]:
29
+ """Iterate key/result payload pairs."""
30
+
31
+ ...
32
+
33
+ def _iter_access_entries(self) -> Iterator[ResultbagEntry]:
34
+ """Iterate entries with suffix metadata."""
35
+
36
+ ...
37
+
38
+
39
+ class ResultbagQuery(ResultbagView):
40
+ """Provide read-only access to Resultbag entries that match filters.
41
+
42
+ The Resultbag loads each entry only when an operation needs the entry.
43
+ Obtain a query from `Resultbag.filter(...)`; do not construct this class
44
+ directly.
45
+ """
46
+
47
+ def __init__(
48
+ self,
49
+ resultbag: ResultbagLike,
50
+ specs: Sequence[_FilterSpec],
51
+ ) -> None:
52
+
53
+ super().__init__(cast(ResultbagReadable, resultbag), specs)
54
+ self._resultbag: ResultbagLike = resultbag
55
+ self._specs: tuple[_FilterSpec, ...] = tuple(specs)
56
+
57
+ def _matches(self, keys: Mapping[str, object]) -> bool:
58
+ """Check whether values matches expected constraints.
59
+
60
+ Parameters
61
+ ----------
62
+ keys : Mapping[str, object]
63
+ Key payload supplied via `keys` for filtering/lookup.
64
+
65
+ Returns
66
+ -------
67
+ bool
68
+ True when the expected condition is satisfied.
69
+
70
+ Notes
71
+ -----
72
+ Internal API: this helper is an implementation detail and may change
73
+ without notice.
74
+ """
75
+
76
+ spec: _FilterSpec
77
+ for spec in self._specs:
78
+ if not spec.matches(keys):
79
+ return False
80
+ return True
81
+
82
+ @property
83
+ def keys(self) -> ResultbagKeys:
84
+ """Return the project keys that match all filters.
85
+
86
+ Returns
87
+ -------
88
+ ResultbagKeys
89
+ Matching project keys in a stable order.
90
+ """
91
+
92
+ unique_keys: dict[str, dict[str, object]] = {}
93
+ for entry in self._access_entries():
94
+ unique_keys[_key_identity(entry.keys)] = dict(entry.keys)
95
+ return ResultbagKeys(unique_keys[key] for key in sorted(unique_keys))
96
+
97
+ def items(self) -> Iterator[tuple[dict[str, object], object]]:
98
+ """Return matching project keys with their stored results.
99
+
100
+ Returns
101
+ -------
102
+ Iterator[tuple[dict[str, object], object]]
103
+ Matching pairs sorted by project keys.
104
+
105
+ Notes
106
+ -----
107
+ Only iterate over a Resultbag file that you trust. This method uses
108
+ Python pickle to load stored results.
109
+ """
110
+
111
+ matching_items: list[tuple[dict[str, object], object]] = [
112
+ (keys_dict, result_payload)
113
+ for keys_dict, result_payload in self._resultbag.items()
114
+ if self._matches(keys_dict)
115
+ ]
116
+ matching_items.sort(key=lambda item: _key_identity(item[0]))
117
+ yield from matching_items
118
+
119
+ def _access_entries(self) -> Iterator[ResultbagEntry]:
120
+ """Iterate entries that satisfy this query's filter conditions."""
121
+
122
+ entry: ResultbagEntry
123
+ for entry in self._resultbag._iter_access_entries():
124
+ if self._matches(entry.keys):
125
+ yield entry
126
+
127
+ def filter(
128
+ self,
129
+ key: str | None = None,
130
+ filter_value: object | None = None,
131
+ /,
132
+ **criteria: object,
133
+ ) -> ResultbagQuery:
134
+ """Narrow the selection by adding project key filters.
135
+
136
+ Parameters
137
+ ----------
138
+ key : str | None, optional
139
+ project key name for a positional filter.
140
+ filter_value : object | None, optional
141
+ Value for a positional filter. Use a plain value for an exact
142
+ match. Use `between(lower, upper)` to include both limits.
143
+ **criteria : object
144
+ project key filters. An entry must match all filters. Plain values,
145
+ including tuples, require an exact match. Use
146
+ `between(lower, upper)` to include both limits.
147
+
148
+ Returns
149
+ -------
150
+ ResultbagQuery
151
+ Read-only access to entries that match all old and new filters.
152
+
153
+ Raises
154
+ ------
155
+ InvalidConfigurationError
156
+ If no filter is supplied, a positional filter is incomplete, a
157
+ project key name is empty or duplicated, or bounds cannot be
158
+ compared with a stored value.
159
+ """
160
+
161
+ additional_specs: tuple[_FilterSpec, ...] = _build_filter_specs(
162
+ key, filter_value, criteria
163
+ )
164
+ return ResultbagQuery(
165
+ self._resultbag,
166
+ (*self._specs, *additional_specs),
167
+ )
168
+
169
+ @property
170
+ def suffixes(self) -> tuple[str | None, ...]:
171
+ """Return suffix patterns for the matching Resultbag entries.
172
+
173
+ Returns
174
+ -------
175
+ tuple[str | None, ...]
176
+ Matching suffix patterns in a stable order.
177
+ """
178
+
179
+ return ResultbagView(cast(ResultbagReadable, self), ()).suffixes
180
+
181
+ def get_results(
182
+ self,
183
+ keys: Mapping[str, object] | Sequence[Mapping[str, object]] | None = None,
184
+ *,
185
+ suffix_pattern: str | None = None,
186
+ ) -> object:
187
+ """Load matching Resultbag entries as solve results.
188
+
189
+ Parameters
190
+ ----------
191
+ keys : Mapping[str, object] | Sequence[Mapping[str, object]] | None, optional
192
+ One set or a sequence of project keys to load. `None` loads all
193
+ matching entries.
194
+ suffix_pattern : str | None, optional
195
+ Suffix pattern to select. `None` selects entries that have no suffix
196
+ pattern.
197
+
198
+ Returns
199
+ -------
200
+ SolveResult | BatchSolveResult | BundledSolveResult | BundledBatchSolveResult
201
+ Solve result shape for the selected entries.
202
+
203
+ Raises
204
+ ------
205
+ InvalidConfigurationError
206
+ If no entry matches, the selection is ambiguous, an empty sequence
207
+ of project keys is supplied, or stored result shapes are not
208
+ compatible.
209
+
210
+ Notes
211
+ -----
212
+ Multiple entries are sorted by project keys before the method assigns
213
+ new batch positions. Only load results from a Resultbag file that you
214
+ trust. This method uses Python pickle to load stored objects.
215
+ """
216
+
217
+ return ResultbagView(cast(ResultbagReadable, self), ()).get_results(
218
+ keys,
219
+ suffix_pattern=suffix_pattern,
220
+ )
221
+
222
+
223
+ def _key_identity(keys: Mapping[str, object]) -> str:
224
+ """Return the canonical deterministic identity used for view ordering."""
225
+
226
+ return json.dumps(_canonicalize_key_value(keys), sort_keys=True, default=str)
@@ -0,0 +1,407 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Versioned raw Resultbag records and result promotion."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import os
9
+ from collections.abc import Mapping
10
+ from pathlib import Path
11
+ from typing import cast
12
+
13
+ from ....exceptions import InvalidConfigurationError
14
+ from ...artifacts import ComputationalCosts, Eigenvalues
15
+ from ...payloads import DictionaryExportMixin
16
+ from ...postprocess_record import PostprocessRecord
17
+
18
+ RAW_RESULT_FORMAT_VERSION: int = 1
19
+ RESULTBAG_SOURCE: str = "resultbag"
20
+
21
+
22
+ def is_raw_result_record(value: object) -> bool:
23
+ """Return whether ``value`` is a supported raw Resultbag record."""
24
+
25
+ if not isinstance(value, Mapping):
26
+ return False
27
+ return value.get("format_version") == RAW_RESULT_FORMAT_VERSION and isinstance(
28
+ value.get("projects"), list
29
+ )
30
+
31
+
32
+ def raw_result_project_count(value: object) -> int:
33
+ """Return the number of project payloads in a raw result record."""
34
+
35
+ return len(_raw_projects(value))
36
+
37
+
38
+ def raw_result_from_solve_result(result: object) -> dict[str, object]:
39
+ """Build a raw record from one single or bundled solve result."""
40
+
41
+ from ...models import BundledSolveResult, SolveResult
42
+
43
+ if isinstance(result, SolveResult):
44
+ projects: list[dict[str, object]] = [
45
+ _raw_project_from_result(
46
+ result,
47
+ source_root=_project_source_root(result.project_file),
48
+ )
49
+ ]
50
+ elif isinstance(result, BundledSolveResult):
51
+ result_project_files: tuple[Path, ...] = tuple(
52
+ project_file
53
+ for entry in result.entries
54
+ for project_file in (entry.result.project_file or entry.project_file,)
55
+ if project_file is not None
56
+ )
57
+ project_identity_files: tuple[Path, ...] = tuple(
58
+ project_file
59
+ for entry in result.entries
60
+ for project_file in (entry.project_file or entry.result.project_file,)
61
+ if project_file is not None
62
+ )
63
+ source_root: Path | None = _common_source_root(result_project_files)
64
+ project_identity_root: Path | None = _common_source_root(project_identity_files)
65
+ projects = [
66
+ _raw_project_from_result(
67
+ entry.result,
68
+ source_root=source_root,
69
+ include_project_identity=True,
70
+ project_identity=entry.project_file or entry.result.project_file,
71
+ project_identity_root=project_identity_root,
72
+ )
73
+ for entry in result.entries
74
+ ]
75
+ else:
76
+ raise InvalidConfigurationError(
77
+ "Resultbag persistence requires a SolveResult or BundledSolveResult."
78
+ )
79
+ return {"format_version": RAW_RESULT_FORMAT_VERSION, "projects": projects}
80
+
81
+
82
+ def promote_raw_result(
83
+ raw_result: object,
84
+ *,
85
+ keys: Mapping[str, object] | None = None,
86
+ log: object | None = None,
87
+ ) -> object:
88
+ """Promote a raw Resultbag record into the current result interface."""
89
+
90
+ from ...models import BundledSolveEntry, BundledSolveResult, SolveResult
91
+
92
+ projects: list[object] = _raw_projects(raw_result)
93
+ promoted: list[object] = [
94
+ _promote_project(project, log=log if index == 0 else None, keys=keys)
95
+ for index, project in enumerate(projects)
96
+ ]
97
+ if len(promoted) == 1:
98
+ return promoted[0]
99
+ return BundledSolveResult(
100
+ entries=tuple(
101
+ BundledSolveEntry(
102
+ project_file=None,
103
+ result=cast(SolveResult, project),
104
+ _project_identity=_project_identity(project_record),
105
+ )
106
+ for project_record, project in zip(projects, promoted)
107
+ )
108
+ )
109
+
110
+
111
+ def _raw_projects(raw_result: object) -> list[object]:
112
+ """Validate and return raw project records."""
113
+
114
+ if isinstance(raw_result, Mapping):
115
+ version: object = raw_result.get("format_version")
116
+ if version != RAW_RESULT_FORMAT_VERSION:
117
+ raise InvalidConfigurationError(
118
+ f"Unsupported Resultbag raw format version: {version!r}."
119
+ )
120
+ if not is_raw_result_record(raw_result):
121
+ raise InvalidConfigurationError(
122
+ "Resultbag entry has an unsupported raw format."
123
+ )
124
+ projects_object: object = cast(Mapping[str, object], raw_result)["projects"]
125
+ projects: list[object] = cast(list[object], projects_object)
126
+ if not projects:
127
+ raise InvalidConfigurationError("Resultbag raw record contains no projects.")
128
+ if not all(isinstance(project, Mapping) for project in projects):
129
+ raise InvalidConfigurationError("Resultbag project records must be mappings.")
130
+ return projects
131
+
132
+
133
+ def _raw_project_from_result(
134
+ result: object,
135
+ *,
136
+ source_root: Path | None,
137
+ include_project_identity: bool = False,
138
+ project_identity: Path | None = None,
139
+ project_identity_root: Path | None = None,
140
+ ) -> dict[str, object]:
141
+ """Extract file-backed data from one SolveResult."""
142
+
143
+ from ...models import SolveResult
144
+
145
+ if not isinstance(result, SolveResult):
146
+ raise InvalidConfigurationError(
147
+ "Resultbag bundle entries must be SolveResult values."
148
+ )
149
+ field_data: object | None = None
150
+ result_file: Path | None = result.file
151
+ if result._field_data is not None:
152
+ field_data = dict(result._field_data)
153
+ elif result_file is not None and result_file.is_file():
154
+ from ....loaders import load_cartesian_fields
155
+
156
+ try:
157
+ field_payload: object = load_cartesian_fields(result_file)
158
+ except (InvalidConfigurationError, RuntimeError, TypeError, ValueError):
159
+ # Result files can contain non-Cartesian fieldbags. They remain
160
+ # available through the normal result-file loader, but cannot be
161
+ # embedded in the Cartesian raw-record schema.
162
+ field_payload = None
163
+ field_mapping: object = getattr(field_payload, "_mapping", None)
164
+ if isinstance(field_mapping, Mapping):
165
+ field_data = dict(field_mapping)
166
+ elif isinstance(field_payload, DictionaryExportMixin):
167
+ field_data = dict(field_payload.to_dict())
168
+ costs: object | None = None if result.costs is None else dict(result.costs._raw)
169
+ eigenvalues: object | None = (
170
+ None if result.eigenvalues is None else dict(result.eigenvalues._raw)
171
+ )
172
+ postprocesses: list[dict[str, object]] = []
173
+ postprocess_sources: list[str | None] = []
174
+ postprocess: PostprocessRecord
175
+ for postprocess in result.postprocesses:
176
+ raw_payload: object | None = postprocess._raw
177
+ if raw_payload is not None and not isinstance(raw_payload, Mapping):
178
+ if postprocess.payload is None or not isinstance(
179
+ postprocess.payload, DictionaryExportMixin
180
+ ):
181
+ raw_payload = None
182
+ else:
183
+ raw_payload = postprocess.payload.to_dict()
184
+ postprocesses.append(
185
+ {
186
+ "title": postprocess.title,
187
+ "available": postprocess.available,
188
+ "failure_message": postprocess.failure_message,
189
+ "data": raw_payload,
190
+ }
191
+ )
192
+ postprocess_sources.append(
193
+ _relative_source_path(postprocess.source_file, source_root)
194
+ )
195
+ sources: dict[str, object] = {
196
+ "field": _relative_source_path(result_file, source_root),
197
+ "costs": _relative_source_path(
198
+ None if result.costs is None else result.costs.source,
199
+ source_root,
200
+ ),
201
+ "eigenvalues": _relative_source_path(
202
+ None if result.eigenvalues is None else result.eigenvalues.source,
203
+ source_root,
204
+ ),
205
+ "postprocesses": postprocess_sources,
206
+ }
207
+ raw_project: dict[str, object] = {
208
+ "log": _log_to_dict(result.log),
209
+ "field": field_data,
210
+ "costs": costs,
211
+ "eigenvalues": eigenvalues,
212
+ "postprocesses": postprocesses,
213
+ "sources": sources,
214
+ }
215
+ if include_project_identity:
216
+ raw_project["project_identity"] = _relative_source_path(
217
+ project_identity or result.project_file,
218
+ project_identity_root or source_root,
219
+ )
220
+ return raw_project
221
+
222
+
223
+ def _project_source_root(project_file: Path | None) -> Path | None:
224
+ """Return the source root for a single project result."""
225
+
226
+ return None if project_file is None else project_file.expanduser().resolve().parent
227
+
228
+
229
+ def _common_source_root(project_files: tuple[Path, ...]) -> Path | None:
230
+ """Return the common source root for bundled project results."""
231
+
232
+ if not project_files:
233
+ return None
234
+ parent_names: list[str] = [
235
+ str(project_file.expanduser().resolve().parent)
236
+ for project_file in project_files
237
+ ]
238
+ try:
239
+ return Path(os.path.commonpath(parent_names))
240
+ except ValueError:
241
+ return None
242
+
243
+
244
+ def _relative_source_path(source: object, source_root: Path | None) -> str | None:
245
+ """Return a portable source path relative to the selected source root."""
246
+
247
+ if not isinstance(source, Path) or source_root is None:
248
+ return None
249
+ try:
250
+ return source.expanduser().resolve().relative_to(source_root).as_posix()
251
+ except (OSError, ValueError):
252
+ return None
253
+
254
+
255
+ def _promote_project(
256
+ project: object,
257
+ *,
258
+ keys: Mapping[str, object] | None,
259
+ log: object | None,
260
+ ) -> object:
261
+ """Promote one raw project mapping."""
262
+
263
+ from ...models import SolveExecutionLog, SolveResult
264
+ from ...postprocess import PostprocessCollection
265
+
266
+ project_mapping: Mapping[str, object] = cast(Mapping[str, object], project)
267
+ result = SolveResult(keys=keys)
268
+ result._file = None
269
+ result._artifact_root = None
270
+ sources: Mapping[str, object] = _source_mapping(project_mapping)
271
+ result._field_source = _promoted_source(sources.get("field"))
272
+ costs_object: object = project_mapping.get("costs")
273
+ result._costs = (
274
+ None
275
+ if not isinstance(costs_object, Mapping)
276
+ else ComputationalCosts(
277
+ table=dict(costs_object),
278
+ source=_promoted_source(sources.get("costs")),
279
+ )
280
+ )
281
+ eigenvalues_object: object = project_mapping.get("eigenvalues")
282
+ result._eigenvalues = (
283
+ None
284
+ if not isinstance(eigenvalues_object, Mapping)
285
+ else Eigenvalues(
286
+ table=dict(eigenvalues_object),
287
+ source=_promoted_source(sources.get("eigenvalues")),
288
+ )
289
+ )
290
+ field_data: object | None = project_mapping.get("field")
291
+ if field_data is not None and isinstance(field_data, Mapping):
292
+ result._field_data = dict(field_data)
293
+ records: list[PostprocessRecord] = []
294
+ raw_records: object = project_mapping.get("postprocesses", [])
295
+ postprocess_sources: object = sources.get("postprocesses", [])
296
+ if isinstance(raw_records, list):
297
+ for index, raw_record in enumerate(raw_records):
298
+ if not isinstance(raw_record, Mapping):
299
+ continue
300
+ title_object: object = raw_record.get("title")
301
+ title: str | None = title_object if isinstance(title_object, str) else None
302
+ available_object: object = raw_record.get("available", True)
303
+ available: bool = bool(available_object)
304
+ failure_object: object = raw_record.get("failure_message")
305
+ failure_message: str | None = (
306
+ failure_object if isinstance(failure_object, str) else None
307
+ )
308
+ records.append(
309
+ PostprocessRecord(
310
+ source_file=_promoted_source(
311
+ _indexed_source(postprocess_sources, index)
312
+ ),
313
+ _raw=raw_record.get("data"),
314
+ title=title,
315
+ available=available,
316
+ failure_message=failure_message,
317
+ )
318
+ )
319
+ result._postprocesses = PostprocessCollection(records=tuple(records))
320
+ result._artifacts_loaded = True
321
+ project_log: object = log
322
+ if project_log is None:
323
+ project_log = project_mapping.get("log")
324
+ if isinstance(project_log, Mapping):
325
+ backend_object: object = project_log.get("backend")
326
+ if backend_object in {"local", "daemon"}:
327
+ result.log = SolveExecutionLog(
328
+ backend=backend_object,
329
+ stdout=str(project_log.get("stdout", "")),
330
+ stderr=str(project_log.get("stderr", "")),
331
+ return_code=cast(int | None, project_log.get("return_code")),
332
+ streamed_to_console=bool(project_log.get("streamed_to_console", False)),
333
+ )
334
+ return result
335
+
336
+
337
+ def _source_mapping(project: Mapping[str, object]) -> Mapping[str, object]:
338
+ """Return optional source metadata from a raw project record."""
339
+
340
+ sources: object = project.get("sources")
341
+ return sources if isinstance(sources, Mapping) else {}
342
+
343
+
344
+ def _indexed_source(sources: object, index: int) -> object:
345
+ """Return one indexed source value when source metadata is available."""
346
+
347
+ if not isinstance(sources, list) or index >= len(sources):
348
+ return None
349
+ return sources[index]
350
+
351
+
352
+ def _promoted_source(source: object) -> str | Path:
353
+ """Return a safe relative source path or the Resultbag fallback."""
354
+
355
+ if not isinstance(source, str) or not source:
356
+ return RESULTBAG_SOURCE
357
+ candidate: Path = Path(source)
358
+ if candidate.is_absolute() or ".." in candidate.parts:
359
+ return RESULTBAG_SOURCE
360
+ return candidate
361
+
362
+
363
+ def _project_identity(project: object) -> str | None:
364
+ """Return a safe bundle-relative project identity from a raw entry."""
365
+
366
+ if not isinstance(project, Mapping):
367
+ return None
368
+ identity: object = project.get("project_identity")
369
+ if not isinstance(identity, str) or not identity:
370
+ return None
371
+ candidate: Path = Path(identity)
372
+ if candidate.is_absolute() or ".." in candidate.parts:
373
+ return None
374
+ return candidate.as_posix()
375
+
376
+
377
+ def _log_to_dict(log: object | None) -> dict[str, object] | None:
378
+ """Convert a solve execution log into stable dictionary data."""
379
+
380
+ if log is None:
381
+ return None
382
+ from ...models import SolveExecutionLog
383
+
384
+ if isinstance(log, SolveExecutionLog):
385
+ return {
386
+ "backend": log.backend,
387
+ "stdout": log.stdout,
388
+ "stderr": log.stderr,
389
+ "return_code": log.return_code,
390
+ "streamed_to_console": log.streamed_to_console,
391
+ }
392
+ if isinstance(log, Mapping):
393
+ backend_object: object = log.get("backend", log.get("backend_used"))
394
+ return {
395
+ "backend": backend_object,
396
+ "stdout": str(log.get("stdout", "")),
397
+ "stderr": str(log.get("stderr", "")),
398
+ "return_code": log.get("return_code"),
399
+ "streamed_to_console": bool(log.get("streamed_to_console", False)),
400
+ }
401
+ return {
402
+ "backend": "daemon",
403
+ "stdout": str(log),
404
+ "stderr": "",
405
+ "return_code": 0,
406
+ "streamed_to_console": False,
407
+ }