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,407 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Namespaced daemon resource management API."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from collections.abc import Iterable
9
+ from typing import TYPE_CHECKING, Literal
10
+
11
+ from ..exceptions import InvalidConfigurationError
12
+ from .models import Cluster, DaemonResource, Queue, SlurmNodes, Workstation
13
+
14
+ if TYPE_CHECKING:
15
+ from .handler import DaemonHandler
16
+
17
+ ResourceKind = Literal["workstation", "cluster", "queue", "slurm"]
18
+
19
+
20
+ class DaemonResources:
21
+ """Resource namespace facade for daemon resource management.
22
+
23
+ Parameters
24
+ ----------
25
+ handler : DaemonHandler
26
+ Owning daemon handler instance.
27
+ """
28
+
29
+ def __init__(self, *, handler: DaemonHandler) -> None:
30
+
31
+ self._handler: DaemonHandler = handler
32
+
33
+ def add(self, resource: DaemonResource) -> DaemonResource:
34
+ """Add one compute resource to the daemon.
35
+
36
+ Parameters
37
+ ----------
38
+ resource : Workstation | Cluster | Queue | SlurmNodes
39
+ Workstation, cluster, queue, or active SLURM allocation to add.
40
+
41
+ Returns
42
+ -------
43
+ Workstation | Cluster | Queue | SlurmNodes
44
+ Added resource.
45
+
46
+ Raises
47
+ ------
48
+ InvalidConfigurationError
49
+ If the resource settings are not valid.
50
+ """
51
+
52
+ _validate_resource(resource)
53
+ return self._handler._add_resource_internal(resource)
54
+
55
+ def list(
56
+ self,
57
+ *,
58
+ kind: ResourceKind | None = None,
59
+ hostname: str | None = None,
60
+ ) -> tuple[DaemonResource, ...]:
61
+ """Return registered resources that match the filters.
62
+
63
+ Parameters
64
+ ----------
65
+ kind : {"workstation", "cluster", "queue", "slurm"} | None, optional
66
+ Resource type to select. If omitted, select all resource types.
67
+ hostname : str | None, optional
68
+ Hostname to select. If omitted, select all hostnames.
69
+
70
+ Returns
71
+ -------
72
+ tuple[Workstation | Cluster | Queue | SlurmNodes, ...]
73
+ Matching resources in registration order.
74
+ """
75
+
76
+ resources: tuple[DaemonResource, ...] = tuple(self._handler._resources)
77
+ filtered_resources: list[DaemonResource] = [
78
+ resource
79
+ for resource in resources
80
+ if _matches_filters(resource, kind=kind, hostname=hostname)
81
+ ]
82
+ return tuple(filtered_resources)
83
+
84
+ def info(
85
+ self,
86
+ *,
87
+ kind: ResourceKind | None = None,
88
+ hostname: str | None = None,
89
+ ) -> object:
90
+ """Return information for resources that match the filters.
91
+
92
+ Parameters
93
+ ----------
94
+ kind : {"workstation", "cluster", "queue", "slurm"} | None, optional
95
+ Resource type to select. If omitted, select all resource types.
96
+ hostname : str | None, optional
97
+ Hostname to select. If omitted, select all hostnames.
98
+
99
+ Returns
100
+ -------
101
+ object
102
+ Information supplied by the daemon. If the handler is not
103
+ connected, return the matching resource settings.
104
+ """
105
+
106
+ resources: tuple[DaemonResource, ...] = tuple(self._handler._resources)
107
+ matching_indices: list[int] = [
108
+ index
109
+ for index, resource in enumerate(resources)
110
+ if _matches_filters(resource, kind=kind, hostname=hostname)
111
+ ]
112
+ fallback_resources: tuple[DaemonResource, ...] = tuple(
113
+ resources[index] for index in matching_indices
114
+ )
115
+ return self._handler._resource_info_impl(
116
+ resource_indices=matching_indices,
117
+ fallback_resources=fallback_resources,
118
+ )
119
+
120
+ def delete(
121
+ self,
122
+ *,
123
+ kind: ResourceKind | None = None,
124
+ hostname: str | None = None,
125
+ allow_many: bool = False,
126
+ ) -> tuple[DaemonResource, ...]:
127
+ """Delete resources that match the filters.
128
+
129
+ Parameters
130
+ ----------
131
+ kind : {"workstation", "cluster", "queue", "slurm"} | None, optional
132
+ Resource type to select. If omitted, select all resource types.
133
+ hostname : str | None, optional
134
+ Hostname to select. If omitted, select all hostnames.
135
+ allow_many : bool, optional
136
+ If `True`, allow the method to delete multiple matching resources.
137
+
138
+ Returns
139
+ -------
140
+ tuple[Workstation | Cluster | Queue | SlurmNodes, ...]
141
+ Removed resources in the order in which they were added. Return an
142
+ empty tuple if no resource matches.
143
+
144
+ Raises
145
+ ------
146
+ InvalidConfigurationError
147
+ If multiple resources match and `allow_many` is `False`.
148
+ """
149
+
150
+ matching_indices: list[int] = [
151
+ index
152
+ for index, resource in enumerate(tuple(self._handler._resources))
153
+ if _matches_filters(resource, kind=kind, hostname=hostname)
154
+ ]
155
+ if not matching_indices:
156
+ return ()
157
+ if not allow_many and len(matching_indices) > 1:
158
+ raise InvalidConfigurationError(
159
+ "delete() matched multiple resources; set allow_many=True to confirm."
160
+ )
161
+ return self._handler._delete_resources_by_indices(matching_indices)
162
+
163
+
164
+ def _resource_kind(resource: DaemonResource) -> ResourceKind:
165
+ """Infer the resource kind discriminator for a daemon resource model.
166
+
167
+ Parameters
168
+ ----------
169
+ resource : DaemonResource
170
+ Resource declaration instance.
171
+
172
+ Returns
173
+ -------
174
+ ResourceKind
175
+ Canonical kind label used by filtering and delete operations.
176
+
177
+ Notes
178
+ -----
179
+ Internal API: this helper is an implementation detail and may change
180
+ without notice.
181
+ """
182
+
183
+ if isinstance(resource, Workstation):
184
+ return "workstation"
185
+ if isinstance(resource, Cluster):
186
+ return "cluster"
187
+ if isinstance(resource, SlurmNodes):
188
+ return "slurm"
189
+ if isinstance(resource, Queue):
190
+ return "queue"
191
+ return "queue"
192
+
193
+
194
+ def _resource_hostnames(resource: DaemonResource) -> tuple[str, ...]:
195
+ """Extract and normalize hostname chains from a daemon resource model.
196
+
197
+ Parameters
198
+ ----------
199
+ resource : DaemonResource
200
+ Resource declaration instance.
201
+
202
+ Returns
203
+ -------
204
+ tuple[str, ...]
205
+ Trimmed hostname chain entries for the resource.
206
+
207
+ Notes
208
+ -----
209
+ Internal API: this helper is an implementation detail and may change
210
+ without notice.
211
+ """
212
+
213
+ hostname_value: str | Iterable[str]
214
+ hostname_value = resource.hostname
215
+ if isinstance(hostname_value, str):
216
+ return _split_chain(hostname_value)
217
+ return tuple(str(entry).strip() for entry in hostname_value if str(entry).strip())
218
+
219
+
220
+ def _matches_filters(
221
+ resource: DaemonResource,
222
+ *,
223
+ kind: ResourceKind | None,
224
+ hostname: str | None,
225
+ ) -> bool:
226
+ """Check whether a resource matches optional kind/hostname filters.
227
+
228
+ Parameters
229
+ ----------
230
+ resource : DaemonResource
231
+ Resource declaration to evaluate.
232
+ kind : ResourceKind | None
233
+ Optional kind filter.
234
+ hostname : str | None
235
+ Optional hostname filter.
236
+
237
+ Returns
238
+ -------
239
+ bool
240
+ True when the expected condition is satisfied.
241
+
242
+ Notes
243
+ -----
244
+ Internal API: this helper is an implementation detail and may change
245
+ without notice.
246
+ """
247
+
248
+ if kind is not None and _resource_kind(resource) != kind:
249
+ return False
250
+ if hostname is None:
251
+ return True
252
+ normalized_hostname: str = hostname.strip()
253
+ if not normalized_hostname:
254
+ return True
255
+ return normalized_hostname in _resource_hostnames(resource)
256
+
257
+
258
+ def _split_chain(value: str) -> tuple[str, ...]:
259
+ """Split semicolon-separated host strings into normalized entries.
260
+
261
+ Parameters
262
+ ----------
263
+ value : str
264
+ Raw chain string.
265
+
266
+ Returns
267
+ -------
268
+ tuple[str, ...]
269
+ Non-empty hostname entries in order.
270
+
271
+ Notes
272
+ -----
273
+ Internal API: this helper is an implementation detail and may change
274
+ without notice.
275
+ """
276
+
277
+ entries: list[str] = [entry.strip() for entry in value.split(";")]
278
+ non_empty_entries: list[str] = [entry for entry in entries if entry]
279
+ return tuple(non_empty_entries)
280
+
281
+
282
+ def _validate_resource(resource: DaemonResource) -> None:
283
+ """Validate required invariants on one resource declaration.
284
+
285
+ Parameters
286
+ ----------
287
+ resource : DaemonResource
288
+ Resource declaration to validate before daemon registration.
289
+
290
+ Returns
291
+ -------
292
+ None
293
+ Raises when validation fails.
294
+
295
+ Notes
296
+ -----
297
+ Internal API: this helper is an implementation detail and may change
298
+ without notice.
299
+ """
300
+
301
+ hostnames: tuple[str, ...] = _resource_hostnames(resource)
302
+ if not hostnames:
303
+ raise InvalidConfigurationError("Resource hostname chain must not be empty.")
304
+ if resource.multiplicity < 1:
305
+ raise InvalidConfigurationError("Resource multiplicity must be >= 1.")
306
+
307
+ if isinstance(resource, Workstation):
308
+ if resource.n_threads < 1:
309
+ raise InvalidConfigurationError("Workstation n_threads must be >= 1.")
310
+ _validate_workstation_gpus(resource.gpus)
311
+ return
312
+
313
+ if isinstance(resource, Cluster):
314
+ if resource.n_threads < 1:
315
+ raise InvalidConfigurationError("Cluster n_threads must be >= 1.")
316
+ if not tuple(resource.nodes):
317
+ raise InvalidConfigurationError(
318
+ "Cluster resource must define at least one node."
319
+ )
320
+ for node in resource.nodes:
321
+ if node.gpu is not None and node.gpu < 0:
322
+ raise InvalidConfigurationError(
323
+ "Cluster node gpu must be a non-negative integer."
324
+ )
325
+ return
326
+
327
+ if isinstance(resource, SlurmNodes):
328
+ return
329
+
330
+ if resource.n_threads < 1:
331
+ raise InvalidConfigurationError("Queue n_threads must be >= 1.")
332
+ if resource.queue_type != "slurm":
333
+ raise InvalidConfigurationError("Only queue_type='slurm' is supported.")
334
+ if resource.n_gpus is not None and resource.n_gpus < 1:
335
+ raise InvalidConfigurationError("Queue n_gpus must be >= 1.")
336
+ if resource.gpu_type is not None and not resource.gpu_type.strip():
337
+ raise InvalidConfigurationError("Queue gpu_type must not be blank.")
338
+ if resource.gres is not None and not resource.gres.strip():
339
+ raise InvalidConfigurationError("Queue gres must not be blank.")
340
+ if (
341
+ resource.node_list.strip()
342
+ and resource.exclude_node.strip()
343
+ and resource.node_list.strip() == resource.exclude_node.strip()
344
+ ):
345
+ raise InvalidConfigurationError(
346
+ "Queue node_list and exclude_node cannot reference the same value."
347
+ )
348
+
349
+
350
+ def _validate_workstation_gpus(
351
+ gpu_value: object,
352
+ ) -> None:
353
+ """Validate workstation GPU selection declaration.
354
+
355
+ Parameters
356
+ ----------
357
+ gpu_value : object
358
+ Raw GPU declaration from `Workstation.gpus`.
359
+
360
+ Returns
361
+ -------
362
+ None
363
+ Raises when the GPU declaration is invalid.
364
+
365
+ Notes
366
+ -----
367
+ Internal API: this helper is an implementation detail and may change
368
+ without notice.
369
+ """
370
+
371
+ if gpu_value is None:
372
+ return
373
+ if isinstance(gpu_value, str):
374
+ if gpu_value not in {"all", "no"}:
375
+ raise InvalidConfigurationError(
376
+ "Workstation gpus string value must be 'all' or 'no'."
377
+ )
378
+ return
379
+ if isinstance(gpu_value, int):
380
+ if gpu_value < 0:
381
+ raise InvalidConfigurationError(
382
+ "Workstation gpus integer value must be non-negative."
383
+ )
384
+ return
385
+
386
+ if not isinstance(gpu_value, Iterable):
387
+ raise InvalidConfigurationError(
388
+ "Workstation gpus must be 'all', 'no', an integer, or a sequence of integers."
389
+ )
390
+
391
+ try:
392
+ gpu_sequence: tuple[object, ...] = tuple(gpu_value)
393
+ except TypeError as error:
394
+ raise InvalidConfigurationError(
395
+ "Workstation gpus must be 'all', 'no', an integer, or a sequence of integers."
396
+ ) from error
397
+
398
+ if not gpu_sequence:
399
+ raise InvalidConfigurationError(
400
+ "Workstation gpus sequence must contain at least one entry."
401
+ )
402
+ entry: object
403
+ for entry in gpu_sequence:
404
+ if not isinstance(entry, int) or entry < 0:
405
+ raise InvalidConfigurationError(
406
+ "Workstation gpus sequence entries must be non-negative integers."
407
+ )
@@ -0,0 +1,53 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """ContextVar-backed daemon handler scope helpers."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import contextvars
9
+ from typing import TYPE_CHECKING
10
+
11
+ from ..exceptions import RuntimeContextError
12
+
13
+ if TYPE_CHECKING:
14
+ from .handler import DaemonHandler
15
+
16
+ _CURRENT_DAEMON_HANDLER: contextvars.ContextVar[DaemonHandler | None] = (
17
+ contextvars.ContextVar("jcmsuite_current_daemon_handler", default=None)
18
+ )
19
+ _DAEMON_TOKEN_STACK: contextvars.ContextVar[
20
+ tuple[contextvars.Token[DaemonHandler | None], ...]
21
+ ] = contextvars.ContextVar("jcmsuite_daemon_token_stack", default=())
22
+
23
+
24
+ def _push_current_daemon_handler(handler: DaemonHandler) -> None:
25
+ """Bind a task-local daemon handler and store its reset token."""
26
+
27
+ token: contextvars.Token[DaemonHandler | None] = _CURRENT_DAEMON_HANDLER.set(
28
+ handler
29
+ )
30
+ token_stack: tuple[contextvars.Token[DaemonHandler | None], ...] = (
31
+ _DAEMON_TOKEN_STACK.get()
32
+ )
33
+ _DAEMON_TOKEN_STACK.set((*token_stack, token))
34
+
35
+
36
+ def _pop_current_daemon_handler() -> None:
37
+ """Restore previous task-local daemon handler from token stack."""
38
+
39
+ token_stack: tuple[contextvars.Token[DaemonHandler | None], ...] = (
40
+ _DAEMON_TOKEN_STACK.get()
41
+ )
42
+ if not token_stack:
43
+ raise RuntimeContextError("DaemonHandler exit called without a matching enter.")
44
+
45
+ token_to_reset: contextvars.Token[DaemonHandler | None] = token_stack[-1]
46
+ _CURRENT_DAEMON_HANDLER.reset(token_to_reset)
47
+ _DAEMON_TOKEN_STACK.set(token_stack[:-1])
48
+
49
+
50
+ def get_current_daemon_handler() -> DaemonHandler | None:
51
+ """Return currently scoped daemon handler for the active task/thread."""
52
+
53
+ return _CURRENT_DAEMON_HANDLER.get()
@@ -0,0 +1,223 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Socket transport helpers for daemon protocol communication."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import re
9
+ import socket
10
+ import struct
11
+ import subprocess
12
+ import tempfile
13
+ from dataclasses import dataclass
14
+ from logging import Logger
15
+ from pathlib import Path
16
+ from threading import RLock
17
+
18
+ from ..exceptions import BackendUnavailableError
19
+ from ..logging import TRACE, get_logger
20
+
21
+ _logger: Logger = get_logger(__name__)
22
+ _SOCKET_LOCK: RLock = RLock()
23
+ _HANDSHAKE_CONFIRM_SIGNAL: str = "__JCM_HANDSHAKE_OK__"
24
+
25
+
26
+ @dataclass(slots=True)
27
+ class DaemonTransportConnection:
28
+ """Connected daemon transport endpoint."""
29
+
30
+ client_socket: socket.socket
31
+ signature: str
32
+ url: str
33
+ port: int
34
+
35
+
36
+ def start_daemon_service(
37
+ *,
38
+ jcm_solve_binary: Path,
39
+ calling_pid: int,
40
+ start_command: str = "--start_daemon",
41
+ default_port: int | None = None,
42
+ ) -> DaemonTransportConnection:
43
+ """Start a JCM socket service through `JCMsolve` and connect."""
44
+
45
+ command: list[str] = [
46
+ str(jcm_solve_binary),
47
+ start_command,
48
+ "--bound",
49
+ str(calling_pid),
50
+ "--response_format",
51
+ "python",
52
+ ]
53
+ if default_port is not None:
54
+ command.extend(["--port", str(default_port)])
55
+
56
+ _logger.log(TRACE, "Starting daemon service: %s", command)
57
+ with (
58
+ tempfile.NamedTemporaryFile(suffix=".log.jcm", mode="w+b") as log_file,
59
+ tempfile.NamedTemporaryFile(suffix=".err.jcm", mode="w+b") as error_file,
60
+ ):
61
+ process: subprocess.Popen[bytes] = subprocess.Popen(
62
+ command,
63
+ stdout=log_file,
64
+ stderr=error_file,
65
+ close_fds=True,
66
+ )
67
+ process.wait()
68
+ log_file.seek(0)
69
+ error_file.seek(0)
70
+ log_text: str = log_file.read().decode("utf-8", errors="replace")
71
+ error_text: str = error_file.read().decode("utf-8", errors="replace")
72
+
73
+ # The daemon startup banner contains:
74
+ # - `running on port <int>` with the selected endpoint port.
75
+ # - `with signature <token>` used for socket handshake authentication.
76
+ # Parsing this line is required to connect the Python socket client.
77
+ match: re.Match[str] | None = re.search(
78
+ r"running on port (?P<port>\d+) with signature (?P<signature>\w+)",
79
+ log_text,
80
+ )
81
+ if match is None:
82
+ raise BackendUnavailableError(
83
+ "Failed to parse daemon startup endpoint from JCMsolve output. "
84
+ f"stderr={error_text.strip()!r}"
85
+ )
86
+
87
+ port: int = int(match.group("port"))
88
+ signature: str = match.group("signature")
89
+ connected_socket: socket.socket = connect_daemon_service(
90
+ host="localhost",
91
+ port=port,
92
+ signature=signature,
93
+ )
94
+ return DaemonTransportConnection(
95
+ client_socket=connected_socket,
96
+ signature=signature,
97
+ url=f"localhost:{port}",
98
+ port=port,
99
+ )
100
+
101
+
102
+ def connect_daemon_service(
103
+ *,
104
+ host: str,
105
+ port: int,
106
+ signature: str,
107
+ ) -> socket.socket:
108
+ """Connect to a running daemon service and perform handshake."""
109
+
110
+ client_socket: socket.socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
111
+ client_socket.connect((host, port))
112
+ client_socket.settimeout(None)
113
+ client_socket.sendall(signature.encode("utf-8"))
114
+ handshake_response: bytes = client_socket.recv(4096)
115
+ if (
116
+ handshake_response.decode("utf-8", errors="replace")
117
+ != _HANDSHAKE_CONFIRM_SIGNAL
118
+ ):
119
+ client_socket.close()
120
+ raise BackendUnavailableError("Daemon handshake failed: connection refused.")
121
+ return client_socket
122
+
123
+
124
+ def close_daemon_connection(connection: DaemonTransportConnection | None) -> None:
125
+ """Close daemon transport socket when available."""
126
+
127
+ if connection is None:
128
+ return
129
+ try:
130
+ connection.client_socket.close()
131
+ except OSError:
132
+ pass
133
+
134
+
135
+ def send_daemon_message(
136
+ *,
137
+ connection: DaemonTransportConnection,
138
+ message: str,
139
+ get_answer: bool = True,
140
+ ) -> str | None:
141
+ """Send one command to daemon and optionally receive response payload."""
142
+
143
+ with _SOCKET_LOCK:
144
+ connection.client_socket.sendall(_command_length_to_bytes(message))
145
+ connection.client_socket.sendall(message.encode("utf-8"))
146
+ if not get_answer:
147
+ return None
148
+ return _receive_sized_message(connection.client_socket)
149
+
150
+
151
+ def _command_length_to_bytes(command: str) -> bytes:
152
+ """Encode command length prefix for daemon socket framing.
153
+
154
+ Parameters
155
+ ----------
156
+ command : str
157
+ Command payload string sent to the daemon.
158
+
159
+ Returns
160
+ -------
161
+ bytes
162
+ 4-byte unsigned length prefix in daemon wire format.
163
+
164
+ Notes
165
+ -----
166
+ Internal API: this helper is an implementation detail and may change
167
+ without notice.
168
+ """
169
+
170
+ return struct.pack("I", len(command))
171
+
172
+
173
+ def _receive_sized_message(client_socket: socket.socket) -> str:
174
+ """Receive one size-prefixed UTF-8 message from the daemon socket.
175
+
176
+ Parameters
177
+ ----------
178
+ client_socket : socket.socket
179
+ Connected daemon socket used for framed payload reads.
180
+
181
+ Returns
182
+ -------
183
+ str
184
+ Decoded daemon response payload.
185
+
186
+ Notes
187
+ -----
188
+ Internal API: this helper is an implementation detail and may change
189
+ without notice.
190
+ """
191
+
192
+ size_buffer: bytearray = bytearray()
193
+ payload_buffer: bytearray = bytearray()
194
+ message_size: int | None = None
195
+
196
+ while True:
197
+ recv_size: int = (
198
+ 4
199
+ if message_size is None
200
+ else min(
201
+ max(message_size - len(payload_buffer), 1),
202
+ 524288,
203
+ )
204
+ )
205
+ chunk: bytes = client_socket.recv(recv_size)
206
+ if not chunk:
207
+ raise BackendUnavailableError(
208
+ "Daemon socket closed while receiving payload."
209
+ )
210
+
211
+ if message_size is None:
212
+ bytes_needed: int = 4 - len(size_buffer)
213
+ size_buffer.extend(chunk[:bytes_needed])
214
+ if len(size_buffer) == 4:
215
+ message_size = int(struct.unpack("I", size_buffer)[0])
216
+ payload_buffer.extend(chunk[bytes_needed:])
217
+ continue
218
+
219
+ payload_buffer.extend(chunk)
220
+ if len(payload_buffer) >= message_size:
221
+ break
222
+
223
+ return bytes(payload_buffer[:message_size]).decode("utf-8", errors="replace")
@@ -0,0 +1,10 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Public editing namespace for `jcmsuite`."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from .editor import edit
9
+
10
+ __all__: list[str] = ["edit"]