jcmsuite 1.0.0__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.
Files changed (106) hide show
  1. jcmsuite/__init__.py +49 -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 +573 -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 +778 -0
  45. jcmsuite/results/discovery.py +82 -0
  46. jcmsuite/results/field_exports.py +897 -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 +28 -0
  51. jcmsuite/results/internal/export/companion.py +16 -0
  52. jcmsuite/results/internal/export/companion_xarray.py +16 -0
  53. jcmsuite/results/internal/export/pandas/__init__.py +4 -0
  54. jcmsuite/results/internal/export/pandas/common.py +105 -0
  55. jcmsuite/results/internal/export/pandas/payload.py +415 -0
  56. jcmsuite/results/internal/export/preview.py +178 -0
  57. jcmsuite/results/internal/export/xarray/__init__.py +4 -0
  58. jcmsuite/results/internal/export/xarray/types.py +28 -0
  59. jcmsuite/results/internal/models/__init__.py +4 -0
  60. jcmsuite/results/internal/models/batch.py +1087 -0
  61. jcmsuite/results/internal/models/batch_postprocess.py +1503 -0
  62. jcmsuite/results/internal/models/bundle.py +343 -0
  63. jcmsuite/results/internal/models/core.py +556 -0
  64. jcmsuite/results/internal/models/submission.py +1157 -0
  65. jcmsuite/results/internal/resultbag/__init__.py +4 -0
  66. jcmsuite/results/internal/resultbag/access.py +531 -0
  67. jcmsuite/results/internal/resultbag/iteration.py +199 -0
  68. jcmsuite/results/internal/resultbag/query.py +230 -0
  69. jcmsuite/results/internal/resultbag/raw.py +407 -0
  70. jcmsuite/results/internal/resultbag/source_files.py +142 -0
  71. jcmsuite/results/internal/resultbag/store.py +882 -0
  72. jcmsuite/results/internal/resultbag/utils.py +258 -0
  73. jcmsuite/results/models.py +76 -0
  74. jcmsuite/results/opening.py +55 -0
  75. jcmsuite/results/pandas_export.py +165 -0
  76. jcmsuite/results/payloads.py +458 -0
  77. jcmsuite/results/postprocess.py +97 -0
  78. jcmsuite/results/postprocess_payloads.py +762 -0
  79. jcmsuite/results/postprocess_record.py +406 -0
  80. jcmsuite/results/resultbag.py +285 -0
  81. jcmsuite/results/resultbag_management.py +433 -0
  82. jcmsuite/results/structured_derivatives.py +387 -0
  83. jcmsuite/solve/__init__.py +10 -0
  84. jcmsuite/solve/daemon_bundle_staging.py +100 -0
  85. jcmsuite/solve/daemon_bundle_wait.py +89 -0
  86. jcmsuite/solve/orchestration.py +1576 -0
  87. jcmsuite/solve/orchestration_execution.py +180 -0
  88. jcmsuite/solve/orchestration_routing.py +128 -0
  89. jcmsuite/solve/orchestration_support.py +323 -0
  90. jcmsuite/solve/path_resolution.py +98 -0
  91. jcmsuite/solve/progress.py +20 -0
  92. jcmsuite/solve/solver.py +709 -0
  93. jcmsuite/solve/staging.py +276 -0
  94. jcmsuite/solve/types.py +25 -0
  95. jcmsuite/solve/working_dirs.py +227 -0
  96. jcmsuite/templates/__init__.py +11 -0
  97. jcmsuite/templates/converter.py +71 -0
  98. jcmsuite/templates/formatting.py +335 -0
  99. jcmsuite/templates/formatting_cli.py +47 -0
  100. jcmsuite/templates/rendering.py +666 -0
  101. jcmsuite/view/__init__.py +10 -0
  102. jcmsuite/view/viewer.py +122 -0
  103. jcmsuite-1.0.0.dist-info/METADATA +194 -0
  104. jcmsuite-1.0.0.dist-info/RECORD +106 -0
  105. jcmsuite-1.0.0.dist-info/WHEEL +4 -0
  106. jcmsuite-1.0.0.dist-info/entry_points.txt +3 -0
