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
jcmsuite/geo/mesh.py ADDED
@@ -0,0 +1,302 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Geometry/mesh generation entrypoint for `jcmsuite`."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import asyncio
9
+ import math
10
+ import shutil
11
+ from collections.abc import Coroutine, Mapping
12
+ from pathlib import Path
13
+ from typing import Literal, overload
14
+
15
+ from ..context import SolverContext, resolve_context
16
+ from ..context.subprocess_tools import _call_binary
17
+ from ..exceptions import (
18
+ ConfigMappingError,
19
+ InvalidConfigurationError,
20
+ RuntimeContextError,
21
+ )
22
+ from ..internal.diagnostics import parse_source_position
23
+ from ..templates import jcmt2jcm
24
+
25
+
26
+ @overload
27
+ def geo(
28
+ project_dir: str | Path = ".",
29
+ *,
30
+ keys: Mapping[str, object] | None = None,
31
+ working_dir: str | Path | None = None,
32
+ suffix_pattern: str | None = None,
33
+ show: bool = False,
34
+ show_duration: float = float("inf"),
35
+ context: SolverContext | None = None,
36
+ asynchronous: Literal[False] = False,
37
+ ) -> None: ...
38
+
39
+
40
+ @overload
41
+ def geo(
42
+ project_dir: str | Path = ".",
43
+ *,
44
+ keys: Mapping[str, object] | None = None,
45
+ working_dir: str | Path | None = None,
46
+ suffix_pattern: str | None = None,
47
+ show: bool = False,
48
+ show_duration: float = float("inf"),
49
+ context: SolverContext | None = None,
50
+ asynchronous: Literal[True],
51
+ ) -> Coroutine[object, object, None]: ...
52
+
53
+
54
+ def geo(
55
+ project_dir: str | Path = ".",
56
+ *,
57
+ keys: Mapping[str, object] | None = None,
58
+ working_dir: str | Path | None = None,
59
+ suffix_pattern: str | None = None,
60
+ show: bool = False,
61
+ show_duration: float = float("inf"),
62
+ context: SolverContext | None = None,
63
+ asynchronous: bool = False,
64
+ ) -> None | Coroutine[object, object, None]:
65
+ """Create the mesh for a project with `JCMgeo`.
66
+
67
+ Parameters
68
+ ----------
69
+ project_dir : str | Path, optional
70
+ project directory that contains `layout.jcm` or `layout.jcmt`.
71
+ keys : Mapping[str, object] | None, optional
72
+ project keys for `.jcmt` input files.
73
+ working_dir : str | Path | None, optional
74
+ Directory in which `JCMgeo` creates the mesh. If omitted, use
75
+ `project_dir`.
76
+ suffix_pattern : str | None, optional
77
+ Suffix pattern that selects `layout.<suffix>.jcm` or
78
+ `layout.<suffix>.jcmt` before the unsuffixed file.
79
+ show : bool, optional
80
+ If `True`, show the generated mesh with `JCMgeo`.
81
+ show_duration : float, optional
82
+ Number of seconds to show the mesh if `show=True`. Use
83
+ `float("inf")` to keep the mesh window open.
84
+ context : SolverContext | None, optional
85
+ JCMsuite settings to use. If omitted, use the active context or the
86
+ default context.
87
+ asynchronous : bool, optional
88
+ If `True`, return a value that you must use with `await`.
89
+
90
+ Returns
91
+ -------
92
+ None | Coroutine[object, object, None]
93
+ `None` after the mesh is created. If `asynchronous` is `True`, returns
94
+ a coroutine that creates the mesh.
95
+
96
+ Raises
97
+ ------
98
+ InvalidConfigurationError
99
+ If a project directory or working directory is not valid.
100
+ ConfigMappingError
101
+ If `JCMgeo` reports an error at a position in an input file.
102
+ RuntimeContextError
103
+ If `JCMgeo` is not available.
104
+ RuntimeError
105
+ If `JCMgeo` fails. This error also occurs if asynchronous code calls
106
+ the function without `asynchronous=True`.
107
+ TypeError
108
+ If `show` is not a Boolean value or `show_duration` is not a number.
109
+ ValueError
110
+ If `show=True` and `show_duration` is not positive.
111
+ """
112
+
113
+ if asynchronous:
114
+ return _geo_impl(
115
+ project_dir=project_dir,
116
+ keys=keys,
117
+ working_dir=working_dir,
118
+ suffix_pattern=suffix_pattern,
119
+ show=show,
120
+ show_duration=show_duration,
121
+ context=context,
122
+ )
123
+
124
+ try:
125
+ asyncio.get_running_loop()
126
+ except RuntimeError:
127
+ return asyncio.run(
128
+ _geo_impl(
129
+ project_dir=project_dir,
130
+ keys=keys,
131
+ working_dir=working_dir,
132
+ suffix_pattern=suffix_pattern,
133
+ show=show,
134
+ show_duration=show_duration,
135
+ context=context,
136
+ )
137
+ )
138
+
139
+ raise RuntimeError(
140
+ "geo() called from a running event loop; use `await geo(..., asynchronous=True)`."
141
+ )
142
+
143
+
144
+ async def _geo_impl(
145
+ *,
146
+ project_dir: str | Path,
147
+ keys: Mapping[str, object] | None,
148
+ working_dir: str | Path | None,
149
+ suffix_pattern: str | None,
150
+ show: bool,
151
+ show_duration: float,
152
+ context: SolverContext | None,
153
+ ) -> None:
154
+ """Internal geo implementation shared by sync and async wrappers."""
155
+
156
+ resolved_context: SolverContext = resolve_context(context)
157
+ await resolved_context.startup()
158
+
159
+ geo_binary_path: Path | None = resolved_context.jcm_geo
160
+ if geo_binary_path is None or not geo_binary_path.is_file():
161
+ raise RuntimeContextError("JCMgeo binary is not available in the context.")
162
+
163
+ project_path: Path = Path(project_dir).expanduser().resolve()
164
+ if not project_path.is_dir():
165
+ raise InvalidConfigurationError(
166
+ f"project_dir must point to an existing directory: {project_path}"
167
+ )
168
+
169
+ resolved_working_dir: Path
170
+ if working_dir is None:
171
+ resolved_working_dir = project_path
172
+ else:
173
+ candidate_working_dir: Path = Path(working_dir).expanduser()
174
+ if not candidate_working_dir.is_absolute():
175
+ candidate_working_dir = (project_path / candidate_working_dir).resolve()
176
+ resolved_working_dir = candidate_working_dir.resolve()
177
+ resolved_working_dir.mkdir(parents=True, exist_ok=True)
178
+
179
+ if keys is not None or suffix_pattern is not None:
180
+ _prepare_geo_input_files(
181
+ project_path=project_path,
182
+ working_dir_path=resolved_working_dir,
183
+ keys={} if keys is None else keys,
184
+ suffix_pattern=suffix_pattern,
185
+ )
186
+
187
+ geo_args: list[str] = [str(resolved_working_dir)]
188
+ if not isinstance(show, bool):
189
+ raise TypeError("show -> boolean value expected.")
190
+ if not isinstance(show_duration, (int, float)) or isinstance(show_duration, bool):
191
+ raise TypeError("show_duration -> float value expected.")
192
+ if show:
193
+ if math.isinf(float(show_duration)) and show_duration > 0:
194
+ geo_args.append("--show")
195
+ elif math.isfinite(float(show_duration)) and show_duration > 0.0:
196
+ geo_args.extend(["--show", str(float(show_duration))])
197
+ else:
198
+ raise ValueError("show_duration must be positive or infinity.")
199
+
200
+ _stdout_text: str
201
+ stderr_text: str
202
+ return_code: int | None
203
+ _stdout_text, stderr_text, return_code = await _call_binary(
204
+ geo_binary_path,
205
+ args=geo_args,
206
+ )
207
+
208
+ if return_code not in (0, None):
209
+ source_path: Path | None
210
+ line: int | None
211
+ column: int | None
212
+ source_path, line, column = parse_source_position(
213
+ stderr_text,
214
+ base_dir=resolved_working_dir,
215
+ )
216
+ if source_path is not None:
217
+ raise ConfigMappingError(
218
+ "*** JCMgeo failed.",
219
+ source=source_path,
220
+ line=line,
221
+ column=column,
222
+ )
223
+ raise RuntimeError(f"*** JCMgeo failed. ==>\n\n{stderr_text}")
224
+
225
+ grid_path: Path = resolved_working_dir / "grid.jcm"
226
+ if not grid_path.is_file():
227
+ raise RuntimeError("*** JCMgeo failed.")
228
+
229
+
230
+ def _prepare_geo_input_files(
231
+ *,
232
+ project_path: Path,
233
+ working_dir_path: Path,
234
+ keys: Mapping[str, object],
235
+ suffix_pattern: str | None,
236
+ ) -> None:
237
+ """Prepare `layout` input files in the working directory."""
238
+
239
+ selected_any: bool = False
240
+ for jcm_file_name in ("layout.jcm",):
241
+ selected_template_path, selected_jcm_path = _select_geo_source_file(
242
+ project_path=project_path,
243
+ jcm_file_name=jcm_file_name,
244
+ suffix_pattern=suffix_pattern,
245
+ )
246
+ if selected_template_path is None and selected_jcm_path is None:
247
+ continue
248
+ selected_any = True
249
+ target_jcm_path: Path = working_dir_path / jcm_file_name
250
+
251
+ if selected_template_path is not None:
252
+ jcmt2jcm(
253
+ selected_template_path,
254
+ keys=keys,
255
+ outputfile=target_jcm_path,
256
+ )
257
+ continue
258
+
259
+ if (
260
+ selected_jcm_path is not None
261
+ and selected_jcm_path.is_file()
262
+ and selected_jcm_path.resolve() != target_jcm_path.resolve()
263
+ ):
264
+ shutil.copyfile(selected_jcm_path, target_jcm_path)
265
+
266
+ if suffix_pattern is not None and not selected_any:
267
+ raise InvalidConfigurationError(
268
+ f"No layout input matched suffix pattern {suffix_pattern!r} in {project_path}."
269
+ )
270
+
271
+
272
+ def _select_geo_source_file(
273
+ *,
274
+ project_path: Path,
275
+ jcm_file_name: str,
276
+ suffix_pattern: str | None,
277
+ ) -> tuple[Path | None, Path | None]:
278
+ """Select preferred template/jcm source file for geo input preparation."""
279
+
280
+ candidate_paths: list[Path] = []
281
+ if suffix_pattern is not None:
282
+ pattern_jcm_name: str = jcm_file_name.replace(".jcm", f".{suffix_pattern}.jcm")
283
+ candidate_paths.extend(
284
+ [
285
+ project_path / f"{pattern_jcm_name}t",
286
+ project_path / pattern_jcm_name,
287
+ ]
288
+ )
289
+ candidate_paths.extend(
290
+ [
291
+ project_path / f"{jcm_file_name}t",
292
+ project_path / jcm_file_name,
293
+ ]
294
+ )
295
+
296
+ for candidate_path in candidate_paths:
297
+ if candidate_path.is_file():
298
+ if candidate_path.suffix in (".jcmt", ".jcmpt"):
299
+ return candidate_path.resolve(), None
300
+ return None, candidate_path.resolve()
301
+
302
+ return None, None
@@ -0,0 +1,10 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Public info namespace for `jcmsuite`."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from .runtime_info import info
9
+
10
+ __all__: list[str] = ["info"]
@@ -0,0 +1,45 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Installation and runtime info entrypoint for `jcmsuite`."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from ..context import SolverContext, resolve_context
9
+ from ..context.models import JCMInfoDetails
10
+
11
+
12
+ def info(
13
+ *,
14
+ context: SolverContext | None = None,
15
+ print: bool = True,
16
+ verbose: bool = False,
17
+ ) -> JCMInfoDetails:
18
+ """Return installation, system, and license information.
19
+
20
+ Parameters
21
+ ----------
22
+ context : SolverContext | None, optional
23
+ JCMsuite settings to use. If omitted, use the active context or the
24
+ default context.
25
+ print : bool, optional
26
+ If `True`, show the information in the terminal.
27
+ verbose : bool, optional
28
+ If `True`, also show the interface build time and Git commit
29
+ identifier.
30
+
31
+ Returns
32
+ -------
33
+ JCMInfoDetails
34
+ Installation, computer, interface, and license information.
35
+
36
+ Raises
37
+ ------
38
+ RuntimeContextError
39
+ If JCMsuite is not configured or `JCMsolve` is not available.
40
+ RuntimeError
41
+ If called from asynchronous code before context startup is complete.
42
+ """
43
+
44
+ resolved_context: SolverContext = resolve_context(context)
45
+ return resolved_context.info(print=print, verbose=verbose)
@@ -0,0 +1,2 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
@@ -0,0 +1,74 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Diagnostic parsing helpers for source-mapped error handling."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import re
9
+ from pathlib import Path
10
+ from typing import TypeVar
11
+
12
+ _ExceptionT = TypeVar("_ExceptionT", bound=BaseException)
13
+
14
+
15
+ def trim_exception_traceback(error: _ExceptionT) -> _ExceptionT:
16
+ """Remove captured internal frames before a public boundary re-raises."""
17
+
18
+ error.__traceback__ = None
19
+ cause: BaseException | None = error.__cause__
20
+ while cause is not None:
21
+ cause.__traceback__ = None
22
+ cause = cause.__cause__
23
+ return error
24
+
25
+
26
+ def parse_source_position(
27
+ diagnostic_text: str,
28
+ *,
29
+ base_dir: Path | None = None,
30
+ ) -> tuple[Path | None, int | None, int | None]:
31
+ """Extract source path/line/column from diagnostic text.
32
+
33
+ Parameters
34
+ ----------
35
+ diagnostic_text : str
36
+ Raw stderr/diagnostic text.
37
+ base_dir : Path | None, optional
38
+ Optional base directory used to resolve relative source paths.
39
+
40
+ Returns
41
+ -------
42
+ tuple[Path | None, int | None, int | None]
43
+ `(source, line, column)` when recognized; `(None, None, None)` if no
44
+ source position is detected.
45
+ """
46
+
47
+ file_pattern: re.Pattern[str] = re.compile(
48
+ # Grouping intent:
49
+ # - Optional solver banner prefix, then `File` and a quoted path:
50
+ # matches diagnostics like `File "layout.jcm", line: 7, column: 5`.
51
+ # Live daemon failures can start with `*** Error: File ...`.
52
+ # - `line` capture:
53
+ # strict integer line number.
54
+ # - optional `column` capture:
55
+ # column may be absent for some tools.
56
+ r'(?im)^\s*(?:\*\*\*\s*Error:\s*)?File\s+"(?P<source>[^"]+)"\s*,\s*line\s*:\s*(?P<line>\d+)(?:\s*,\s*column\s*:\s*(?P<column>\d+))?',
57
+ )
58
+ file_match: re.Match[str] | None = file_pattern.search(diagnostic_text)
59
+ if file_match is None:
60
+ return None, None, None
61
+
62
+ source_text: str = file_match.group("source").strip()
63
+ line_text: str = file_match.group("line")
64
+ column_text: str | None = file_match.group("column")
65
+
66
+ source_path: Path = Path(source_text).expanduser()
67
+ if not source_path.is_absolute() and base_dir is not None:
68
+ source_path = (base_dir / source_path).resolve()
69
+ else:
70
+ source_path = source_path.resolve()
71
+
72
+ line: int = int(line_text)
73
+ column: int | None = int(column_text) if column_text is not None else None
74
+ return source_path, line, column
@@ -0,0 +1,80 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Shared progress-bar implementation for solve and daemon workflows."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from dataclasses import dataclass
9
+ from typing import Protocol, cast
10
+
11
+ from ..exceptions import InvalidConfigurationError
12
+
13
+
14
+ class _TqdmLike(Protocol):
15
+ """Subset of tqdm methods used by the tracked progress wrapper."""
16
+
17
+ def update(self, n: float | None = 1) -> bool | None: ...
18
+
19
+ def set_postfix_str(self, s: str) -> None: ...
20
+
21
+ def close(self) -> None: ...
22
+
23
+
24
+ class NoopProgressBar:
25
+ """No-op progress bar used when tqdm is unavailable or disabled."""
26
+
27
+ def update(self, count: int) -> None:
28
+ return None
29
+
30
+ def mark_failure(self, count: int = 1) -> None:
31
+ return None
32
+
33
+ def close(self) -> None:
34
+ return None
35
+
36
+
37
+ class ProgressBar(Protocol):
38
+ """Minimal progress-bar protocol."""
39
+
40
+ def update(self, count: int) -> None: ...
41
+
42
+ def mark_failure(self, count: int = 1) -> None: ...
43
+
44
+ def close(self) -> None: ...
45
+
46
+
47
+ @dataclass(slots=True)
48
+ class _TrackedTqdmProgressBar:
49
+ """Tqdm-backed progress bar with hidden failure-count postfix."""
50
+
51
+ bar: _TqdmLike
52
+ failure_count: int = 0
53
+
54
+ def update(self, count: int) -> None:
55
+ self.bar.update(count)
56
+
57
+ def mark_failure(self, count: int = 1) -> None:
58
+ self.failure_count += count
59
+ if self.failure_count > 0:
60
+ self.bar.set_postfix_str(f"fail: {self.failure_count}")
61
+
62
+ def close(self) -> None:
63
+ self.bar.close()
64
+
65
+
66
+ def create_progress_bar(*, total: int, enabled: bool, description: str) -> ProgressBar:
67
+ """Create a tqdm progress bar when requested; otherwise return no-op."""
68
+
69
+ if not enabled:
70
+ return NoopProgressBar()
71
+ try:
72
+ from tqdm.auto import tqdm
73
+ except Exception as exception:
74
+ raise InvalidConfigurationError(
75
+ "`progress=True` requires `tqdm` to be installed."
76
+ ) from exception
77
+ return cast(
78
+ ProgressBar,
79
+ _TrackedTqdmProgressBar(bar=tqdm(total=total, desc=description)),
80
+ )
@@ -0,0 +1,18 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Result loader namespace for `jcmsuite`."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from .cartesian_fields import CartesianFieldFormat as CartesianFieldFormat
9
+ from .cartesian_fields import load_cartesian_fields as load_cartesian_fields
10
+ from .powerflux import convert_to_powerflux as convert_to_powerflux
11
+ from .table import load_table as load_table
12
+
13
+ __all__: list[str] = [
14
+ "CartesianFieldFormat",
15
+ "convert_to_powerflux",
16
+ "load_cartesian_fields",
17
+ "load_table",
18
+ ]