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,264 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Solve project staging and companion-template rendering."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import shutil
9
+ from collections.abc import Mapping, Sequence
10
+ from pathlib import Path
11
+
12
+ from ..exceptions import InvalidConfigurationError
13
+ from ..results import TemplateRenderInfo
14
+ from ..templates import jcmt2jcm
15
+
16
+ _LEGACY_COMPANION_FILE_NAMES: tuple[str, ...] = (
17
+ "layout.jcm",
18
+ "grid.jcm",
19
+ "materials.jcm",
20
+ "sources.jcm",
21
+ "boundary_conditions.jcm",
22
+ )
23
+
24
+
25
+ def _select_file_variant(
26
+ *,
27
+ source_dir: Path,
28
+ file_name: str,
29
+ suffix_pattern: str | None,
30
+ ) -> Path | None:
31
+ """Return one preferred file variant for a companion input."""
32
+
33
+ stem: str = Path(file_name).stem
34
+ candidates: list[Path] = []
35
+ if suffix_pattern is not None:
36
+ candidates.extend(
37
+ [
38
+ source_dir / f"{stem}.{suffix_pattern}.jcmt",
39
+ source_dir / f"{stem}.{suffix_pattern}.jcm",
40
+ ]
41
+ )
42
+ candidates.extend(
43
+ [
44
+ source_dir / f"{stem}.jcmt",
45
+ source_dir / f"{stem}.jcm",
46
+ ]
47
+ )
48
+
49
+ candidate: Path
50
+ for candidate in candidates:
51
+ if candidate.is_file():
52
+ return candidate.resolve()
53
+ return None
54
+
55
+
56
+ def render_companion_templates(
57
+ *,
58
+ source_project_path: Path,
59
+ execution_project_path: Path,
60
+ keys: Mapping[str, object],
61
+ suffix_pattern: str | None = None,
62
+ ) -> tuple[TemplateRenderInfo, ...]:
63
+ """Render or stage selected companion inputs into the execution directory."""
64
+
65
+ source_dir: Path = source_project_path.parent.resolve()
66
+ output_dir: Path = execution_project_path.parent.resolve()
67
+ selected_sources: tuple[tuple[Path, Path], ...] = _select_legacy_companion_sources(
68
+ source_project_path=source_project_path.resolve(),
69
+ suffix_pattern=suffix_pattern,
70
+ )
71
+ rendered_infos: list[TemplateRenderInfo] = []
72
+ selected_any: bool = False
73
+
74
+ source_path: Path
75
+ target_path: Path
76
+ for source_path, target_path in selected_sources:
77
+ selected_any = True
78
+ output_target: Path
79
+ if source_path == source_project_path and source_path.suffix in (
80
+ ".jcmt",
81
+ ".jcmpt",
82
+ ):
83
+ output_target = derive_output_path_from_template(
84
+ template_path=source_path,
85
+ output_dir=output_dir,
86
+ )
87
+ else:
88
+ output_target = output_dir / target_path.name
89
+
90
+ if source_path.suffix in (".jcmt", ".jcmpt"):
91
+ rendered_output: Path = jcmt2jcm(
92
+ source_path,
93
+ keys=keys,
94
+ outputfile=output_target,
95
+ )
96
+ rendered_infos.append(
97
+ TemplateRenderInfo(
98
+ source_template=source_path,
99
+ rendered_project=rendered_output.resolve(),
100
+ keys=dict(keys),
101
+ )
102
+ )
103
+ continue
104
+
105
+ if source_path.resolve() != output_target.resolve():
106
+ shutil.copy2(source_path, output_target)
107
+
108
+ if suffix_pattern is not None and not selected_any:
109
+ raise InvalidConfigurationError(
110
+ f"No companion input matched suffix pattern {suffix_pattern!r} in {source_dir}."
111
+ )
112
+ return tuple(rendered_infos)
113
+
114
+
115
+ def _select_legacy_companion_sources(
116
+ *, source_project_path: Path, suffix_pattern: str | None = None
117
+ ) -> tuple[tuple[Path, Path], ...]:
118
+ """Return selected companion sources and their canonical target paths."""
119
+
120
+ source_dir: Path = source_project_path.parent.resolve()
121
+ selected_sources: list[tuple[Path, Path]] = []
122
+ seen_targets: set[Path] = set()
123
+
124
+ if source_project_path.suffix in (".jcmt", ".jcmpt"):
125
+ selected_sources.append((source_project_path, source_project_path))
126
+ seen_targets.add(source_project_path)
127
+
128
+ file_name: str
129
+ for file_name in _LEGACY_COMPANION_FILE_NAMES:
130
+ if file_name == "grid.jcm":
131
+ continue
132
+ source_path: Path | None = _select_file_variant(
133
+ source_dir=source_dir,
134
+ file_name=file_name,
135
+ suffix_pattern=suffix_pattern,
136
+ )
137
+ if source_path is None:
138
+ continue
139
+ if source_path == source_project_path:
140
+ continue
141
+ target_path: Path = source_dir / file_name
142
+ if target_path in seen_targets:
143
+ continue
144
+ selected_sources.append((source_path, target_path))
145
+ seen_targets.add(target_path)
146
+
147
+ return tuple(selected_sources)
148
+
149
+
150
+ def resolve_project_source_files(
151
+ *, project_path: Path, keys: Mapping[str, object], suffix_pattern: str | None
152
+ ) -> tuple[Path, ...]:
153
+ """Return source files that define one solve's executable inputs.
154
+
155
+ The project entrypoint and selected companion inputs are included. Companion
156
+ inputs are only selected for ordinary project files when rendering or a
157
+ suffix pattern is active, matching ``prepare_project_inputs``.
158
+ """
159
+
160
+ resolved_project_path: Path = project_path.resolve()
161
+ source_files: list[Path] = [resolved_project_path]
162
+ if resolved_project_path.suffix in (".jcmt", ".jcmpt") or (
163
+ resolved_project_path.suffix in (".jcm", ".jcmp")
164
+ and (keys or suffix_pattern is not None)
165
+ ):
166
+ source_files.extend(
167
+ source_path
168
+ for source_path, _ in _select_legacy_companion_sources(
169
+ source_project_path=resolved_project_path,
170
+ suffix_pattern=suffix_pattern,
171
+ )
172
+ if source_path != resolved_project_path
173
+ )
174
+ return tuple(source_files)
175
+
176
+
177
+ def stage_project_for_execution(
178
+ *, project_path: Path, working_dir: Path | None
179
+ ) -> Path:
180
+ """Stage project inputs into `working_dir` when configured."""
181
+
182
+ if working_dir is None:
183
+ return project_path
184
+
185
+ resolved_working_dir: Path = working_dir.resolve()
186
+ source_dir: Path = project_path.parent.resolve()
187
+ if resolved_working_dir == source_dir:
188
+ return project_path
189
+
190
+ stage_runtime_inputs(
191
+ source_dir=source_dir, target_dir=resolved_working_dir, skip_files=set()
192
+ )
193
+ staged_project_file: Path = resolved_working_dir / project_path.name
194
+ shutil.copy2(project_path, staged_project_file)
195
+
196
+ if not staged_project_file.is_file():
197
+ raise InvalidConfigurationError(
198
+ "Failed to stage project file into working directory: "
199
+ f"{staged_project_file}"
200
+ )
201
+ return staged_project_file.resolve()
202
+
203
+
204
+ def stage_runtime_inputs(
205
+ *, source_dir: Path, target_dir: Path, skip_files: set[Path]
206
+ ) -> None:
207
+ """Copy runtime-relevant project inputs into an execution directory."""
208
+
209
+ target_dir.mkdir(parents=True, exist_ok=True)
210
+ resolved_skip_files: set[Path] = {path.resolve() for path in skip_files}
211
+ source_pattern: str
212
+ for source_pattern in ("*.jcm", "*.jcmp", "*.gds"):
213
+ source_file: Path
214
+ for source_file in source_dir.glob(source_pattern):
215
+ resolved_source: Path = source_file.resolve()
216
+ if not source_file.is_file() or resolved_source in resolved_skip_files:
217
+ continue
218
+ target_file: Path = target_dir / source_file.name
219
+ shutil.copy2(source_file, target_file)
220
+
221
+
222
+ def stage_bundle_runtime_inputs(
223
+ *,
224
+ source_root: Path,
225
+ target_root: Path,
226
+ skip_files: set[Path],
227
+ skip_directories: Sequence[Path] = (),
228
+ ) -> None:
229
+ """Copy bundle runtime inputs recursively from one common source root."""
230
+
231
+ resolved_source_root: Path = source_root.resolve()
232
+ resolved_target_root: Path = target_root.resolve()
233
+ if resolved_target_root == resolved_source_root:
234
+ return
235
+
236
+ target_root.mkdir(parents=True, exist_ok=True)
237
+ resolved_skip_files: set[Path] = {path.resolve() for path in skip_files}
238
+ resolved_skip_directories: tuple[Path, ...] = tuple(
239
+ path.resolve() for path in skip_directories
240
+ )
241
+ source_pattern: str
242
+ for source_pattern in ("*.jcm", "*.jcmp", "*.gds"):
243
+ source_file: Path
244
+ for source_file in resolved_source_root.rglob(source_pattern):
245
+ resolved_source: Path = source_file.resolve()
246
+ if not source_file.is_file() or resolved_source in resolved_skip_files:
247
+ continue
248
+ if resolved_target_root in (resolved_source, *resolved_source.parents):
249
+ continue
250
+ if any(
251
+ resolved_source.is_relative_to(path)
252
+ for path in resolved_skip_directories
253
+ ):
254
+ continue
255
+ relative_path: Path = resolved_source.relative_to(resolved_source_root)
256
+ target_file: Path = target_root / relative_path
257
+ target_file.parent.mkdir(parents=True, exist_ok=True)
258
+ shutil.copy2(resolved_source, target_file)
259
+
260
+
261
+ def derive_output_path_from_template(*, template_path: Path, output_dir: Path) -> Path:
262
+ """Derive rendered output path in `output_dir` from a template file path."""
263
+
264
+ return output_dir / Path(str(template_path.name)[:-1])
@@ -0,0 +1,25 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Typed option aliases for solve orchestration."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from collections.abc import Mapping, Sequence
9
+ from pathlib import Path
10
+ from typing import Literal
11
+
12
+ SolveMode = Literal["solve", "postprocess"]
13
+
14
+ BatchOnError = Literal["raise", "collect"]
15
+ DispatchMode = Literal["wait", "submit"]
16
+ WaitBreakWhen = Literal["all", "any"]
17
+ WaitOnTimeout = Literal["raise", "return"]
18
+ ProjectPathInput = str | Path
19
+ ProjectBundleInput = (
20
+ list[str] | list[Path] | list[ProjectPathInput] | tuple[ProjectPathInput, ...]
21
+ )
22
+ SolveKeysInput = Mapping[str, object] | None
23
+ BatchSolveKeysInput = Sequence[Mapping[str, object]]
24
+ WorkingDirValue = str | Path
25
+ WorkingDirInput = WorkingDirValue | Sequence[WorkingDirValue] | None
@@ -0,0 +1,227 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Working-directory resolution for solve execution."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import os
9
+ import tempfile
10
+ from collections.abc import Sequence
11
+ from pathlib import Path
12
+ from typing import cast
13
+
14
+ from ..exceptions import InvalidConfigurationError
15
+ from .types import WorkingDirInput, WorkingDirValue
16
+
17
+
18
+ def is_path_sequence(value: object) -> bool:
19
+ """Return whether a value represents a path sequence (not a scalar path)."""
20
+
21
+ if isinstance(value, (str, bytes, bytearray, Path)):
22
+ return False
23
+ return isinstance(value, Sequence)
24
+
25
+
26
+ def normalize_working_dir_path(raw_path: WorkingDirValue) -> Path:
27
+ """Normalize one working-directory path value."""
28
+
29
+ return Path(raw_path).expanduser().resolve()
30
+
31
+
32
+ def create_temporary_working_dir(
33
+ *,
34
+ index: int | None = None,
35
+ temp_dir_root: Path | None = None,
36
+ ) -> Path:
37
+ """Create one temporary solve working directory.
38
+
39
+ Parameters
40
+ ----------
41
+ index : int | None, optional
42
+ Optional batch index used only to make the generated prefix stable.
43
+ temp_dir_root : Path | None, optional
44
+ Optional base directory for the temporary solve directory.
45
+
46
+ Returns
47
+ -------
48
+ Path
49
+ Absolute path to the created temporary directory.
50
+ """
51
+
52
+ if temp_dir_root is not None:
53
+ temp_dir_root = temp_dir_root.expanduser().resolve()
54
+ temp_dir_root.mkdir(parents=True, exist_ok=True)
55
+ if index is None:
56
+ if temp_dir_root is None:
57
+ temp_dir = tempfile.mkdtemp(prefix="__jcmsuite__")
58
+ else:
59
+ temp_dir = tempfile.mkdtemp(
60
+ prefix="__jcmsuite__",
61
+ dir=str(temp_dir_root),
62
+ )
63
+ else:
64
+ if temp_dir_root is None:
65
+ temp_dir = tempfile.mkdtemp(prefix=f"__jcmsuite_batch_{index}_")
66
+ else:
67
+ temp_dir = tempfile.mkdtemp(
68
+ prefix=f"__jcmsuite_batch_{index}_",
69
+ dir=str(temp_dir_root),
70
+ )
71
+ return Path(temp_dir).resolve()
72
+
73
+
74
+ def resolve_single_working_dir(
75
+ *,
76
+ working_dir: WorkingDirInput,
77
+ temporary: bool,
78
+ temp_dir_root: Path | None,
79
+ ) -> Path | None:
80
+ """Resolve working-directory option for a single solve entry.
81
+
82
+ Parameters
83
+ ----------
84
+ working_dir : WorkingDirInput
85
+ Optional working-directory input from `solve(...)`.
86
+ temporary : bool
87
+ Temporary working-directory toggle from `solve(...)`.
88
+ temp_dir_root : Path | None
89
+ Optional base directory for temporary solve directories.
90
+
91
+ Returns
92
+ -------
93
+ Path | None
94
+ Resolved working directory, or `None` when no staging is requested.
95
+
96
+ Notes
97
+ -----
98
+ Resolution precedence:
99
+ - explicit `working_dir` is authoritative (even when `temporary=True`),
100
+ - otherwise `temporary=True` creates one new temporary directory,
101
+ - otherwise returns `None` to indicate source-directory execution.
102
+
103
+ Overload shape:
104
+ - scalar path input is accepted,
105
+ - sequence input is rejected for single solves.
106
+ """
107
+
108
+ if working_dir is not None:
109
+ if is_path_sequence(working_dir):
110
+ raise InvalidConfigurationError(
111
+ "Single solve expects one scalar working directory location."
112
+ )
113
+ return normalize_working_dir_path(cast(WorkingDirValue, working_dir))
114
+ if temporary:
115
+ return create_temporary_working_dir(temp_dir_root=temp_dir_root)
116
+ return None
117
+
118
+
119
+ def resolve_batch_working_dirs(
120
+ *,
121
+ working_dir: WorkingDirInput,
122
+ batch_size: int,
123
+ temporary: bool,
124
+ temp_dir_root: Path | None,
125
+ ) -> list[Path | None]:
126
+ """Resolve one working-directory location per batch key entry.
127
+
128
+ Parameters
129
+ ----------
130
+ working_dir : WorkingDirInput
131
+ Optional batch working-directory input from `solve(...)`.
132
+ batch_size : int
133
+ Number of key entries in the batch solve request.
134
+ temporary : bool
135
+ Temporary working-directory toggle from `solve(...)`.
136
+ temp_dir_root : Path | None
137
+ Optional base directory for temporary solve directories.
138
+
139
+ Returns
140
+ -------
141
+ list[Path | None]
142
+ One resolved working directory per batch entry.
143
+
144
+ Notes
145
+ -----
146
+ Resolution precedence:
147
+ - explicit `working_dir` is authoritative (even when `temporary=True`),
148
+ - otherwise `temporary=True` creates one distinct temporary directory per
149
+ batch entry,
150
+ - otherwise returns a `None` placeholder per batch entry.
151
+
152
+ Overload shape:
153
+ - sequence input length must match `batch_size`,
154
+ - scalar input is accepted only when `batch_size == 1`.
155
+ """
156
+
157
+ if working_dir is not None:
158
+ if is_path_sequence(working_dir):
159
+ sequence_working_dir: Sequence[WorkingDirValue] = cast(
160
+ Sequence[WorkingDirValue], working_dir
161
+ )
162
+ working_dir_values: list[WorkingDirValue] = list(sequence_working_dir)
163
+ if len(working_dir_values) != batch_size:
164
+ raise InvalidConfigurationError(
165
+ "Batch solve requires one working directory per key entry."
166
+ )
167
+ return [
168
+ normalize_working_dir_path(raw_working_dir)
169
+ for raw_working_dir in working_dir_values
170
+ ]
171
+ if batch_size == 1:
172
+ return [normalize_working_dir_path(cast(WorkingDirValue, working_dir))]
173
+ raise InvalidConfigurationError(
174
+ "Batch solve requires one working directory per key entry."
175
+ )
176
+ if temporary:
177
+ return [
178
+ create_temporary_working_dir(
179
+ index=batch_index,
180
+ temp_dir_root=temp_dir_root,
181
+ )
182
+ for batch_index in range(batch_size)
183
+ ]
184
+ return [None] * batch_size
185
+
186
+
187
+ def resolve_bundle_working_dirs(
188
+ *,
189
+ project_files: Sequence[Path],
190
+ bundle_root: Path | None,
191
+ ) -> list[Path | None]:
192
+ """Resolve per-project working directories for one ordered project bundle.
193
+
194
+ Parameters
195
+ ----------
196
+ project_files : Sequence[Path]
197
+ Normalized project input paths in bundle order.
198
+ bundle_root : Path | None
199
+ Root directory for staged bundle execution. When `None`, each project
200
+ runs in its source directory.
201
+
202
+ Returns
203
+ -------
204
+ list[Path | None]
205
+ One working directory per project in bundle order.
206
+ """
207
+
208
+ if bundle_root is None:
209
+ return [None] * len(project_files)
210
+
211
+ common_base: Path = resolve_bundle_common_base(project_files=project_files)
212
+ resolved_bundle_root: Path = bundle_root.resolve()
213
+ working_directories: list[Path] = []
214
+ project_file: Path
215
+ for project_file in project_files:
216
+ relative_parent: Path = project_file.parent.resolve().relative_to(common_base)
217
+ working_directories.append((resolved_bundle_root / relative_parent).resolve())
218
+ return cast(list[Path | None], working_directories)
219
+
220
+
221
+ def resolve_bundle_common_base(*, project_files: Sequence[Path]) -> Path:
222
+ """Return the common source root for one ordered project bundle."""
223
+
224
+ parent_directories: list[str] = [
225
+ str(project_file.parent) for project_file in project_files
226
+ ]
227
+ return Path(os.path.commonpath(parent_directories)).resolve()
@@ -0,0 +1,11 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Public template namespace for `jcmsuite`."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from .converter import jcmt2jcm
9
+ from .formatting import format_jcm
10
+
11
+ __all__: list[str] = ["format_jcm", "jcmt2jcm"]
@@ -0,0 +1,71 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Template-processing namespace for `jcmsuite`."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from collections.abc import Mapping
9
+ from pathlib import Path
10
+
11
+ from ..exceptions import InvalidConfigurationError
12
+ from .rendering import render_template
13
+
14
+
15
+ def jcmt2jcm(
16
+ jcmt_file: str | Path,
17
+ keys: Mapping[str, object] | None = None,
18
+ outputfile: str | Path | None = None,
19
+ ) -> Path:
20
+ """Create a JCM file from a `.jcmt` or `.jcmpt` template.
21
+
22
+ Parameters
23
+ ----------
24
+ jcmt_file : str | Path
25
+ Path to the template file. The file name must end in `.jcmt` or
26
+ `.jcmpt`.
27
+ keys : Mapping[str, object] | None, optional
28
+ Project Key values to insert into the template. Python blocks in the
29
+ template can also use these values.
30
+ outputfile : str | Path | None, optional
31
+ Path for the generated file. If omitted, the converter removes the
32
+ trailing `t` from the template extension (`.jcmt` becomes `.jcm` and
33
+ `.jcmpt` becomes `.jcmp`).
34
+
35
+ Returns
36
+ -------
37
+ Path
38
+ Absolute path of the new JCM file.
39
+
40
+ Raises
41
+ ------
42
+ InvalidConfigurationError
43
+ If the template path or extension is invalid.
44
+ TemplateMappingError
45
+ If the template contains an error. The error identifies the source
46
+ position when possible.
47
+ """
48
+
49
+ input_path: Path = Path(jcmt_file).expanduser().resolve()
50
+ if input_path.suffix not in (".jcmt", ".jcmpt"):
51
+ raise InvalidConfigurationError(
52
+ f"Template file has unsupported extension: {input_path}"
53
+ )
54
+ if not input_path.is_file():
55
+ raise InvalidConfigurationError(f"Template file does not exist: {input_path}")
56
+
57
+ output_path: Path
58
+ if outputfile is None:
59
+ output_path = Path(str(input_path)[:-1]).resolve()
60
+ else:
61
+ output_path = Path(outputfile).expanduser().resolve()
62
+
63
+ rendered_text: str
64
+ _rendered_line_map: list[int]
65
+ rendered_text, _rendered_line_map = render_template(
66
+ input_path.read_text(encoding="utf-8"),
67
+ keys={} if keys is None else keys,
68
+ source=input_path,
69
+ )
70
+ output_path.write_text(rendered_text, encoding="utf-8")
71
+ return output_path