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,801 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Daemon protocol command builders and response parsing helpers."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import os
9
+ from collections.abc import Mapping, Sequence
10
+ from dataclasses import dataclass, field
11
+ from pathlib import Path
12
+ from typing import Literal, cast
13
+
14
+ from jcmsuite_data_tree import (
15
+ TreeDir,
16
+ TreePrimitive,
17
+ create_tree_dir,
18
+ data_primitives,
19
+ serialize_tree_dir,
20
+ )
21
+
22
+ from ..exceptions import BackendUnavailableError
23
+ from .internal.bundle_protocol import build_bundle_submit_command
24
+ from .models import Cluster, ClusterNode, DaemonResource, Queue, SlurmNodes, Workstation
25
+
26
+ DaemonScalar = int | float | str
27
+ DaemonPrimitive = DaemonScalar | Sequence[int]
28
+
29
+
30
+ @dataclass(slots=True)
31
+ class DaemonTreeNode:
32
+ """Small typed tree node used to serialize daemon command payloads."""
33
+
34
+ name: str
35
+ primitives: Mapping[str, DaemonPrimitive] = field(default_factory=dict)
36
+ branches: Sequence["DaemonTreeNode"] = field(default_factory=tuple)
37
+
38
+
39
+ def build_register_workstation_command(resource: DaemonResource) -> str:
40
+ """Build a `RegisterResource` command for one workstation resource."""
41
+
42
+ if not isinstance(resource, Workstation):
43
+ raise BackendUnavailableError(
44
+ "build_register_workstation_command requires Workstation resource."
45
+ )
46
+
47
+ normalized_connection: _NormalizedConnection = _normalize_connection(
48
+ hostname=resource.hostname,
49
+ login=resource.login,
50
+ ssh_client=resource.ssh_client,
51
+ pem_file=resource.pem_file,
52
+ )
53
+
54
+ root_primitives: dict[str, DaemonPrimitive] = {
55
+ "Hostname": normalized_connection.hostname_chain,
56
+ "Login": normalized_connection.login_chain,
57
+ "Multiplicity": resource.multiplicity,
58
+ }
59
+ if normalized_connection.ssh_client_chain:
60
+ root_primitives["SSHClient"] = normalized_connection.ssh_client_chain
61
+ if resource.ssh_agent_forwarding is not None:
62
+ root_primitives["SSHAgentForwarding"] = (
63
+ "yes" if resource.ssh_agent_forwarding else "no"
64
+ )
65
+ if resource.ssh_timeout_s is not None:
66
+ root_primitives["SSHTimeOut"] = resource.ssh_timeout_s
67
+ if normalized_connection.pem_chain is not None:
68
+ root_primitives["PEMFile"] = normalized_connection.pem_chain
69
+ if resource.jcm_root is not None:
70
+ # Resource paths belong to the target host, not the client filesystem.
71
+ root_primitives["JCMROOT"] = str(resource.jcm_root)
72
+ if resource.license_server_port is not None:
73
+ root_primitives["LicenseServerPort"] = resource.license_server_port
74
+
75
+ workstation: DaemonTreeNode = DaemonTreeNode(
76
+ name="Workstation",
77
+ primitives={
78
+ "NThreads": resource.n_threads,
79
+ "WorkingDir": str(resource.working_dir),
80
+ },
81
+ )
82
+ workstation_primitives: dict[str, DaemonPrimitive] = dict(workstation.primitives)
83
+ if resource.ooc_dir is not None:
84
+ workstation_primitives["OOCDir"] = str(resource.ooc_dir)
85
+ if resource.max_core_size_mb is not None:
86
+ workstation_primitives["MaxCoreSize"] = resource.max_core_size_mb
87
+ if resource.memory_limit_mb is not None:
88
+ workstation_primitives["MemoryLimit"] = resource.memory_limit_mb
89
+ if resource.gpus is not None:
90
+ workstation_primitives["GPUs"] = _serialize_workstation_gpus(resource.gpus)
91
+ workstation = DaemonTreeNode(
92
+ name="Workstation",
93
+ primitives=workstation_primitives,
94
+ )
95
+
96
+ return serialize_task_command(
97
+ DaemonTreeNode(
98
+ name="RegisterResource",
99
+ primitives=root_primitives,
100
+ branches=(workstation,),
101
+ )
102
+ )
103
+
104
+
105
+ def build_register_cluster_command(resource: Cluster) -> str:
106
+ """Build a `RegisterResource` command for one cluster resource."""
107
+
108
+ normalized_connection: _NormalizedConnection = _normalize_connection(
109
+ hostname=resource.hostname,
110
+ login=resource.login,
111
+ ssh_client=resource.ssh_client,
112
+ pem_file=resource.pem_file,
113
+ )
114
+ root_primitives: dict[str, DaemonPrimitive] = {
115
+ "Hostname": normalized_connection.hostname_chain,
116
+ "Login": normalized_connection.login_chain,
117
+ "Multiplicity": resource.multiplicity,
118
+ }
119
+ if normalized_connection.ssh_client_chain:
120
+ root_primitives["SSHClient"] = normalized_connection.ssh_client_chain
121
+ if resource.ssh_agent_forwarding is not None:
122
+ root_primitives["SSHAgentForwarding"] = (
123
+ "yes" if resource.ssh_agent_forwarding else "no"
124
+ )
125
+ if resource.ssh_timeout_s is not None:
126
+ root_primitives["SSHTimeOut"] = resource.ssh_timeout_s
127
+ if normalized_connection.pem_chain is not None:
128
+ root_primitives["PEMFile"] = normalized_connection.pem_chain
129
+ if resource.jcm_root is not None:
130
+ # Resource paths belong to the target host, not the client filesystem.
131
+ root_primitives["JCMROOT"] = str(resource.jcm_root)
132
+ if resource.license_server_port is not None:
133
+ root_primitives["LicenseServerPort"] = resource.license_server_port
134
+
135
+ cluster_primitives: dict[str, DaemonPrimitive] = {
136
+ "NThreads": resource.n_threads,
137
+ "WorkingDir": str(resource.working_dir),
138
+ }
139
+ if resource.ooc_dir is not None:
140
+ cluster_primitives["OOCDir"] = str(resource.ooc_dir)
141
+ if resource.max_core_size_mb is not None:
142
+ cluster_primitives["MaxCoreSize"] = resource.max_core_size_mb
143
+ cluster_branches: list[DaemonTreeNode] = [
144
+ _build_cluster_node_branch(node) for node in resource.nodes
145
+ ]
146
+
147
+ cluster_branch: DaemonTreeNode = DaemonTreeNode(
148
+ name="Cluster",
149
+ primitives=cluster_primitives,
150
+ branches=tuple(cluster_branches),
151
+ )
152
+ return serialize_task_command(
153
+ DaemonTreeNode(
154
+ name="RegisterResource",
155
+ primitives=root_primitives,
156
+ branches=(cluster_branch,),
157
+ )
158
+ )
159
+
160
+
161
+ def build_register_queue_command(resource: Queue) -> str:
162
+ """Build a `RegisterResource` command for one queue resource."""
163
+
164
+ normalized_connection: _NormalizedConnection = _normalize_connection(
165
+ hostname=resource.hostname,
166
+ login=resource.login,
167
+ ssh_client=resource.ssh_client,
168
+ pem_file=resource.pem_file,
169
+ )
170
+ root_primitives: dict[str, DaemonPrimitive] = {
171
+ "Hostname": normalized_connection.hostname_chain,
172
+ "Login": normalized_connection.login_chain,
173
+ "Multiplicity": resource.multiplicity,
174
+ }
175
+ if normalized_connection.ssh_client_chain:
176
+ root_primitives["SSHClient"] = normalized_connection.ssh_client_chain
177
+ if resource.ssh_agent_forwarding is not None:
178
+ root_primitives["SSHAgentForwarding"] = (
179
+ "yes" if resource.ssh_agent_forwarding else "no"
180
+ )
181
+ if resource.ssh_timeout_s is not None:
182
+ root_primitives["SSHTimeOut"] = resource.ssh_timeout_s
183
+ if normalized_connection.pem_chain is not None:
184
+ root_primitives["PEMFile"] = normalized_connection.pem_chain
185
+ if resource.jcm_root is not None:
186
+ # Resource paths belong to the target host, not the client filesystem.
187
+ root_primitives["JCMROOT"] = str(resource.jcm_root)
188
+ if resource.remote_daemon_port is not None:
189
+ root_primitives["Port"] = resource.remote_daemon_port
190
+ if resource.remote_daemon_signature is not None:
191
+ root_primitives["Signature"] = resource.remote_daemon_signature
192
+ if resource.exclusive is not None:
193
+ root_primitives["Exclusive"] = "yes" if resource.exclusive else "no"
194
+
195
+ queue_primitives: dict[str, DaemonPrimitive] = {
196
+ "Type": resource.queue_type.capitalize(),
197
+ "Account": resource.account,
198
+ "JobName": resource.job_name,
199
+ "PartitionName": resource.partition_name,
200
+ "WorkingDir": str(resource.working_dir),
201
+ "NThreads": resource.n_threads,
202
+ }
203
+ if resource.n_nodes is not None:
204
+ queue_primitives["NNodes"] = resource.n_nodes
205
+ if resource.n_tasks is not None:
206
+ queue_primitives["NTasks"] = resource.n_tasks
207
+ if resource.n_tasks_per_node is not None:
208
+ queue_primitives["NTasksPerNode"] = resource.n_tasks_per_node
209
+ if resource.node_list:
210
+ queue_primitives["NodeList"] = resource.node_list
211
+ if resource.exclude_node:
212
+ queue_primitives["ExcludeNode"] = resource.exclude_node
213
+ if resource.cmd_line_args:
214
+ queue_primitives["CmdLineArgs"] = resource.cmd_line_args
215
+ if resource.time_minutes is not None:
216
+ queue_primitives["Time"] = float(resource.time_minutes)
217
+ if resource.features is not None:
218
+ queue_primitives["Features"] = resource.features
219
+ if resource.memory_per_job_mb is not None:
220
+ queue_primitives["MemoryPerJob"] = resource.memory_per_job_mb
221
+ if resource.ooc_dir is not None:
222
+ queue_primitives["OOCDir"] = str(resource.ooc_dir)
223
+ if resource.max_core_size_mb is not None:
224
+ queue_primitives["MaxCoreSize"] = resource.max_core_size_mb
225
+ if resource.environment is not None:
226
+ queue_primitives["Environment"] = resource.environment
227
+ if resource.gpu_type is not None:
228
+ queue_primitives["GPUType"] = resource.gpu_type
229
+ if resource.n_gpus is not None:
230
+ queue_primitives["NGPUs"] = resource.n_gpus
231
+ if resource.gres is not None:
232
+ queue_primitives["GRES"] = resource.gres
233
+
234
+ queue_branch: DaemonTreeNode = DaemonTreeNode(
235
+ name="Queue",
236
+ primitives=queue_primitives,
237
+ )
238
+ return serialize_task_command(
239
+ DaemonTreeNode(
240
+ name="RegisterResource",
241
+ primitives=root_primitives,
242
+ branches=(queue_branch,),
243
+ )
244
+ )
245
+
246
+
247
+ def build_register_slurm_nodes_command(resource: SlurmNodes) -> str:
248
+ """Build a `RegisterResource` command for one SLURM allocation resource."""
249
+
250
+ if not isinstance(resource, SlurmNodes):
251
+ raise BackendUnavailableError(
252
+ "build_register_slurm_nodes_command requires SlurmNodes resource."
253
+ )
254
+
255
+ task_ids: list[int]
256
+ if resource.task_ids is None:
257
+ task_ids = []
258
+ elif isinstance(resource.task_ids, int):
259
+ task_ids = [resource.task_ids]
260
+ elif isinstance(resource.task_ids, set):
261
+ task_ids = sorted(int(task_id) for task_id in resource.task_ids)
262
+ else:
263
+ task_ids = [int(task_id) for task_id in resource.task_ids]
264
+
265
+ slurm_branch: DaemonTreeNode = DaemonTreeNode(
266
+ name="SlurmNodes",
267
+ primitives={
268
+ "TaskIds": task_ids,
269
+ "UseAsCluster": "yes" if resource.cluster else "no",
270
+ },
271
+ )
272
+ return serialize_task_command(
273
+ DaemonTreeNode(
274
+ name="RegisterResource",
275
+ primitives={"Hostname": "localhost"},
276
+ branches=(slurm_branch,),
277
+ )
278
+ )
279
+
280
+
281
+ def build_register_resource_command(resource: DaemonResource) -> str:
282
+ """Build a `RegisterResource` command for any typed resource."""
283
+
284
+ if isinstance(resource, Workstation):
285
+ return build_register_workstation_command(resource)
286
+ if isinstance(resource, Cluster):
287
+ return build_register_cluster_command(resource)
288
+ if isinstance(resource, SlurmNodes):
289
+ return build_register_slurm_nodes_command(resource)
290
+ return build_register_queue_command(resource)
291
+
292
+
293
+ def build_submit_job_command(
294
+ *,
295
+ project_file: Path | Sequence[Path],
296
+ mode: str = "solve",
297
+ resources: Sequence[int] | None = None,
298
+ log_file: Path | None = None,
299
+ ) -> str:
300
+ """Build one `SubmitJob` for a project or an ordered project bundle."""
301
+
302
+ if not isinstance(project_file, Path):
303
+ return build_bundle_submit_command(
304
+ project_files=project_file,
305
+ mode=mode,
306
+ resources=resources,
307
+ log_file=log_file,
308
+ )
309
+ submit_primitives: dict[str, DaemonPrimitive] = {
310
+ "ProjectFile": str(project_file),
311
+ "Mode": mode,
312
+ "Resource": [] if resources is None else list(resources),
313
+ }
314
+ if log_file is not None:
315
+ submit_primitives["LogFile"] = str(log_file)
316
+ return serialize_task_command(
317
+ DaemonTreeNode(name="SubmitJob", primitives=submit_primitives)
318
+ )
319
+
320
+
321
+ def build_job_info_command(
322
+ *,
323
+ job_ids: Sequence[int],
324
+ status_only: bool,
325
+ ) -> str:
326
+ """Build a `JobInfo` command for selected job identifiers."""
327
+
328
+ return serialize_task_command(
329
+ DaemonTreeNode(
330
+ name="JobInfo",
331
+ primitives={
332
+ "Id": list(job_ids),
333
+ "StatusOnly": int(status_only),
334
+ },
335
+ )
336
+ )
337
+
338
+
339
+ def build_close_job_command(
340
+ *,
341
+ job_ids: Sequence[int],
342
+ ) -> str:
343
+ """Build a `CloseJob` command for selected job identifiers."""
344
+
345
+ return serialize_task_command(
346
+ DaemonTreeNode(
347
+ name="CloseJob",
348
+ primitives={
349
+ "Id": list(job_ids),
350
+ },
351
+ )
352
+ )
353
+
354
+
355
+ def build_shutdown_command() -> str:
356
+ """Build a `Shutdown` command."""
357
+
358
+ return serialize_task_command(DaemonTreeNode(name="Shutdown"))
359
+
360
+
361
+ def build_daemon_status_command() -> str:
362
+ """Build a `DaemonStatus` command."""
363
+
364
+ return serialize_task_command(DaemonTreeNode(name="DaemonStatus"))
365
+
366
+
367
+ def build_resource_info_command(
368
+ *,
369
+ resource_ids: Sequence[int] | None = None,
370
+ ) -> str:
371
+ """Build a `ResourceInfo` command for selected resource identifiers."""
372
+
373
+ ids: list[int] = [] if resource_ids is None else list(resource_ids)
374
+ return serialize_task_command(
375
+ DaemonTreeNode(
376
+ name="ResourceInfo",
377
+ primitives={
378
+ "Id": ids,
379
+ },
380
+ )
381
+ )
382
+
383
+
384
+ def build_remove_resource_command(
385
+ *,
386
+ resource_ids: Sequence[int] | None = None,
387
+ hostname: str = "",
388
+ ) -> str:
389
+ """Build a `RemoveResource` command for selected resources."""
390
+
391
+ ids: list[int] = [] if resource_ids is None else list(resource_ids)
392
+ return serialize_task_command(
393
+ DaemonTreeNode(
394
+ name="RemoveResource",
395
+ primitives={
396
+ "Hostname": hostname,
397
+ "Id": ids,
398
+ },
399
+ )
400
+ )
401
+
402
+
403
+ def serialize_task_command(task: DaemonTreeNode) -> str:
404
+ """Serialize one daemon task node with required top-level `Task` wrapper.
405
+
406
+ Notes
407
+ -----
408
+ Legacy daemon payloads are serialized from a synthetic `root` node, but the
409
+ serializer emits only branch nodes of that root. In practice, the command
410
+ text starts at `Task { ... }` and does not include an outer `root { ... }`
411
+ block. New protocol output mirrors that behavior for compatibility.
412
+ """
413
+
414
+ root_dir: TreeDir = create_tree_dir("root")
415
+ task_wrapper: DaemonTreeNode = DaemonTreeNode(name="Task", branches=(task,))
416
+ root_dir.AddTreeDir(_to_tree_dir(task_wrapper))
417
+ serialized: str = serialize_tree_dir(root_dir)
418
+ return serialized.lstrip("\n")
419
+
420
+
421
+ def extract_return_value(response_payload: str) -> object:
422
+ """Extract daemon `ReturnValue` from python-formatted response payload."""
423
+
424
+ # Legacy daemon `--response_format python` returns Python assignments
425
+ # (typically `s0 = {...}`) rather than JSON. `exec` is therefore required
426
+ # to preserve protocol compatibility.
427
+ escaped_payload: str = response_payload.replace("\\", "\\\\")
428
+ namespace: dict[str, object] = {}
429
+ exec(escaped_payload, {}, namespace)
430
+ root_payload: object = namespace.get("s0")
431
+ if not isinstance(root_payload, Mapping):
432
+ raise BackendUnavailableError(
433
+ "Daemon response payload is missing root mapping."
434
+ )
435
+
436
+ typed_root_payload: Mapping[str, object] = cast(Mapping[str, object], root_payload)
437
+ return_value: object | None = typed_root_payload.get("ReturnValue")
438
+ if return_value is not None:
439
+ return return_value
440
+
441
+ error_payload: object | None = typed_root_payload.get("Error")
442
+ if isinstance(error_payload, Mapping):
443
+ error_message: object | None = error_payload.get("Message")
444
+ raise BackendUnavailableError(f"Daemon command failed: {error_message}")
445
+
446
+ raise BackendUnavailableError(
447
+ "Daemon response payload does not contain ReturnValue."
448
+ )
449
+
450
+
451
+ def _to_tree_dir(node: DaemonTreeNode) -> TreeDir:
452
+ """Convert a typed daemon tree node into a runtime TreeDir object.
453
+
454
+ Parameters
455
+ ----------
456
+ node : DaemonTreeNode
457
+ Typed daemon tree node containing primitive values and child branches.
458
+
459
+ Returns
460
+ -------
461
+ TreeDir
462
+ Runtime ``TreeDir`` instance compatible with daemon APIs.
463
+
464
+ Notes
465
+ -----
466
+ Internal API: this helper is an implementation detail and may change
467
+ without notice.
468
+ """
469
+
470
+ tree_dir: TreeDir = create_tree_dir(node.name)
471
+ primitive_name: str
472
+ primitive_value: DaemonPrimitive
473
+ for primitive_name, primitive_value in node.primitives.items():
474
+ tree_dir.AddPrimitive(primitive_name, _to_tree_primitive(primitive_value))
475
+ branch: DaemonTreeNode
476
+ for branch in node.branches:
477
+ tree_dir.AddTreeDir(_to_tree_dir(branch))
478
+ return tree_dir
479
+
480
+
481
+ def _to_tree_primitive(value: DaemonPrimitive) -> TreePrimitive:
482
+ """Convert a typed daemon primitive into a runtime tree primitive.
483
+
484
+ Parameters
485
+ ----------
486
+ value : DaemonPrimitive
487
+ Typed primitive payload (scalar, text, or integer vector).
488
+
489
+ Returns
490
+ -------
491
+ TreePrimitive
492
+ Runtime tree primitive instance used by daemon command builders.
493
+
494
+ Notes
495
+ -----
496
+ Internal API: this helper is an implementation detail and may change
497
+ without notice.
498
+ """
499
+
500
+ if isinstance(value, str):
501
+ escaped: str = value.replace("\\", "\\\\").replace('"', '\\"')
502
+ return data_primitives.StringPrimitive.Create(quotMarks=True, strArg=escaped)
503
+ if isinstance(value, int):
504
+ return data_primitives.NumberPrimitive.Create(value, int)
505
+ if isinstance(value, float):
506
+ return data_primitives.NumberPrimitive.Create(value, float)
507
+ return data_primitives.VectorPrimitive.Create(list(value), int)
508
+
509
+
510
+ @dataclass(slots=True, frozen=True)
511
+ class _NormalizedConnection:
512
+ hostname_chain: str
513
+ login_chain: str
514
+ ssh_client_chain: str | None
515
+ pem_chain: str | None
516
+
517
+
518
+ def _build_cluster_node_branch(node: ClusterNode) -> DaemonTreeNode:
519
+ """Build the daemon tree branch describing one cluster node.
520
+
521
+ Parameters
522
+ ----------
523
+ node : ClusterNode
524
+ Cluster node model from the public daemon resource API.
525
+
526
+ Returns
527
+ -------
528
+ DaemonTreeNode
529
+ Serialized node branch ready to embed into a cluster resource tree.
530
+
531
+ Notes
532
+ -----
533
+ Internal API: this helper is an implementation detail and may change
534
+ without notice.
535
+ """
536
+
537
+ node_primitives: dict[str, DaemonPrimitive] = {"Hostname": node.hostname}
538
+ if node.jcm_root is not None:
539
+ # Node installation paths are interpreted on the cluster node.
540
+ node_primitives["JCMROOT"] = str(node.jcm_root)
541
+ if node.memory_limit_mb is not None:
542
+ node_primitives["MemoryLimit"] = node.memory_limit_mb
543
+ if node.gpu is not None:
544
+ node_primitives["GPU"] = node.gpu
545
+ return DaemonTreeNode(name="Node", primitives=node_primitives)
546
+
547
+
548
+ def _serialize_workstation_gpus(
549
+ gpu_value: Literal["all", "no"] | int | Sequence[int],
550
+ ) -> DaemonPrimitive:
551
+ """Serialize workstation GPU declaration into daemon primitive payload.
552
+
553
+ Parameters
554
+ ----------
555
+ gpu_value : Literal["all", "no"] | int | Sequence[int]
556
+ GPU selection value from `Workstation.gpus`.
557
+
558
+ Returns
559
+ -------
560
+ DaemonPrimitive
561
+ String literal (`"all"`/`"no"`) or integer-vector selection payload.
562
+
563
+ Notes
564
+ -----
565
+ Internal API: this helper is an implementation detail and may change
566
+ without notice.
567
+ """
568
+
569
+ if isinstance(gpu_value, str):
570
+ return gpu_value
571
+ if isinstance(gpu_value, int):
572
+ return [gpu_value]
573
+ return list(gpu_value)
574
+
575
+
576
+ def _normalize_connection(
577
+ *,
578
+ hostname: str | Sequence[str],
579
+ login: str | Sequence[str | None] | None,
580
+ ssh_client: str | Sequence[str | None] | None,
581
+ pem_file: Path | str | Sequence[Path | str | None] | None,
582
+ ) -> _NormalizedConnection:
583
+ """Normalize connection-chain inputs into semicolon-separated daemon tokens.
584
+
585
+ Parameters
586
+ ----------
587
+ hostname : str | Sequence[str]
588
+ One hostname or a full hop chain.
589
+ login : str | Sequence[str | None] | None
590
+ Login value(s), optionally one per hop.
591
+ ssh_client : str | Sequence[str | None] | None
592
+ SSH client command value(s), optionally one per hop.
593
+ pem_file : Path | str | Sequence[Path | str | None] | None
594
+ Optional pem-file path(s), optionally one per hop.
595
+
596
+ Returns
597
+ -------
598
+ _NormalizedConnection
599
+ Normalized connection model ready for daemon payload serialization.
600
+
601
+ Notes
602
+ -----
603
+ Internal API: this helper is an implementation detail and may change
604
+ without notice.
605
+ """
606
+
607
+ host_chain: tuple[str, ...] = _normalize_host_chain(hostname)
608
+ hop_count: int = len(host_chain)
609
+ login_chain: tuple[str, ...] = _normalize_text_chain(
610
+ value=login,
611
+ hop_count=hop_count,
612
+ default_value=os.environ.get("USER", ""),
613
+ )
614
+ ssh_chain: tuple[str, ...] = _normalize_text_chain(
615
+ value=ssh_client,
616
+ hop_count=hop_count,
617
+ default_value="ssh",
618
+ )
619
+ pem_chain: tuple[Path | None, ...] = _normalize_path_chain(
620
+ value=pem_file,
621
+ hop_count=hop_count,
622
+ )
623
+
624
+ pem_tokens: list[str] = [
625
+ "" if entry is None else str(entry.expanduser().resolve())
626
+ for entry in pem_chain
627
+ ]
628
+ has_pem: bool = any(token for token in pem_tokens)
629
+ return _NormalizedConnection(
630
+ hostname_chain=";".join(host_chain),
631
+ login_chain=";".join(login_chain),
632
+ ssh_client_chain=";".join(ssh_chain),
633
+ pem_chain=";".join(pem_tokens) if has_pem else None,
634
+ )
635
+
636
+
637
+ def _normalize_host_chain(hostname: str | Sequence[str]) -> tuple[str, ...]:
638
+ """Normalize host input into a non-empty hostname tuple.
639
+
640
+ Parameters
641
+ ----------
642
+ hostname : str | Sequence[str]
643
+ One hostname string or an explicit sequence of hostnames.
644
+
645
+ Returns
646
+ -------
647
+ tuple[str, ...]
648
+ Trimmed hostname tuple without empty entries.
649
+
650
+ Notes
651
+ -----
652
+ Internal API: this helper is an implementation detail and may change
653
+ without notice.
654
+ """
655
+
656
+ raw_entries: Sequence[str]
657
+ if isinstance(hostname, str):
658
+ raw_entries = _split_chain_string(hostname)
659
+ else:
660
+ raw_entries = [str(entry) for entry in hostname]
661
+ normalized_entries: list[str] = [
662
+ entry.strip() for entry in raw_entries if entry.strip()
663
+ ]
664
+ if not normalized_entries:
665
+ raise BackendUnavailableError("Resource hostname chain must not be empty.")
666
+ return tuple(normalized_entries)
667
+
668
+
669
+ def _normalize_text_chain(
670
+ *,
671
+ value: str | Sequence[str | None] | None,
672
+ hop_count: int,
673
+ default_value: str,
674
+ ) -> tuple[str, ...]:
675
+ """Normalize chain-like text fields to one value per connection hop.
676
+
677
+ Parameters
678
+ ----------
679
+ value : str | Sequence[str | None] | None
680
+ Raw text chain input for fields like ``login`` or ``ssh_client``.
681
+ hop_count : int
682
+ Expected number of hops in the normalized output.
683
+ default_value : str
684
+ Default value used when explicit input is absent.
685
+
686
+ Returns
687
+ -------
688
+ tuple[str, ...]
689
+ Text tuple aligned with ``hop_count``.
690
+
691
+ Notes
692
+ -----
693
+ Internal API: this helper is an implementation detail and may change
694
+ without notice.
695
+ """
696
+
697
+ if value is None:
698
+ return tuple(default_value for _ in range(hop_count))
699
+
700
+ if isinstance(value, str):
701
+ explicit_entries: tuple[str, ...] = tuple(
702
+ entry.strip() for entry in _split_chain_string(value)
703
+ )
704
+ if len(explicit_entries) == 1:
705
+ return tuple(explicit_entries[0] for _ in range(hop_count))
706
+ if len(explicit_entries) != hop_count:
707
+ raise BackendUnavailableError(
708
+ "Connection chain length mismatch for text field."
709
+ )
710
+ return explicit_entries
711
+
712
+ normalized_entries: list[str] = []
713
+ item: str | None
714
+ for item in value:
715
+ normalized_entries.append(default_value if item is None else str(item).strip())
716
+ if len(normalized_entries) == 1:
717
+ return tuple(normalized_entries[0] for _ in range(hop_count))
718
+ if len(normalized_entries) != hop_count:
719
+ raise BackendUnavailableError("Connection chain length mismatch for sequence.")
720
+ return tuple(normalized_entries)
721
+
722
+
723
+ def _normalize_path_chain(
724
+ *,
725
+ value: Path | str | Sequence[Path | str | None] | None,
726
+ hop_count: int,
727
+ ) -> tuple[Path | None, ...]:
728
+ """Normalize pem-file path input to one optional path per connection hop.
729
+
730
+ Parameters
731
+ ----------
732
+ value : Path | str | Sequence[Path | str | None] | None
733
+ Path input in scalar or chain form.
734
+ hop_count : int
735
+ Expected number of hops in the normalized output.
736
+
737
+ Returns
738
+ -------
739
+ tuple[Path | None, ...]
740
+ Path tuple aligned with ``hop_count``.
741
+
742
+ Notes
743
+ -----
744
+ Internal API: this helper is an implementation detail and may change
745
+ without notice.
746
+ """
747
+
748
+ if value is None:
749
+ return tuple(None for _ in range(hop_count))
750
+ if isinstance(value, Path):
751
+ return tuple(value for _ in range(hop_count))
752
+ if isinstance(value, str):
753
+ entries: tuple[str, ...] = tuple(_split_chain_string(value))
754
+ if len(entries) == 1:
755
+ return tuple(Path(entries[0]) for _ in range(hop_count))
756
+ if len(entries) != hop_count:
757
+ raise BackendUnavailableError(
758
+ "Connection chain length mismatch for pem_file text chain."
759
+ )
760
+ return tuple(Path(entry) for entry in entries)
761
+
762
+ normalized_entries: list[Path | None] = []
763
+ item: Path | str | None
764
+ for item in value:
765
+ if item is None:
766
+ normalized_entries.append(None)
767
+ else:
768
+ normalized_entries.append(Path(item))
769
+ if len(normalized_entries) == 1:
770
+ return tuple(normalized_entries[0] for _ in range(hop_count))
771
+ if len(normalized_entries) != hop_count:
772
+ raise BackendUnavailableError(
773
+ "Connection chain length mismatch for pem_file sequence."
774
+ )
775
+ return tuple(normalized_entries)
776
+
777
+
778
+ def _split_chain_string(value: str) -> list[str]:
779
+ """Split semicolon-separated chain syntax and drop empty segments.
780
+
781
+ Parameters
782
+ ----------
783
+ value : str
784
+ Raw chain string as accepted by daemon resource APIs.
785
+
786
+ Returns
787
+ -------
788
+ list[str]
789
+ Non-empty chain entries in order.
790
+
791
+ Notes
792
+ -----
793
+ Internal API: this helper is an implementation detail and may change
794
+ without notice.
795
+ """
796
+
797
+ entries: list[str] = [entry.strip() for entry in value.split(";")]
798
+ non_empty_entries: list[str] = [entry for entry in entries if entry]
799
+ if non_empty_entries:
800
+ return non_empty_entries
801
+ return [value.strip()]