structured-data-models 0.2.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.
Files changed (152) hide show
  1. sdm/__init__.py +58 -0
  2. sdm/_constants.py +6 -0
  3. sdm/_inference.py +42 -0
  4. sdm/_kernels/__init__.py +10 -0
  5. sdm/_kernels/rmsnorm_cast.py +92 -0
  6. sdm/_kernels/segment_multi_reduce.py +141 -0
  7. sdm/_kernels/triton/__init__.py +7 -0
  8. sdm/_kernels/triton/rmsnorm_cast.py +136 -0
  9. sdm/_kernels/triton/segment_multi_reduce.py +173 -0
  10. sdm/_memory.py +34 -0
  11. sdm/_warnings.py +29 -0
  12. sdm/cache.py +163 -0
  13. sdm/ensemble.py +501 -0
  14. sdm/evaluation/__init__.py +11 -0
  15. sdm/evaluation/classification.py +205 -0
  16. sdm/explain/__init__.py +12 -0
  17. sdm/explain/base.py +123 -0
  18. sdm/explain/gradient.py +112 -0
  19. sdm/models/__init__.py +20 -0
  20. sdm/models/_huggingface.py +58 -0
  21. sdm/models/base.py +966 -0
  22. sdm/models/callback.py +106 -0
  23. sdm/models/ecoc.py +197 -0
  24. sdm/models/kumo/__init__.py +13 -0
  25. sdm/models/kumo/relational/NOTICE +5 -0
  26. sdm/models/kumo/relational/__init__.py +11 -0
  27. sdm/models/kumo/relational/graph.py +101 -0
  28. sdm/models/kumo/relational/invariant_gnn.py +122 -0
  29. sdm/models/kumo/relational/model.py +602 -0
  30. sdm/models/kumo/relational/recipe.py +18 -0
  31. sdm/models/kumo/relational/task.py +113 -0
  32. sdm/models/kumo/tabular/__init__.py +17 -0
  33. sdm/models/kumo/tabular/batching.py +139 -0
  34. sdm/models/kumo/tabular/block.py +100 -0
  35. sdm/models/kumo/tabular/cell_embedding.py +85 -0
  36. sdm/models/kumo/tabular/icl.py +136 -0
  37. sdm/models/kumo/tabular/model.py +299 -0
  38. sdm/models/kumo/tabular/recipe.py +71 -0
  39. sdm/models/kumo/tabular/row_embedding.py +214 -0
  40. sdm/models/tabfm/LICENSE +209 -0
  41. sdm/models/tabfm/__init__.py +11 -0
  42. sdm/models/tabfm/block.py +94 -0
  43. sdm/models/tabfm/cell_embedding.py +219 -0
  44. sdm/models/tabfm/ckpt.py +242 -0
  45. sdm/models/tabfm/icl.py +107 -0
  46. sdm/models/tabfm/model.py +261 -0
  47. sdm/models/tabfm/recipe.py +46 -0
  48. sdm/models/tabfm/row_embedding.py +241 -0
  49. sdm/models/tabiclv2/LICENSE +33 -0
  50. sdm/models/tabiclv2/__init__.py +11 -0
  51. sdm/models/tabiclv2/block.py +81 -0
  52. sdm/models/tabiclv2/ckpt.py +134 -0
  53. sdm/models/tabiclv2/icl.py +420 -0
  54. sdm/models/tabiclv2/model.py +293 -0
  55. sdm/models/tabiclv2/recipe.py +46 -0
  56. sdm/models/tabiclv2/row_embedding.py +254 -0
  57. sdm/nn/__init__.py +28 -0
  58. sdm/nn/_buffer.py +91 -0
  59. sdm/nn/attention.py +825 -0
  60. sdm/nn/glu.py +78 -0
  61. sdm/nn/linear.py +46 -0
  62. sdm/nn/rms_norm.py +59 -0
  63. sdm/nn/rope.py +107 -0
  64. sdm/nn/scaling.py +240 -0
  65. sdm/nn/set_transformer.py +162 -0
  66. sdm/nn/softplus.py +65 -0
  67. sdm/processing/__init__.py +96 -0
  68. sdm/processing/base.py +254 -0
  69. sdm/processing/categorical/__init__.py +16 -0
  70. sdm/processing/categorical/_categorical.py +60 -0
  71. sdm/processing/categorical/align.py +540 -0
  72. sdm/processing/categorical/count.py +121 -0
  73. sdm/processing/categorical/impute.py +107 -0
  74. sdm/processing/categorical/shuffle.py +204 -0
  75. sdm/processing/common/__init__.py +32 -0
  76. sdm/processing/common/callable.py +29 -0
  77. sdm/processing/common/choice.py +185 -0
  78. sdm/processing/common/drop.py +28 -0
  79. sdm/processing/common/ensemble.py +187 -0
  80. sdm/processing/common/identity.py +18 -0
  81. sdm/processing/common/select.py +107 -0
  82. sdm/processing/common/sequential.py +158 -0
  83. sdm/processing/common/shuffle.py +195 -0
  84. sdm/processing/common/stype.py +199 -0
  85. sdm/processing/common/table.py +120 -0
  86. sdm/processing/common/task.py +135 -0
  87. sdm/processing/common/to_numerical.py +60 -0
  88. sdm/processing/datetime/__init__.py +8 -0
  89. sdm/processing/datetime/calendar.py +196 -0
  90. sdm/processing/ensemble.py +203 -0
  91. sdm/processing/execution.py +418 -0
  92. sdm/processing/numerical/__init__.py +38 -0
  93. sdm/processing/numerical/_stats.py +29 -0
  94. sdm/processing/numerical/cast.py +33 -0
  95. sdm/processing/numerical/clip.py +48 -0
  96. sdm/processing/numerical/clip_soft.py +54 -0
  97. sdm/processing/numerical/constant.py +235 -0
  98. sdm/processing/numerical/flip_sign.py +78 -0
  99. sdm/processing/numerical/impute.py +52 -0
  100. sdm/processing/numerical/pca.py +62 -0
  101. sdm/processing/numerical/power.py +325 -0
  102. sdm/processing/numerical/quantile.py +306 -0
  103. sdm/processing/numerical/quantile_clip.py +63 -0
  104. sdm/processing/numerical/random_projection.py +86 -0
  105. sdm/processing/numerical/rank_gaussian.py +168 -0
  106. sdm/processing/numerical/robust_scale.py +88 -0
  107. sdm/processing/numerical/sigma_clip.py +123 -0
  108. sdm/processing/numerical/standardize.py +71 -0
  109. sdm/processing/output/__init__.py +14 -0
  110. sdm/processing/output/reduce.py +86 -0
  111. sdm/processing/output/softmax.py +48 -0
  112. sdm/processing/output/sort.py +16 -0
  113. sdm/processing/recipe.py +154 -0
  114. sdm/processing/text/__init__.py +12 -0
  115. sdm/processing/text/sentence_transformer.py +451 -0
  116. sdm/processing/text/tfidf.py +478 -0
  117. sdm/relational/__init__.py +16 -0
  118. sdm/relational/backend/__init__.py +12 -0
  119. sdm/relational/backend/_cugraph.py +546 -0
  120. sdm/relational/backend/_pyg_lib.py +175 -0
  121. sdm/relational/data.py +393 -0
  122. sdm/relational/join.py +173 -0
  123. sdm/relational/sampler.py +259 -0
  124. sdm/relational/task.py +465 -0
  125. sdm/stype.py +396 -0
  126. sdm/task.py +53 -0
  127. sdm/tensor/__init__.py +20 -0
  128. sdm/tensor/categorical.py +953 -0
  129. sdm/tensor/columnar.py +1127 -0
  130. sdm/tensor/io/__init__.py +22 -0
  131. sdm/tensor/io/arrow.py +120 -0
  132. sdm/tensor/io/cudf.py +47 -0
  133. sdm/tensor/mixin.py +124 -0
  134. sdm/tensor/nullable.py +963 -0
  135. sdm/tensor/string.py +526 -0
  136. sdm/tensor/table.py +2035 -0
  137. sdm/tensor/var_len.py +1486 -0
  138. sdm/testing/__init__.py +14 -0
  139. sdm/testing/decorators.py +61 -0
  140. sdm/testing/memory.py +92 -0
  141. structured_data_models-0.2.0.dist-info/METADATA +142 -0
  142. structured_data_models-0.2.0.dist-info/RECORD +152 -0
  143. structured_data_models-0.2.0.dist-info/WHEEL +5 -0
  144. structured_data_models-0.2.0.dist-info/licenses/LICENSE +204 -0
  145. structured_data_models-0.2.0.dist-info/licenses/THIRD_PARTY_LICENSES.md +40 -0
  146. structured_data_models-0.2.0.dist-info/licenses/sdm/models/kumo/relational/NOTICE +5 -0
  147. structured_data_models-0.2.0.dist-info/licenses/sdm/models/tabfm/LICENSE +209 -0
  148. structured_data_models-0.2.0.dist-info/licenses/sdm/models/tabiclv2/LICENSE +33 -0
  149. structured_data_models-0.2.0.dist-info/licenses/third_party/contributor-covenant/LICENSE +20 -0
  150. structured_data_models-0.2.0.dist-info/licenses/third_party/pytorch/LICENSE +84 -0
  151. structured_data_models-0.2.0.dist-info/licenses/third_party/tabpfn-extensions/LICENSE +202 -0
  152. structured_data_models-0.2.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,953 @@
