Unify scalars and 0d tiles

Signed-off-by: Greg Bonik <gbonik@nvidia.com>

Author: gbonik

changelog.d/unify-scalar-0d-tile.md

@@ -0,0 +1,5 @@
+<!--- SPDX-FileCopyrightText: Copyright (c) <2026> NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
+<!--- SPDX-License-Identifier: Apache-2.0 -->
+
+- Erased the distinction between scalars and zero-dimensional tiles.
+  They are now completely interchangeable.

docs/source/data.rst

@@ -22,38 +22,112 @@ An array-based model was chosen because:
 
 Within |tile code|, only the types described in this section are supported.
 
+
 Global Arrays
 -------------
 
-.. autoclass:: Array
-   :no-members:
-   :no-index:
+A *global array* (or *array*) is a container of elements of a specific |dtype|
+arranged in a logical multidimensional space.
+
+Array's *shape* is a tuple of integer values, each denoting the length of
+the corresponding dimension.
+The length of the shape tuple equals the arrays's number of dimensions.
+The product of shape values equals the total logical number of elements in the array.
+
+Arrays are stored in global memory using a *strided memory layout*: in addition to a shape,
+an array also has an equally sized tuple of *strides*. Strides determine the mapping of logical
+array indices to physical memory locations. For example, for a 3-dimensional `float32` array
+with strides `(s1, s2, s3)`, the memory address of the element at the logical index
+`(i1, i2, i3)` will be:
+
+.. code-block::
+
+    base_addr + 4 * (s1 * i1 + s2 * i2 + s3 * i3),
+
+where ``base_addr`` is the base address of the array and `4` is the byte size of a single `float32`
+element.
+
+New arrays can only be allocated by the host, and passed to the tile kernel as arguments.
+|Tile code| can only create new views of existing arrays, for example using
+:meth:`Array.slice`. Like in Python, assigning an array object to another variable does not copy
+the underlying data, but creates another reference to the array object.
+
+Any object that implements the |DLPack| interface or the |CUDA Array Interface|
+can be passed to the kernel as an argument. Example: |CuPy| arrays and |PyTorch| tensors.
 
-   .. seealso::
-      :ref:`Complete cuda.tile.Array class documentation <data-array-cuda-tile-array>`
+If two or more array arguments are passed to the kernel, their memory storage must not overlap.
+Otherwise, behavior is undefined.
+
+Array's shape can be queried using the :py:attr:`Array.shape` attribute, which
+returns a tuple of `int32` scalars. These scalars are non-constant, runtime values.
+Using `int32` makes the tile code more performant at the cost of limiting the maximum
+representable shape at 2,147,483,647 elements. This limitation will be lifted in the future.
+
+
+.. seealso::
+  :ref:`cuda.tile.Array class documentation <data-array-cuda-tile-array>`
 
 .. toctree::
    :maxdepth: 2
    :hidden:
 
    data/array
 
-Tiles
------
 
-.. autoclass:: Tile
-   :no-members:
-   :no-index:
+.. _data-tiles-and-scalars:
+
+Tiles and Scalars
+-----------------
+A *tile* is an immutable multidimensional collection of elements of a specific |dtype|.
+
+Tile's *shape* is a tuple of integer values, each denoting the length of the corresponding dimension.
+The length of the shape tuple equals the tile's number of dimensions.
+The product of shape values equals the total number of elements in the tile.
+
+The shape of a tile must be known at compile time. Each dimension of a tile must be a power of 2.
+
+Tile's dtype and shape can be queried with the ``dtype`` and ``shape`` attributes, respectively.
+For example, if ``x`` is a `float32` tile, the expression ``x.dtype`` will return
+a compile-time constant equal to :py:data:`cuda.tile.float32`.
 
-   .. seealso::
-      :ref:`Complete cuda.tile.Tile class documentation <data-tile-cuda-tile-tile>`
+A zero-dimensional tile is called a *scalar*. Such tile has exactly one element. The shape
+of a scalar is the empty tuple `()`. Numeric literals like `7` or `3.14` are treated as
+constant scalars, i.e. zero-dimensional tiles.
+
+Since scalars are tiles, they slightly differ in behavior from Python's ``int``/``float`` objects.
+For example, they have ``dtype`` and ``shape`` attributes:
+
+.. code-block:: python
+
+    a = 0
+    # The following line will evaluate to cuda.tile.int32 in cuTile,
+    # but would raise an AttributeError in Python:
+    a.dtype
+
+Tiles can only be used in |tile code|, not host code.
+The contents of a tile do not necessarily have a physical representation in memory.
+Non-scalar tiles can be created by loading from |global arrays| using functions such as
+:py:func:`cuda.tile.load` and :py:func:`cuda.tile.gather` or with |factory| functions
+such as :py:func:`cuda.tile.zeros`.
+
+Tiles can also be stored into global arrays using functions such as :py:func:`cuda.tile.store`
+or :py:func:`cuda.tile.scatter`.
+
+Only scalars (i.e. 0-dimensional tiles) can be used as |kernel| parameters.
+
+Scalar constants are |loosely typed| by default, for example, a literal ``2`` or
+a constant attribute like ``Tile.ndim``, ``Tile.shape``, or ``Array.ndim``.
+
+.. seealso::
+  :ref:`cuda.tile.Tile class documentation <data-tile-cuda-tile-tile>`
 
 .. toctree::
    :maxdepth: 2
    :hidden:
 
    data/tile
 
