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,180 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Execution helpers for solve orchestration runtime branches."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from collections.abc import Mapping
9
+ from logging import Logger
10
+ from pathlib import Path
11
+ from typing import TYPE_CHECKING, Protocol
12
+
13
+ from ..context import SolverContext
14
+ from ..exceptions import (
15
+ BackendUnavailableError,
16
+ ConfigMappingError,
17
+ RuntimeContextError,
18
+ SolveExecutionError,
19
+ )
20
+ from ..internal.diagnostics import parse_source_position
21
+ from ..results import Resultbag, SolveExecutionLog, SolveResult, SolveSubmission
22
+ from .types import DispatchMode, SolveMode, WaitBreakWhen, WaitOnTimeout
23
+
24
+ if TYPE_CHECKING:
25
+ from ..daemon.handler import DaemonHandler
26
+
27
+
28
+ class _BinaryCaller(Protocol):
29
+ """Protocol for the async subprocess boundary used by local solves."""
30
+
31
+ async def __call__(
32
+ self,
33
+ binary_path: Path,
34
+ args: list[str] | str | None = None,
35
+ cwd: Path | None = None,
36
+ stream_output: bool = False,
37
+ env: Mapping[str, str] | None = None,
38
+ ) -> tuple[str, str, int | None]: ...
39
+
40
+
41
+ async def execute_local_solve_runtime(
42
+ *,
43
+ result: SolveResult,
44
+ context: SolverContext,
45
+ prepared_project: Path,
46
+ quiet: bool,
47
+ mode: SolveMode = "solve",
48
+ call_binary: _BinaryCaller,
49
+ logger: Logger,
50
+ ) -> object:
51
+ """Run local JCMsolve and update result/log payload."""
52
+
53
+ solve_binary_path: Path | None = context.jcm_solve
54
+ if solve_binary_path is None or not solve_binary_path.is_file():
55
+ if context.jcm_root is None:
56
+ raise RuntimeContextError(
57
+ "JCMsolve binary is not available in the resolved context because "
58
+ "JCMROOT is not configured and binary discovery did not run. "
59
+ "Set JCMROOT or pass `create_context(jcm_root=...)`."
60
+ )
61
+ raise RuntimeContextError(
62
+ "JCMsolve binary is not available in the resolved context. "
63
+ f"Expected binary at: {solve_binary_path}."
64
+ )
65
+
66
+ stdout_text: str
67
+ stderr_text: str
68
+ return_code: int | None
69
+ stdout_text, stderr_text, return_code = await call_binary(
70
+ solve_binary_path,
71
+ args=[
72
+ "--post_process" if mode == "postprocess" else "--solve",
73
+ str(prepared_project),
74
+ ],
75
+ cwd=prepared_project.parent,
76
+ stream_output=not quiet,
77
+ env=context._subprocess_environment(),
78
+ )
79
+ result.log = SolveExecutionLog(
80
+ backend="local",
81
+ stdout=stdout_text,
82
+ stderr=stderr_text,
83
+ return_code=return_code,
84
+ streamed_to_console=not quiet,
85
+ )
86
+
87
+ if return_code not in (0, None):
88
+ execution_error: SolveExecutionError = SolveExecutionError(
89
+ backend="local",
90
+ exit_code=return_code,
91
+ log=stderr_text,
92
+ )
93
+ source_path: Path | None
94
+ line: int | None
95
+ column: int | None
96
+ source_path, line, column = parse_source_position(
97
+ stderr_text,
98
+ base_dir=prepared_project.parent,
99
+ )
100
+ if source_path is not None:
101
+ raise ConfigMappingError(
102
+ "JCMsolve failed with source-mapped diagnostics.",
103
+ source=source_path,
104
+ line=line,
105
+ column=column,
106
+ ) from execution_error
107
+ raise execution_error
108
+
109
+ if stderr_text.strip():
110
+ logger.warning("*** JCMsolve partially failed. ==>\n\n%s", stderr_text)
111
+
112
+ result.refresh_artifacts()
113
+ return {
114
+ "backend_used": result.backend_used,
115
+ "stdout": stdout_text,
116
+ "stderr": stderr_text,
117
+ "return_code": return_code,
118
+ "streamed_to_console": not quiet,
119
+ }
120
+
121
+
122
+ async def submit_or_wait_daemon_runtime(
123
+ *,
124
+ result: SolveResult,
125
+ daemon_handler: DaemonHandler | None,
126
+ prepared_project: Path,
127
+ source_project: Path,
128
+ resolved_keys: Mapping[str, object],
129
+ resultbag: Resultbag | None,
130
+ suffix_pattern: str | None,
131
+ dispatch: DispatchMode,
132
+ wait_break_when: WaitBreakWhen,
133
+ wait_timeout: float | None,
134
+ wait_on_timeout: WaitOnTimeout,
135
+ wait_progress: bool,
136
+ wait_progress_label: str | None,
137
+ mode: SolveMode = "solve",
138
+ ) -> object:
139
+ """Submit daemon solve and optionally wait for completion."""
140
+
141
+ if daemon_handler is None:
142
+ raise BackendUnavailableError(
143
+ "Daemon backend resolved without an available handler."
144
+ )
145
+ daemon_job_id: int = daemon_handler._submit_solve_job(
146
+ result=result,
147
+ project_file=prepared_project,
148
+ source_project_mappings=((prepared_project, source_project),),
149
+ keys=dict(resolved_keys),
150
+ resultbag=resultbag,
151
+ suffix_pattern=suffix_pattern,
152
+ mode=mode,
153
+ )
154
+ result.daemon_job_id = daemon_job_id
155
+
156
+ if dispatch == "wait":
157
+ waited_result: SolveResult = await daemon_handler.wait(
158
+ SolveSubmission(
159
+ job_id=daemon_job_id,
160
+ result=result,
161
+ keys=dict(resolved_keys),
162
+ index=None,
163
+ )._bind_runtime(
164
+ waiter=daemon_handler,
165
+ source_project_mappings=((prepared_project, source_project),),
166
+ ),
167
+ asynchronous=True,
168
+ break_when=wait_break_when,
169
+ timeout=wait_timeout,
170
+ on_timeout=wait_on_timeout,
171
+ on_error="raise",
172
+ progress=wait_progress,
173
+ progress_label=wait_progress_label,
174
+ )
175
+ return waited_result
176
+
177
+ return {
178
+ "backend_used": result.backend_used,
179
+ "daemon_job_id": daemon_job_id,
180
+ }
@@ -0,0 +1,128 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Routing and option-validation helpers for solve orchestration."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from collections.abc import Mapping, Sequence
9
+ from pathlib import Path
10
+
11
+ from ..exceptions import InvalidConfigurationError
12
+ from .path_resolution import resolve_project_input_path
13
+ from .staging import stage_bundle_runtime_inputs
14
+ from .types import (
15
+ BatchOnError,
16
+ DispatchMode,
17
+ ProjectBundleInput,
18
+ WaitBreakWhen,
19
+ WaitOnTimeout,
20
+ )
21
+ from .working_dirs import resolve_bundle_common_base
22
+
23
+
24
+ def _stage_bundle_common_runtime_inputs(
25
+ *,
26
+ project_files: Sequence[Path],
27
+ bundle_root: Path | None,
28
+ ) -> None:
29
+ """Stage shared runtime inputs from the bundle common base when needed."""
30
+
31
+ if bundle_root is None:
32
+ return
33
+
34
+ common_base: Path = resolve_bundle_common_base(project_files=project_files)
35
+ stage_bundle_runtime_inputs(
36
+ source_root=common_base,
37
+ target_root=bundle_root.resolve(),
38
+ skip_files=set(),
39
+ )
40
+
41
+
42
+ def is_project_bundle(project_file: object) -> bool:
43
+ """Return whether `project_file` represents an ordered project bundle."""
44
+
45
+ if isinstance(project_file, (str, Path)):
46
+ return False
47
+ return isinstance(project_file, Sequence)
48
+
49
+
50
+ def normalize_project_bundle(
51
+ project_file: ProjectBundleInput,
52
+ *,
53
+ caller_file: str | Path | None = None,
54
+ ) -> tuple[Path, ...]:
55
+ """Normalize an ordered project bundle into resolved `Path` objects."""
56
+
57
+ project_paths: list[Path] = [
58
+ resolve_project_input_path(raw_project_file, caller_file=caller_file)
59
+ for raw_project_file in project_file
60
+ ]
61
+ if not project_paths:
62
+ raise InvalidConfigurationError(
63
+ "Project bundle input must contain at least one project file."
64
+ )
65
+ return tuple(project_paths)
66
+
67
+
68
+ def is_batch_keys(
69
+ keys: Mapping[str, object] | Sequence[Mapping[str, object]] | None,
70
+ ) -> bool:
71
+ """Return whether keys represent a batch input."""
72
+
73
+ if keys is None:
74
+ return False
75
+ if isinstance(keys, Mapping):
76
+ return False
77
+ if isinstance(keys, (str, bytes, bytearray)):
78
+ return False
79
+ return True
80
+
81
+
82
+ def _validate_dispatch_options(
83
+ *,
84
+ dispatch: DispatchMode,
85
+ on_error: BatchOnError,
86
+ max_retries: int,
87
+ wait_break_when: WaitBreakWhen,
88
+ wait_timeout: float | None,
89
+ wait_on_timeout: WaitOnTimeout,
90
+ wait_progress: bool,
91
+ wait_progress_label: str | None,
92
+ ) -> None:
93
+ """Validate dispatch/wait option combinations."""
94
+
95
+ if dispatch not in ("wait", "submit"):
96
+ raise InvalidConfigurationError(f"Unsupported dispatch policy: {dispatch!r}")
97
+ if max_retries < 0:
98
+ raise InvalidConfigurationError("max_retries must be >= 0.")
99
+ if dispatch != "submit":
100
+ return
101
+ if max_retries != 0:
102
+ raise InvalidConfigurationError(
103
+ "`max_retries` is only valid when `dispatch='wait'`."
104
+ )
105
+ if on_error != "raise":
106
+ raise InvalidConfigurationError(
107
+ "`on_error` is only valid when `dispatch='wait'`."
108
+ )
109
+ if wait_break_when != "all":
110
+ raise InvalidConfigurationError(
111
+ "`wait_break_when` is only valid when `dispatch='wait'`."
112
+ )
113
+ if wait_timeout is not None:
114
+ raise InvalidConfigurationError(
115
+ "`wait_timeout` is only valid when `dispatch='wait'`."
116
+ )
117
+ if wait_on_timeout != "raise":
118
+ raise InvalidConfigurationError(
119
+ "`wait_on_timeout` is only valid when `dispatch='wait'`."
120
+ )
121
+ if wait_progress:
122
+ raise InvalidConfigurationError(
123
+ "`wait_progress` is only valid when `dispatch='wait'`."
124
+ )
125
+ if wait_progress_label is not None:
126
+ raise InvalidConfigurationError(
127
+ "`wait_progress_label` is only valid when `dispatch='wait'`."
128
+ )
@@ -0,0 +1,323 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Support helpers for solve orchestration state resolution and caching."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import os
9
+ from collections.abc import Mapping, Sequence
10
+ from pathlib import Path
11
+ from typing import TypeVar
12
+
13
+ from ..context import BackendMode, SolverContext, resolve_context
14
+ from ..daemon.handler import DaemonHandler, resolve_scoped_handler
15
+ from ..exceptions import BackendUnavailableError, InvalidConfigurationError
16
+ from ..results import (
17
+ BundledSolveResult,
18
+ Resultbag,
19
+ SolveResult,
20
+ TemplateRenderInfo,
21
+ )
22
+ from .staging import (
23
+ derive_output_path_from_template,
24
+ render_companion_templates,
25
+ resolve_project_source_files,
26
+ stage_project_for_execution,
27
+ stage_runtime_inputs,
28
+ )
29
+
30
+ _ResultbagPayloadT = TypeVar("_ResultbagPayloadT", SolveResult, BundledSolveResult)
31
+
32
+
33
+ def resolve_context_backend(
34
+ *,
35
+ context: SolverContext | None,
36
+ backend: BackendMode | None,
37
+ ) -> tuple[SolverContext, BackendMode, DaemonHandler | None]:
38
+ """Resolve effective context and backend daemon binding."""
39
+
40
+ scoped_daemon_handler: DaemonHandler | None = resolve_scoped_handler(
41
+ context=context
42
+ )
43
+ resolved_context: SolverContext
44
+ if context is not None:
45
+ resolved_context = resolve_context(context)
46
+ elif scoped_daemon_handler is not None:
47
+ resolved_context = scoped_daemon_handler.context
48
+ else:
49
+ resolved_context = resolve_context(None)
50
+
51
+ resolved_backend, backend_daemon_handler = resolve_backend_mode(
52
+ backend=backend,
53
+ context=resolved_context,
54
+ scoped_daemon_handler=scoped_daemon_handler,
55
+ )
56
+ return resolved_context, resolved_backend, backend_daemon_handler
57
+
58
+
59
+ def resolve_backend_mode(
60
+ *,
61
+ backend: BackendMode | None,
62
+ context: SolverContext,
63
+ scoped_daemon_handler: DaemonHandler | None,
64
+ ) -> tuple[BackendMode, DaemonHandler | None]:
65
+ """Resolve backend mode from per-call override, scope, and context defaults."""
66
+
67
+ context_daemon_handler: DaemonHandler | None = context._get_daemon_handler()
68
+ requested_backend: BackendMode = (
69
+ backend if backend is not None else context.backend_mode
70
+ )
71
+
72
+ if requested_backend == "auto":
73
+ if (
74
+ scoped_daemon_handler is not None
75
+ and scoped_daemon_handler.context is context
76
+ ):
77
+ return "daemon", scoped_daemon_handler
78
+ if (
79
+ context_daemon_handler is not None
80
+ and context_daemon_handler.status().connected
81
+ ):
82
+ return "daemon", context_daemon_handler
83
+ return "local", None
84
+
85
+ if requested_backend == "local":
86
+ return "local", None
87
+
88
+ if scoped_daemon_handler is not None and scoped_daemon_handler.context is context:
89
+ return "daemon", scoped_daemon_handler
90
+ if context_daemon_handler is not None and context_daemon_handler.status().connected:
91
+ return "daemon", context_daemon_handler
92
+
93
+ raise BackendUnavailableError(
94
+ "Daemon backend requested but no connected daemon handler is available for "
95
+ "the resolved context. Use `with jcmsuite.daemon.handler(...):` or call "
96
+ "`connect()` on the context-owned daemon handler first."
97
+ )
98
+
99
+
100
+ def load_cached_payload(
101
+ *,
102
+ resultbag: Resultbag | None,
103
+ source_files: Sequence[Path],
104
+ keys: Mapping[str, object],
105
+ recompute: bool,
106
+ suffix_pattern: str | None,
107
+ expected_type: type[_ResultbagPayloadT],
108
+ expected_name: str,
109
+ ) -> _ResultbagPayloadT | None:
110
+ """Load/validate one typed cached resultbag payload when available."""
111
+
112
+ if resultbag is None:
113
+ return None
114
+
115
+ management = resultbag.management
116
+ source_matches: bool = management.check_source_files(source_files)
117
+ if not source_matches:
118
+ if recompute:
119
+ management.reset()
120
+ management.set_source_files(source_files)
121
+ elif resultbag.has_results():
122
+ raise InvalidConfigurationError(
123
+ "Resultbag source files changed. Pass `recompute=True` or "
124
+ "reset the resultbag before solving."
125
+ )
126
+ else:
127
+ management.set_source_files(source_files)
128
+
129
+ if not recompute and management.check_result(
130
+ keys,
131
+ suffix_pattern=suffix_pattern,
132
+ ):
133
+ cached_result: object = resultbag.get_results(
134
+ keys,
135
+ suffix_pattern=suffix_pattern,
136
+ )
137
+ if not isinstance(cached_result, expected_type):
138
+ raise InvalidConfigurationError(
139
+ f"Resultbag entry is not a {expected_name} instance."
140
+ )
141
+ return cached_result
142
+ return None
143
+
144
+
145
+ def load_cached_result(
146
+ *,
147
+ resultbag: Resultbag | None,
148
+ project_path: Path,
149
+ keys: Mapping[str, object],
150
+ recompute: bool,
151
+ suffix_pattern: str | None,
152
+ ) -> SolveResult | None:
153
+ """Load/validate cached single-project resultbag entry when available."""
154
+
155
+ return load_cached_payload(
156
+ resultbag=resultbag,
157
+ source_files=resolve_project_source_files(
158
+ project_path=project_path,
159
+ keys=keys,
160
+ suffix_pattern=suffix_pattern,
161
+ ),
162
+ keys=keys,
163
+ recompute=recompute,
164
+ suffix_pattern=suffix_pattern,
165
+ expected_type=SolveResult,
166
+ expected_name="SolveResult",
167
+ )
168
+
169
+
170
+ def load_cached_bundle_result(
171
+ *,
172
+ resultbag: Resultbag | None,
173
+ project_paths: Sequence[Path],
174
+ keys: Mapping[str, object],
175
+ recompute: bool,
176
+ suffix_pattern: str | None,
177
+ ) -> BundledSolveResult | None:
178
+ """Load/validate cached multi-project bundle resultbag entry when available."""
179
+
180
+ cached_result: BundledSolveResult | None = load_cached_payload(
181
+ resultbag=resultbag,
182
+ source_files=tuple(
183
+ source_file
184
+ for project_path in project_paths
185
+ for source_file in resolve_project_source_files(
186
+ project_path=project_path,
187
+ keys=keys,
188
+ suffix_pattern=suffix_pattern,
189
+ )
190
+ ),
191
+ keys=keys,
192
+ recompute=recompute,
193
+ suffix_pattern=suffix_pattern,
194
+ expected_type=BundledSolveResult,
195
+ expected_name="BundledSolveResult",
196
+ )
197
+ if cached_result is None:
198
+ return None
199
+ if not project_paths:
200
+ return None
201
+
202
+ project_parents: tuple[str, ...] = tuple(
203
+ str(project_path.expanduser().resolve().parent)
204
+ for project_path in project_paths
205
+ )
206
+ source_root: Path = Path(os.path.commonpath(project_parents))
207
+ requested_project_identities: tuple[str, ...] = tuple(
208
+ project_path.expanduser().resolve().relative_to(source_root).as_posix()
209
+ for project_path in project_paths
210
+ )
211
+ cached_project_identities: tuple[str | None, ...] = tuple(
212
+ entry._project_identity for entry in cached_result.entries
213
+ )
214
+ if cached_project_identities != requested_project_identities:
215
+ return None
216
+ return cached_result
217
+
218
+
219
+ def prepare_project_inputs(
220
+ *,
221
+ project_path: Path,
222
+ working_dir: Path | None,
223
+ resolved_keys: Mapping[str, object],
224
+ suffix_pattern: str | None = None,
225
+ ) -> tuple[Path, tuple[TemplateRenderInfo, ...]]:
226
+ """Prepare one executable project file and template render metadata."""
227
+
228
+ if project_path.suffix in (".jcmt", ".jcmpt"):
229
+ execution_dir: Path = (
230
+ project_path.parent.resolve()
231
+ if working_dir is None
232
+ else working_dir.resolve()
233
+ )
234
+ if execution_dir != project_path.parent.resolve():
235
+ stage_runtime_inputs(
236
+ source_dir=project_path.parent.resolve(),
237
+ target_dir=execution_dir,
238
+ skip_files={project_path.resolve()},
239
+ )
240
+ template_renders = render_companion_templates(
241
+ source_project_path=project_path.resolve(),
242
+ execution_project_path=derive_output_path_from_template(
243
+ template_path=project_path.resolve(),
244
+ output_dir=execution_dir,
245
+ ),
246
+ keys=resolved_keys,
247
+ suffix_pattern=suffix_pattern,
248
+ )
249
+ prepared_project: Path = derive_output_path_from_template(
250
+ template_path=project_path.resolve(),
251
+ output_dir=execution_dir,
252
+ )
253
+ if not prepared_project.is_file():
254
+ raise InvalidConfigurationError(
255
+ "Failed to render project template into execution directory: "
256
+ f"{prepared_project}"
257
+ )
258
+ return prepared_project, template_renders
259
+
260
+ if project_path.suffix in (".jcm", ".jcmp"):
261
+ execution_project_path: Path = stage_project_for_execution(
262
+ project_path=project_path,
263
+ working_dir=working_dir,
264
+ )
265
+ template_renders = tuple()
266
+ if resolved_keys or suffix_pattern is not None:
267
+ template_renders = render_companion_templates(
268
+ source_project_path=project_path.resolve(),
269
+ execution_project_path=execution_project_path.resolve(),
270
+ keys=resolved_keys,
271
+ suffix_pattern=suffix_pattern,
272
+ )
273
+ return execution_project_path, template_renders
274
+
275
+ raise InvalidConfigurationError(
276
+ "Unsupported project extension for solve: " f"{project_path.suffix}"
277
+ )
278
+
279
+
280
+ def _is_pending_daemon_submission(
281
+ *,
282
+ daemon_handler: DaemonHandler | None,
283
+ daemon_job_id: int,
284
+ ) -> bool:
285
+ """Return whether a daemon submission id is tracked on this handler."""
286
+
287
+ if daemon_handler is None:
288
+ return False
289
+ return (
290
+ daemon_job_id in daemon_handler._pending_jobs
291
+ or daemon_job_id in daemon_handler._completed_jobs
292
+ )
293
+
294
+
295
+ def _is_retryable_solve_error(error: Exception) -> bool:
296
+ """Return whether solve execution error should trigger a retry."""
297
+
298
+ return isinstance(error, (RuntimeError, TimeoutError))
299
+
300
+
301
+ def _build_attempt_log_payload(
302
+ *,
303
+ attempt_index: int,
304
+ exception: Exception,
305
+ result: SolveResult,
306
+ ) -> dict[str, object]:
307
+ """Build one persisted attempt-log payload for Resultbag storage."""
308
+
309
+ payload: dict[str, object] = {
310
+ "attempt_index": attempt_index,
311
+ "backend": result.backend_used,
312
+ "exception_type": type(exception).__name__,
313
+ "exception_message": str(exception),
314
+ }
315
+ if result.log is not None:
316
+ payload["execution_log"] = {
317
+ "backend": result.log.backend,
318
+ "stdout": result.log.stdout,
319
+ "stderr": result.log.stderr,
320
+ "return_code": result.log.return_code,
321
+ "streamed_to_console": result.log.streamed_to_console,
322
+ }
323
+ return payload