From e531085fda385c25974d2a8a54ce6bb021728d7e Mon Sep 17 00:00:00 2001 From: Evgeni Burovski Date: Fri, 1 May 2026 10:56:28 +0200 Subject: [PATCH 1/2] docs: allow per-device dtype subsets --- spec/draft/API_specification/creation_functions.rst | 5 +++++ spec/draft/API_specification/data_types.rst | 5 ++++- spec/draft/design_topics/device_support.rst | 1 + 3 files changed, 10 insertions(+), 1 deletion(-) diff --git a/spec/draft/API_specification/creation_functions.rst b/spec/draft/API_specification/creation_functions.rst index ff5c06368..4fe4ca669 100644 --- a/spec/draft/API_specification/creation_functions.rst +++ b/spec/draft/API_specification/creation_functions.rst @@ -34,3 +34,8 @@ Objects in API triu zeros zeros_like + + +.. note:: + Creation functions which accept ``device`` and ``dtype`` arguments should raise an + exception if the explicitly provided ``dtype`` is not supported by the ``device``. diff --git a/spec/draft/API_specification/data_types.rst b/spec/draft/API_specification/data_types.rst index 5987dd322..f7cffc544 100644 --- a/spec/draft/API_specification/data_types.rst +++ b/spec/draft/API_specification/data_types.rst @@ -5,7 +5,7 @@ Data Types Array API specification for supported data types. -A conforming implementation of the array API standard must provide and support +A conforming implementation of the array API standard should provide and support the following data types ("dtypes") in its array object, and as data type objects in its main namespace under the specified names: @@ -39,6 +39,9 @@ objects in its main namespace under the specified names: | complex128 | Double-precision (128-bit) complex floating-point number whose real and imaginary components must be IEEE 754 double-precision (64-bit) binary floating-point numbers (see IEEE 754-2019). | +--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +If a library only supports a subset of data types, it must support at least one data type +from each :ref:`category `. + Data type objects must have the following methods (no attributes are required): .. diff --git a/spec/draft/design_topics/device_support.rst b/spec/draft/design_topics/device_support.rst index a16a94f93..afd91e42f 100644 --- a/spec/draft/design_topics/device_support.rst +++ b/spec/draft/design_topics/device_support.rst @@ -77,6 +77,7 @@ rather than hard requirements: - Respect explicit device assignment (i.e. if the input to the ``device=`` keyword is not ``None``, guarantee that the array is created on the given device, and raise an exception otherwise). - Preserve device assignment as much as possible (e.g. output arrays from a function are expected to be on the same device as input arrays to the function). - Raise an exception if an operation involves arrays on different devices (i.e. avoid implicit data transfer between devices). +- Raise an exception if the user explicitly requests an unsupported combination of a ``device=`` and ``dtype=`` arguments (e.g. when a user attempts to create an array of a data type which is not supported by the device, we recommend raising an error instead of silently returning an array of a dtype supported by the device). - When a function accepts a mix of arrays and Python scalars, the scalars should inherit the device of the arrays, much like what happens with :ref:`type-promotion`. - Use a default for ``device=None`` which is consistent between functions within the same library. - If a library has multiple ways of controlling device placement, the most explicit method should have the highest priority: From d64de1f0ea52f6e2ab2ba8f6556bb2f3a5b06af1 Mon Sep 17 00:00:00 2001 From: Evgeni Burovski Date: Fri, 1 May 2026 11:49:14 +0200 Subject: [PATCH 2/2] stubs: clarify that indexing/setitem is unspecified across devices --- src/array_api_stubs/_draft/array_object.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/array_api_stubs/_draft/array_object.py b/src/array_api_stubs/_draft/array_object.py index 785acdc52..9a2d36696 100644 --- a/src/array_api_stubs/_draft/array_object.py +++ b/src/array_api_stubs/_draft/array_object.py @@ -669,6 +669,10 @@ def __getitem__( - See :ref:`indexing` for details on supported indexing semantics. - When ``__getitem__`` is defined on an object, Python will automatically define iteration (i.e., the behavior from ``iter(x)``) as ``x[0]``, ``x[1]``, ..., ``x[N-1]``. This can also be implemented directly by defining ``__iter__``. Therefore, for a one-dimensional array ``x``, iteration should produce a sequence of zero-dimensional arrays ``x[0]``, ``x[1]``, ..., ``x[N-1]``, where ``N`` is the number of elements in the array. Iteration behavior for arrays having zero dimensions or more than one dimension is unspecified and thus implementation-defined. + .. note:: + When ``key`` contains integer arrays on a device different from the device of ``self``, the + behavior is unspecified and thus implementation-defined. + .. versionchanged:: 2024.12 Clarified that iteration is defined for one-dimensional arrays. """ @@ -1154,6 +1158,10 @@ def __setitem__( .. note:: Indexing semantics when ``key`` is an integer array or a tuple of integers and integer arrays is currently unspecified and thus implementation-defined. This will be revisited in a future revision of this standard. + .. note:: + When ``value`` is an array on a device different from the device of ``self``, the + behavior is unspecified and thus implementation-defined. + - Setting array values must not affect the data type of ``self``. - ``value`` must be promoted to the data type of ``self`` according to :ref:`type-promotion`. If this is not supported according to :ref:`type-promotion`, behavior is unspecified and thus implementation-defined.