jcmsuite-xarray 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,62 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """`xarray` conversion for collections of table payloads."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from collections.abc import Mapping, Sequence
9
+ from pathlib import Path
10
+ from typing import TYPE_CHECKING, cast
11
+
12
+ from jcmsuite.results.artifacts import PostprocessRecord
13
+ from jcmsuite.results.internal.export.xarray.types import XarrayDataset, XarrayDataTree
14
+
15
+ from . import runtime
16
+
17
+ if TYPE_CHECKING:
18
+ from jcmsuite.loaders.table import SingleTableData
19
+
20
+
21
+ def table_collection_to_xarray(
22
+ tables: Sequence["SingleTableData"],
23
+ names: tuple[str, ...],
24
+ *,
25
+ source_file: Path | None,
26
+ ) -> XarrayDataTree:
27
+ """Export ordered table members using supplied core-selected names."""
28
+
29
+ xarray_module = runtime._load_xarray_module()
30
+ datatree_module = runtime._load_datatree_module()
31
+ children: dict[str, XarrayDataTree] = {}
32
+ for name, payload in zip(names, tables, strict=True):
33
+ title_value: object = payload.get("title")
34
+ title: str | None = title_value if isinstance(title_value, str) else None
35
+ child_tree: XarrayDataTree = PostprocessRecord(
36
+ source_file=Path() if source_file is None else source_file,
37
+ _raw=payload,
38
+ title=title,
39
+ ).to_xarray()
40
+ child_dataset: XarrayDataset | None = getattr(
41
+ child_tree, "ds", getattr(child_tree, "dataset", None)
42
+ )
43
+ child_children: Mapping[str, XarrayDataTree] | None = cast(
44
+ "Mapping[str, XarrayDataTree] | None",
45
+ getattr(child_tree, "children", None),
46
+ )
47
+ children[name] = runtime._create_data_tree(
48
+ datatree_module=datatree_module,
49
+ dataset=child_dataset,
50
+ children=child_children,
51
+ name=name,
52
+ )
53
+
54
+ attrs: dict[str, object] = {"table_count": len(tables), "tables": names}
55
+ if source_file is not None:
56
+ attrs["source_file"] = str(source_file)
57
+ root_dataset = xarray_module.Dataset(data_vars={}, attrs=attrs)
58
+ return runtime._create_data_tree(
59
+ datatree_module=datatree_module,
60
+ dataset=root_dataset,
61
+ children=children or None,
62
+ )
@@ -0,0 +1,305 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Tabular payload helpers for internal `xarray` exports."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import logging
9
+ from collections.abc import Mapping, Sequence
10
+ from dataclasses import dataclass
11
+ from typing import Protocol
12
+
13
+ import numpy as np
14
+
15
+ from jcmsuite.exceptions import InvalidConfigurationError
16
+ from jcmsuite.results.internal.export.pandas.payload import payload_to_tabular_rows
17
+ from jcmsuite.results.internal.export.xarray.types import XarrayDataset
18
+
19
+ from .runtime import _XarrayModule
20
+ from .shared import (
21
+ _ensure_generated_value_dim_coords,
22
+ _normalize_scalar_coord_value,
23
+ _ordered_union,
24
+ _tabular_column_dtype_for_padding,
25
+ )
26
+
27
+
28
+ class _BatchIndexedKeys(Protocol):
29
+ """Structural batch metadata required by tabular stacking."""
30
+
31
+ @property
32
+ def index(self) -> int: ...
33
+
34
+ @property
35
+ def keys(self) -> Mapping[str, object]: ...
36
+
37
+
38
+ logger = logging.getLogger(f"{__package__}.export")
39
+
40
+
41
+ @dataclass(slots=True, frozen=True)
42
+ class _TabularXarrayTable:
43
+ """Normalized tabular payload ready for xarray export."""
44
+
45
+ row_count: int
46
+ column_names: tuple[str, ...]
47
+ column_arrays: dict[str, np.ndarray]
48
+ column_dims: dict[str, tuple[str, ...]]
49
+ attrs: dict[str, object]
50
+
51
+
52
+ def tabular_payload_to_xarray_table(
53
+ payload: object,
54
+ *,
55
+ payload_name: str,
56
+ ) -> _TabularXarrayTable:
57
+ """Normalize one tabular payload into stacked column arrays."""
58
+
59
+ rows: list[dict[str, object]] | None = payload_to_tabular_rows(payload)
60
+ if rows is None:
61
+ raise InvalidConfigurationError(
62
+ f"{payload_name} is not tabular and cannot be exported via to_xarray()."
63
+ )
64
+
65
+ row_count: int = len(rows)
66
+ ordered_column_names: tuple[object, ...] = _ordered_union(
67
+ [tuple(row.keys()) for row in rows]
68
+ )
69
+ column_names: tuple[str, ...] = tuple(
70
+ str(column_name) for column_name in ordered_column_names
71
+ )
72
+ column_arrays: dict[str, np.ndarray] = {}
73
+ column_dims: dict[str, tuple[str, ...]] = {}
74
+ column_name: str
75
+ for column_name in column_names:
76
+ values: list[object] = [row[column_name] for row in rows]
77
+ column_array: np.ndarray
78
+ column_dims_tuple: tuple[str, ...]
79
+ column_array, column_dims_tuple = _stack_tabular_column_values(
80
+ column_name,
81
+ values,
82
+ )
83
+ column_arrays[column_name] = column_array
84
+ column_dims[column_name] = column_dims_tuple
85
+
86
+ attrs: dict[str, object] = {}
87
+ if isinstance(payload, Mapping):
88
+ title_value: object | None = payload.get("title")
89
+ header_value: object | None = payload.get("header")
90
+ if title_value is not None:
91
+ attrs["title"] = title_value
92
+ if header_value is not None:
93
+ attrs["header"] = header_value
94
+
95
+ return _TabularXarrayTable(
96
+ row_count=row_count,
97
+ column_names=column_names,
98
+ column_arrays=column_arrays,
99
+ column_dims=column_dims,
100
+ attrs=attrs,
101
+ )
102
+
103
+
104
+ def tabular_table_to_xarray_dataset(
105
+ table: _TabularXarrayTable,
106
+ *,
107
+ xarray_module: _XarrayModule,
108
+ ) -> XarrayDataset:
109
+ """Convert one normalized tabular payload into an `xarray.Dataset`."""
110
+
111
+ data_vars: dict[str, object] = {}
112
+ column_name: str
113
+ for column_name in table.column_names:
114
+ data_vars[column_name] = (
115
+ table.column_dims[column_name],
116
+ table.column_arrays[column_name],
117
+ )
118
+
119
+ is_valid: np.ndarray = np.ones((table.row_count,), dtype=bool)
120
+ is_padded: np.ndarray = np.zeros((table.row_count,), dtype=bool)
121
+ data_vars["is_valid"] = (("row_index",), is_valid)
122
+ data_vars["is_padded"] = (("row_index",), is_padded)
123
+
124
+ coords: dict[str, object] = {"row_index": list(range(table.row_count))}
125
+ return xarray_module.Dataset(
126
+ data_vars=data_vars,
127
+ coords=coords,
128
+ attrs=dict(table.attrs),
129
+ )
130
+
131
+
132
+ def _stack_batch_tabular_tables(
133
+ entries: Sequence[_BatchIndexedKeys],
134
+ tables: Sequence[_TabularXarrayTable | None],
135
+ *,
136
+ xarray_module: _XarrayModule,
137
+ batch_axis_name: str = "index",
138
+ valid_entries: Sequence[bool] | None = None,
139
+ ) -> XarrayDataset:
140
+ """Stack normalized tabular payloads onto a leading batch axis."""
141
+
142
+ available_tables: list[_TabularXarrayTable] = [
143
+ table for table in tables if table is not None
144
+ ]
145
+ if not available_tables:
146
+ raise InvalidConfigurationError(
147
+ "No batch tabular payloads are available for to_xarray()."
148
+ )
149
+ first_table: _TabularXarrayTable = available_tables[0]
150
+ max_rows: int = max(table.row_count for table in available_tables)
151
+ requires_padding: bool = len(available_tables) != len(entries) or any(
152
+ table.row_count != max_rows for table in available_tables
153
+ )
154
+ if requires_padding:
155
+ logger.debug(
156
+ "Padding batch eigenvalues to row count %d from row counts %s.",
157
+ max_rows,
158
+ [None if table is None else table.row_count for table in tables],
159
+ )
160
+
161
+ for table in available_tables[1:]:
162
+ if table.column_names != first_table.column_names:
163
+ raise InvalidConfigurationError(
164
+ "Selected batch eigenvalue stream mixes different tabular columns and cannot be stacked via to_xarray()."
165
+ )
166
+ column_name: str
167
+ for column_name in first_table.column_names:
168
+ if table.column_dims[column_name] != first_table.column_dims[column_name]:
169
+ raise InvalidConfigurationError(
170
+ "Selected batch eigenvalue stream mixes incompatible column shapes and cannot be stacked via to_xarray()."
171
+ )
172
+
173
+ coords: dict[str, object] = {
174
+ batch_axis_name: [entry.index for entry in entries],
175
+ "row_index": list(range(max_rows)),
176
+ }
177
+ common_key_names: set[str] = set(entries[0].keys)
178
+ entry: _BatchIndexedKeys
179
+ for entry in entries[1:]:
180
+ common_key_names &= set(entry.keys)
181
+ key_name: str
182
+ for key_name in sorted(common_key_names):
183
+ normalized_values: list[object] = []
184
+ supported: bool = True
185
+ entry_value: object
186
+ for entry in entries:
187
+ entry_value = entry.keys[key_name]
188
+ normalized_value: object | None = _normalize_scalar_coord_value(entry_value)
189
+ if normalized_value is None:
190
+ supported = False
191
+ break
192
+ normalized_values.append(normalized_value)
193
+ if supported:
194
+ coords[key_name] = (batch_axis_name, np.asarray(normalized_values))
195
+
196
+ data_vars: dict[str, object] = {}
197
+ column_name = ""
198
+ for column_name in first_table.column_names:
199
+ first_array: np.ndarray = first_table.column_arrays[column_name]
200
+ arrays: list[np.ndarray] = [
201
+ (
202
+ np.empty(
203
+ (0,) + first_array.shape[1:],
204
+ dtype=first_array.dtype,
205
+ )
206
+ if table is None
207
+ else table.column_arrays[column_name]
208
+ )
209
+ for table in tables
210
+ ]
211
+ stacked_array: np.ndarray = _stack_batch_tabular_column(
212
+ arrays,
213
+ target_rows=max_rows,
214
+ )
215
+ base_dims: tuple[str, ...] = first_table.column_dims[column_name]
216
+ _ensure_generated_value_dim_coords(
217
+ coords,
218
+ value_dims=(batch_axis_name,) + base_dims,
219
+ value_array=stacked_array,
220
+ )
221
+ data_vars[column_name] = ((batch_axis_name,) + base_dims, stacked_array)
222
+
223
+ is_valid: np.ndarray = np.zeros((len(entries), max_rows), dtype=bool)
224
+ is_padded: np.ndarray = np.ones((len(entries), max_rows), dtype=bool)
225
+ entry_position: int
226
+ batch_table: _TabularXarrayTable | None
227
+ for entry_position, batch_table in enumerate(tables):
228
+ if batch_table is not None and (
229
+ valid_entries is None or valid_entries[entry_position]
230
+ ):
231
+ is_valid[entry_position, : batch_table.row_count] = True
232
+ is_padded[entry_position, : batch_table.row_count] = False
233
+ data_vars["is_valid"] = ((batch_axis_name, "row_index"), is_valid)
234
+ data_vars["is_padded"] = ((batch_axis_name, "row_index"), is_padded)
235
+
236
+ attrs: dict[str, object] = {}
237
+ if "title" in first_table.attrs:
238
+ attrs["title"] = first_table.attrs["title"]
239
+ if "header" in first_table.attrs:
240
+ attrs["header"] = first_table.attrs["header"]
241
+
242
+ return xarray_module.Dataset(
243
+ data_vars=data_vars,
244
+ coords=coords,
245
+ attrs=attrs,
246
+ )
247
+
248
+
249
+ def _stack_tabular_column_values(
250
+ column_name: str,
251
+ values: Sequence[object],
252
+ ) -> tuple[np.ndarray, tuple[str, ...]]:
253
+ """Stack one tabular column into a dense array plus dimension labels."""
254
+
255
+ value_arrays: list[np.ndarray] = [np.asarray(value) for value in values]
256
+ first_shape: tuple[int, ...] = value_arrays[0].shape if value_arrays else ()
257
+ value_array: np.ndarray
258
+ for value_array in value_arrays[1:]:
259
+ if value_array.shape != first_shape:
260
+ raise InvalidConfigurationError(
261
+ f"Tabular column {column_name!r} has inconsistent row value shapes and cannot be exported via to_xarray()."
262
+ )
263
+
264
+ if not value_arrays:
265
+ return np.asarray([], dtype=float), ("row_index",)
266
+
267
+ if first_shape == ():
268
+ return np.asarray(values), ("row_index",)
269
+
270
+ stacked: np.ndarray = np.stack(value_arrays, axis=0)
271
+ trailing_dims: tuple[str, ...] = tuple(
272
+ f"{column_name}_dim_{dimension_index}"
273
+ for dimension_index in range(len(first_shape))
274
+ )
275
+ return stacked, ("row_index",) + trailing_dims
276
+
277
+
278
+ def _stack_batch_tabular_column(
279
+ arrays: Sequence[np.ndarray],
280
+ *,
281
+ target_rows: int,
282
+ ) -> np.ndarray:
283
+ """Stack one tabular column across batch entries with row padding."""
284
+
285
+ requires_padding: bool = any(int(array.shape[0]) != target_rows for array in arrays)
286
+ dtype: np.dtype[np.generic] = _tabular_column_dtype_for_padding(
287
+ arrays,
288
+ requires_padding=requires_padding,
289
+ )
290
+ first_array: np.ndarray = arrays[0]
291
+ trailing_shape: tuple[int, ...] = tuple(int(axis) for axis in first_array.shape[1:])
292
+ fill_value: object = np.nan if dtype != np.dtype(object) else None
293
+ output_shape: tuple[int, ...] = (len(arrays), target_rows) + trailing_shape
294
+ stacked: np.ndarray = np.full(output_shape, fill_value, dtype=dtype)
295
+
296
+ array_position: int
297
+ array_value: np.ndarray
298
+ for array_position, array_value in enumerate(arrays):
299
+ row_count: int = int(array_value.shape[0])
300
+ cast_array: np.ndarray = array_value.astype(dtype, copy=False)
301
+ if trailing_shape:
302
+ stacked[array_position, :row_count, ...] = cast_array
303
+ else:
304
+ stacked[array_position, :row_count] = cast_array
305
+ return stacked
@@ -0,0 +1,18 @@
1
+ Metadata-Version: 2.4
2
+ Name: jcmsuite-xarray
3
+ Version: 1.0.0
4
+ Summary: Optional xarray exports for the matching JCMsuite Python interface.
5
+ License-Expression: MIT
6
+ Requires-Python: >=3.13
7
+ Classifier: Programming Language :: Python :: 3
8
+ Classifier: Programming Language :: Python :: 3.13
9
+ Classifier: Programming Language :: Python :: 3.14
10
+ Classifier: Programming Language :: Python :: 3.15
11
+ Requires-Dist: jcmsuite (==1.0.0)
12
+ Requires-Dist: xarray (>=2024.10.0,<2027.0)
13
+ Description-Content-Type: text/markdown
14
+
15
+ # JCMsuite xarray exports
16
+
17
+ Install the matching companion with `jcmsuite[xarray]` to use DataTree exports.
18
+
@@ -0,0 +1,13 @@
1
+ jcmsuite_xarray/__init__.py,sha256=JwdribfTC8B-gsoltx5VbQUHadLGM1VxeJad5aD0Y_M,109
2
+ jcmsuite_xarray/export.py,sha256=rv_vBwBxMUX9udbhUIevSPUvT7EAgdvBVWKL7GTVEKI,28832
3
+ jcmsuite_xarray/fields.py,sha256=Nl_xc9zhQqwuAH-SAgQigFrZZjnfXwLAZIK792C0-aU,8500
4
+ jcmsuite_xarray/grouped.py,sha256=Txiq4tujNGRwB3KMhhcPEjOyrxLpsBFj7HV2GoQWORQ,23523
5
+ jcmsuite_xarray/headers.py,sha256=78R5JpQ083M9-yHSSsrUkdM4ryyGEVDsDwKfLerSjwk,10898
6
+ jcmsuite_xarray/runtime.py,sha256=lJRDd2Wcc7THaQENjrqkj7Sm_5FTOOQL4xC02_tH6s4,3037
7
+ jcmsuite_xarray/shared.py,sha256=-oroGRxne2CPUKSpvYEmgaiqFrpJCEZws5NOP6o0tHw,8120
8
+ jcmsuite_xarray/single.py,sha256=oHdjFIj29dHbhKrYjlUHmGW5r0m9W6cXNaU8Er5W5bo,2416
9
+ jcmsuite_xarray/tables.py,sha256=9vZawM_Nd1xuiFVbg3UQscZGCpVU3b7s-UyH83nh5TY,2190
10
+ jcmsuite_xarray/tabular.py,sha256=3-uPQNR5SvFD7l0uYImzCov3_2xtala_SxkrKFAidg8,10818
11
+ jcmsuite_xarray-1.0.0.dist-info/METADATA,sha256=Ld4cj9Mlozyqf21UA1FZD7WuguXzCKN2pNrzRrbVD08,612
12
+ jcmsuite_xarray-1.0.0.dist-info/WHEEL,sha256=L-WvLdSBvJWHXv5zrQxDvNRnIgoBzLUpcbuiw19KCuQ,88
13
+ jcmsuite_xarray-1.0.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: poetry-core 2.5.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any