+
 .. _data-element-tile-space:
 
 Element & Tile Space
@@ -145,23 +219,6 @@ to a common dtype using the following process:
 
 .. include:: generated/includes/dtype_promotion_table.rst
 
-
-.. _data-scalars:
-
-Scalars
--------
-
-A *scalar* is a single immutable value of a specific |data type|. A *scalar* and *0D-tile*
-can be used interchangably in a tile |kernel|. They can also be |kernel| parameters.
-
-Typing of a *scalar* has the following rules:
-
-- Constant scalars are |loosely typed| by default, for example, a literal ``2`` or
-  a constant property like ``Tile.ndim``, ``Tile.shape``, or ``Array.ndim``.
-- ``Array.shape`` and ``Array.stride`` are not constant by default and has default int type `int32`.
-  Using default `int32` makes kernel more performant at the cost of limiting max representable shape.
-  This limitation will be lifted in the near future.
-
 Tuples
 ------
 

docs/source/references.rst

@@ -63,10 +63,10 @@
 .. |arrays| replace:: :ref:`arrays <data-array-cuda-tile-array>`
 .. |Arrays| replace:: :ref:`Arrays <data-array-cuda-tile-array>`
 
-.. |tile| replace:: :ref:`tile <data-tile-cuda-tile-tile>`
-.. |Tile| replace:: :ref:`Tile <data-tile-cuda-tile-tile>`
-.. |tiles| replace:: :ref:`tiles <data-tile-cuda-tile-tile>`
-.. |Tiles| replace:: :ref:`Tiles <data-tile-cuda-tile-tile>`
+.. |tile| replace:: :ref:`tile <data-tiles-and-scalars>`
+.. |Tile| replace:: :ref:`Tile <data-tiles-and-scalars>`
+.. |tiles| replace:: :ref:`tiles <data-tiles-and-scalars>`
+.. |Tiles| replace:: :ref:`Tiles <data-tiles-and-scalars>`
 
 .. |data type| replace:: :ref:`data type <data-data-types>`
 .. |Data type| replace:: :ref:`Data type <data-data-types>`
@@ -102,10 +102,10 @@
 .. |tile spaces| replace:: :ref:`tile spaces <data-element-tile-space>`
 .. |Tile spaces| replace:: :ref:`Tile spaces <data-element-tile-space>`
 
-.. |scalar| replace:: :ref:`scalar <data-scalars>`
-.. |Scalar| replace:: :ref:`Scalar <data-scalars>`
-.. |scalars| replace:: :ref:`scalars <data-scalars>`
-.. |Scalars| replace:: :ref:`Scalars <data-scalars>`
+.. |scalar| replace:: :ref:`scalar <data-tiles-and-scalars>`
+.. |Scalar| replace:: :ref:`Scalar <data-tiles-and-scalars>`
+.. |scalars| replace:: :ref:`scalars <data-tiles-and-scalars>`
+.. |Scalars| replace:: :ref:`Scalars <data-tiles-and-scalars>`
 
 .. |Rounding Modes| replace:: :ref:`Rounding Modes <data-rounding-modes>`
 .. |Padding Modes| replace:: :ref:`Padding Modes <data-padding-modes>`

src/cuda/tile/_datatype.py

@@ -21,7 +21,7 @@
            "NumericDTypeCategories"]
 
 
-class DType(Type):
+class DType:
     """A *data type* (or *dtype*) describes the type of the objects of an |array|, |tile|, or
     operation.
 
@@ -57,6 +57,10 @@ def name(self):
     def __name__(self) -> str:
         return self._name
 
+    @function(host=True, tile=False)
+    def __repr__(self):
+        return f"<DType '{self._name}'>"
+
     @function(host=True, tile=False)
     def __str__(self):
         return self._name

src/cuda/tile/_ir/ir.py

@@ -179,6 +179,7 @@ def get_type_allow_invalid(self) -> Type:
             raise TileInternalError(f"Type of variable {self.name} not found")
 
     def set_type(self, ty: Type, force: bool = False):
+        assert isinstance(ty, Type)
         if not force:
             assert self.name not in self.ctx.typemap
         self.ctx.typemap[self.name] = ty
@@ -207,6 +208,7 @@ def get_loose_type_allow_invalid(self) -> Type:
         return self.get_type_allow_invalid() if ty is None else ty
 
     def set_loose_type(self, ty: Type, force: bool = False):
+        assert isinstance(ty, Type)
         if not force:
             assert self.name not in self.ctx._loose_typemap
         self.ctx._loose_typemap[self.name] = ty