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
sdm/tensor/nullable.py ADDED
@@ -0,0 +1,963 @@
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
+ import math
8
+ from collections.abc import Callable, Sequence
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 typing_extensions import override
15
+
16
+ from sdm.tensor.io import (
17
+ ARROW_TORCH_DTYPES,
18
+ arrow_as_tensor,
19
+ combine_arrow_chunks,
20
+ to_arrow,
21
+ to_cudf,
22
+ )
23
+
24
+ if TYPE_CHECKING:
25
+ import cudf
26
+
27
+ aten = torch.ops.aten
28
+
29
+
30
+ def preserve_view_inference_mode(fn: Callable) -> Callable:
31
+ r"""Preserve input inference state for tensor view operations."""
32
+
33
+ @functools.wraps(fn)
34
+ def wrapper(*args: Any, **kwargs: Any) -> Any:
35
+ with torch.inference_mode(args[0].is_inference()):
36
+ return fn(*args, **kwargs)
37
+
38
+ return wrapper
39
+
40
+
41
+ class NullableTensor(Tensor):
42
+ r"""A :class:`torch.Tensor` for nullable values.
43
+
44
+ Args:
45
+ data: Tensor containing the values.
46
+ valid: Boolean mask indicating valid, non-null values.
47
+ """
48
+
49
+ ALLOWED_DTYPES: ClassVar[tuple[torch.dtype, ...]] = (
50
+ torch.bool,
51
+ torch.uint8,
52
+ torch.uint16,
53
+ torch.uint32,
54
+ torch.uint64,
55
+ torch.int8,
56
+ torch.int16,
57
+ torch.int32,
58
+ torch.int64,
59
+ )
60
+ HANDLED_FUNCTIONS: ClassVar[
61
+ dict[Callable[..., Any], Callable[..., Any]]
62
+ ] = {}
63
+
64
+ _data: Tensor
65
+ _valid: Tensor
66
+
67
+ # Constructors ############################################################
68
+
69
+ def __init__(self, data: Tensor, valid: Tensor) -> None:
70
+ pass
71
+
72
+ def __new__(cls, data: Tensor, valid: Tensor) -> Self:
73
+ r"""Create a tensor wrapper."""
74
+ if data.dtype not in cls.ALLOWED_DTYPES:
75
+ raise ValueError(
76
+ f"Expected 'data' in {cls.__name__!r} to have integer or "
77
+ f"boolean dtype (got '{data.dtype}')"
78
+ )
79
+ if valid.dtype != torch.bool:
80
+ raise ValueError(
81
+ f"Expected 'valid' in {cls.__name__!r} to have 'torch.bool' "
82
+ f"dtype (got '{valid.dtype}')"
83
+ )
84
+ if valid.size() != data.size():
85
+ raise ValueError(
86
+ f"Expected 'data' and 'valid' in {cls.__name__!r} to have the "
87
+ f"same size (got {tuple(data.size())} and "
88
+ f"{tuple(valid.size())})"
89
+ )
90
+ if valid.device != data.device:
91
+ raise ValueError(
92
+ f"Expected 'data' and 'valid' in {cls.__name__!r} to be on "
93
+ f"the same device (got '{data.device}' and '{valid.device}')"
94
+ )
95
+
96
+ out = Tensor._make_wrapper_subclass(
97
+ cls,
98
+ size=data.size(),
99
+ strides=data.stride(),
100
+ storage_offset=data.storage_offset(),
101
+ dtype=data.dtype,
102
+ device=data.device,
103
+ requires_grad=False,
104
+ )
105
+
106
+ out._data = data
107
+ out._valid = valid
108
+
109
+ return out
110
+
111
+ @classmethod
112
+ def from_tensor(cls, tensor: Tensor) -> Self:
113
+ r"""Wrap a tensor into a nullable tensor.
114
+
115
+ Args:
116
+ tensor: The tensor to wrap.
117
+ """
118
+ return cls(tensor, valid=torch.ones_like(tensor, dtype=torch.bool))
119
+
120
+ @classmethod
121
+ def from_arrow(
122
+ cls,
123
+ array: pa.Array | pa.ChunkedArray,
124
+ *,
125
+ dtype: torch.dtype | None = None,
126
+ size: Sequence[int] | None = None,
127
+ device: torch.device | str | None = None,
128
+ ) -> Self:
129
+ r"""Create tensor from a :class:`pyarrow.Array`.
130
+
131
+ Args:
132
+ array: The :class:`pyarrow.Array` or :class:`pyarrow.ChunkedArray`.
133
+ dtype: The dtype.
134
+ size: The shape of the tensor.
135
+ device: The device.
136
+ """
137
+ if isinstance(array, pa.ChunkedArray):
138
+ array = combine_arrow_chunks(array)
139
+
140
+ if size is None:
141
+ size = (len(array),)
142
+ elif math.prod(size) != len(array):
143
+ raise ValueError(
144
+ f"Expected 'size' in '{cls.__name__}.from_arrow' to contain "
145
+ f"{len(array)} elements (got {math.prod(size)})"
146
+ )
147
+
148
+ arrow_dtype = ARROW_TORCH_DTYPES.get(array.type)
149
+ if arrow_dtype is None:
150
+ raise TypeError(f"Unsupported value type '{array.type}'")
151
+
152
+ buffer = array.buffers()[1]
153
+ storage_offset = array.offset
154
+ if buffer is not None and buffer.size > 0:
155
+ if arrow_dtype == torch.bool:
156
+ data = arrow_as_tensor(
157
+ array.fill_null(False) if array.null_count > 0 else array,
158
+ dtype=arrow_dtype,
159
+ )
160
+ storage_offset = 0
161
+ else:
162
+ data = torch.frombuffer(buffer, dtype=arrow_dtype)
163
+ else:
164
+ data = torch.empty(0, dtype=arrow_dtype, device=device)
165
+ data = torch.as_strided(
166
+ data,
167
+ size=size,
168
+ stride=_contiguous_stride(size),
169
+ storage_offset=storage_offset,
170
+ ).to(device, dtype)
171
+
172
+ if array.null_count > 0:
173
+ valid = arrow_as_tensor(
174
+ array.is_valid(),
175
+ dtype=torch.bool,
176
+ device=device,
177
+ ).view(size)
178
+ else:
179
+ valid = torch.ones_like(data, dtype=torch.bool)
180
+
181
+ return cls(data, valid)
182
+
183
+ def to_arrow(self) -> pa.Array:
184
+ r"""Convert this tensor to a flat :class:`pyarrow.Array`."""
185
+ return to_arrow(self._data, self._valid)
186
+
187
+ @classmethod
188
+ def from_cudf(
189
+ cls,
190
+ ser: cudf.Series | cudf.Index,
191
+ *,
192
+ dtype: torch.dtype | None = None,
193
+ size: Sequence[int] | None = None,
194
+ device: torch.device | str | None = None,
195
+ ) -> Self:
196
+ r"""Create tensor from a :class:`cudf.Series`.
197
+
198
+ Args:
199
+ ser: The :class:`cudf.Series` or :class:`cudf.Index`.
200
+ dtype: The dtype.
201
+ size: The shape of the tensor.
202
+ device: The device.
203
+ """
204
+ import cupy as cp
205
+ import pylibcudf as plc
206
+
207
+ if size is None:
208
+ size = (len(ser),)
209
+ elif math.prod(size) != len(ser):
210
+ raise ValueError(
211
+ f"Expected 'size' in '{cls.__name__}.from_cudf' to contain "
212
+ f"{len(ser)} elements (got {math.prod(size)})"
213
+ )
214
+
215
+ column, _ = ser.to_pylibcudf()
216
+ cp_dtype = {
217
+ plc.TypeId.BOOL8: cp.bool_,
218
+ plc.TypeId.UINT8: cp.uint8,
219
+ plc.TypeId.UINT16: cp.uint16,
220
+ plc.TypeId.UINT32: cp.uint32,
221
+ plc.TypeId.UINT64: cp.uint64,
222
+ plc.TypeId.INT8: cp.int8,
223
+ plc.TypeId.INT16: cp.int16,
224
+ plc.TypeId.INT32: cp.int32,
225
+ plc.TypeId.INT64: cp.int64,
226
+ }[column.type().id()]
227
+ data = torch.from_dlpack(cp.asarray(column.data()).view(cp_dtype))
228
+ start = column.offset()
229
+ data = data[start : start + len(ser)].to(device=device, dtype=dtype)
230
+
231
+ if ser.hasnans:
232
+ valid = torch.from_dlpack(ser.notnull().to_cupy()).to(device)
233
+ else:
234
+ valid = torch.ones_like(data, dtype=torch.bool)
235
+
236
+ return cls(data.view(size), valid.view(size))
237
+
238
+ def to_cudf(self) -> cudf.Series:
239
+ r"""Convert this CUDA tensor to a flat :class:`cudf.Series`."""
240
+ return to_cudf(self._data, self._valid)
241
+
242
+ @classmethod
243
+ def from_list(
244
+ cls,
245
+ values: int | bool | Sequence[Any] | None,
246
+ *,
247
+ dtype: torch.dtype | None = None,
248
+ device: torch.device | str | None = None,
249
+ ) -> Self:
250
+ r"""Create tensor from a rectangular Python list.
251
+
252
+ Args:
253
+ values: The rectangular Python list.
254
+ dtype: The dtype.
255
+ device: The device.
256
+ """
257
+ data: list[Any] = []
258
+ valid: list[bool] = []
259
+
260
+ def is_sequence(value: Any) -> bool:
261
+ return isinstance(value, Sequence) and not isinstance(
262
+ value, str | bytes | bytearray
263
+ )
264
+
265
+ def flatten(value: Any) -> tuple[int, ...]:
266
+ if value is None:
267
+ data.append(False)
268
+ valid.append(False)
269
+ return ()
270
+
271
+ if not is_sequence(value):
272
+ data.append(value)
273
+ valid.append(True)
274
+ return ()
275
+
276
+ if len(value) == 0:
277
+ return (0,)
278
+
279
+ if not is_sequence(value[0]):
280
+ data.extend(False if item is None else item for item in value)
281
+ valid.extend(item is not None for item in value)
282
+ return (len(value),)
283
+
284
+ child_size: tuple[int, ...] | None = None
285
+ for item in value:
286
+ item_size = flatten(item)
287
+ if child_size is None:
288
+ child_size = item_size
289
+ elif item_size != child_size:
290
+ raise ValueError(
291
+ f"{cls.__name__!r} data must be rectangular"
292
+ )
293
+
294
+ assert child_size is not None
295
+ return (len(value), *child_size)
296
+
297
+ size = flatten(values)
298
+ if dtype is None and not any(valid):
299
+ dtype = torch.int64
300
+
301
+ return cls(
302
+ torch.tensor(data, dtype=dtype, device=device).view(size),
303
+ torch.tensor(valid, dtype=torch.bool, device=device).view(size),
304
+ )
305
+
306
+ # Properties ##############################################################
307
+
308
+ @property
309
+ def data(self) -> Tensor:
310
+ r"""Return the physical data.
311
+
312
+ Values at positions where :attr:`valid` is ``False`` are unspecified.
313
+ """
314
+ return self._data
315
+
316
+ @property
317
+ def valid(self) -> Tensor:
318
+ r"""Return the logical validity mask."""
319
+ return self._valid
320
+
321
+ # Decorators ##############################################################
322
+
323
+ @classmethod
324
+ def implements(
325
+ cls,
326
+ torch_function: Callable[..., Any],
327
+ ) -> Callable[..., Any]:
328
+ r"""Register a ``__torch_dispatch__`` implementation.
329
+
330
+ See PyTorch's
331
+ :ref:`calling convention <torch-dispatch-calling-convention>`.
332
+ """
333
+ if "HANDLED_FUNCTIONS" not in cls.__dict__:
334
+ cls.HANDLED_FUNCTIONS = cls.HANDLED_FUNCTIONS.copy()
335
+
336
+ def decorator(my_function: Callable[..., Any]) -> Callable[..., Any]:
337
+ cls.HANDLED_FUNCTIONS[torch_function] = my_function
338
+ return my_function
339
+
340
+ return decorator
341
+
342
+ # PyTorch/Python builtins #################################################
343
+
344
+ def __tensor_flatten__(self) -> tuple[list[str], tuple[Any, ...]]:
345
+ attrs = ["_data", "_valid"]
346
+ ctx = (self.__class__,)
347
+ return attrs, ctx
348
+
349
+ @staticmethod
350
+ def __tensor_unflatten__(
351
+ inner_tensors: dict[str, Any],
352
+ ctx: tuple[Any, ...],
353
+ outer_size: tuple[int, ...],
354
+ outer_stride: tuple[int, ...],
355
+ ) -> NullableTensor:
356
+ (cls,) = ctx
357
+ return cls(inner_tensors["_data"], inner_tensors["_valid"])
358
+
359
+ def __reduce_ex__(self, proto: SupportsIndex) -> Any:
360
+ return (self.__class__, (self._data, self._valid))
361
+
362
+ @classmethod
363
+ def __torch_function__(
364
+ cls,
365
+ func: Callable[..., Any],
366
+ types: tuple[type[Any], ...],
367
+ args: tuple[Any, ...] = (),
368
+ kwargs: dict[str, Any] | None = None,
369
+ ) -> Any:
370
+ if func is torch.isfinite or func is Tensor.isfinite:
371
+ assert isinstance(args[0], NullableTensor)
372
+ return _isfinite(args[0])
373
+
374
+ with torch._C.DisableTorchFunction():
375
+ return func(*args, **(kwargs or {}))
376
+
377
+ @classmethod
378
+ def __torch_dispatch__( # type: ignore
379
+ cls,
380
+ func: Any,
381
+ types: tuple[type[Any], ...],
382
+ args: tuple[Any, ...] = (),
383
+ kwargs: dict[str, Any] | None = None,
384
+ ) -> Any:
385
+ if (handler := cls.HANDLED_FUNCTIONS.get(func)) is not None:
386
+ return handler(*args, **(kwargs or {}))
387
+
388
+ raise NotImplementedError(
389
+ f"'{func}' is not supported for {cls.__name__!r}"
390
+ )
391
+
392
+ @override
393
+ def is_shared(self) -> bool:
394
+ return self._data.is_shared() and self._valid.is_shared()
395
+
396
+ @override
397
+ def share_memory_(self) -> Self:
398
+ self._data.share_memory_()
399
+ self._valid.share_memory_()
400
+ return self
401
+
402
+ @override
403
+ def is_contiguous(
404
+ self,
405
+ memory_format: torch.memory_format = torch.contiguous_format,
406
+ ) -> bool:
407
+ return self._data.is_contiguous(
408
+ memory_format=memory_format
409
+ ) and self._valid.is_contiguous(memory_format=memory_format)
410
+
411
+ @override
412
+ def contiguous(
413
+ self,
414
+ memory_format: torch.memory_format = torch.contiguous_format,
415
+ ) -> Self:
416
+ if self.is_contiguous(memory_format=memory_format):
417
+ return self
418
+ return self.__class__(
419
+ data=self._data.contiguous(memory_format=memory_format),
420
+ valid=self._valid.contiguous(memory_format=memory_format),
421
+ )
422
+
423
+ @override
424
+ def tolist(self) -> Any:
425
+ def apply_valid(data: Any, valid: Any) -> Any:
426
+ if isinstance(valid, bool):
427
+ return data if valid else None
428
+
429
+ return [
430
+ apply_valid(value, is_valid)
431
+ for value, is_valid in zip(data, valid)
432
+ ]
433
+
434
+ return apply_valid(
435
+ data=self._data.cpu().tolist(),
436
+ valid=self._valid.cpu().tolist(),
437
+ )
438
+
439
+ @override
440
+ def item(self) -> int | bool | None: # type: ignore
441
+ if self._data.numel() != 1:
442
+ raise RuntimeError(
443
+ f"{self.__class__.__name__!r} with {self._data.numel()} "
444
+ "elements cannot be converted to a single item"
445
+ )
446
+ return self.view(-1).tolist()[0]
447
+
448
+ def __repr__(self, *, tensor_contents: Any = None) -> str:
449
+ # TODO Support tensor content printing.
450
+ out = f"{self.__class__.__name__}("
451
+ out += f"size={tuple(self.size())}"
452
+ if self.dtype != torch.int64:
453
+ out += f", dtype={self.dtype}"
454
+ out += f", null_count={int((~self.valid).sum())}"
455
+ if not self.is_cpu:
456
+ out += f", device={self.device}"
457
+ out += ")"
458
+ return out
459
+
460
+
461
+ @NullableTensor.implements(aten.alias.default)
462
+ @preserve_view_inference_mode
463
+ def _alias(inp: NullableTensor) -> NullableTensor:
464
+ return inp.__class__(
465
+ data=aten.alias.default(inp._data),
466
+ valid=aten.alias.default(inp._valid),
467
+ )
468
+
469
+
470
+ @NullableTensor.implements(aten.record_stream.default)
471
+ def _record_stream(inp: NullableTensor, stream: torch.Stream) -> None:
472
+ inp._data.record_stream(stream)
473
+ inp._valid.record_stream(stream)
474
+
475
+
476
+ @NullableTensor.implements(aten.to.dtype_layout)
477
+ def _to_dtype_layout(
478
+ inp: NullableTensor,
479
+ *,
480
+ dtype: torch.dtype | None = None,
481
+ layout: torch.layout | None = None,
482
+ device: torch.device | str | None = None,
483
+ pin_memory: bool | None = None, # Ignored by PyTorch.
484
+ non_blocking: bool = False,
485
+ copy: bool = False,
486
+ memory_format: torch.memory_format | None = None,
487
+ ) -> NullableTensor:
488
+
489
+ if dtype is not None and dtype not in inp.ALLOWED_DTYPES:
490
+ raise TypeError(
491
+ f"Can't convert {inp.__class__.__name__!r} to dtype '{dtype}'"
492
+ )
493
+
494
+ if (
495
+ not copy
496
+ and (dtype is None or dtype == inp.dtype)
497
+ and (device is None or torch.device(device) == inp.device)
498
+ and (layout is None or layout == inp.layout)
499
+ and (
500
+ memory_format is None
501
+ or memory_format == torch.preserve_format
502
+ or (
503
+ memory_format == torch.contiguous_format
504
+ and inp.is_contiguous()
505
+ )
506
+ )
507
+ ):
508
+ return inp
509
+
510
+ return inp.__class__(
511
+ data=aten.to.dtype_layout(
512
+ inp._data,
513
+ dtype=dtype,
514
+ layout=layout,
515
+ device=device,
516
+ pin_memory=pin_memory,
517
+ non_blocking=non_blocking,
518
+ copy=copy,
519
+ memory_format=memory_format,
520
+ ),
521
+ valid=aten.to.dtype_layout(
522
+ inp._valid,
523
+ dtype=None,
524
+ layout=layout,
525
+ device=device,
526
+ pin_memory=pin_memory,
527
+ non_blocking=non_blocking,
528
+ copy=copy,
529
+ memory_format=memory_format,
530
+ ),
531
+ )
532
+
533
+
534
+ @NullableTensor.implements(aten.to.dtype)
535
+ def _to_dtype(
536
+ inp: NullableTensor,
537
+ dtype: torch.dtype,
538
+ non_blocking: bool = False,
539
+ copy: bool = False,
540
+ memory_format: torch.memory_format | None = None,
541
+ ) -> NullableTensor:
542
+ return _to_dtype_layout(
543
+ inp,
544
+ dtype=dtype,
545
+ non_blocking=non_blocking,
546
+ copy=copy,
547
+ memory_format=memory_format,
548
+ )
549
+
550
+
551
+ @NullableTensor.implements(aten.to.device)
552
+ def _to_device(
553
+ inp: NullableTensor,
554
+ device: torch.device,
555
+ dtype: torch.dtype,
556
+ non_blocking: bool = False,
557
+ copy: bool = False,
558
+ memory_format: torch.memory_format | None = None,
559
+ ) -> NullableTensor:
560
+ return _to_dtype_layout(
561
+ inp,
562
+ dtype=dtype,
563
+ device=device,
564
+ non_blocking=non_blocking,
565
+ copy=copy,
566
+ memory_format=memory_format,
567
+ )
568
+
569
+
570
+ @NullableTensor.implements(aten.to.other)
571
+ def _to_other(
572
+ inp: NullableTensor,
573
+ other: Tensor,
574
+ non_blocking: bool = False,
575
+ copy: bool = False,
576
+ memory_format: torch.memory_format | None = None,
577
+ ) -> NullableTensor:
578
+ return _to_dtype_layout(
579
+ inp,
580
+ dtype=other.dtype,
581
+ layout=other.layout,
582
+ device=other.device,
583
+ non_blocking=non_blocking,
584
+ copy=copy,
585
+ memory_format=memory_format,
586
+ )
587
+
588
+
589
+ @NullableTensor.implements(aten._to_copy.default)
590
+ def _to_copy(
591
+ inp: NullableTensor,
592
+ *,
593
+ dtype: torch.dtype | None = None,
594
+ layout: torch.layout | None = None,
595
+ device: torch.device | str | None = None,
596
+ pin_memory: bool = False, # Ignored by PyTorch.
597
+ non_blocking: bool = False,
598
+ memory_format: torch.memory_format | None = None,
599
+ ) -> NullableTensor:
600
+ return _to_dtype_layout(
601
+ inp,
602
+ dtype=dtype,
603
+ layout=layout,
604
+ device=device,
605
+ pin_memory=pin_memory,
606
+ non_blocking=non_blocking,
607
+ copy=True,
608
+ memory_format=memory_format,
609
+ )
610
+
611
+
612
+ @NullableTensor.implements(aten.clone.default)
613
+ def _clone(
614
+ inp: NullableTensor,
615
+ *,
616
+ memory_format: torch.memory_format | None = None,
617
+ ) -> NullableTensor:
618
+ return _to_dtype_layout(inp, copy=True, memory_format=memory_format)
619
+
620
+
621
+ @NullableTensor.implements(aten.contiguous.default)
622
+ def _contiguous(
623
+ inp: NullableTensor,
624
+ *,
625
+ memory_format: torch.memory_format = torch.contiguous_format,
626
+ ) -> NullableTensor:
627
+ return inp.__class__(
628
+ data=inp._data.contiguous(memory_format=memory_format),
629
+ valid=inp._valid.contiguous(memory_format=memory_format),
630
+ )
631
+
632
+
633
+ @NullableTensor.implements(aten.is_pinned.default)
634
+ def _is_pinned(inp: NullableTensor) -> bool:
635
+ return inp._data.is_pinned() and inp._valid.is_pinned()
636
+
637
+
638
+ @NullableTensor.implements(aten._pin_memory.default)
639
+ def _pin_memory(inp: NullableTensor) -> NullableTensor:
640
+ return inp.__class__(
641
+ data=inp._data.pin_memory(),
642
+ valid=inp._valid.pin_memory(),
643
+ )
644
+
645
+
646
+ @NullableTensor.implements(aten.pin_memory.default)
647
+ def _pin_memory_composite(
648
+ inp: NullableTensor,
649
+ device: torch.device | None = None,
650
+ ) -> NullableTensor:
651
+ if _is_pinned(inp):
652
+ return inp
653
+ return _pin_memory(inp)
654
+
655
+
656
+ @NullableTensor.implements(aten.isnan.default)
657
+ def _isnan(inp: NullableTensor) -> Tensor:
658
+ return ~inp._valid
659
+
660
+
661
+ @NullableTensor.implements(aten.isfinite.default)
662
+ def _isfinite(inp: NullableTensor) -> Tensor:
663
+ return inp._valid.clone()
664
+
665
+
666
+ @NullableTensor.implements(aten.nan_to_num.default)
667
+ def _nan_to_num(
668
+ inp: NullableTensor,
669
+ nan: int = 0,
670
+ posinf: Any = None,
671
+ neginf: Any = None,
672
+ ) -> Tensor:
673
+ return torch.where(inp._valid, inp._data, nan)
674
+
675
+
676
+ @NullableTensor.implements(aten.equal.default)
677
+ def _equal(inp: NullableTensor, other: Tensor) -> bool:
678
+ if inp.__class__ is not other.__class__:
679
+ return False
680
+ if inp.size() != other.size():
681
+ return False
682
+
683
+ if not inp._valid.equal(other._valid):
684
+ return False
685
+
686
+ return inp._data[inp._valid].equal(other._data[other._valid])
687
+
688
+
689
+ @NullableTensor.implements(aten.allclose.default)
690
+ def _allclose(
691
+ inp: NullableTensor,
692
+ other: Tensor,
693
+ rtol: float = 1e-05,
694
+ atol: float = 1e-08,
695
+ equal_nan: bool = False,
696
+ ) -> bool:
697
+ return _equal(inp, other)
698
+
699
+
700
+ @NullableTensor.implements(aten.view.default)
701
+ @preserve_view_inference_mode
702
+ def _view(inp: NullableTensor, size: Sequence[int]) -> NullableTensor:
703
+ return _apply(inp, lambda x: aten.view.default(x, size))
704
+
705
+
706
+ @NullableTensor.implements(aten._unsafe_view.default)
707
+ @preserve_view_inference_mode
708
+ def _unsafe_view(
709
+ inp: NullableTensor,
710
+ size: Sequence[int],
711
+ ) -> NullableTensor:
712
+ return _apply(inp, lambda x: aten._unsafe_view.default(x, size))
713
+
714
+
715
+ @NullableTensor.implements(aten.reshape.default)
716
+ def _reshape(inp: NullableTensor, size: Sequence[int]) -> NullableTensor:
717
+ return cast(
718
+ NullableTensor,
719
+ aten.reshape.default.decompose(inp, size),
720
+ )
721
+
722
+
723
+ @NullableTensor.implements(aten.flatten.using_ints)
724
+ def _flatten(
725
+ inp: NullableTensor,
726
+ start_dim: int = 0,
727
+ end_dim: int = -1,
728
+ ) -> NullableTensor:
729
+ return cast(
730
+ NullableTensor,
731
+ aten.flatten.using_ints.decompose(inp, start_dim, end_dim),
732
+ )
733
+
734
+
735
+ @NullableTensor.implements(aten.squeeze.default)
736
+ @preserve_view_inference_mode
737
+ def _squeeze(inp: NullableTensor) -> NullableTensor:
738
+ return _apply(inp, lambda x: aten.squeeze.default(x))
739
+
740
+
741
+ @NullableTensor.implements(aten.squeeze.dim)
742
+ @preserve_view_inference_mode
743
+ def _squeeze_dim(inp: NullableTensor, dim: int) -> NullableTensor:
744
+ return _apply(inp, lambda x: aten.squeeze.dim(x, dim))
745
+
746
+
747
+ @NullableTensor.implements(aten.squeeze.dims)
748
+ @preserve_view_inference_mode
749
+ def _squeeze_dims(
750
+ inp: NullableTensor,
751
+ dim: Sequence[int],
752
+ ) -> NullableTensor:
753
+ return _apply(inp, lambda x: aten.squeeze.dims(x, dim))
754
+
755
+
756
+ @NullableTensor.implements(aten.unsqueeze.default)
757
+ @preserve_view_inference_mode
758
+ def _unsqueeze(inp: NullableTensor, dim: int) -> NullableTensor:
759
+ return _apply(inp, lambda x: aten.unsqueeze.default(x, dim))
760
+
761
+
762
+ @NullableTensor.implements(aten.expand.default)
763
+ @preserve_view_inference_mode
764
+ def _expand(
765
+ inp: NullableTensor,
766
+ size: Sequence[int],
767
+ *,
768
+ implicit: bool = False,
769
+ ) -> NullableTensor:
770
+ return _apply(
771
+ inp,
772
+ lambda x: aten.expand.default(x, size, implicit=implicit),
773
+ )
774
+
775
+
776
+ @NullableTensor.implements(aten.t.default)
777
+ @preserve_view_inference_mode
778
+ def _t(inp: NullableTensor) -> NullableTensor:
779
+ return _apply(inp, lambda x: aten.t.default(x))
780
+
781
+
782
+ @NullableTensor.implements(aten.transpose.int)
783
+ @preserve_view_inference_mode
784
+ def _transpose(inp: NullableTensor, dim0: int, dim1: int) -> NullableTensor:
785
+ return _apply(inp, lambda x: aten.transpose.int(x, dim0, dim1))
786
+
787
+
788
+ @NullableTensor.implements(aten.permute.default)
789
+ @preserve_view_inference_mode
790
+ def _permute(inp: NullableTensor, dims: Sequence[int]) -> NullableTensor:
791
+ return _apply(inp, lambda x: aten.permute.default(x, dims))
792
+
793
+
794
+ @NullableTensor.implements(aten.movedim.int)
795
+ def _movedim_int(
796
+ inp: NullableTensor,
797
+ source: int,
798
+ destination: int,
799
+ ) -> NullableTensor:
800
+ return cast(
801
+ NullableTensor,
802
+ aten.movedim.int.decompose(inp, source, destination),
803
+ )
804
+
805
+
806
+ @NullableTensor.implements(aten.movedim.intlist)
807
+ def _movedim_intlist(
808
+ inp: NullableTensor,
809
+ source: Sequence[int],
810
+ destination: Sequence[int],
811
+ ) -> NullableTensor:
812
+ return cast(
813
+ NullableTensor,
814
+ aten.movedim.intlist.decompose(inp, source, destination),
815
+ )
816
+
817
+
818
+ @NullableTensor.implements(aten.select.int)
819
+ @preserve_view_inference_mode
820
+ def _select(inp: NullableTensor, dim: int, index: int) -> NullableTensor:
821
+ return _apply(inp, lambda x: aten.select.int(x, dim, index))
822
+
823
+
824
+ @NullableTensor.implements(aten.slice.Tensor)
825
+ @preserve_view_inference_mode
826
+ def _slice(
827
+ inp: NullableTensor,
828
+ dim: int = 0,
829
+ start: int | None = None,
830
+ end: int | None = None,
831
+ step: int = 1,
832
+ ) -> NullableTensor:
833
+ return _apply(inp, lambda x: aten.slice.Tensor(x, dim, start, end, step))
834
+
835
+
836
+ @NullableTensor.implements(aten.narrow.default)
837
+ @preserve_view_inference_mode
838
+ def _narrow(
839
+ inp: NullableTensor,
840
+ dim: int,
841
+ start: int,
842
+ length: int,
843
+ ) -> NullableTensor:
844
+ return _apply(inp, lambda x: aten.narrow.default(x, dim, start, length))
845
+
846
+
847
+ @NullableTensor.implements(aten.unbind.int)
848
+ @preserve_view_inference_mode
849
+ def _unbind(
850
+ inp: NullableTensor,
851
+ dim: int = 0,
852
+ ) -> tuple[NullableTensor, ...]:
853
+ return tuple(
854
+ inp.__class__(data, valid)
855
+ for data, valid in zip(
856
+ inp._data.unbind(dim=dim),
857
+ inp._valid.unbind(dim=dim),
858
+ )
859
+ )
860
+
861
+
862
+ @NullableTensor.implements(aten.split.Tensor)
863
+ @preserve_view_inference_mode
864
+ def _split(
865
+ inp: NullableTensor,
866
+ split_size: int,
867
+ dim: int = 0,
868
+ ) -> tuple[NullableTensor, ...]:
869
+ return tuple(
870
+ inp.__class__(data, valid)
871
+ for data, valid in zip(
872
+ inp._data.split(split_size, dim=dim),
873
+ inp._valid.split(split_size, dim=dim),
874
+ )
875
+ )
876
+
877
+
878
+ @NullableTensor.implements(aten.split.sizes)
879
+ @NullableTensor.implements(aten.split.default)
880
+ @NullableTensor.implements(aten.split_with_sizes.default)
881
+ @preserve_view_inference_mode
882
+ def _split_with_sizes(
883
+ inp: NullableTensor,
884
+ split_sizes: Sequence[int],
885
+ dim: int = 0,
886
+ ) -> tuple[NullableTensor, ...]:
887
+ return tuple(
888
+ inp.__class__(data, valid)
889
+ for data, valid in zip(
890
+ inp._data.split(split_sizes, dim=dim),
891
+ inp._valid.split(split_sizes, dim=dim),
892
+ )
893
+ )
894
+
895
+
896
+ @NullableTensor.implements(aten.masked_select.default)
897
+ def _masked_select(inp: NullableTensor, mask: Tensor) -> NullableTensor:
898
+ return _apply(inp, lambda x: aten.masked_select.default(x, mask))
899
+
900
+
901
+ @NullableTensor.implements(aten.index_select.default)
902
+ def _index_select(
903
+ inp: NullableTensor,
904
+ dim: int,
905
+ index: Tensor,
906
+ ) -> NullableTensor:
907
+ return _apply(inp, lambda x: aten.index_select.default(x, dim, index))
908
+
909
+
910
+ @NullableTensor.implements(aten.take.default)
911
+ def _take(inp: NullableTensor, index: Tensor) -> NullableTensor:
912
+ return _apply(inp, lambda x: aten.take.default(x, index))
913
+
914
+
915
+ @NullableTensor.implements(aten.index.Tensor)
916
+ def _index(
917
+ inp: NullableTensor,
918
+ indices: Sequence[Tensor | None],
919
+ ) -> NullableTensor:
920
+ return _apply(inp, lambda x: aten.index.Tensor(x, indices))
921
+
922
+
923
+ @NullableTensor.implements(aten.cat.default)
924
+ def _cat(tensors: Sequence[Tensor], dim: int = 0) -> NullableTensor:
925
+ if len(tensors) == 0:
926
+ raise ValueError("Expected a non-empty list of Tensors")
927
+
928
+ if not isinstance(tensors[0], NullableTensor):
929
+ raise TypeError(
930
+ f"Expected {NullableTensor.__name__!r} as element 0, but got "
931
+ f"{tensors[0].__class__.__name__!r}"
932
+ )
933
+
934
+ tensors = cast(Sequence[NullableTensor], tensors)
935
+ return tensors[0].__class__(
936
+ data=torch.cat([tensor._data for tensor in tensors], dim=dim),
937
+ valid=torch.cat([tensor._valid for tensor in tensors], dim=dim),
938
+ )
939
+
940
+
941
+ @NullableTensor.implements(aten.stack.default)
942
+ def _stack(tensors: Sequence[Tensor], dim: int = 0) -> NullableTensor:
943
+ out = torch.cat([tensor.unsqueeze(dim) for tensor in tensors], dim=dim)
944
+ return cast(NullableTensor, out)
945
+
946
+
947
+ # Helpers #####################################################################
948
+
949
+
950
+ def _contiguous_stride(size: Sequence[int]) -> tuple[int, ...]:
951
+ value = 1
952
+ stride = []
953
+ for dim_size in reversed(size):
954
+ stride.append(value)
955
+ value *= dim_size
956
+ return tuple(stride[::-1])
957
+
958
+
959
+ def _apply(
960
+ inp: NullableTensor,
961
+ fn: Callable[[Tensor], Tensor],
962
+ ) -> NullableTensor:
963
+ return inp.__class__(fn(inp._data), fn(inp._valid))