@@ -0,0 +1,569 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """SolverContext class implementation."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import asyncio
9
+ import builtins
10
+ import datetime as dt
11
+ import os
12
+ import re
13
+ from logging import Logger
14
+ from pathlib import Path
15
+ from types import TracebackType
16
+ from typing import TYPE_CHECKING
17
+
18
+ from ..exceptions import InvalidConfigurationError, RuntimeContextError
19
+ from ..logging import TRACE, get_logger, setup_logger
20
+ from .interface_metadata import load_interface_details
21
+ from .models import (
22
+ BackendMode,
23
+ GPUSelection,
24
+ JCMInfoDetails,
25
+ JCMInstallationDetails,
26
+ JCMInterfaceDetails,
27
+ JCMLicenseDetails,
28
+ JCMSystemDetails,
29
+ normalize_gpu_usage,
30
+ )
31
+ from .scope import _pop_current_context, _push_current_context
32
+
33
+ _logger: Logger = get_logger(__name__)
34
+
35
+ if TYPE_CHECKING:
36
+ from ..daemon.handler import DaemonHandler
37
+
38
+
39
+ class SolverContext:
40
+ """Store settings for JCMsuite operations.
41
+
42
+ Parameters
43
+ ----------
44
+ jcm_root_dir : Path | None, optional
45
+ JCMsuite installation root. If omitted, use the `JCMROOT` environment
46
+ variable.
47
+ backend_mode : Literal["auto", "local", "daemon"], optional
48
+ Default execution method for `solve(...)`.
49
+ num_threads : int | None, optional
50
+ Number of solver threads.
51
+ memory_limit_mb : int | None, optional
52
+ Solver memory limit in megabytes.
53
+ gpus : GPUSelection | None, optional
54
+ Local GPU selection. Use ``"all"`` or ``"no"``. You can also give one
55
+ non-negative GPU identifier or a non-empty sequence of GPU identifiers.
56
+ temp_dir_root : Path | None, optional
57
+ Directory in which JCMsuite creates temporary working directories.
58
+ debug : bool, optional
59
+ If `True`, enable debug logging.
60
+ skip_logger : bool, optional
61
+ If `True`, do not configure logging.
62
+ logging_level : int | None, optional
63
+ Amount of information to write to the log.
64
+ log_dir : Path | None, optional
65
+ Directory for `jcmsuite.log`.
66
+ """
67
+
68
+ def __init__(
69
+ self,
70
+ *,
71
+ jcm_root_dir: Path | None = None,
72
+ backend_mode: BackendMode = "auto",
73
+ num_threads: int | None = None,
74
+ memory_limit_mb: int | None = None,
75
+ gpus: GPUSelection | None = None,
76
+ temp_dir_root: Path | None = None,
77
+ debug: bool = False,
78
+ skip_logger: bool = False,
79
+ logging_level: int | None = None,
80
+ log_dir: Path | None = None,
81
+ ) -> None:
82
+
83
+ if not skip_logger:
84
+ setup_logger(
85
+ logging_level=logging_level,
86
+ log_dir=log_dir,
87
+ debug=debug,
88
+ )
89
+
90
+ self.backend_mode: BackendMode = backend_mode
91
+ self._jcm_root: Path | None = self._resolve_jcm_root(jcm_root_dir)
92
+ self._system: JCMSystemDetails = JCMSystemDetails.detect()
93
+ self._system.n_threads = num_threads
94
+ self._system.max_memory_mb = memory_limit_mb
95
+ try:
96
+ self._system.gpu_usage = normalize_gpu_usage(gpus)
97
+ except ValueError as error:
98
+ raise InvalidConfigurationError(str(error)) from error
99
+ self._system.temp_dir_root = (
100
+ None if temp_dir_root is None else temp_dir_root.expanduser().resolve()
101
+ )
102
+
103
+ self.jcm_geo: Path | None = None
104
+ self.jcm_solve: Path | None = None
105
+ self.jcm_view: Path | None = None
106
+ self.jcm_edit: Path | None = None
107
+ self.jcm_control: Path | None = None
108
+ self._has_binaries: bool = False
109
+
110
+ if self._jcm_root is not None:
111
+ self._initialize_binary_paths()
112
+
113
+ self._installation: JCMInstallationDetails | None = None
114
+ self._license: JCMLicenseDetails | None = None
115
+ self._has_startup_run: bool = False
116
+ self._daemon_handler: DaemonHandler | None = None
117
+
118
+ def __enter__(self) -> "SolverContext":
119
+ """Bind this context as the active task-local context."""
120
+
121
+ _push_current_context(self)
122
+ return self
123
+
124
+ def __exit__(
125
+ self,
126
+ exc_type: type[BaseException] | None,
127
+ exc: BaseException | None,
128
+ tb: TracebackType | None,
129
+ ) -> None:
130
+ """Restore the previously active task-local context."""
131
+
132
+ del exc_type, exc, tb
133
+ _pop_current_context()
134
+
135
+ @staticmethod
136
+ def _resolve_jcm_root(jcm_root_dir: Path | None) -> Path | None:
137
+ """Resolve explicit or environment-provided JCMROOT path."""
138
+
139
+ resolved_input: Path | None = jcm_root_dir
140
+ if resolved_input is None:
141
+ jcm_root_env: str | None = os.environ.get("JCMROOT")
142
+ if jcm_root_env is None:
143
+ return None
144
+ resolved_input = Path(jcm_root_env)
145
+
146
+ resolved_root: Path = resolved_input.expanduser().resolve()
147
+ if not resolved_root.is_dir():
148
+ raise RuntimeContextError(f"JCMROOT is not a directory: {resolved_root}")
149
+ return resolved_root
150
+
151
+ def _initialize_binary_paths(self) -> None:
152
+ """Initialize binary paths and availability flags from JCMROOT."""
153
+
154
+ if self._jcm_root is None:
155
+ return
156
+
157
+ binary_dir: Path = self._jcm_root / "bin"
158
+ binext: str = self._system.binext
159
+
160
+ def _binary_path(directory: Path, binary_name: str) -> Path:
161
+ """Build the full binary path for a named JCM executable.
162
+
163
+ Parameters
164
+ ----------
165
+ directory : Path
166
+ Directory that contains JCM executable binaries.
167
+ binary_name : str
168
+ Binary basename (for example ``\"JCMsolve\"``).
169
+
170
+ Returns
171
+ -------
172
+ Path
173
+ Absolute executable path with platform-specific suffix.
174
+
175
+ Notes
176
+ -----
177
+ Internal API: this helper is an implementation detail and may change
178
+ without notice.
179
+ """
180
+
181
+ return (directory / binary_name).with_suffix(binext)
182
+
183
+ self.jcm_geo = _binary_path(binary_dir, "JCMgeo")
184
+ self.jcm_solve = _binary_path(binary_dir, "JCMsolve")
185
+ self.jcm_view = _binary_path(binary_dir, "JCMview")
186
+ self.jcm_edit = _binary_path(binary_dir, "JCMedit")
187
+ self.jcm_control = _binary_path(binary_dir, "JCMcontrol")
188
+ self._has_binaries = self.jcm_solve.is_file()
189
+
190
+ if not self._has_binaries:
191
+ _logger.warning(
192
+ "JCMsolve binary not found at %s; startup-dependent operations are unavailable.",
193
+ self.jcm_solve,
194
+ )
195
+
196
+ async def startup(self) -> None:
197
+ """Load the JCMsuite installation and license information.
198
+
199
+ Call this method with `await` before you use `info()` in asynchronous
200
+ code. A second call reuses the information from the first call.
201
+
202
+ Returns
203
+ -------
204
+ None
205
+ This method has no return value.
206
+
207
+ Raises
208
+ ------
209
+ RuntimeContextError
210
+ If the JCMsuite installation is not configured, `JCMsolve` is not
211
+ available, or installation or license information cannot be read.
212
+ """
213
+
214
+ if self._has_startup_run:
215
+ _logger.log(TRACE, "SolverContext.startup() already completed; skipping.")
216
+ return
217
+
218
+ if self.jcm_solve is None or not self._has_binaries:
219
+ if self._jcm_root is None:
220
+ raise RuntimeContextError(
221
+ "JCMROOT is not configured, so JCMsuite binary discovery did not run. "
222
+ "Set the JCMROOT environment variable or call "
223
+ "`create_context(jcm_root=...)`."
224
+ )
225
+ raise RuntimeContextError(
226
+ "JCMsolve binary is not available; cannot execute startup probes. "
227
+ f"Expected binary at: {self.jcm_solve}."
228
+ )
229
+
230
+ self._installation = await self._get_installation_info()
231
+ self._license = await self._get_license_info()
232
+ self._has_startup_run = True
233
+
234
+ def info(
235
+ self,
236
+ *,
237
+ print: bool = True,
238
+ verbose: bool = False,
239
+ ) -> JCMInfoDetails:
240
+ """Return installation, system, and license information.
241
+
242
+ Parameters
243
+ ----------
244
+ print : bool, optional
245
+ If `True`, show the information in the terminal.
246
+ verbose : bool, optional
247
+ If `True`, also show the interface build time and Git commit
248
+ identifier.
249
+
250
+ Returns
251
+ -------
252
+ JCMInfoDetails
253
+ Installation, computer, interface, and license information.
254
+
255
+ Raises
256
+ ------
257
+ RuntimeError
258
+ If asynchronous code calls this method before `startup()` is
259
+ complete.
260
+ """
261
+
262
+ if not self._has_startup_run:
263
+ try:
264
+ asyncio.get_running_loop()
265
+ except RuntimeError:
266
+ asyncio.run(self.startup())
267
+ else:
268
+ raise RuntimeError(
269
+ "SolverContext.info() is synchronous. "
270
+ "Run `await context.startup()` first when calling inside "
271
+ "a running event loop."
272
+ )
273
+
274
+ installation_info: JCMInstallationDetails = self.installation
275
+ interface_info: JCMInterfaceDetails = load_interface_details()
276
+ system_info: JCMSystemDetails = self.system
277
+ license_info: JCMLicenseDetails = self.license
278
+ info_details: JCMInfoDetails = JCMInfoDetails(
279
+ installation=installation_info,
280
+ interface=interface_info,
281
+ system=system_info,
282
+ license=license_info,
283
+ )
284
+
285
+ if not print:
286
+ return info_details
287
+
288
+ year: int = dt.datetime.now().year
289
+ builtins.print(
290
+ f"\nCopyright (c) 2001-{year} JCMwave GmbH, Berlin. All Rights Reserved"
291
+ )
292
+ builtins.print("\n\n")
293
+ builtins.print(f"{'JCMROOT'.rjust(20)} : {installation_info.jcm_root}")
294
+ builtins.print(f"{'JCMsuite version'.rjust(20)} : {installation_info.version}")
295
+ builtins.print(f"{'Buildtag'.rjust(20)} : {installation_info.buildtag}")
296
+ builtins.print(f"{'Number CPUs'.rjust(20)} : {system_info.n_cores}")
297
+ builtins.print(
298
+ f"{'Number threads'.rjust(20)} : {system_info.n_threads if system_info.n_threads is not None else 'default'}"
299
+ )
300
+
301
+ if system_info.nodes is not None:
302
+ builtins.print(f"{'Nodes'.rjust(20)} : {system_info.nodes}")
303
+ if system_info.ooc_dir is not None:
304
+ builtins.print(f"{'OOC directory'.rjust(20)} : {system_info.ooc_dir}")
305
+ if system_info.temp_dir_root is not None:
306
+ builtins.print(f"{'Temp dir root'.rjust(20)} : {system_info.temp_dir_root}")
307
+ if system_info.max_core_size_mb is not None:
308
+ builtins.print(
309
+ f"{'Maximum core size'.rjust(20)} : {system_info.max_core_size_mb} [MB]"
310
+ )
311
+ if system_info.max_memory_mb is not None:
312
+ builtins.print(
313
+ f"{'Memory limit'.rjust(20)} : {system_info.max_memory_mb} [MB]"
314
+ )
315
+ if system_info.gpu_usage is not None:
316
+ builtins.print(f"{'GPUs'.rjust(20)} : {system_info.gpu_usage}")
317
+
318
+ if license_info.file is not None:
319
+ builtins.print(f"{'License file'.rjust(20)} : {license_info.file}")
320
+ builtins.print(f"{'License period'.rjust(20)} : {license_info.period}")
321
+ elif license_info.server is not None:
322
+ builtins.print(f"{'License server'.rjust(20)} : {license_info.server}")
323
+ else:
324
+ builtins.print("\n\n No valid license found.")
325
+
326
+ if verbose:
327
+ builtins.print("")
328
+ builtins.print("Interface metadata")
329
+ builtins.print(f"{'Package'.rjust(20)} : {interface_info.package_name}")
330
+ builtins.print(
331
+ f"{'Version'.rjust(20)} : {interface_info.version if interface_info.version is not None else 'unknown'}"
332
+ )
333
+ builtins.print(
334
+ f"{'Build time'.rjust(20)} : {interface_info.build_timestamp if interface_info.build_timestamp is not None else 'unknown'}"
335
+ )
336
+ builtins.print(
337
+ f"{'Git SHA'.rjust(20)} : {interface_info.git_commit_sha if interface_info.git_commit_sha is not None else 'unknown'}"
338
+ )
339
+ builtins.print(
340
+ f"{'SHA source'.rjust(20)} : {interface_info.git_commit_sha_source}"
341
+ )
342
+
343
+ builtins.print("\n\n")
344
+ return info_details
345
+
346
+ def _get_or_create_daemon_handler(self) -> DaemonHandler:
347
+ """Return the context-owned daemon handler instance."""
348
+
349
+ if self._daemon_handler is None:
350
+ from ..daemon.handler import DaemonHandler
351
+
352
+ self._daemon_handler = DaemonHandler(context=self)
353
+ return self._daemon_handler
354
+
355
+ def _get_daemon_handler(self) -> DaemonHandler | None:
356
+ """Return the context-owned daemon handler when it already exists."""
357
+
358
+ return self._daemon_handler
359
+
360
+ def _subprocess_environment(self) -> dict[str, str]:
361
+ """Return an environment with this context's local GPU setting applied."""
362
+
363
+ environment: dict[str, str] = dict(os.environ)
364
+ if self._jcm_root is not None:
365
+ environment["JCMROOT"] = str(self._jcm_root)
366
+ if self.system.gpu_usage == "no":
367
+ environment.pop("JCM_USE_GPUS", None)
368
+ elif self.system.gpu_usage is not None:
369
+ environment["JCM_USE_GPUS"] = self.system.gpu_usage
370
+ return environment
371
+
372
+ async def _get_installation_info(self) -> JCMInstallationDetails:
373
+ """Call `JCMsolve --version` and parse version/build metadata."""
374
+
375
+ from .subprocess_tools import _call_binary
376
+
377
+ if self.jcm_solve is None or self._jcm_root is None:
378
+ raise RuntimeContextError("JCMsolve path is not initialized.")
379
+
380
+ stdout: str
381
+ stderr: str
382
+ return_code: int | None
383
+ stdout, stderr, return_code = await _call_binary(self.jcm_solve, "--version")
384
+ if return_code not in (0, None):
385
+ raise RuntimeContextError(
386
+ f"Failed to probe installation info (exit={return_code}): {stderr}"
387
+ )
388
+
389
+ # Matches and captures into the groups `version_tag` and `build_tag`:
390
+ # - `Version[ ]*` -> matches the literal "Version" token and optional spaces.
391
+ # - `(?P<version_tag>\d+\.\d+\.\d+)` -> captures semantic version components
392
+ # (major.minor.patch).
393
+ # - `.*` -> consumes any intermediate text between version and build tag.
394
+ # `re.DOTALL` below allows this to cross line breaks in multiline output.
395
+ # - `Buildtag:[ ]*` -> matches the build tag label with optional spaces.
396
+ # - `(?P<build_tag>.*-\d+\.\d+\.\d+\.\d+\.\d+)` -> captures the full build tag,
397
+ # anchored by the legacy numeric tail pattern.
398
+ # Parsing is intentionally strict so malformed or changed upstream output fails
399
+ # fast with a clear context-level error.
400
+ version_and_build: re.Match[str] | None = re.search(
401
+ r"Version[ ]*(?P<version_tag>\d+\.\d+\.\d+).*Buildtag:[ ]*(?P<build_tag>.*-\d+\.\d+\.\d+\.\d+\.\d+)",
402
+ stdout,
403
+ flags=re.DOTALL,
404
+ )
405
+ if version_and_build is None:
406
+ raise RuntimeContextError(
407
+ "Could not parse JCMsuite version/buildtag output."
408
+ )
409
+
410
+ return JCMInstallationDetails(
411
+ jcm_root=self._jcm_root,
412
+ version=version_and_build.group("version_tag"),
413
+ buildtag=version_and_build.group("build_tag"),
414
+ )
415
+
416
+ async def _get_license_info(self) -> JCMLicenseDetails:
417
+ """Call `JCMsolve --license_info` and parse license metadata."""
418
+
419
+ from .subprocess_tools import _call_binary
420
+
421
+ if self.jcm_solve is None:
422
+ raise RuntimeContextError("JCMsolve path is not initialized.")
423
+
424
+ stdout: str
425
+ stderr: str
426
+ return_code: int | None
427
+ stdout, stderr, return_code = await _call_binary(
428
+ self.jcm_solve, "--license_info"
429
+ )
430
+ if return_code not in (0, None):
431
+ raise RuntimeContextError(
432
+ f"Failed to probe license info (exit={return_code}): {stderr}"
433
+ )
434
+
435
+ # Matches and captures into the group `license_file`:
436
+ # - `(?im)` -> enables case-insensitive and multiline matching.
437
+ # - `^\s*License File:` -> matches the start of a line, optional leading spaces,
438
+ # and the "License File:" label.
439
+ # - `\s*` -> allows flexible whitespace after the colon.
440
+ # - `(?:File\s*)?` -> optional literal "File" token used by some builds.
441
+ # - `(?: ... | ... )` -> two capture variants:
442
+ # 1) `"(?P<license_file>[^"]+)"` captures a quoted path (keeps spaces in path
443
+ # segments; supports Linux and Windows paths).
444
+ # 2) `(\S+)` fallback for unquoted, no-whitespace paths.
445
+ # We preserve this dual-branch behavior for parity with historical output variants
446
+ # seen in legacy environments.
447
+ license_file: re.Match[str] | None = re.search(
448
+ r'(?im)^\s*License File:\s*(?:File\s*)?(?:"(?P<license_file>[^"]+)"|(\S+))',
449
+ stdout,
450
+ )
451
+
452
+ # Matches and captures into the group `license_period`:
453
+ # - `(?im)` -> enables case-insensitive and multiline matching.
454
+ # - `^\s*License period:` -> matches the labeled line with optional
455
+ # leading spaces.
456
+ # - `[ ]*` -> allows optional spaces after the colon.
457
+ # - `(?P<license_period>...)` captures exactly one of:
458
+ # 1) `perpetual`
459
+ # 2) `YYYY-MM-DD -> YYYY-MM-DD`
460
+ # This pattern stays intentionally strict to reject ambiguous or malformed
461
+ # values instead of silently accepting them.
462
+ license_period: re.Match[str] | None = re.search(
463
+ r"(?im)^\s*License period:[ ]*(?P<license_period>perpetual|\d{4}-\d{2}-\d{2} -> \d{4}-\d{2}-\d{2})",
464
+ stdout,
465
+ )
466
+
467
+ # Matches and captures into the group `license_server`:
468
+ # - `(?im)` -> enables case-insensitive and multiline matching.
469
+ # - `^\s*server\s+address\s*:` -> matches the label while allowing
470
+ # flexible spaces and capitalization (`server address:` variants).
471
+ # - `\s*` -> allows spaces after the colon.
472
+ # - `(?P<license_server>[^\r\n]*)` -> captures the rest of the line up to
473
+ # newline as the server endpoint text.
474
+ # We trim surrounding spaces after capture so downstream state is normalized
475
+ # while preserving the original legacy extraction semantics.
476
+ license_server: re.Match[str] | None = re.search(
477
+ r"(?im)^\s*server\s+address\s*:\s*(?P<license_server>[^\r\n]*)",
478
+ stdout,
479
+ )
480
+
481
+ if license_server is not None and license_period is not None:
482
+ return JCMLicenseDetails(
483
+ server=license_server.group("license_server").strip(),
484
+ period=license_period.group("license_period").strip(),
485
+ )
486
+
487
+ if license_file is not None and license_period is not None:
488
+ file_match: str | None = license_file.group("license_file")
489
+ license_path: Path | None = None
490
+ if file_match is not None:
491
+ license_path = Path(file_match.strip())
492
+ return JCMLicenseDetails(
493
+ file=license_path,
494
+ period=license_period.group("license_period").strip(),
495
+ )
496
+
497
+ raise RuntimeContextError(
498
+ "Could not parse JCMsuite license information output."
499
+ )
500
+
501
+ @property
502
+ def jcm_root(self) -> Path | None:
503
+ """Return the JCMsuite installation directory.
504
+
505
+ Returns
506
+ -------
507
+ Path | None
508
+ Installation directory, or `None` if JCMsuite is not configured.
509
+ """
510
+
511
+ return self._jcm_root
512
+
513
+ @property
514
+ def system(self) -> JCMSystemDetails:
515
+ """Return the computer and solver settings.
516
+
517
+ Returns
518
+ -------
519
+ JCMSystemDetails
520
+ Detected computer information and configured solver limits.
521
+ """
522
+
523
+ return self._system
524
+
525
+ @property
526
+ def installation(self) -> JCMInstallationDetails:
527
+ """Return the JCMsuite installation information.
528
+
529
+ Call `startup()` before you read this property.
530
+
531
+ Returns
532
+ -------
533
+ JCMInstallationDetails
534
+ Installed JCMsuite version and directory.
535
+
536
+ Raises
537
+ ------
538
+ RuntimeContextError
539
+ If `startup()` has not loaded the installation information.
540
+ """
541
+
542
+ if self._installation is None:
543
+ raise RuntimeContextError(
544
+ "Installation information is unavailable; call startup() first."
545
+ )
546
+ return self._installation
547
+
548
+ @property
549
+ def license(self) -> JCMLicenseDetails:
550
+ """Return the JCMsuite license information.
551
+
552
+ Call `startup()` before you read this property.
553
+
554
+ Returns
555
+ -------
556
+ JCMLicenseDetails
557
+ Active JCMsuite license information.
558
+
559
+ Raises
560
+ ------
561
+ RuntimeContextError
562
+ If `startup()` has not loaded the license information.
563
+ """
564
+
565
+ if self._license is None:
566
+ raise RuntimeContextError(
567
+ "License information is unavailable; call startup() first."
568
+ )
569
+ return self._license