1
+ # SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ from __future__ import annotations
5
+
6
+ import functools
7
+ from collections.abc import Callable, Sequence
8
+ from itertools import accumulate, chain
9
+ from typing import TYPE_CHECKING, Any, ClassVar, Self, SupportsIndex, cast
10
+
11
+ import pyarrow as pa
12
+ import torch
13
+ from torch import Tensor
14
+ from torch.utils import _pytree as pytree
15
+ from typing_extensions import override
16
+
17
+ from sdm.tensor import StringTensor, VarLenTensor
18
+ from sdm.tensor.io import (
19
+ arrow_as_tensor,
20
+ combine_arrow_chunks,
21
+ to_arrow,
22
+ to_cudf,
23
+ )
24
+
25
+ if TYPE_CHECKING:
26
+ import cudf
27
+
28
+ aten = torch.ops.aten
29
+
30
+
31
+ def preserve_view_inference_mode(fn: Callable) -> Callable:
32
+ r"""Preserve input inference state for tensor view operations."""
33
+
34
+ @functools.wraps(fn)
35
+ def wrapper(*args: Any, **kwargs: Any) -> Any:
36
+ with torch.inference_mode(args[0].is_inference()):
37
+ return fn(*args, **kwargs)
38
+
39
+ return wrapper
40
+
41
+
42
+ class CategoricalTensor(Tensor):
43
+ r"""A :class:`torch.Tensor` for categorical columns.
44
+
45
+ A :class:`CategoricalTensor` stores categorical indices in ``code`` and one
46
+ category vector per column in ``categories``.
47
+ Code values are direct indices into the corresponding category vector.
48
+ Negative indices represent missing values.
49
+
50
+ .. testcode::
51
+
52
+ import torch
53
+ from sdm import CategoricalTensor, StringTensor
54
+
55
+ tensor = CategoricalTensor(
56
+ code=torch.randint(0, 2, size=(10, 2)),
57
+ categories=(
58
+ StringTensor.from_list(["USA", "GERMANY"]),
59
+ StringTensor.from_list(["enterprise", "startup"]),
60
+ ),
61
+ )
62
+
63
+ Args:
64
+ code: The categorical indices of shape ``[..., C]``.
65
+ categories: A tuple of ``C`` category vectors.
66
+ """
67
+
68
+ ALLOWED_DTYPES = (torch.int32, torch.int64)
69
+ HANDLED_FUNCTIONS: ClassVar[
70
+ dict[Callable[..., Any], Callable[..., Any]]
71
+ ] = {}
72
+
73
+ _code: Tensor
74
+ _categories: tuple[Tensor, ...]
75
+
76
+ # Constructors ############################################################
77
+
78
+ def __init__(
79
+ self,
80
+ code: Tensor,
81
+ categories: Sequence[Tensor],
82
+ ) -> None:
83
+ pass
84
+
85
+ def __new__(
86
+ cls,
87
+ code: Tensor,
88
+ categories: Sequence[Tensor],
89
+ ) -> Self:
90
+ r"""Create a tensor wrapper."""
91
+ if code.dtype not in cls.ALLOWED_DTYPES:
92
+ raise ValueError(
93
+ f"Expected 'code' in {cls.__name__!r} to have dtype "
94
+ f"in '{cls.ALLOWED_DTYPES}' (got '{code.dtype}')"
95
+ )
96
+ if code.dim() == 0:
97
+ raise ValueError(
98
+ f"Expected {cls.__name__!r} to have at least one dimension"
99
+ )
100
+ if code.size(-1) != len(categories):
101
+ raise ValueError(
102
+ f"Expected the last dimension in {cls.__name__!r} to match "
103
+ f"the number of category vectors (got {code.size(-1)} and "
104
+ f"{len(categories)})"
105
+ )
106
+ for i, category in enumerate(categories):
107
+ if category.dim() != 1:
108
+ raise ValueError(
109
+ f"Expected category {i} in {cls.__name__!r} to be "
110
+ f"one-dimensional (got {category.dim()}D)"
111
+ )
112
+ if isinstance(category, VarLenTensor) and category.is_nullable:
113
+ raise ValueError(
114
+ f"Expected category {i} in {cls.__name__!r} to not "
115
+ "contain null values"
116
+ )
117
+
118
+ out = Tensor._make_wrapper_subclass(
119
+ cls,
120
+ size=code.size(),
121
+ strides=code.stride(),
122
+ storage_offset=code.storage_offset(),
123
+ dtype=code.dtype,
124
+ device=code.device,
125
+ requires_grad=False,
126
+ )
127
+
128
+ out._code = code
129
+ out._categories = tuple(categories)
130
+
131
+ return out
132
+
133
+ @classmethod
134
+ def from_arrow(
135
+ cls,
136
+ array: pa.Array | pa.ChunkedArray,
137
+ *,
138
+ dtype: torch.dtype | None = None,
139
+ device: torch.device | str | None = None,
140
+ ) -> Self:
141
+ r"""Create tensor from a :class:`pyarrow.Array`.
142
+
143
+ .. testcode::
144
+
145
+ import pyarrow as pa
146
+ from sdm import CategoricalTensor
147
+
148
+ array = pa.array(["foo", None, "bar"])
149
+ tensor = CategoricalTensor.from_arrow(array)
150
+
151
+ assert tensor.code.tolist() == [[0], [-1], [1]]
152
+ assert tensor.categories[0].tolist() == ["foo", "bar"]
153
+
154
+ Args:
155
+ array: The :class:`pyarrow.Array` or
156
+ :class:`pyarrow.ChunkedArray`.
157
+ dtype: The dtype.
158
+ device: The device.
159
+ """
160
+ device = torch.device("cpu" if device is None else device)
161
+
162
+ if isinstance(array, pa.ChunkedArray):
163
+ array = combine_arrow_chunks(array)
164
+
165
+ encoded = array.dictionary_encode()
166
+ code = arrow_as_tensor(
167
+ encoded.indices.fill_null(-1),
168
+ dtype=dtype,
169
+ device=device,
170
+ ).unsqueeze(-1)
171
+ if dtype is None and code.dtype not in cls.ALLOWED_DTYPES:
172
+ code = code.to(torch.int32)
173
+
174
+ dictionary = encoded.dictionary
175
+ is_string = pa.types.is_string(dictionary.type)
176
+ is_large_string = pa.types.is_large_string(dictionary.type)
177
+ if is_string or is_large_string:
178
+ category = StringTensor.from_arrow(dictionary, device=device)
179
+ elif pa.types.is_null(dictionary.type):
180
+ category = torch.empty(0, dtype=torch.int64, device=device)
181
+ else: # Use regular torch.Tensor for Tensor-compatible dictionaries:
182
+ category = arrow_as_tensor(dictionary, device=device)
183
+
184
+ return cls(code=code, categories=(category,))
185
+
186
+ def to_arrow(self, names: Sequence[str] | None = None) -> pa.Table:
187
+ r"""Convert this tensor to a two-dimensional :class:`pyarrow.Table`.
188
+
189
+ Args:
190
+ names: Column names.
191
+ """
192
+ if names is None:
193
+ names = tuple(str(i) for i in range(self.size(-1)))
194
+ elif len(names) != self.size(-1):
195
+ raise ValueError(
196
+ f"Expected 'columns' to contain {self.size(-1)} entries "
197
+ f"(got {len(names)})"
198
+ )
199
+
200
+ arrays = []
201
+ for code, category, mask in zip(
202
+ self.code.movedim(-1, 0).contiguous().cpu().unbind(0),
203
+ self.categories,
204
+ self.isfinite().movedim(-1, 0).contiguous().cpu().unbind(0),
205
+ ):
206
+ arrays.append(
207
+ pa.DictionaryArray.from_arrays(
208
+ indices=to_arrow(code, mask),
209
+ dictionary=category.to_arrow()
210
+ if isinstance(category, StringTensor)
211
+ else to_arrow(category),
212
+ )
213
+ )
214
+
215
+ return pa.Table.from_arrays(arrays, names=names)
216
+
217
+ @classmethod
218
+ def from_cudf(
219
+ cls,
220
+ ser: cudf.Series,
221
+ *,
222
+ dtype: torch.dtype = torch.int32,
223
+ device: torch.device | str | None = None,
224
+ ) -> Self:
225
+ r"""Create tensor from a categorical :class:`cudf.Series`.
226
+
227
+ Args:
228
+ ser: The categorical :class:`cudf.Series`.
229
+ dtype: The dtype.
230
+ device: The device.
231
+ """
232
+ import cudf
233
+ from cudf.api.types import is_string_dtype
234
+
235
+ if isinstance(ser.dtype, cudf.CategoricalDtype):
236
+ code_dtype = "int64" if dtype == torch.int64 else "int32"
237
+ codes = ser.cat.codes.astype(code_dtype, copy=False).to_cupy(
238
+ na_value=-1
239
+ )
240
+ categories = ser.cat.categories
241
+ else:
242
+ codes, categories = ser.factorize(
243
+ sort=False,
244
+ use_na_sentinel=True,
245
+ )
246
+ code = torch.from_dlpack(codes).unsqueeze(-1).to(device, dtype)
247
+
248
+ if len(categories) == 0:
249
+ category = torch.empty(0, dtype=torch.int64, device=code.device)
250
+ elif is_string_dtype(categories.dtype):
251
+ category = StringTensor.from_cudf(categories, device=device)
252
+ else:
253
+ category = torch.from_dlpack(categories.to_cupy()).to(device)
254
+
255
+ return cls(code=code, categories=(category,))
256
+
257
+ def to_cudf(self, names: Sequence[str] | None = None) -> cudf.DataFrame:
258
+ r"""Convert this tensor to a two-dimensional :class:`cudf.DataFrame`.
259
+
260
+ Args:
261
+ names: Column names.
262
+ """
263
+ import cudf
264
+
265
+ if names is None:
266
+ names = tuple(str(i) for i in range(self.size(-1)))
267
+ elif len(names) != self.size(-1):
268
+ raise ValueError(
269
+ f"Expected 'columns' to contain {self.size(-1)} entries "
270
+ f"(got {len(names)})"
271
+ )
272
+
273
+ columns = {}
274
+ for name, code, category, mask in zip(
275
+ names,
276
+ self.code.movedim(-1, 0).contiguous().unbind(0),
277
+ self.categories,
278
+ self.isfinite().movedim(-1, 0).contiguous().unbind(0),
279
+ ):
280
+ columns[name] = cudf.CategoricalIndex.from_codes(
281
+ codes=to_cudf(code, mask)._column,
282
+ categories=category.to_cudf()
283
+ if isinstance(category, StringTensor)
284
+ else to_cudf(category),
285
+ ordered=False,
286
+ )
287
+
288
+ return cudf.DataFrame(columns)
289
+
290
+ @classmethod
291
+ def from_tensor(cls, tensor: Tensor) -> Self:
292
+ r"""Create tensor from a numerical :class:`torch.Tensor`.
293
+
294
+ Args:
295
+ tensor: The numerical tensor.
296
+ """
297
+ if tensor.size(-1) == 0:
298
+ return cls(
299
+ code=tensor.to(torch.int64),
300
+ categories=(),
301
+ )
302
+
303
+ categories, values = zip(
304
+ *[
305
+ column.unique(return_inverse=True)
306
+ for column in tensor.unbind(dim=-1)
307
+ ]
308
+ )
309
+ return cls(
310
+ code=torch.stack(values, dim=-1),
311
+ categories=categories,
312
+ )
313
+
314
+ # Properties ##############################################################
315
+
316
+ @property
317
+ def code(self) -> Tensor:
318
+ r"""Return the categorical code tensor."""
319
+ return self._code
320
+
321
+ @property
322
+ def categories(self) -> tuple[Tensor, ...]:
323
+ r"""Return category vector for each categorical column."""
324
+ return self._categories
325
+
326
+ # Decorators ##############################################################
327
+
328
+ @classmethod
329
+ def implements(
330
+ cls,
331
+ torch_function: Callable[..., Any],
332
+ ) -> Callable[..., Any]:
333
+ r"""Register a ``__torch_dispatch__`` implementation.
334
+
335
+ See PyTorch's
336
+ :ref:`calling convention <torch-dispatch-calling-convention>`.
337
+ """
338
+ if "HANDLED_FUNCTIONS" not in cls.__dict__:
339
+ cls.HANDLED_FUNCTIONS = cls.HANDLED_FUNCTIONS.copy()
340
+
341
+ def decorator(my_function: Callable[..., Any]) -> Callable[..., Any]:
342
+ cls.HANDLED_FUNCTIONS[torch_function] = my_function
343
+ return my_function
344
+
345
+ return decorator
346
+
347
+ # PyTorch/Python builtins #################################################
348
+
349
+ def __reduce_ex__(self, proto: SupportsIndex) -> Any:
350
+ args = (self._code, self._categories)
351
+ return (self.__class__, args)
352
+
353
+ @classmethod
354
+ def __torch_function__(
355
+ cls,
356
+ func: Callable[..., Any],
357
+ types: tuple[type[Any], ...],
358
+ args: tuple[Any, ...] = (),
359
+ kwargs: dict[str, Any] | None = None,
360
+ ) -> Any:
361
+ if func is torch.isfinite or func is Tensor.isfinite:
362
+ assert isinstance(args[0], CategoricalTensor)
363
+ return _isfinite(args[0])
364
+
365
+ with torch._C.DisableTorchFunction():
366
+ return func(*args, **(kwargs or {}))
367
+
368
+ @classmethod
369
+ def __torch_dispatch__( # type: ignore
370
+ cls,
371
+ func: Callable[..., Any],
372
+ types: tuple[type[Any], ...],
373
+ args: tuple[Any, ...] = (),
374
+ kwargs: dict[str, Any] | None = None,
375
+ ) -> Any:
376
+ if (handler := cls.HANDLED_FUNCTIONS.get(func)) is not None:
377
+ return handler(*args, **(kwargs or {}))
378
+
379
+ # Operate on vanilla tensors for all non-handled functions:
380
+ args = pytree.tree_map_only(CategoricalTensor, lambda x: x._code, args)
381
+ kwargs = pytree.tree_map_only(
382
+ CategoricalTensor, lambda x: x._code, kwargs
383
+ )
384
+ return func(*args, **(kwargs or {}))
385
+
386
+ @override
387
+ def is_shared(self) -> bool:
388
+ return self._code.is_shared()
389
+
390
+ @override
391
+ def share_memory_(self) -> Self:
392
+ self._code.share_memory_()
393
+ return self
394
+
395
+ @override
396
+ def tolist(self) -> Any:
397
+ def apply_na_mask(values: Any, na_mask: Any) -> Any:
398
+ if isinstance(na_mask, bool):
399
+ return None if na_mask else values
400
+
401
+ return [
402
+ apply_na_mask(value, isna)
403
+ for value, isna in zip(values, na_mask)
404
+ ]
405
+
406
+ def decode_column(tensor: CategoricalTensor) -> Sequence[Any]:
407
+ out = tensor.categories[0][tensor.code.clamp(min=0).squeeze(-1)]
408
+ return apply_na_mask(
409
+ out.tolist(),
410
+ tensor.isnan().squeeze(-1).tolist(),
411
+ )
412
+
413
+ def columns_to_rows(
414
+ columns: Sequence[Any],
415
+ size: tuple[int, ...],
416
+ ) -> Any:
417
+ if len(size) == 0:
418
+ return list(columns)
419
+
420
+ return [
421
+ columns_to_rows(
422
+ columns=[column[i] for column in columns],
423
+ size=size[1:],
424
+ )
425
+ for i in range(size[0])
426
+ ]
427
+
428
+ columns = [
429
+ decode_column(cast(CategoricalTensor, column))
430
+ for column in self.split(1, dim=-1)
431
+ ]
432
+ return columns_to_rows(columns, tuple(self.size()[:-1]))
433
+
434
+
435
+ @CategoricalTensor.implements(aten.isnan.default)
436
+ def _isnan(inp: CategoricalTensor) -> Tensor:
437
+ return inp._code < 0
438
+
439
+
440
+ @CategoricalTensor.implements(aten.isfinite.default)
441
+ def _isfinite(inp: CategoricalTensor) -> Tensor:
442
+ return inp._code >= 0
443
+
444
+
445
+ @CategoricalTensor.implements(aten.alias.default)
446
+ @preserve_view_inference_mode
447
+ def _alias(inp: CategoricalTensor) -> CategoricalTensor:
448
+ return inp.__class__(aten.alias.default(inp._code), inp._categories)
449
+
450
+
451
+ @CategoricalTensor.implements(aten.record_stream.default)
452
+ def _record_stream(inp: CategoricalTensor, stream: torch.Stream) -> None:
453
+ inp._code.record_stream(stream)
454
+ for category in inp._categories:
455
+ category.record_stream(stream)
456
+
457
+
458
+ @CategoricalTensor.implements(aten.to.dtype_layout)
459
+ def _to_dtype_layout(
460
+ inp: CategoricalTensor,
461
+ *,
462
+ dtype: torch.dtype | None = None,
463
+ layout: torch.layout | None = None,
464
+ device: torch.device | str | None = None,
465
+ pin_memory: bool | None = None, # Ignored by PyTorch.
466
+ non_blocking: bool = False,
467
+ copy: bool = False,
468
+ memory_format: torch.memory_format | None = None,
469
+ ) -> Tensor:
470
+
471
+ if (
472
+ not copy
473
+ and (dtype is None or dtype == inp.dtype)
474
+ and (device is None or torch.device(device) == inp.device)
475
+ and (layout is None or layout == inp.layout)
476
+ and (
477
+ memory_format is None
478
+ or memory_format == torch.preserve_format
479
+ or (
480
+ memory_format == torch.contiguous_format
481
+ and inp.is_contiguous()
482
+ )
483
+ )
484
+ ):
485
+ return inp
486
+
487
+ code = aten.to.dtype_layout(
488
+ inp._code,
489
+ dtype=dtype,
490
+ layout=layout,
491
+ device=device,
492
+ pin_memory=pin_memory,
493
+ non_blocking=non_blocking,
494
+ copy=copy,
495
+ memory_format=memory_format,
496
+ )
497
+ if code.dtype not in inp.ALLOWED_DTYPES or code.layout != torch.strided:
498
+ return code
499
+
500
+ categories = tuple(
501
+ aten.to.dtype_layout(
502
+ category,
503
+ dtype=None,
504
+ layout=None,
505
+ device=device,
506
+ pin_memory=pin_memory,
507
+ non_blocking=non_blocking,
508
+ copy=copy,
509
+ memory_format=None,
510
+ )
511
+ for category in inp._categories
512
+ )
513
+ return inp.__class__(code, categories)
514
+
515
+
516
+ @CategoricalTensor.implements(aten.to.dtype)
517
+ def _to_dtype(
518
+ inp: CategoricalTensor,
519
+ dtype: torch.dtype,
520
+ non_blocking: bool = False,
521
+ copy: bool = False,
522
+ memory_format: torch.memory_format | None = None,
523
+ ) -> Tensor:
524
+ return _to_dtype_layout(
525
+ inp,
526
+ dtype=dtype,
527
+ non_blocking=non_blocking,
528
+ copy=copy,
529
+ memory_format=memory_format,
530
+ )
531
+
532
+
533
+ @CategoricalTensor.implements(aten.to.device)
534
+ def _to_device(
535
+ inp: CategoricalTensor,
536
+ device: torch.device | str,
537
+ dtype: torch.dtype,
538
+ non_blocking: bool = False,
539
+ copy: bool = False,
540
+ memory_format: torch.memory_format | None = None,
541
+ ) -> Tensor:
542
+ return _to_dtype_layout(
543
+ inp,
544
+ dtype=dtype,
545
+ device=device,
546
+ non_blocking=non_blocking,
547
+ copy=copy,
548
+ memory_format=memory_format,
549
+ )
550
+
551
+
552
+ @CategoricalTensor.implements(aten.to.other)
553
+ def _to_other(
554
+ inp: CategoricalTensor,
555
+ other: Tensor,
556
+ non_blocking: bool = False,
557
+ copy: bool = False,
558
+ memory_format: torch.memory_format | None = None,
559
+ ) -> Tensor:
560
+ return _to_dtype_layout(
561
+ inp,
562
+ dtype=other.dtype,
563
+ layout=other.layout,
564
+ device=other.device,
565
+ non_blocking=non_blocking,
566
+ copy=copy,
567
+ memory_format=memory_format,
568
+ )
569
+
570
+
571
+ @CategoricalTensor.implements(aten._to_copy.default)
572
+ def _to_copy(
573
+ inp: CategoricalTensor,
574
+ *,
575
+ dtype: torch.dtype | None = None,
576
+ layout: torch.layout | None = None,
577
+ device: torch.device | str | None = None,
578
+ pin_memory: bool = False, # Ignored by PyTorch.
579
+ non_blocking: bool = False,
580
+ memory_format: torch.memory_format | None = None,
581
+ ) -> Tensor:
582
+ return _to_dtype_layout(
583
+ inp,
584
+ dtype=dtype,
585
+ layout=layout,
586
+ device=device,
587
+ pin_memory=pin_memory,
588
+ non_blocking=non_blocking,
589
+ copy=True,
590
+ memory_format=memory_format,
591
+ )
592
+
593
+
594
+ @CategoricalTensor.implements(aten.clone.default)
595
+ def _clone(
596
+ inp: CategoricalTensor,
597
+ *,
598
+ memory_format: torch.memory_format | None = None,
599
+ ) -> CategoricalTensor:
600
+ return _to_dtype_layout(inp, copy=True, memory_format=memory_format)
601
+
602
+
603
+ @CategoricalTensor.implements(aten.contiguous.default)
604
+ def _contiguous(
605
+ inp: CategoricalTensor,
606
+ *,
607
+ memory_format: torch.memory_format = torch.contiguous_format,
608
+ ) -> CategoricalTensor:
609
+ code = inp._code.contiguous(memory_format=memory_format)
610
+ return inp.__class__(code, inp._categories)
611
+
612
+
613
+ @CategoricalTensor.implements(aten.is_pinned.default)
614
+ def _is_pinned(inp: CategoricalTensor) -> bool:
615
+ return inp._code.is_pinned() and all(
616
+ category.is_pinned() for category in inp._categories
617
+ )
618
+
619
+
620
+ @CategoricalTensor.implements(aten._pin_memory.default)
621
+ def _pin_memory(inp: CategoricalTensor) -> CategoricalTensor:
622
+ categories = tuple(category.pin_memory() for category in inp._categories)
623
+ return inp.__class__(inp._code.pin_memory(), categories)
624
+
625
+
626
+ @CategoricalTensor.implements(aten.pin_memory.default)
627
+ def _pin_memory_composite(
628
+ inp: CategoricalTensor,
629
+ device: torch.device | None = None,
630
+ ) -> CategoricalTensor:
631
+ if _is_pinned(inp):
632
+ return inp
633
+ return _pin_memory(inp)
634
+
635
+
636
+ @CategoricalTensor.implements(aten.equal.default)
637
+ def _equal(inp: CategoricalTensor, other: Tensor) -> bool:
638
+ if inp.__class__ is not other.__class__:
639
+ return False
640
+ if inp.size() != other.size():
641
+ return False
642
+
643
+ if not inp._code.equal(other._code):
644
+ return False
645
+
646
+ for category1, category2 in zip(inp._categories, other._categories):
647
+ if not category1.equal(category2):
648
+ return False
649
+
650
+ return True
651
+
652
+
653
+ @CategoricalTensor.implements(aten.allclose.default)
654
+ def _allclose(
655
+ inp: CategoricalTensor,
656
+ other: Tensor,
657
+ rtol: float = 1e-05,
658
+ atol: float = 1e-08,
659
+ equal_nan: bool = False,
660
+ ) -> bool:
661
+ return _equal(inp, other)
662
+
663
+
664
+ @CategoricalTensor.implements(aten.view.default)
665
+ @preserve_view_inference_mode
666
+ def _view(inp: CategoricalTensor, size: Sequence[int]) -> Tensor:
667
+ return _maybe_wrap(inp, inp._code.view(size))
668
+
669
+
670
+ @CategoricalTensor.implements(aten._unsafe_view.default)
671
+ @preserve_view_inference_mode
672
+ def _unsafe_view(inp: CategoricalTensor, size: Sequence[int]) -> Tensor:
673
+ return _maybe_wrap(inp, aten._unsafe_view(inp._code, size))
674
+
675
+
676
+ @CategoricalTensor.implements(aten.reshape.default)
677
+ def _reshape(inp: CategoricalTensor, size: Sequence[int]) -> Tensor:
678
+ return aten.reshape.default.decompose(inp, size)
679
+
680
+
681
+ @CategoricalTensor.implements(aten.flatten.using_ints)
682
+ def _flatten(
683
+ inp: CategoricalTensor,
684
+ start_dim: int = 0,
685
+ end_dim: int = -1,
686
+ ) -> Tensor:
687
+ return aten.flatten.using_ints.decompose(inp, start_dim, end_dim)
688
+
689
+
690
+ @CategoricalTensor.implements(aten.squeeze.default)
691
+ @preserve_view_inference_mode
692
+ def _squeeze(inp: CategoricalTensor) -> Tensor:
693
+ return _maybe_wrap(inp, inp._code.squeeze())
694
+
695
+
696
+ @CategoricalTensor.implements(aten.squeeze.dim)
697
+ @preserve_view_inference_mode
698
+ def _squeeze_dim(inp: CategoricalTensor, dim: int) -> Tensor:
699
+ return _maybe_wrap(inp, inp._code.squeeze(dim))
700
+
701
+
702
+ @CategoricalTensor.implements(aten.squeeze.dims)
703
+ @preserve_view_inference_mode
704
+ def _squeeze_dims(inp: CategoricalTensor, dim: Sequence[int]) -> Tensor:
705
+ return _maybe_wrap(inp, inp._code.squeeze(tuple(dim)))
706
+
707
+
708
+ @CategoricalTensor.implements(aten.unsqueeze.default)
709
+ @preserve_view_inference_mode
710
+ def _unsqueeze(inp: CategoricalTensor, dim: int) -> Tensor:
711
+ return _maybe_wrap(inp, inp._code.unsqueeze(dim))
712
+
713
+
714
+ @CategoricalTensor.implements(aten.expand.default)
715
+ @preserve_view_inference_mode
716
+ def _expand(
717
+ inp: CategoricalTensor,
718
+ size: Sequence[int],
719
+ *,
720
+ implicit: bool = False,
721
+ ) -> Tensor:
722
+ code = aten.expand.default(inp._code, size, implicit=implicit)
723
+ return _maybe_wrap(inp, code)
724
+
725
+
726
+ @CategoricalTensor.implements(aten.transpose.int)
727
+ @preserve_view_inference_mode
728
+ def _transpose(inp: CategoricalTensor, dim0: int, dim1: int) -> Tensor:
729
+ code = inp._code.transpose(dim0, dim1)
730
+ dim0 %= inp.dim()
731
+ dim1 %= inp.dim()
732
+ if dim0 != dim1 and inp.dim() - 1 in (dim0, dim1):
733
+ return code
734
+ return inp.__class__(code, inp.categories)
735
+
736
+
737
+ @CategoricalTensor.implements(aten.permute.default)
738
+ @preserve_view_inference_mode
739
+ def _permute(inp: CategoricalTensor, dims: Sequence[int]) -> Tensor:
740
+ code = inp._code.permute(tuple(dims))
741
+ dims = tuple(dim % inp.dim() for dim in dims)
742
+ if dims[-1] != inp.dim() - 1:
743
+ return code
744
+ return inp.__class__(code, inp.categories)
745
+
746
+
747
+ @CategoricalTensor.implements(aten.movedim.int)
748
+ def _movedim_int(
749
+ inp: CategoricalTensor,
750
+ source: int,
751
+ destination: int,
752
+ ) -> Tensor:
753
+ return aten.movedim.int.decompose(inp, source, destination)
754
+
755
+
756
+ @CategoricalTensor.implements(aten.movedim.intlist)
757
+ def _movedim_intlist(
758
+ inp: CategoricalTensor,
759
+ source: Sequence[int],
760
+ destination: Sequence[int],
761
+ ) -> Tensor:
762
+ return aten.movedim.intlist.decompose(inp, source, destination)
763
+
764
+
765
+ @CategoricalTensor.implements(aten.select.int)
766
+ @preserve_view_inference_mode
767
+ def _select(inp: CategoricalTensor, dim: int, index: int) -> Tensor:
768
+ code = inp._code.select(dim, index)
769
+ dim %= inp.dim()
770
+ if dim == inp.dim() - 1:
771
+ return code
772
+ return inp.__class__(code, inp.categories)
773
+
774
+
775
+ @CategoricalTensor.implements(aten.slice.Tensor)
776
+ @preserve_view_inference_mode
777
+ def _slice(
778
+ inp: CategoricalTensor,
779
+ dim: int = 0,
780
+ start: int | None = None,
781
+ end: int | None = None,
782
+ step: int = 1,
783
+ ) -> CategoricalTensor:
784
+ code = aten.slice.Tensor(inp._code, dim, start, end, step)
785
+ dim %= inp.dim()
786
+ if dim != inp.dim() - 1:
787
+ return inp.__class__(code, inp.categories)
788
+ return inp.__class__(code, inp.categories[slice(start, end, step)])
789
+
790
+
791
+ @CategoricalTensor.implements(aten.narrow.default)
792
+ @preserve_view_inference_mode
793
+ def _narrow(
794
+ inp: CategoricalTensor,
795
+ dim: int,
796
+ start: int,
797
+ length: int,
798
+ ) -> CategoricalTensor:
799
+ code = inp._code.narrow(dim, start, length)
800
+ dim %= inp.dim()
801
+ if dim != inp.dim() - 1:
802
+ return inp.__class__(code, inp.categories)
803
+ if start < 0:
804
+ start += inp.size(dim)
805
+ return inp.__class__(code, inp.categories[start : start + length])
806
+
807
+
808
+ @CategoricalTensor.implements(aten.unbind.int)
809
+ @preserve_view_inference_mode
810
+ def _unbind(inp: CategoricalTensor, dim: int = 0) -> tuple[Tensor, ...]:
811
+ code_list = inp._code.unbind(dim)
812
+ dim %= inp.dim()
813
+ if dim == inp.dim() - 1:
814
+ return code_list
815
+ return tuple(inp.__class__(code, inp.categories) for code in code_list)
816
+
817
+
818
+ @CategoricalTensor.implements(aten.split.Tensor)
819
+ @preserve_view_inference_mode
820
+ def _split(
821
+ inp: CategoricalTensor,
822
+ split_size: int,
823
+ dim: int = 0,
824
+ ) -> tuple[CategoricalTensor, ...]:
825
+ code_list = inp._code.split(split_size, dim)
826
+ dim %= inp.dim()
827
+ if dim != inp.dim() - 1:
828
+ return tuple(inp.__class__(code, inp.categories) for code in code_list)
829
+ return tuple(
830
+ inp.__class__(code, inp.categories[i : i + split_size])
831
+ for code, i in zip(code_list, range(0, inp.size(dim), split_size))
832
+ )
833
+
834
+
835
+ @CategoricalTensor.implements(aten.split.sizes)
836
+ @CategoricalTensor.implements(aten.split.default)
837
+ @CategoricalTensor.implements(aten.split_with_sizes.default)
838
+ @preserve_view_inference_mode
839
+ def _split_with_sizes(
840
+ inp: CategoricalTensor,
841
+ split_sizes: Sequence[int],
842
+ dim: int = 0,
843
+ ) -> tuple[CategoricalTensor, ...]:
844
+ code_list = inp._code.split(tuple(split_sizes), dim)
845
+ dim %= inp.dim()
846
+ if dim != inp.dim() - 1:
847
+ return tuple(inp.__class__(code, inp.categories) for code in code_list)
848
+
849
+ offset = (0, *accumulate(split_sizes))
850
+ return tuple(
851
+ inp.__class__(code, inp.categories[start:end])
852
+ for code, start, end in zip(code_list, offset[:-1], offset[1:])
853
+ )
854
+
855
+
856
+ @CategoricalTensor.implements(aten.index_select.default)
857
+ def _index_select(
858
+ inp: CategoricalTensor,
859
+ dim: int,
860
+ index: Tensor,
861
+ ) -> CategoricalTensor:
862
+ code = inp._code.index_select(dim, index)
863
+ dim %= inp.dim()
864
+ if dim != inp.dim() - 1:
865
+ return inp.__class__(code, inp.categories)
866
+ categories = tuple(inp.categories[i] for i in index.tolist())
867
+ return inp.__class__(code, categories)
868
+
869
+
870
+ @CategoricalTensor.implements(aten.index.Tensor)
871
+ def _index(
872
+ inp: CategoricalTensor,
873
+ indices: Sequence[Tensor | None],
874
+ ) -> Tensor:
875
+ code = aten.index.Tensor(inp._code, indices)
876
+
877
+ current_dim = 0
878
+ has_other_index = False
879
+ category_index: Tensor | None = None
880
+ for index in indices:
881
+ if index is None:
882
+ current_dim += 1
883
+ continue
884
+
885
+ # Check whether we index the category dimension:
886
+ num_indexed_dims = index.dim() if index.dtype == torch.bool else 1
887
+ if current_dim <= inp.dim() - 1 < current_dim + num_indexed_dims:
888
+ if num_indexed_dims != 1:
889
+ return code
890
+ category_index = index
891
+ else:
892
+ has_other_index = True
893
+ current_dim += num_indexed_dims
894
+
895
+ if category_index is None:
896
+ return _maybe_wrap(inp, code)
897
+
898
+ if has_other_index or category_index.dim() != 1:
899
+ return code
900
+
901
+ if category_index.dtype == torch.bool:
902
+ category_index = category_index.nonzero().view(-1)
903
+
904
+ categories = tuple(inp.categories[i] for i in category_index.tolist())
905
+ return inp.__class__(code, categories)
906
+
907
+
908
+ @CategoricalTensor.implements(aten.cat.default)
909
+ def _cat(tensors: Sequence[Tensor], dim: int = 0) -> Tensor:
910
+ code = torch.cat([_as_tensor(tensor) for tensor in tensors], dim=dim)
911
+ if not all(isinstance(tensor, CategoricalTensor) for tensor in tensors):
912
+ return code
913
+
914
+ tensors = cast(Sequence[CategoricalTensor], tensors)
915
+ dim %= tensors[0].dim()
916
+ if dim != tensors[0].dim() - 1:
917
+ # NOTE We trust the user to ensure category compatibility.
918
+ return tensors[0].__class__(code, tensors[0].categories)
919
+
920
+ categories = tuple(
921
+ chain.from_iterable(tensor.categories for tensor in tensors)
922
+ )
923
+ return tensors[0].__class__(code, categories)
924
+
925
+
926
+ @CategoricalTensor.implements(aten.stack.default)
927
+ def _stack(tensors: Sequence[Tensor], dim: int = 0) -> Tensor:
928
+ code = torch.stack([_as_tensor(tensor) for tensor in tensors], dim=dim)
929
+ if not all(isinstance(tensor, CategoricalTensor) for tensor in tensors):
930
+ return code
931
+
932
+ tensors = cast(Sequence[CategoricalTensor], tensors)
933
+ dim %= tensors[0].dim() + 1
934
+ if dim >= tensors[0].dim():
935
+ return code
936
+
937
+ # NOTE We trust the user to ensure category compatibility.
938
+ return tensors[0].__class__(code, tensors[0].categories)
939
+
940
+
941
+ # Helpers #####################################################################
942
+
943
+
944
+ def _maybe_wrap(inp: CategoricalTensor, code: Tensor) -> Tensor:
945
+ if code.dim() > 0 and code.size(-1) == inp.size(-1):
946
+ return inp.__class__(code, inp.categories)
947
+ return code
948
+
949
+
950
+ def _as_tensor(inp: Tensor) -> Tensor:
951
+ if isinstance(inp, CategoricalTensor):
952
+ return inp._code
953
+ return inp