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,290 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Header-specific helpers for internal `xarray` exports."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from collections.abc import Mapping, Sequence
9
+ from typing import cast
10
+
11
+ import numpy as np
12
+
13
+ from .....exceptions import InvalidConfigurationError
14
+ from ..pandas.payload import is_numeric_key_mapping
15
+ from .runtime import _XarrayModule
16
+ from .shared import _field_key_sort_key, _tabular_column_dtype_for_padding
17
+ from .types import XarrayDataset
18
+
19
+
20
+ def _header_payload_to_dataset(
21
+ payload: Mapping[object, object],
22
+ *,
23
+ xarray_module: _XarrayModule,
24
+ ) -> XarrayDataset:
25
+ """Convert one header mapping into a root dataset."""
26
+
27
+ flattened_fields: dict[str, object] = {}
28
+ _flatten_header_fields(
29
+ payload,
30
+ flattened_fields=flattened_fields,
31
+ field_prefix="",
32
+ )
33
+ data_vars: dict[str, object] = {}
34
+ coords: dict[str, object] = {}
35
+ attrs: dict[str, object] = {}
36
+ field_name: str
37
+ field_value: object
38
+ for field_name, field_value in flattened_fields.items():
39
+ if isinstance(field_value, str):
40
+ attrs[field_name] = field_value
41
+ continue
42
+ _append_header_data_variable(
43
+ data_vars=data_vars,
44
+ coords=coords,
45
+ field_name=field_name,
46
+ field_value=field_value,
47
+ )
48
+ return xarray_module.Dataset(
49
+ data_vars=data_vars,
50
+ coords=coords or None,
51
+ attrs=attrs or None,
52
+ )
53
+
54
+
55
+ def _flatten_header_fields(
56
+ payload: Mapping[object, object],
57
+ *,
58
+ flattened_fields: dict[str, object],
59
+ field_prefix: str,
60
+ ) -> None:
61
+ """Flatten non-numeric nested header mappings into dotted field names."""
62
+
63
+ field_key: object
64
+ field_value: object
65
+ for field_key, field_value in payload.items():
66
+ field_name: str = (
67
+ f"{field_prefix}.{field_key}" if field_prefix else str(field_key)
68
+ )
69
+ if isinstance(field_value, Mapping) and not is_numeric_key_mapping(field_value):
70
+ _flatten_header_fields(
71
+ field_value,
72
+ flattened_fields=flattened_fields,
73
+ field_prefix=field_name,
74
+ )
75
+ continue
76
+ flattened_fields[field_name] = field_value
77
+
78
+
79
+ def _append_header_data_variable(
80
+ *,
81
+ data_vars: dict[str, object],
82
+ coords: dict[str, object],
83
+ field_name: str,
84
+ field_value: object,
85
+ ) -> None:
86
+ """Append one single-header header data variable."""
87
+
88
+ if isinstance(field_value, Mapping):
89
+ if not is_numeric_key_mapping(field_value):
90
+ raise InvalidConfigurationError(
91
+ f"Header field {field_name!r} is not supported by to_xarray()."
92
+ )
93
+ field_keys: list[object] = sorted(field_value, key=_field_key_sort_key)
94
+ arrays: list[np.ndarray] = [
95
+ _header_value_to_ndarray(field_value[field_key]) for field_key in field_keys
96
+ ]
97
+ first_shape: tuple[int, ...] = tuple(int(axis) for axis in arrays[0].shape)
98
+ array_value: np.ndarray
99
+ for array_value in arrays[1:]:
100
+ if tuple(int(axis) for axis in array_value.shape) != first_shape:
101
+ raise InvalidConfigurationError(
102
+ f"Header field {field_name!r} has inconsistent grouped value shapes for to_xarray()."
103
+ )
104
+ stacked_array: np.ndarray = np.stack(arrays, axis=0)
105
+ field_index_dim: str = f"{field_name}_field_index"
106
+ coords[field_index_dim] = list(field_keys)
107
+ dims: tuple[str, ...] = (field_index_dim,) + _header_value_dims(
108
+ field_name=field_name,
109
+ value_shape=first_shape,
110
+ )
111
+ data_vars[field_name] = (dims, stacked_array)
112
+ return
113
+
114
+ value_array: np.ndarray = _header_value_to_ndarray(field_value)
115
+ dims = _header_value_dims(
116
+ field_name=field_name,
117
+ value_shape=tuple(int(axis) for axis in value_array.shape),
118
+ )
119
+ if value_array.ndim == 0:
120
+ data_vars[field_name] = ((), value_array[()])
121
+ return
122
+ data_vars[field_name] = (dims, value_array)
123
+
124
+
125
+ def _append_stacked_header_data_variable(
126
+ *,
127
+ data_vars: dict[str, object],
128
+ coords: dict[str, object],
129
+ field_name: str,
130
+ values: Sequence[object | None],
131
+ ) -> None:
132
+ """Append one batch-stacked header data variable."""
133
+
134
+ present_values: list[object] = [value for value in values if value is not None]
135
+ first_value: object = present_values[0]
136
+ if isinstance(first_value, Mapping):
137
+ if not is_numeric_key_mapping(first_value):
138
+ raise InvalidConfigurationError(
139
+ f"Header field {field_name!r} is not supported by to_xarray()."
140
+ )
141
+ field_keys: list[object] = sorted(first_value, key=_field_key_sort_key)
142
+ present_mapping: object
143
+ for present_mapping in present_values[1:]:
144
+ if not isinstance(present_mapping, Mapping) or not is_numeric_key_mapping(
145
+ present_mapping
146
+ ):
147
+ raise InvalidConfigurationError(
148
+ f"Header field {field_name!r} mixes incompatible grouped/non-grouped shapes for to_xarray()."
149
+ )
150
+ if tuple(sorted(present_mapping, key=_field_key_sort_key)) != tuple(
151
+ field_keys
152
+ ):
153
+ raise InvalidConfigurationError(
154
+ f"Header field {field_name!r} mixes incompatible grouped field-index keys for to_xarray()."
155
+ )
156
+ arrays: list[np.ndarray] = [
157
+ _header_value_to_ndarray(
158
+ cast(Mapping[object, object], first_value)[field_key]
159
+ )
160
+ for field_key in field_keys
161
+ ]
162
+ first_shape: tuple[int, ...] = tuple(int(axis) for axis in arrays[0].shape)
163
+ field_key: object
164
+ for field_key in field_keys:
165
+ present_mapping_value: object
166
+ for present_mapping_value in present_values:
167
+ candidate_array: np.ndarray = _header_value_to_ndarray(
168
+ cast(Mapping[object, object], present_mapping_value)[field_key]
169
+ )
170
+ if tuple(int(axis) for axis in candidate_array.shape) != first_shape:
171
+ raise InvalidConfigurationError(
172
+ f"Header field {field_name!r} has inconsistent grouped value shapes for to_xarray()."
173
+ )
174
+ requires_padding: bool = any(value is None for value in values)
175
+ value_dtype: np.dtype[np.generic] = _tabular_column_dtype_for_padding(
176
+ arrays,
177
+ requires_padding=requires_padding,
178
+ )
179
+ stacked_shape: tuple[int, ...] = (len(values), len(field_keys)) + first_shape
180
+ grouped_stacked_array: np.ndarray
181
+ if requires_padding:
182
+ grouped_stacked_array = np.full(
183
+ stacked_shape,
184
+ np.nan,
185
+ dtype=value_dtype,
186
+ )
187
+ else:
188
+ grouped_stacked_array = np.empty(stacked_shape, dtype=value_dtype)
189
+ entry_position: int
190
+ for entry_position, grouped_entry_value in enumerate(values):
191
+ if grouped_entry_value is None:
192
+ continue
193
+ field_position: int
194
+ for field_position, field_key in enumerate(field_keys):
195
+ candidate_array = _header_value_to_ndarray(
196
+ cast(Mapping[object, object], grouped_entry_value)[field_key]
197
+ )
198
+ grouped_stacked_array[entry_position, field_position, ...] = (
199
+ candidate_array.astype(value_dtype, copy=False)
200
+ )
201
+ field_index_dim: str = f"{field_name}_field_index"
202
+ coords[field_index_dim] = list(field_keys)
203
+ dims: tuple[str, ...] = ("index", field_index_dim) + _header_value_dims(
204
+ field_name=field_name,
205
+ value_shape=first_shape,
206
+ )
207
+ data_vars[field_name] = (dims, grouped_stacked_array)
208
+ return
209
+
210
+ first_array: np.ndarray = _header_value_to_ndarray(first_value)
211
+ first_shape = tuple(int(axis) for axis in first_array.shape)
212
+ present_value: object
213
+ for present_value in present_values[1:]:
214
+ candidate_shape: tuple[int, ...] = tuple(
215
+ int(axis) for axis in _header_value_to_ndarray(present_value).shape
216
+ )
217
+ if candidate_shape != first_shape:
218
+ raise InvalidConfigurationError(
219
+ f"Header field {field_name!r} has inconsistent value shapes for to_xarray()."
220
+ )
221
+ requires_padding = any(value is None for value in values)
222
+ value_dtype = _tabular_column_dtype_for_padding(
223
+ [first_array],
224
+ requires_padding=requires_padding,
225
+ )
226
+ stacked_shape = (len(values),) + first_shape
227
+ scalar_or_tensor_stacked_array: np.ndarray
228
+ if requires_padding:
229
+ scalar_or_tensor_stacked_array = np.full(
230
+ stacked_shape,
231
+ np.nan,
232
+ dtype=value_dtype,
233
+ )
234
+ else:
235
+ scalar_or_tensor_stacked_array = np.empty(stacked_shape, dtype=value_dtype)
236
+ entry_position = 0
237
+ scalar_entry_value: object | None
238
+ for entry_position, scalar_entry_value in enumerate(values):
239
+ if scalar_entry_value is None:
240
+ continue
241
+ candidate_array = _header_value_to_ndarray(scalar_entry_value)
242
+ if candidate_array.ndim == 0:
243
+ scalar_or_tensor_stacked_array[entry_position] = candidate_array.astype(
244
+ value_dtype,
245
+ copy=False,
246
+ )
247
+ continue
248
+ scalar_or_tensor_stacked_array[entry_position, ...] = candidate_array.astype(
249
+ value_dtype,
250
+ copy=False,
251
+ )
252
+ dims = ("index",) + _header_value_dims(
253
+ field_name=field_name,
254
+ value_shape=first_shape,
255
+ )
256
+ if first_array.ndim == 0:
257
+ data_vars[field_name] = (("index",), scalar_or_tensor_stacked_array)
258
+ return
259
+ data_vars[field_name] = (dims, scalar_or_tensor_stacked_array)
260
+
261
+
262
+ def _header_value_to_ndarray(value: object) -> np.ndarray:
263
+ """Normalize one header value into an ndarray for xarray export."""
264
+
265
+ if isinstance(value, np.ndarray):
266
+ return value
267
+ if isinstance(value, (int, float, complex, bool, np.generic, str)):
268
+ return np.asarray(value)
269
+ raise InvalidConfigurationError(
270
+ f"Header value {value!r} is not supported by to_xarray()."
271
+ )
272
+
273
+
274
+ def _header_value_dims(
275
+ *,
276
+ field_name: str,
277
+ value_shape: tuple[int, ...],
278
+ ) -> tuple[str, ...]:
279
+ """Return dimension names for one header value shape."""
280
+
281
+ value_ndim: int = len(value_shape)
282
+ if value_ndim == 0:
283
+ return ()
284
+ if value_ndim == 1:
285
+ return ("component",)
286
+ if value_ndim == 2:
287
+ return ("row", "col")
288
+ return tuple(
289
+ f"{field_name}_dim_{dimension_index}" for dimension_index in range(value_ndim)
290
+ )
@@ -0,0 +1,99 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Lazy runtime loading helpers for internal `xarray` exports."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from collections.abc import Mapping
9
+ from typing import Protocol, cast
10
+
11
+ from .....exceptions import InvalidConfigurationError
12
+ from .types import XarrayDataset, XarrayDataTree
13
+
14
+
15
+ class _DatasetFactory(Protocol):
16
+ def __call__(
17
+ self,
18
+ data_vars: Mapping[str, object],
19
+ coords: Mapping[str, object] | None = None,
20
+ attrs: Mapping[str, object] | None = None,
21
+ ) -> XarrayDataset: ...
22
+
23
+
24
+ class _XarrayModule(Protocol):
25
+ Dataset: _DatasetFactory
26
+
27
+
28
+ class _DataTreeFactory(Protocol):
29
+ def __call__(self, *args: object, **kwargs: object) -> XarrayDataTree: ...
30
+
31
+
32
+ class _DataTreeModule(Protocol):
33
+ DataTree: _DataTreeFactory
34
+
35
+
36
+ def _load_xarray_module() -> _XarrayModule:
37
+ """Load `xarray` lazily for internal dataset construction."""
38
+
39
+ try:
40
+ import xarray as xarray_module # pyright: ignore[reportMissingImports]
41
+ except ModuleNotFoundError as exc:
42
+ raise InvalidConfigurationError(
43
+ "xarray integration requires `xarray` to be installed."
44
+ ) from exc
45
+ return cast(_XarrayModule, xarray_module)
46
+
47
+
48
+ def _load_datatree_module() -> _DataTreeModule:
49
+ """Load `xarray.DataTree` lazily for public tree exports."""
50
+
51
+ try:
52
+ import xarray as xarray_module # pyright: ignore[reportMissingImports]
53
+ except ModuleNotFoundError as exc:
54
+ raise InvalidConfigurationError(
55
+ "xarray DataTree integration requires `xarray` to be installed."
56
+ ) from exc
57
+ if not hasattr(xarray_module, "DataTree"):
58
+ raise InvalidConfigurationError(
59
+ "xarray DataTree integration requires an xarray version that provides `DataTree`."
60
+ )
61
+ return cast(_DataTreeModule, xarray_module)
62
+
63
+
64
+ def _create_data_tree(
65
+ *,
66
+ datatree_module: _DataTreeModule,
67
+ dataset: XarrayDataset | None,
68
+ children: Mapping[str, XarrayDataTree] | None = None,
69
+ name: str | None = None,
70
+ ) -> XarrayDataTree:
71
+ """Build a `DataTree` across xarray constructor variants.
72
+
73
+ Older environments accept `data=` while newer ones accept `dataset=`.
74
+ Preserve both without forcing callers to branch on the installed xarray API.
75
+ """
76
+
77
+ normalized_children: Mapping[str, XarrayDataTree] | None = children or None
78
+
79
+ try:
80
+ return datatree_module.DataTree(
81
+ data=dataset,
82
+ children=normalized_children,
83
+ name=name,
84
+ )
85
+ except TypeError as exc:
86
+ if "unexpected keyword argument 'data'" not in str(exc):
87
+ raise
88
+
89
+ try:
90
+ return datatree_module.DataTree(
91
+ dataset=dataset,
92
+ children=normalized_children,
93
+ name=name,
94
+ )
95
+ except TypeError as exc:
96
+ if "unexpected keyword argument 'dataset'" not in str(exc):
97
+ raise
98
+
99
+ return datatree_module.DataTree(dataset, normalized_children, name)
@@ -0,0 +1,246 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Shared low-level helpers for internal `xarray` exports."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from collections.abc import Sequence
9
+ from typing import cast
10
+
11
+ import numpy as np
12
+
13
+ from .....exceptions import InvalidConfigurationError
14
+
15
+
16
+ def _ordered_union(sequences: Sequence[tuple[object, ...]]) -> tuple[object, ...]:
17
+ """Return a stable first-seen union of label tuples."""
18
+
19
+ seen: set[object] = set()
20
+ ordered: list[object] = []
21
+ sequence: tuple[object, ...]
22
+ label: object
23
+ for sequence in sequences:
24
+ for label in sequence:
25
+ if label in seen:
26
+ continue
27
+ seen.add(label)
28
+ ordered.append(label)
29
+ return tuple(ordered)
30
+
31
+
32
+ def _normalize_scalar_coord_value(value: object) -> object | None:
33
+ """Return a coordinate-safe scalar value or `None` when unsupported."""
34
+
35
+ if isinstance(value, np.ndarray):
36
+ if value.ndim == 0:
37
+ return cast(object, value[()])
38
+ return None
39
+ if isinstance(value, (str, bytes, bytearray, int, float, complex, bool)):
40
+ return value
41
+ return None
42
+
43
+
44
+ def _normalize_rectangular_coord_array_value(value: object) -> np.ndarray | None:
45
+ """Return a non-scalar ndarray for rectangular coord exports or `None`."""
46
+
47
+ if isinstance(value, (str, bytes, bytearray)):
48
+ return None
49
+ try:
50
+ array_value: np.ndarray = np.asarray(value)
51
+ except ValueError:
52
+ return None
53
+ if array_value.ndim == 0:
54
+ return None
55
+ return array_value
56
+
57
+
58
+ def _build_batch_coord_variable(
59
+ key_name: str,
60
+ values: Sequence[object],
61
+ ) -> tuple[tuple[str, ...], np.ndarray] | None:
62
+ """Build one batch coord variable from scalar or rectangular entry values."""
63
+
64
+ normalized_scalars: list[object] = []
65
+ value: object
66
+ for value in values:
67
+ normalized_scalar: object | None = _normalize_scalar_coord_value(value)
68
+ if normalized_scalar is None:
69
+ break
70
+ normalized_scalars.append(normalized_scalar)
71
+ else:
72
+ return ("index",), np.asarray(normalized_scalars)
73
+
74
+ rectangular_arrays: list[np.ndarray] = []
75
+ reference_shape: tuple[int, ...] | None = None
76
+ for value in values:
77
+ normalized_array: np.ndarray | None = _normalize_rectangular_coord_array_value(
78
+ value
79
+ )
80
+ if normalized_array is None:
81
+ return None
82
+ current_shape: tuple[int, ...] = tuple(
83
+ int(axis) for axis in normalized_array.shape
84
+ )
85
+ if reference_shape is None:
86
+ reference_shape = current_shape
87
+ elif current_shape != reference_shape:
88
+ return None
89
+ rectangular_arrays.append(normalized_array)
90
+ if reference_shape is None:
91
+ return None
92
+ try:
93
+ stacked_array: np.ndarray = np.stack(rectangular_arrays, axis=0)
94
+ except ValueError:
95
+ return None
96
+ coord_dims: tuple[str, ...] = ("index",) + tuple(
97
+ f"{key_name}_dim_{dimension_index}"
98
+ for dimension_index in range(stacked_array.ndim - 1)
99
+ )
100
+ return coord_dims, stacked_array
101
+
102
+
103
+ def _ensure_generated_companion_dim_coords(
104
+ coords: dict[str, object],
105
+ *,
106
+ coord_dims: tuple[str, ...],
107
+ coord_array: np.ndarray,
108
+ ) -> None:
109
+ """Populate coordinate labels for generated trailing companion dimensions."""
110
+
111
+ trailing_dim_name: str
112
+ trailing_dim_size: int
113
+ for trailing_dim_name, trailing_dim_size in zip(
114
+ coord_dims[1:],
115
+ coord_array.shape[1:],
116
+ ):
117
+ coords.setdefault(trailing_dim_name, list(range(int(trailing_dim_size))))
118
+
119
+
120
+ def _ensure_generated_value_dim_coords(
121
+ coords: dict[str, object],
122
+ *,
123
+ value_dims: tuple[str, ...],
124
+ value_array: np.ndarray,
125
+ ) -> None:
126
+ """Populate coordinate labels for generated grouped-value trailing dims."""
127
+
128
+ trailing_dim_name: str
129
+ trailing_dim_size: int
130
+ for trailing_dim_name, trailing_dim_size in zip(
131
+ value_dims[2:],
132
+ value_array.shape[2:],
133
+ ):
134
+ coords.setdefault(trailing_dim_name, list(range(int(trailing_dim_size))))
135
+
136
+
137
+ def _stack_sample_coordinate_arrays(
138
+ arrays: Sequence[np.ndarray],
139
+ *,
140
+ sample_count: int,
141
+ ) -> np.ndarray:
142
+ """Stack sample-aligned coordinate arrays along the batch axis."""
143
+
144
+ requires_padding: bool = any(
145
+ int(array.shape[0]) != sample_count for array in arrays
146
+ )
147
+ trailing_shape: tuple[int, ...] = tuple(int(axis) for axis in arrays[0].shape[1:])
148
+ array_value: np.ndarray
149
+ for array_value in arrays[1:]:
150
+ if tuple(int(axis) for axis in array_value.shape[1:]) != trailing_shape:
151
+ raise InvalidConfigurationError(
152
+ "Sample-aligned companion coordinates must share trailing dimensions for batch to_xarray() export."
153
+ )
154
+ dtype: np.dtype[np.generic] = _coordinate_dtype_for_padding(
155
+ arrays,
156
+ requires_padding=requires_padding,
157
+ )
158
+ stacked: np.ndarray
159
+ if requires_padding:
160
+ fill_value: object = np.nan if dtype != np.dtype(object) else None
161
+ stacked = np.full(
162
+ (len(arrays), sample_count) + trailing_shape,
163
+ fill_value,
164
+ dtype=dtype,
165
+ )
166
+ else:
167
+ stacked = np.empty((len(arrays), sample_count) + trailing_shape, dtype=dtype)
168
+ array_position: int
169
+ for array_position, array_value in enumerate(arrays):
170
+ local_count: int = int(array_value.shape[0])
171
+ stacked[array_position, :local_count, ...] = array_value.astype(
172
+ dtype,
173
+ copy=False,
174
+ )
175
+ return stacked
176
+
177
+
178
+ def _coordinate_dtype_for_padding(
179
+ arrays: Sequence[np.ndarray],
180
+ *,
181
+ requires_padding: bool,
182
+ ) -> np.dtype[np.generic]:
183
+ """Return a coordinate dtype that can represent optional padded values."""
184
+
185
+ candidate_dtype: np.dtype[np.generic] = np.result_type(*arrays)
186
+ if not requires_padding:
187
+ return candidate_dtype
188
+ if np.issubdtype(candidate_dtype, np.complexfloating):
189
+ return cast(np.dtype[np.generic], np.dtype(np.complex128))
190
+ if np.issubdtype(candidate_dtype, np.floating):
191
+ return candidate_dtype
192
+ if np.issubdtype(candidate_dtype, np.integer) or np.issubdtype(
193
+ candidate_dtype,
194
+ np.bool_,
195
+ ):
196
+ return cast(np.dtype[np.generic], np.dtype(np.float64))
197
+ return cast(np.dtype[np.generic], np.dtype(object))
198
+
199
+
200
+ def _field_key_sort_key(field_key: object) -> int | str:
201
+ """Sort field indices deterministically while preserving numeric order."""
202
+
203
+ if isinstance(field_key, int) and not isinstance(field_key, bool):
204
+ return field_key
205
+ if isinstance(field_key, str) and field_key.isdigit():
206
+ return int(field_key)
207
+ return str(field_key)
208
+
209
+
210
+ def _array_dtype_for_padding(
211
+ arrays: Sequence[np.ndarray],
212
+ *,
213
+ requires_padding: bool,
214
+ ) -> np.dtype[np.generic]:
215
+ """Return a dtype that can represent actual values and optional padding."""
216
+
217
+ candidate_dtype: np.dtype[np.generic] = np.result_type(*arrays)
218
+ if not requires_padding:
219
+ return candidate_dtype
220
+ if np.issubdtype(candidate_dtype, np.complexfloating):
221
+ return cast(np.dtype[np.generic], np.dtype(np.complex128))
222
+ if np.issubdtype(candidate_dtype, np.floating):
223
+ return candidate_dtype
224
+ return cast(np.dtype[np.generic], np.dtype(np.float64))
225
+
226
+
227
+ def _tabular_column_dtype_for_padding(
228
+ arrays: Sequence[np.ndarray],
229
+ *,
230
+ requires_padding: bool,
231
+ ) -> np.dtype[np.generic]:
232
+ """Return a dtype that can represent tabular values plus optional padding."""
233
+
234
+ candidate_dtype: np.dtype[np.generic] = np.result_type(*arrays)
235
+ if not requires_padding:
236
+ return candidate_dtype
237
+ if np.issubdtype(candidate_dtype, np.complexfloating):
238
+ return cast(np.dtype[np.generic], np.dtype(np.complex128))
239
+ if np.issubdtype(candidate_dtype, np.floating):
240
+ return candidate_dtype
241
+ if np.issubdtype(candidate_dtype, np.integer) or np.issubdtype(
242
+ candidate_dtype,
243
+ np.bool_,
244
+ ):
245
+ return cast(np.dtype[np.generic], np.dtype(np.float64))
246
+ return cast(np.dtype[np.generic], np.dtype(object))