From d299407073789ae3770c8fb07b86dad714dada96 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 17 Feb 2025 04:49:51 -0800 Subject: [PATCH 01/31] feat: add support for integer array indexing Closes: https://github.com/data-apis/array-api/issues/669 Ref: https://numpy.org/neps/nep-0021-advanced-indexing.html --- spec/draft/API_specification/indexing.rst | 46 +++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index eb61c26d5..599566d1c 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -7,6 +7,9 @@ Indexing A conforming implementation of the array API standard must adhere to the following conventions. + +.. _indexing-single-axis: + Single-axis Indexing -------------------- @@ -121,6 +124,9 @@ The behavior outside of these bounds is unspecified. .. note:: *Rationale: this is consistent with bounds checking for integer indexing; the behavior of out-of-bounds indices is left unspecified. Implementations may choose to clip (consistent with Python* ``list`` *slicing semantics), raise an exception, return junk values, or some other behavior depending on device requirements and performance considerations.* + +.. _indexing-multi-axis: + Multi-axis Indexing ------------------- @@ -173,6 +179,46 @@ Multi-dimensional arrays must extend the concept of single-axis indexing to mult *Rationale: this is consistent with bounds-checking for single-axis indexing. An implementation may choose to set the axis (dimension) size of the result array to* ``0`` *, raise an exception, return junk values, or some other behavior depending on device requirements and performance considerations.* +Integer Array Indexing +---------------------- + +An array must support indexing a one-dimensional array by a one-dimensional integer array according to the following rules. Let ``A`` be a one-dimensional array with shape ``S1 = (n)``, and let ``J`` be a one-dimensional integer array with ``S2 = (k,)``. + +- Each integer index element in ``J`` must satisfy the rules stated above for indexing a single-axis (see :ref:`indexing-single-axis`). Namely, + + - Nonnegative indices must start at ``0`` (i.e., zero-based indexing). + - **Valid** nonnegative indices must reside on the half-open interval ``[0, n)``. + - Negative indices must count backward from the last index along an array dimension, starting from ``-1`` (i.e., negative-one-based indexing, where ``-1`` refers to the last index along an array dimension). + - **Valid** negative indices must reside on the closed interval ``[-n, -1]``. + - A negative index ``j`` is related to a zero-based nonnegative index ``i`` via ``i = n+j``. + + .. note:: + This specification does not require bounds checking. The behavior for out-of-bounds integer indices is left unspecified. + +- Providing duplicate integer index elements in ``J`` must result in the duplication of the corresponding elements of ``A`` in the resulting array. + +- The result of providing a valid integer index for each element in ``J`` must be an array having shape ``S3 = (k,)``. + +An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and one-dimensional integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, ..., sM, ..., sN)`` and ``T`` be a tuple ``(t1, ..., tM, ..., tN)`` having length ``N`` and containing only valid integer and one-dimensional integer array indices. + +.. note:: + This specification does not require bounds checking. The behavior for out-of-bounds integer indices is left unspecified. + +- Providing an integer tuple element ``tk`` having value ``k`` must be equivalent to providing a zero-dimensional integer array ``K`` containing ``k``. + +- If ``T`` consists of only integers and zero-dimensional integer arrays, the result must be equivalent to indexing multiple axes using integer indices (see :ref:`indexing-multi-axis`). + +- When ``T`` contains a one-dimensional integer array ``J`` having shape ``S2 = (m,)``, where ``m`` is greater than or equal to the number of elements in any other one-dimensional integer array in ``T``, each element of ``T`` must be broadcast to the same shape as ``J``. + +- An ``IndexError`` exception must be raised if any element of ``T`` is not broadcast-compatible with ``J`` (see :ref:`broadcasting`). + +- After broadcasting, ``T`` must be equivalent to a tuple ``U = (u1, ..., uM, ..., uN)`` containing only one-dimensional integer arrays having shape ``S2``. + +- Let ``v_i`` be the tuple formed by the integer indices ``u1[i], u2[i], ..., uM[i], ..., uN[i]``. When applying the indexing tuple ``U`` to ``A``, the resulting array must be a one-dimensional array containing each element ``A[v_i]`` for ``i`` on the half-open interval ``[0, m)``. + +.. note:: + This specification does not currently address indexing tuples which combine slices and integer arrays. Behavior for such indexing tuples is left unspecified and thus implementation-defined. This may be revisited in a future revision of this standard. + Boolean Array Indexing ---------------------- From 6ca9c63d2e9eebabdbec04169cea4798481e185f Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 17 Feb 2025 04:54:21 -0800 Subject: [PATCH 02/31] docs: fix copy --- spec/draft/API_specification/indexing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 599566d1c..15714aa5e 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -182,7 +182,7 @@ Multi-dimensional arrays must extend the concept of single-axis indexing to mult Integer Array Indexing ---------------------- -An array must support indexing a one-dimensional array by a one-dimensional integer array according to the following rules. Let ``A`` be a one-dimensional array with shape ``S1 = (n)``, and let ``J`` be a one-dimensional integer array with ``S2 = (k,)``. +An array must support indexing a one-dimensional array by a one-dimensional integer array according to the following rules. Let ``A`` be a one-dimensional array with shape ``S1 = (n,)``, and let ``J`` be a one-dimensional integer array with ``S2 = (k,)``. - Each integer index element in ``J`` must satisfy the rules stated above for indexing a single-axis (see :ref:`indexing-single-axis`). Namely, From 7c8715b8c4522a95e3dd9b7a7f6e6e1b48d80b7e Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 17 Feb 2025 04:55:19 -0800 Subject: [PATCH 03/31] docs: fix copy --- spec/draft/API_specification/indexing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 15714aa5e..86967f75e 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -188,7 +188,7 @@ An array must support indexing a one-dimensional array by a one-dimensional inte - Nonnegative indices must start at ``0`` (i.e., zero-based indexing). - **Valid** nonnegative indices must reside on the half-open interval ``[0, n)``. - - Negative indices must count backward from the last index along an array dimension, starting from ``-1`` (i.e., negative-one-based indexing, where ``-1`` refers to the last index along an array dimension). + - Negative indices must count backward from the last index, starting from ``-1`` (i.e., negative-one-based indexing, where ``-1`` refers to the last index). - **Valid** negative indices must reside on the closed interval ``[-n, -1]``. - A negative index ``j`` is related to a zero-based nonnegative index ``i`` via ``i = n+j``. From 7d60bcb9ba85d39dde2e842f29ab02611a4a2fe3 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 17 Feb 2025 05:01:51 -0800 Subject: [PATCH 04/31] docs: update copy --- spec/draft/API_specification/indexing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 86967f75e..95488ad53 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -199,7 +199,7 @@ An array must support indexing a one-dimensional array by a one-dimensional inte - The result of providing a valid integer index for each element in ``J`` must be an array having shape ``S3 = (k,)``. -An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and one-dimensional integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, ..., sM, ..., sN)`` and ``T`` be a tuple ``(t1, ..., tM, ..., tN)`` having length ``N`` and containing only valid integer and one-dimensional integer array indices. +An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and one-dimensional integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, s2, ..., sN)`` and ``T`` be a tuple ``(t1, t2, ..., tN)`` having length ``N`` and containing only valid integer and one-dimensional integer array indices. .. note:: This specification does not require bounds checking. The behavior for out-of-bounds integer indices is left unspecified. @@ -212,9 +212,9 @@ An array must support indexing an array having more than one dimension by an ind - An ``IndexError`` exception must be raised if any element of ``T`` is not broadcast-compatible with ``J`` (see :ref:`broadcasting`). -- After broadcasting, ``T`` must be equivalent to a tuple ``U = (u1, ..., uM, ..., uN)`` containing only one-dimensional integer arrays having shape ``S2``. +- After broadcasting, ``T`` must be equivalent to a tuple ``U = (u1, u2, ..., uN)`` containing only one-dimensional integer arrays having shape ``S2``. -- Let ``v_i`` be the tuple formed by the integer indices ``u1[i], u2[i], ..., uM[i], ..., uN[i]``. When applying the indexing tuple ``U`` to ``A``, the resulting array must be a one-dimensional array containing each element ``A[v_i]`` for ``i`` on the half-open interval ``[0, m)``. +- Let ``v_i`` be the tuple formed by the integer indices ``u1[i], u2[i], ..., uN[i]``. When applying the indexing tuple ``U`` to ``A``, the resulting array must be a one-dimensional array having shape ``(m,)`` and containing each element ``A[v_i]`` for ``i`` on the half-open interval ``[0, m)``. .. note:: This specification does not currently address indexing tuples which combine slices and integer arrays. Behavior for such indexing tuples is left unspecified and thus implementation-defined. This may be revisited in a future revision of this standard. From 9395d2cdee6019aebb5299ad50c909c87718aa3a Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 17 Feb 2025 05:11:39 -0800 Subject: [PATCH 05/31] docs: remove note --- spec/draft/API_specification/indexing.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 95488ad53..b295f24bc 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -201,9 +201,6 @@ An array must support indexing a one-dimensional array by a one-dimensional inte An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and one-dimensional integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, s2, ..., sN)`` and ``T`` be a tuple ``(t1, t2, ..., tN)`` having length ``N`` and containing only valid integer and one-dimensional integer array indices. -.. note:: - This specification does not require bounds checking. The behavior for out-of-bounds integer indices is left unspecified. - - Providing an integer tuple element ``tk`` having value ``k`` must be equivalent to providing a zero-dimensional integer array ``K`` containing ``k``. - If ``T`` consists of only integers and zero-dimensional integer arrays, the result must be equivalent to indexing multiple axes using integer indices (see :ref:`indexing-multi-axis`). From f1d7c9267338c6eec471e5ea4d1124ac80db1d51 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 17 Feb 2025 05:12:46 -0800 Subject: [PATCH 06/31] docs: update copy --- spec/draft/API_specification/indexing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index b295f24bc..3f2f007d3 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -197,7 +197,7 @@ An array must support indexing a one-dimensional array by a one-dimensional inte - Providing duplicate integer index elements in ``J`` must result in the duplication of the corresponding elements of ``A`` in the resulting array. -- The result of providing a valid integer index for each element in ``J`` must be an array having shape ``S3 = (k,)``. +- The result of providing a valid integer index for each element in ``J`` must be an array having shape ``(k,)``. An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and one-dimensional integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, s2, ..., sN)`` and ``T`` be a tuple ``(t1, t2, ..., tN)`` having length ``N`` and containing only valid integer and one-dimensional integer array indices. From 6a2820a9cffef8c5dd10e5ba764a7c87eb932a0b Mon Sep 17 00:00:00 2001 From: Athan Date: Mon, 17 Feb 2025 05:15:21 -0800 Subject: [PATCH 07/31] docs: fix typo Co-authored-by: Evgeni Burovski --- spec/draft/API_specification/indexing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 3f2f007d3..9716dbf51 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -182,7 +182,7 @@ Multi-dimensional arrays must extend the concept of single-axis indexing to mult Integer Array Indexing ---------------------- -An array must support indexing a one-dimensional array by a one-dimensional integer array according to the following rules. Let ``A`` be a one-dimensional array with shape ``S1 = (n,)``, and let ``J`` be a one-dimensional integer array with ``S2 = (k,)``. +An array must support indexing a one-dimensional array by a one-dimensional integer array according to the following rules. Let ``A`` be a one-dimensional array with shape ``S1 = (n,)``, and let ``J`` be a one-dimensional integer array with shape ``S2 = (k,)``. - Each integer index element in ``J`` must satisfy the rules stated above for indexing a single-axis (see :ref:`indexing-single-axis`). Namely, From 364587316d485a0b17d208f300a4b054b979ea46 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 17 Feb 2025 11:55:33 -0800 Subject: [PATCH 08/31] docs: update copy --- spec/draft/API_specification/indexing.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 9716dbf51..53fa45662 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -182,7 +182,7 @@ Multi-dimensional arrays must extend the concept of single-axis indexing to mult Integer Array Indexing ---------------------- -An array must support indexing a one-dimensional array by a one-dimensional integer array according to the following rules. Let ``A`` be a one-dimensional array with shape ``S1 = (n,)``, and let ``J`` be a one-dimensional integer array with shape ``S2 = (k,)``. +An array must support indexing a one-dimensional array by an integer array according to the following rules. Let ``A`` be a one-dimensional array with shape ``(n,)``, and let ``J`` be an integer array. - Each integer index element in ``J`` must satisfy the rules stated above for indexing a single-axis (see :ref:`indexing-single-axis`). Namely, @@ -197,7 +197,9 @@ An array must support indexing a one-dimensional array by a one-dimensional inte - Providing duplicate integer index elements in ``J`` must result in the duplication of the corresponding elements of ``A`` in the resulting array. -- The result of providing a valid integer index for each element in ``J`` must be an array having shape ``(k,)``. +- If ``J`` is a zero-dimensional array containing an integer index ``k``, the result must be equivalent to providing a single-axis integer index ``k`` (i.e., if ``J`` is a zero-dimensional array, ``A[J]`` must equal ``A[k]``; see :ref:`indexing-single-axis). + +- If ``J`` is a one-dimensional array with shape ``(k,)``, the result must be a one-dimensional array ``B``having shape ``(k,)``. Each element of ``B`` must follow the relation ``B[i] = A[J[i]]``. An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and one-dimensional integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, s2, ..., sN)`` and ``T`` be a tuple ``(t1, t2, ..., tN)`` having length ``N`` and containing only valid integer and one-dimensional integer array indices. From 134d11c62f5a95a62f7369d8d5c7f57944f10373 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 17 Feb 2025 12:06:58 -0800 Subject: [PATCH 09/31] docs: update copy --- spec/draft/API_specification/indexing.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 53fa45662..175dccbbc 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -201,17 +201,17 @@ An array must support indexing a one-dimensional array by an integer array accor - If ``J`` is a one-dimensional array with shape ``(k,)``, the result must be a one-dimensional array ``B``having shape ``(k,)``. Each element of ``B`` must follow the relation ``B[i] = A[J[i]]``. -An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and one-dimensional integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, s2, ..., sN)`` and ``T`` be a tuple ``(t1, t2, ..., tN)`` having length ``N`` and containing only valid integer and one-dimensional integer array indices. +An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, s2, ..., sN)`` and ``T`` be a tuple ``(I, J, ..., K)`` having length ``N`` and containing only valid integer and integer array indices. -- Providing an integer tuple element ``tk`` having value ``k`` must be equivalent to providing a zero-dimensional integer array ``K`` containing ``k``. +- Providing an integer tuple element ``K`` having value ``k`` must be equivalent to providing a zero-dimensional integer array ``K`` containing ``k``. -- If ``T`` consists of only integers and zero-dimensional integer arrays, the result must be equivalent to indexing multiple axes using integer indices (see :ref:`indexing-multi-axis`). +- If ``T`` consists of only integers and zero-dimensional integer arrays, the result must be equivalent to indexing multiple axes using integer indices. For example, if ``A`` is a two-dimensional array, ``T`` is the tuple ``(i, J)``, ``i`` is a valid integer index, and ``J`` is a zero-dimensional array containing a valid integer index ``j``, the result of ``A[T]`` must be equivalent to ``A[(i,j)]`` (see :ref:`indexing-multi-axis`). -- When ``T`` contains a one-dimensional integer array ``J`` having shape ``S2 = (m,)``, where ``m`` is greater than or equal to the number of elements in any other one-dimensional integer array in ``T``, each element of ``T`` must be broadcast to the same shape as ``J``. +- If ``T`` consists of only integers and integer arrays, with at least one of those integer arrays being a one-dimensional integer array ``J`` having shape ``S2 = (m,)``, where ``m`` is greater than or equal to the number of elements in any other integer array in ``T``, each element of ``T`` must be broadcast to the same shape as ``J``. - An ``IndexError`` exception must be raised if any element of ``T`` is not broadcast-compatible with ``J`` (see :ref:`broadcasting`). -- After broadcasting, ``T`` must be equivalent to a tuple ``U = (u1, u2, ..., uN)`` containing only one-dimensional integer arrays having shape ``S2``. +- After broadcasting, ``T`` must be equivalent to a tuple ``U = (u1, u2, ..., uN)`` containing only integer arrays having shape ``S2``. - Let ``v_i`` be the tuple formed by the integer indices ``u1[i], u2[i], ..., uN[i]``. When applying the indexing tuple ``U`` to ``A``, the resulting array must be a one-dimensional array having shape ``(m,)`` and containing each element ``A[v_i]`` for ``i`` on the half-open interval ``[0, m)``. From e30e06f526a7583ffcd600fb9ac20cb82665ae15 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 17 Feb 2025 12:17:22 -0800 Subject: [PATCH 10/31] docs: update copy --- spec/draft/API_specification/indexing.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 175dccbbc..559d3e497 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -182,7 +182,10 @@ Multi-dimensional arrays must extend the concept of single-axis indexing to mult Integer Array Indexing ---------------------- -An array must support indexing a one-dimensional array by an integer array according to the following rules. Let ``A`` be a one-dimensional array with shape ``(n,)``, and let ``J`` be an integer array. +An array must support indexing a one-dimensional array by an integer array (or an equivalent sequence) according to the following rules. Let ``A`` be a one-dimensional array with shape ``(n,)``, and let ``J`` be an integer array (or an equivalent sequence). + +.. note:: + An **equivalent sequence** is defined as a sequence such as a a list or tuple which, when provided as an argument to ``asarray``, results in an integer array. - Each integer index element in ``J`` must satisfy the rules stated above for indexing a single-axis (see :ref:`indexing-single-axis`). Namely, @@ -199,15 +202,15 @@ An array must support indexing a one-dimensional array by an integer array accor - If ``J`` is a zero-dimensional array containing an integer index ``k``, the result must be equivalent to providing a single-axis integer index ``k`` (i.e., if ``J`` is a zero-dimensional array, ``A[J]`` must equal ``A[k]``; see :ref:`indexing-single-axis). -- If ``J`` is a one-dimensional array with shape ``(k,)``, the result must be a one-dimensional array ``B``having shape ``(k,)``. Each element of ``B`` must follow the relation ``B[i] = A[J[i]]``. +- If ``J`` is a one-dimensional array (or an equivalent sequence) with shape ``(k,)``, the result must be a one-dimensional array ``B``having shape ``(k,)``. Each element of ``B`` must follow the relation ``B[i] = A[J[i]]``. -An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, s2, ..., sN)`` and ``T`` be a tuple ``(I, J, ..., K)`` having length ``N`` and containing only valid integer and integer array indices. +An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and integer arrays (or equivalent sequences) according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, s2, ..., sN)`` and ``T`` be a tuple ``(I, J, ..., K)`` having length ``N`` and containing only valid integer and integer array (or an equivalent sequence) indices. - Providing an integer tuple element ``K`` having value ``k`` must be equivalent to providing a zero-dimensional integer array ``K`` containing ``k``. - If ``T`` consists of only integers and zero-dimensional integer arrays, the result must be equivalent to indexing multiple axes using integer indices. For example, if ``A`` is a two-dimensional array, ``T`` is the tuple ``(i, J)``, ``i`` is a valid integer index, and ``J`` is a zero-dimensional array containing a valid integer index ``j``, the result of ``A[T]`` must be equivalent to ``A[(i,j)]`` (see :ref:`indexing-multi-axis`). -- If ``T`` consists of only integers and integer arrays, with at least one of those integer arrays being a one-dimensional integer array ``J`` having shape ``S2 = (m,)``, where ``m`` is greater than or equal to the number of elements in any other integer array in ``T``, each element of ``T`` must be broadcast to the same shape as ``J``. +- If ``T`` consists of only integers and integer arrays (or equivalent sequences), with at least one of those integer arrays being a one-dimensional integer array (or an equivalent sequence) ``J`` having shape ``S2 = (m,)``, where ``m`` is greater than or equal to the number of elements in any other integer array (or an equivalent sequence) in ``T``, each element of ``T`` must be broadcast to the same shape as ``J``. - An ``IndexError`` exception must be raised if any element of ``T`` is not broadcast-compatible with ``J`` (see :ref:`broadcasting`). From a4dd7cb8cee925a23aa1c60eebef5e62868b2b9e Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 17 Feb 2025 12:22:22 -0800 Subject: [PATCH 11/31] docs: add note --- spec/draft/API_specification/indexing.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 559d3e497..1737dfe23 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -204,6 +204,9 @@ An array must support indexing a one-dimensional array by an integer array (or a - If ``J`` is a one-dimensional array (or an equivalent sequence) with shape ``(k,)``, the result must be a one-dimensional array ``B``having shape ``(k,)``. Each element of ``B`` must follow the relation ``B[i] = A[J[i]]``. +.. note:: + If ``J`` is an array having more than one dimension, behavior is left unspecified and thus implementation-defined. This may be revisited in a future revision of this standard. + An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and integer arrays (or equivalent sequences) according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, s2, ..., sN)`` and ``T`` be a tuple ``(I, J, ..., K)`` having length ``N`` and containing only valid integer and integer array (or an equivalent sequence) indices. - Providing an integer tuple element ``K`` having value ``k`` must be equivalent to providing a zero-dimensional integer array ``K`` containing ``k``. From 49a54bbdf6a39ee84ba622493ac1401b7e171d28 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 17 Feb 2025 12:23:27 -0800 Subject: [PATCH 12/31] docs: update copy --- spec/draft/API_specification/indexing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 1737dfe23..c3a6090cc 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -207,7 +207,7 @@ An array must support indexing a one-dimensional array by an integer array (or a .. note:: If ``J`` is an array having more than one dimension, behavior is left unspecified and thus implementation-defined. This may be revisited in a future revision of this standard. -An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and integer arrays (or equivalent sequences) according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, s2, ..., sN)`` and ``T`` be a tuple ``(I, J, ..., K)`` having length ``N`` and containing only valid integer and integer array (or an equivalent sequence) indices. +An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and integer arrays (or equivalent sequences) according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, s2, ..., sN)`` and ``T`` be a tuple ``(I, J, ..., K)`` having length ``N`` and containing only valid integer and integer array (or equivalent sequence) indices. - Providing an integer tuple element ``K`` having value ``k`` must be equivalent to providing a zero-dimensional integer array ``K`` containing ``k``. From 8eb307a5f59f34752c385dd9c6e514040cc65a29 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 17 Feb 2025 12:25:08 -0800 Subject: [PATCH 13/31] docs: update copy --- spec/draft/API_specification/indexing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index c3a6090cc..932ae543e 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -207,7 +207,7 @@ An array must support indexing a one-dimensional array by an integer array (or a .. note:: If ``J`` is an array having more than one dimension, behavior is left unspecified and thus implementation-defined. This may be revisited in a future revision of this standard. -An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and integer arrays (or equivalent sequences) according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, s2, ..., sN)`` and ``T`` be a tuple ``(I, J, ..., K)`` having length ``N`` and containing only valid integer and integer array (or equivalent sequence) indices. +An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and integer arrays (or equivalent sequences) according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, s2, ..., sN)`` and ``T`` be a tuple ``(I, J, ..., K)`` having length ``N`` and containing only valid integers and integer arrays (or equivalent sequences). - Providing an integer tuple element ``K`` having value ``k`` must be equivalent to providing a zero-dimensional integer array ``K`` containing ``k``. From 6421f24a7f8bac818fbf6dd02f15f80dd55e1bb4 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 17 Feb 2025 12:28:50 -0800 Subject: [PATCH 14/31] docs: update copy --- spec/draft/API_specification/indexing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 932ae543e..9739f0523 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -219,7 +219,7 @@ An array must support indexing an array having more than one dimension by an ind - After broadcasting, ``T`` must be equivalent to a tuple ``U = (u1, u2, ..., uN)`` containing only integer arrays having shape ``S2``. -- Let ``v_i`` be the tuple formed by the integer indices ``u1[i], u2[i], ..., uN[i]``. When applying the indexing tuple ``U`` to ``A``, the resulting array must be a one-dimensional array having shape ``(m,)`` and containing each element ``A[v_i]`` for ``i`` on the half-open interval ``[0, m)``. +- Let ``v_i`` be the tuple formed by the integer indices ``u1[i], u2[i], ..., uN[i]``. When applying the indexing tuple ``U`` to ``A``, the result must be an array having shape ``S2`` and contain each element ``A[v_i]``. .. note:: This specification does not currently address indexing tuples which combine slices and integer arrays. Behavior for such indexing tuples is left unspecified and thus implementation-defined. This may be revisited in a future revision of this standard. From e650e5a7b19884e647b7da9c385da832ea1a7579 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 17 Feb 2025 12:29:40 -0800 Subject: [PATCH 15/31] docs: add note --- spec/draft/API_specification/indexing.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 9739f0523..0b235961c 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -224,6 +224,9 @@ An array must support indexing an array having more than one dimension by an ind .. note:: This specification does not currently address indexing tuples which combine slices and integer arrays. Behavior for such indexing tuples is left unspecified and thus implementation-defined. This may be revisited in a future revision of this standard. +.. note:: + If an indexing tuple contains an integer array having more than one dimension, behavior is left unspecified and thus implementation-defined. This may be revisited in a future revision of this standard. + Boolean Array Indexing ---------------------- From c4c9f00f8cb8781cb77c9c475a8aef8854d54bed Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 17 Feb 2025 12:33:39 -0800 Subject: [PATCH 16/31] docs: fix symbol --- spec/draft/API_specification/indexing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 0b235961c..e89625d25 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -200,7 +200,7 @@ An array must support indexing a one-dimensional array by an integer array (or a - Providing duplicate integer index elements in ``J`` must result in the duplication of the corresponding elements of ``A`` in the resulting array. -- If ``J`` is a zero-dimensional array containing an integer index ``k``, the result must be equivalent to providing a single-axis integer index ``k`` (i.e., if ``J`` is a zero-dimensional array, ``A[J]`` must equal ``A[k]``; see :ref:`indexing-single-axis). +- If ``J`` is a zero-dimensional array containing an integer index ``k``, the result must be equivalent to providing a single-axis integer index ``k`` (i.e., if ``J`` is a zero-dimensional array, ``A[J]`` must equal ``A[k]``; see :ref:`indexing-single-axis`). - If ``J`` is a one-dimensional array (or an equivalent sequence) with shape ``(k,)``, the result must be a one-dimensional array ``B``having shape ``(k,)``. Each element of ``B`` must follow the relation ``B[i] = A[J[i]]``. From 60acb1ed96358d2de947ca5db5169e355dfc7494 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 17 Feb 2025 12:43:25 -0800 Subject: [PATCH 17/31] docs: fix typo --- spec/draft/API_specification/indexing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index e89625d25..e720f83f1 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -185,7 +185,7 @@ Integer Array Indexing An array must support indexing a one-dimensional array by an integer array (or an equivalent sequence) according to the following rules. Let ``A`` be a one-dimensional array with shape ``(n,)``, and let ``J`` be an integer array (or an equivalent sequence). .. note:: - An **equivalent sequence** is defined as a sequence such as a a list or tuple which, when provided as an argument to ``asarray``, results in an integer array. + An **equivalent sequence** is defined as a sequence such as a list or tuple which, when provided as an argument to ``asarray``, results in an integer array. - Each integer index element in ``J`` must satisfy the rules stated above for indexing a single-axis (see :ref:`indexing-single-axis`). Namely, From d3c5a2e6bd97f23f9ffe40cf52d1df02d4bbf43b Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 19 Feb 2025 20:48:32 -0800 Subject: [PATCH 18/31] docs: remove copy regarding equivalent sequences --- spec/draft/API_specification/indexing.rst | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index e720f83f1..14a3def64 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -182,10 +182,7 @@ Multi-dimensional arrays must extend the concept of single-axis indexing to mult Integer Array Indexing ---------------------- -An array must support indexing a one-dimensional array by an integer array (or an equivalent sequence) according to the following rules. Let ``A`` be a one-dimensional array with shape ``(n,)``, and let ``J`` be an integer array (or an equivalent sequence). - -.. note:: - An **equivalent sequence** is defined as a sequence such as a list or tuple which, when provided as an argument to ``asarray``, results in an integer array. +An array must support indexing a one-dimensional array by an integer array according to the following rules. Let ``A`` be a one-dimensional array with shape ``(n,)``, and let ``J`` be an integer array. - Each integer index element in ``J`` must satisfy the rules stated above for indexing a single-axis (see :ref:`indexing-single-axis`). Namely, @@ -202,18 +199,18 @@ An array must support indexing a one-dimensional array by an integer array (or a - If ``J`` is a zero-dimensional array containing an integer index ``k``, the result must be equivalent to providing a single-axis integer index ``k`` (i.e., if ``J`` is a zero-dimensional array, ``A[J]`` must equal ``A[k]``; see :ref:`indexing-single-axis`). -- If ``J`` is a one-dimensional array (or an equivalent sequence) with shape ``(k,)``, the result must be a one-dimensional array ``B``having shape ``(k,)``. Each element of ``B`` must follow the relation ``B[i] = A[J[i]]``. +- If ``J`` is a one-dimensional array with shape ``(k,)``, the result must be a one-dimensional array ``B``having shape ``(k,)``. Each element of ``B`` must follow the relation ``B[i] = A[J[i]]``. .. note:: If ``J`` is an array having more than one dimension, behavior is left unspecified and thus implementation-defined. This may be revisited in a future revision of this standard. -An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and integer arrays (or equivalent sequences) according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, s2, ..., sN)`` and ``T`` be a tuple ``(I, J, ..., K)`` having length ``N`` and containing only valid integers and integer arrays (or equivalent sequences). +An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, s2, ..., sN)`` and ``T`` be a tuple ``(I, J, ..., K)`` having length ``N`` and containing only valid integers and integer arrays. - Providing an integer tuple element ``K`` having value ``k`` must be equivalent to providing a zero-dimensional integer array ``K`` containing ``k``. - If ``T`` consists of only integers and zero-dimensional integer arrays, the result must be equivalent to indexing multiple axes using integer indices. For example, if ``A`` is a two-dimensional array, ``T`` is the tuple ``(i, J)``, ``i`` is a valid integer index, and ``J`` is a zero-dimensional array containing a valid integer index ``j``, the result of ``A[T]`` must be equivalent to ``A[(i,j)]`` (see :ref:`indexing-multi-axis`). -- If ``T`` consists of only integers and integer arrays (or equivalent sequences), with at least one of those integer arrays being a one-dimensional integer array (or an equivalent sequence) ``J`` having shape ``S2 = (m,)``, where ``m`` is greater than or equal to the number of elements in any other integer array (or an equivalent sequence) in ``T``, each element of ``T`` must be broadcast to the same shape as ``J``. +- If ``T`` consists of only integers and integer arrays, with at least one of those integer arrays being a one-dimensional integer array ``J`` having shape ``S2 = (m,)``, where ``m`` is greater than or equal to the number of elements in any other integer array in ``T``, each element of ``T`` must be broadcast to the same shape as ``J``. - An ``IndexError`` exception must be raised if any element of ``T`` is not broadcast-compatible with ``J`` (see :ref:`broadcasting`). From 19f1f5d06febd56db9993870b2fa164e9bd3d9c0 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 19 Feb 2025 20:52:20 -0800 Subject: [PATCH 19/31] docs: update notation --- spec/draft/API_specification/indexing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 14a3def64..eec8ecd50 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -204,7 +204,7 @@ An array must support indexing a one-dimensional array by an integer array accor .. note:: If ``J`` is an array having more than one dimension, behavior is left unspecified and thus implementation-defined. This may be revisited in a future revision of this standard. -An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, s2, ..., sN)`` and ``T`` be a tuple ``(I, J, ..., K)`` having length ``N`` and containing only valid integers and integer arrays. +An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, s2, ..., sN)`` and ``T`` be a tuple ``(t0, t1, ..., tN)`` having length ``N`` and containing only valid integers and integer arrays. - Providing an integer tuple element ``K`` having value ``k`` must be equivalent to providing a zero-dimensional integer array ``K`` containing ``k``. From a4b603375e496b7d61df60d84f17a65bac34ec4e Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 19 Feb 2025 20:58:24 -0800 Subject: [PATCH 20/31] docs: remove explicit exception prescription --- spec/draft/API_specification/indexing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index eec8ecd50..940100c30 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -212,7 +212,7 @@ An array must support indexing an array having more than one dimension by an ind - If ``T`` consists of only integers and integer arrays, with at least one of those integer arrays being a one-dimensional integer array ``J`` having shape ``S2 = (m,)``, where ``m`` is greater than or equal to the number of elements in any other integer array in ``T``, each element of ``T`` must be broadcast to the same shape as ``J``. -- An ``IndexError`` exception must be raised if any element of ``T`` is not broadcast-compatible with ``J`` (see :ref:`broadcasting`). +- An exception must be raised if any element of ``T`` is not broadcast-compatible with ``J`` (see :ref:`broadcasting`). - After broadcasting, ``T`` must be equivalent to a tuple ``U = (u1, u2, ..., uN)`` containing only integer arrays having shape ``S2``. From 304c4462ea6cfb3490a2e5bb8cb0a9e421f5e8d4 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 20 Feb 2025 01:00:45 -0800 Subject: [PATCH 21/31] docs: revise indexing guidance --- spec/draft/API_specification/indexing.rst | 37 ++++++----------------- 1 file changed, 9 insertions(+), 28 deletions(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 940100c30..267b241ac 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -182,48 +182,29 @@ Multi-dimensional arrays must extend the concept of single-axis indexing to mult Integer Array Indexing ---------------------- -An array must support indexing a one-dimensional array by an integer array according to the following rules. Let ``A`` be a one-dimensional array with shape ``(n,)``, and let ``J`` be an integer array. +An array must support indexing by an indexing tuple which includes only integers and integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1``, ``T`` be a tuple ``(t1, t2, ..., tN)`` having length ``N`` and, for ``N > 0``, containing only integers and integer arrays, and ``tk`` be an individual element of ``T``. -- Each integer index element in ``J`` must satisfy the rules stated above for indexing a single-axis (see :ref:`indexing-single-axis`). Namely, +- Providing a zero-dimensional integer array ``tk`` containing an integer index must be equivalent to providing an integer index having value ``tk[()]``. Conversely, each integer index ``tk`` must be equivalent to a zero-dimensional integer array containing the same value and be treated as such in all contexts, including shape inference and broadcasting. Accordingly, if ``T`` consists of only integers and zero-dimensional integer arrays, the result must be equivalent to indexing multiple axes using integer indices. For example, if ``A`` is a two-dimensional array, ``T`` is the tuple ``(i, J)``, ``i`` is a valid integer index, and ``J`` is a zero-dimensional array containing a valid integer index ``j``, the result of ``A[T]`` must be equivalent to ``A[(i,j)]`` (see :ref:`indexing-multi-axis`). - - Nonnegative indices must start at ``0`` (i.e., zero-based indexing). - - **Valid** nonnegative indices must reside on the half-open interval ``[0, n)``. - - Negative indices must count backward from the last index, starting from ``-1`` (i.e., negative-one-based indexing, where ``-1`` refers to the last index). - - **Valid** negative indices must reside on the closed interval ``[-n, -1]``. - - A negative index ``j`` is related to a zero-based nonnegative index ``i`` via ``i = n+j``. +- If ``tk`` is an integer array, each element in ``tk`` must independently satisfy the rules stated above for indexing a single-axis with an integer index (see :ref:`indexing-single-axis`). .. note:: This specification does not require bounds checking. The behavior for out-of-bounds integer indices is left unspecified. -- Providing duplicate integer index elements in ``J`` must result in the duplication of the corresponding elements of ``A`` in the resulting array. +- If ``tk`` is an integer array containing duplicate valid integer indices, the result must include the corresponding elements of ``A`` with the same duplication. -- If ``J`` is a zero-dimensional array containing an integer index ``k``, the result must be equivalent to providing a single-axis integer index ``k`` (i.e., if ``J`` is a zero-dimensional array, ``A[J]`` must equal ``A[k]``; see :ref:`indexing-single-axis`). - -- If ``J`` is a one-dimensional array with shape ``(k,)``, the result must be a one-dimensional array ``B``having shape ``(k,)``. Each element of ``B`` must follow the relation ``B[i] = A[J[i]]``. - -.. note:: - If ``J`` is an array having more than one dimension, behavior is left unspecified and thus implementation-defined. This may be revisited in a future revision of this standard. - -An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, s2, ..., sN)`` and ``T`` be a tuple ``(t0, t1, ..., tN)`` having length ``N`` and containing only valid integers and integer arrays. - -- Providing an integer tuple element ``K`` having value ``k`` must be equivalent to providing a zero-dimensional integer array ``K`` containing ``k``. - -- If ``T`` consists of only integers and zero-dimensional integer arrays, the result must be equivalent to indexing multiple axes using integer indices. For example, if ``A`` is a two-dimensional array, ``T`` is the tuple ``(i, J)``, ``i`` is a valid integer index, and ``J`` is a zero-dimensional array containing a valid integer index ``j``, the result of ``A[T]`` must be equivalent to ``A[(i,j)]`` (see :ref:`indexing-multi-axis`). - -- If ``T`` consists of only integers and integer arrays, with at least one of those integer arrays being a one-dimensional integer array ``J`` having shape ``S2 = (m,)``, where ``m`` is greater than or equal to the number of elements in any other integer array in ``T``, each element of ``T`` must be broadcast to the same shape as ``J``. + .. note:: + Given the assignment operation ``x[T] = y[...]``, if ``T`` contains an integer array having duplicate indices, the order in which elements in ``y`` are assigned to the corresponding element(s) in ``x`` is unspecified and thus implementation-defined. -- An exception must be raised if any element of ``T`` is not broadcast-compatible with ``J`` (see :ref:`broadcasting`). +- If ``T`` consists of at least one of non-zero-dimensional integer array, all elements of ``T`` must be broadcast against each other to determine a common shape ``S2 = (s1, s2, ..., sN)`` according to standard broadcasting rules (see :ref:`broadcasting`). If one or more elements in ``T`` are not broadcast-compatible with the others, an exception must be raised. -- After broadcasting, ``T`` must be equivalent to a tuple ``U = (u1, u2, ..., uN)`` containing only integer arrays having shape ``S2``. +- After broadcasting elements of ``T`` to a common shape ``S2``, the resulting tuple ``U = (u1, u2, ..., uN)`` must only contain integer arrays having shape ``S2``. -- Let ``v_i`` be the tuple formed by the integer indices ``u1[i], u2[i], ..., uN[i]``. When applying the indexing tuple ``U`` to ``A``, the result must be an array having shape ``S2`` and contain each element ``A[v_i]``. +- Each element in ``U`` must specify a multi-dimensional index ``v_i = (u1[i], u2[i], ..., uN[i])``, where ``i`` ranges over ``S2``. The result of ``A[U]`` must be constructed by gathering elements from ``A`` at each coordinate tuple ``v_i``. For example, let ``A`` have shape ``(4,4)`` and ``U`` contain integer arrays equivalent to ``([0,1], [2,3])``, with ``u1 = [0,1]`` and ``u2 = [2,3]``. The resulting coordinate tuples must be ``(0,2)`` and ``(1,3)``, respectively, and the resulting array must have shape ``(2,)`` and contain elements ``A[(0,2)]`` and ``A[(1,3)]``. .. note:: This specification does not currently address indexing tuples which combine slices and integer arrays. Behavior for such indexing tuples is left unspecified and thus implementation-defined. This may be revisited in a future revision of this standard. -.. note:: - If an indexing tuple contains an integer array having more than one dimension, behavior is left unspecified and thus implementation-defined. This may be revisited in a future revision of this standard. - Boolean Array Indexing ---------------------- From a1e24cbf577e8345ae2196ff5300ad9645701ab6 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 20 Feb 2025 01:02:58 -0800 Subject: [PATCH 22/31] docs: split into multiple sentences --- spec/draft/API_specification/indexing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 267b241ac..def0c3ff1 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -182,7 +182,7 @@ Multi-dimensional arrays must extend the concept of single-axis indexing to mult Integer Array Indexing ---------------------- -An array must support indexing by an indexing tuple which includes only integers and integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1``, ``T`` be a tuple ``(t1, t2, ..., tN)`` having length ``N`` and, for ``N > 0``, containing only integers and integer arrays, and ``tk`` be an individual element of ``T``. +An array must support indexing by an indexing tuple which includes only integers and integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1``. Let ``T`` be a tuple ``(t1, t2, ..., tN)`` having length ``N`` and, for ``N > 0``, containing only integers and integer arrays. Let ``tk`` be an individual element of ``T``. - Providing a zero-dimensional integer array ``tk`` containing an integer index must be equivalent to providing an integer index having value ``tk[()]``. Conversely, each integer index ``tk`` must be equivalent to a zero-dimensional integer array containing the same value and be treated as such in all contexts, including shape inference and broadcasting. Accordingly, if ``T`` consists of only integers and zero-dimensional integer arrays, the result must be equivalent to indexing multiple axes using integer indices. For example, if ``A`` is a two-dimensional array, ``T`` is the tuple ``(i, J)``, ``i`` is a valid integer index, and ``J`` is a zero-dimensional array containing a valid integer index ``j``, the result of ``A[T]`` must be equivalent to ``A[(i,j)]`` (see :ref:`indexing-multi-axis`). From f51cab17b037c2c09ad5b79787ea75fc2a9f6bf2 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 20 Feb 2025 01:04:19 -0800 Subject: [PATCH 23/31] docs: update copy --- spec/draft/API_specification/indexing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index def0c3ff1..12ce9d90d 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -182,7 +182,7 @@ Multi-dimensional arrays must extend the concept of single-axis indexing to mult Integer Array Indexing ---------------------- -An array must support indexing by an indexing tuple which includes only integers and integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1``. Let ``T`` be a tuple ``(t1, t2, ..., tN)`` having length ``N`` and, for ``N > 0``, containing only integers and integer arrays. Let ``tk`` be an individual element of ``T``. +An array must support indexing by an indexing tuple which contains only integers and integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1``. Let ``T`` be a tuple ``(t1, t2, ..., tN)`` having length ``N``. Let ``tk`` be an individual element of ``T``. - Providing a zero-dimensional integer array ``tk`` containing an integer index must be equivalent to providing an integer index having value ``tk[()]``. Conversely, each integer index ``tk`` must be equivalent to a zero-dimensional integer array containing the same value and be treated as such in all contexts, including shape inference and broadcasting. Accordingly, if ``T`` consists of only integers and zero-dimensional integer arrays, the result must be equivalent to indexing multiple axes using integer indices. For example, if ``A`` is a two-dimensional array, ``T`` is the tuple ``(i, J)``, ``i`` is a valid integer index, and ``J`` is a zero-dimensional array containing a valid integer index ``j``, the result of ``A[T]`` must be equivalent to ``A[(i,j)]`` (see :ref:`indexing-multi-axis`). From 88757eafffb9b69a97738d89c0cc2d82c1bcdb75 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 20 Feb 2025 01:07:39 -0800 Subject: [PATCH 24/31] docs: fix copy --- spec/draft/API_specification/indexing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 12ce9d90d..0cd561c3b 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -196,7 +196,7 @@ An array must support indexing by an indexing tuple which contains only integers .. note:: Given the assignment operation ``x[T] = y[...]``, if ``T`` contains an integer array having duplicate indices, the order in which elements in ``y`` are assigned to the corresponding element(s) in ``x`` is unspecified and thus implementation-defined. -- If ``T`` consists of at least one of non-zero-dimensional integer array, all elements of ``T`` must be broadcast against each other to determine a common shape ``S2 = (s1, s2, ..., sN)`` according to standard broadcasting rules (see :ref:`broadcasting`). If one or more elements in ``T`` are not broadcast-compatible with the others, an exception must be raised. +- If ``T`` contains at least one non-zero-dimensional integer array, all elements of ``T`` must be broadcast against each other to determine a common shape ``S2 = (s1, s2, ..., sN)`` according to standard broadcasting rules (see :ref:`broadcasting`). If one or more elements in ``T`` are not broadcast-compatible with the others, an exception must be raised. - After broadcasting elements of ``T`` to a common shape ``S2``, the resulting tuple ``U = (u1, u2, ..., uN)`` must only contain integer arrays having shape ``S2``. From d39814e78b5df490ca93942099fa80bb70ea6da9 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 20 Feb 2025 01:09:14 -0800 Subject: [PATCH 25/31] docs: update copy --- spec/draft/API_specification/indexing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 0cd561c3b..874a04dba 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -198,7 +198,7 @@ An array must support indexing by an indexing tuple which contains only integers - If ``T`` contains at least one non-zero-dimensional integer array, all elements of ``T`` must be broadcast against each other to determine a common shape ``S2 = (s1, s2, ..., sN)`` according to standard broadcasting rules (see :ref:`broadcasting`). If one or more elements in ``T`` are not broadcast-compatible with the others, an exception must be raised. -- After broadcasting elements of ``T`` to a common shape ``S2``, the resulting tuple ``U = (u1, u2, ..., uN)`` must only contain integer arrays having shape ``S2``. +- After broadcasting elements of ``T`` to a common shape ``S2``, the resulting tuple ``U = (u1, u2, ..., uN)`` must only contain integer arrays having shape ``S2`` (i.e., ``u1 = broadcast_to(t1, S2)``, ``u2 = broadcast_to(t2, S2)``, et cetera). - Each element in ``U`` must specify a multi-dimensional index ``v_i = (u1[i], u2[i], ..., uN[i])``, where ``i`` ranges over ``S2``. The result of ``A[U]`` must be constructed by gathering elements from ``A`` at each coordinate tuple ``v_i``. For example, let ``A`` have shape ``(4,4)`` and ``U`` contain integer arrays equivalent to ``([0,1], [2,3])``, with ``u1 = [0,1]`` and ``u2 = [2,3]``. The resulting coordinate tuples must be ``(0,2)`` and ``(1,3)``, respectively, and the resulting array must have shape ``(2,)`` and contain elements ``A[(0,2)]`` and ``A[(1,3)]``. From 6b93ab97c92728b6b76e098716b9b82326f16cc4 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 20 Feb 2025 01:15:29 -0800 Subject: [PATCH 26/31] docs: add note --- spec/draft/API_specification/indexing.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 874a04dba..8bdf35678 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -202,6 +202,8 @@ An array must support indexing by an indexing tuple which contains only integers - Each element in ``U`` must specify a multi-dimensional index ``v_i = (u1[i], u2[i], ..., uN[i])``, where ``i`` ranges over ``S2``. The result of ``A[U]`` must be constructed by gathering elements from ``A`` at each coordinate tuple ``v_i``. For example, let ``A`` have shape ``(4,4)`` and ``U`` contain integer arrays equivalent to ``([0,1], [2,3])``, with ``u1 = [0,1]`` and ``u2 = [2,3]``. The resulting coordinate tuples must be ``(0,2)`` and ``(1,3)``, respectively, and the resulting array must have shape ``(2,)`` and contain elements ``A[(0,2)]`` and ``A[(1,3)]``. +- The result of ``A[U]`` must be an array having the broadcasted shape ``S2``. + .. note:: This specification does not currently address indexing tuples which combine slices and integer arrays. Behavior for such indexing tuples is left unspecified and thus implementation-defined. This may be revisited in a future revision of this standard. From b3e42887472edcf6f41e562a627140b271bd34cf Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 20 Feb 2025 01:16:21 -0800 Subject: [PATCH 27/31] docs: update copy --- spec/draft/API_specification/indexing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 8bdf35678..0566e2665 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -184,7 +184,7 @@ Integer Array Indexing An array must support indexing by an indexing tuple which contains only integers and integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1``. Let ``T`` be a tuple ``(t1, t2, ..., tN)`` having length ``N``. Let ``tk`` be an individual element of ``T``. -- Providing a zero-dimensional integer array ``tk`` containing an integer index must be equivalent to providing an integer index having value ``tk[()]``. Conversely, each integer index ``tk`` must be equivalent to a zero-dimensional integer array containing the same value and be treated as such in all contexts, including shape inference and broadcasting. Accordingly, if ``T`` consists of only integers and zero-dimensional integer arrays, the result must be equivalent to indexing multiple axes using integer indices. For example, if ``A`` is a two-dimensional array, ``T`` is the tuple ``(i, J)``, ``i`` is a valid integer index, and ``J`` is a zero-dimensional array containing a valid integer index ``j``, the result of ``A[T]`` must be equivalent to ``A[(i,j)]`` (see :ref:`indexing-multi-axis`). +- Providing a zero-dimensional integer array ``tk`` containing an integer index must be equivalent to providing an integer index having the value ``tk[()]``. Conversely, each integer index ``tk`` must be equivalent to a zero-dimensional integer array containing the same value and be treated as such in all contexts, including shape inference and broadcasting. Accordingly, if ``T`` consists of only integers and zero-dimensional integer arrays, the result must be equivalent to indexing multiple axes using integer indices. For example, if ``A`` is a two-dimensional array, ``T`` is the tuple ``(i, J)``, ``i`` is a valid integer index, and ``J`` is a zero-dimensional array containing a valid integer index ``j``, the result of ``A[T]`` must be equivalent to ``A[(i,j)]`` (see :ref:`indexing-multi-axis`). - If ``tk`` is an integer array, each element in ``tk`` must independently satisfy the rules stated above for indexing a single-axis with an integer index (see :ref:`indexing-single-axis`). From a2a786e31d8309214b1fe9a210cc8e039acb5370 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 20 Feb 2025 09:58:58 -0800 Subject: [PATCH 28/31] docs: add note --- spec/draft/API_specification/indexing.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 0566e2665..3a70170ba 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -182,6 +182,9 @@ Multi-dimensional arrays must extend the concept of single-axis indexing to mult Integer Array Indexing ---------------------- +.. note:: + Integer array indexing, as described in this specification, is a reduced subset of "vectorized indexing" semantics, as implemented in libraries such as NumPy. In vectorized indexing, integers and integer arrays are broadcasted to integer arrays having a common shape before being "zipped" together to form a list of index coordinates. This form of indexing diverges from the multi-axis indexing semantics described above (see :ref:`indexing-multi-axis`) where each element of an indexing tuple comprised of integers and slices independently indexes a particular axis. This latter form of indexing is commonly referred to as "orthogonal indexing" and is the default form of indexing outside of Python in languages such as Julia and MATLAB. + An array must support indexing by an indexing tuple which contains only integers and integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1``. Let ``T`` be a tuple ``(t1, t2, ..., tN)`` having length ``N``. Let ``tk`` be an individual element of ``T``. - Providing a zero-dimensional integer array ``tk`` containing an integer index must be equivalent to providing an integer index having the value ``tk[()]``. Conversely, each integer index ``tk`` must be equivalent to a zero-dimensional integer array containing the same value and be treated as such in all contexts, including shape inference and broadcasting. Accordingly, if ``T`` consists of only integers and zero-dimensional integer arrays, the result must be equivalent to indexing multiple axes using integer indices. For example, if ``A`` is a two-dimensional array, ``T`` is the tuple ``(i, J)``, ``i`` is a valid integer index, and ``J`` is a zero-dimensional array containing a valid integer index ``j``, the result of ``A[T]`` must be equivalent to ``A[(i,j)]`` (see :ref:`indexing-multi-axis`). From 911ee68657c20f77e50d56e43d4efe9542d213b0 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 20 Feb 2025 11:05:55 -0800 Subject: [PATCH 29/31] docs: update copy --- spec/draft/API_specification/indexing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index 3a70170ba..adf6115d7 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -187,7 +187,7 @@ Integer Array Indexing An array must support indexing by an indexing tuple which contains only integers and integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1``. Let ``T`` be a tuple ``(t1, t2, ..., tN)`` having length ``N``. Let ``tk`` be an individual element of ``T``. -- Providing a zero-dimensional integer array ``tk`` containing an integer index must be equivalent to providing an integer index having the value ``tk[()]``. Conversely, each integer index ``tk`` must be equivalent to a zero-dimensional integer array containing the same value and be treated as such in all contexts, including shape inference and broadcasting. Accordingly, if ``T`` consists of only integers and zero-dimensional integer arrays, the result must be equivalent to indexing multiple axes using integer indices. For example, if ``A`` is a two-dimensional array, ``T`` is the tuple ``(i, J)``, ``i`` is a valid integer index, and ``J`` is a zero-dimensional array containing a valid integer index ``j``, the result of ``A[T]`` must be equivalent to ``A[(i,j)]`` (see :ref:`indexing-multi-axis`). +- Providing a zero-dimensional integer array ``tk`` containing an integer index must be equivalent to providing an integer index having the value ``tk[()]``. Conversely, each integer index ``tk`` must be equivalent to a zero-dimensional integer array containing the same value and be treated as such, including shape inference and broadcasting. Accordingly, if ``T`` consists of only integers and zero-dimensional integer arrays, the result must be equivalent to indexing multiple axes using integer indices. For example, if ``A`` is a two-dimensional array, ``T`` is the tuple ``(i, J)``, ``i`` is a valid integer index, and ``J`` is a zero-dimensional array containing a valid integer index ``j``, the result of ``A[T]`` must be equivalent to ``A[(i,j)]`` (see :ref:`indexing-multi-axis`). - If ``tk`` is an integer array, each element in ``tk`` must independently satisfy the rules stated above for indexing a single-axis with an integer index (see :ref:`indexing-single-axis`). From acb49cdd15d91107b0416a38def61426fe296732 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Fri, 21 Feb 2025 04:15:57 -0800 Subject: [PATCH 30/31] docs: update guidance --- spec/draft/API_specification/indexing.rst | 18 +++++++++++----- src/array_api_stubs/_draft/array_object.py | 24 +++++++++++++--------- 2 files changed, 27 insertions(+), 15 deletions(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index adf6115d7..b818e445f 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -187,6 +187,17 @@ Integer Array Indexing An array must support indexing by an indexing tuple which contains only integers and integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1``. Let ``T`` be a tuple ``(t1, t2, ..., tN)`` having length ``N``. Let ``tk`` be an individual element of ``T``. +.. note:: + This specification does not currently address indexing tuples which combine slices and integer arrays. Behavior for such indexing tuples is left unspecified and thus implementation-defined. This may be revisited in a future revision of this standard. + +.. note:: + This specification does not currently address indexing tuples which include array-like elements, such as Python lists, tuples, and other sequences. Behavior when indexing an array using array-like elements is left unspecified and thus implementation-defined. + +- If ``tk`` is an integer array, ``tk`` should have the default array index data type (see :ref:`data-type-defaults`). + +.. note:: + Conforming implementations of this standard may support integer arrays having other integer data types; however, consumers of this standard should be aware that integer arrays having uncommon array index data types such as ``int8`` and ``uint8`` may not be widely supported as index arrays across conforming array libraries. To dynamically resolve the default array index data type, including for that of the current device context, use the inspection API ``default_dtypes()``. + - Providing a zero-dimensional integer array ``tk`` containing an integer index must be equivalent to providing an integer index having the value ``tk[()]``. Conversely, each integer index ``tk`` must be equivalent to a zero-dimensional integer array containing the same value and be treated as such, including shape inference and broadcasting. Accordingly, if ``T`` consists of only integers and zero-dimensional integer arrays, the result must be equivalent to indexing multiple axes using integer indices. For example, if ``A`` is a two-dimensional array, ``T`` is the tuple ``(i, J)``, ``i`` is a valid integer index, and ``J`` is a zero-dimensional array containing a valid integer index ``j``, the result of ``A[T]`` must be equivalent to ``A[(i,j)]`` (see :ref:`indexing-multi-axis`). - If ``tk`` is an integer array, each element in ``tk`` must independently satisfy the rules stated above for indexing a single-axis with an integer index (see :ref:`indexing-single-axis`). @@ -196,8 +207,8 @@ An array must support indexing by an indexing tuple which contains only integers - If ``tk`` is an integer array containing duplicate valid integer indices, the result must include the corresponding elements of ``A`` with the same duplication. - .. note:: - Given the assignment operation ``x[T] = y[...]``, if ``T`` contains an integer array having duplicate indices, the order in which elements in ``y`` are assigned to the corresponding element(s) in ``x`` is unspecified and thus implementation-defined. + .. + TODO: once setitem semantics are determined, insert the following note: Given the assignment operation ``x[T] = y[...]``, if ``T`` contains an integer array having duplicate indices, the order in which elements in ``y`` are assigned to the corresponding element(s) in ``x`` is unspecified and thus implementation-defined. - If ``T`` contains at least one non-zero-dimensional integer array, all elements of ``T`` must be broadcast against each other to determine a common shape ``S2 = (s1, s2, ..., sN)`` according to standard broadcasting rules (see :ref:`broadcasting`). If one or more elements in ``T`` are not broadcast-compatible with the others, an exception must be raised. @@ -207,9 +218,6 @@ An array must support indexing by an indexing tuple which contains only integers - The result of ``A[U]`` must be an array having the broadcasted shape ``S2``. -.. note:: - This specification does not currently address indexing tuples which combine slices and integer arrays. Behavior for such indexing tuples is left unspecified and thus implementation-defined. This may be revisited in a future revision of this standard. - Boolean Array Indexing ---------------------- diff --git a/src/array_api_stubs/_draft/array_object.py b/src/array_api_stubs/_draft/array_object.py index ee4c2a0e3..55ef60f07 100644 --- a/src/array_api_stubs/_draft/array_object.py +++ b/src/array_api_stubs/_draft/array_object.py @@ -610,7 +610,7 @@ def __getitem__( slice, ellipsis, None, - Tuple[Union[int, slice, ellipsis, None], ...], + Tuple[Union[int, slice, ellipsis, array, None], ...], array, ], /, @@ -618,13 +618,11 @@ def __getitem__( """ Returns ``self[key]``. - See :ref:`indexing` for details on supported indexing semantics. - Parameters ---------- self: array array instance. - key: Union[int, slice, ellipsis, None, Tuple[Union[int, slice, ellipsis, None], ...], array] + key: Union[int, slice, ellipsis, None, Tuple[Union[int, slice, ellipsis, array, None], ...], array] index key. Returns @@ -632,8 +630,11 @@ def __getitem__( out: array an array containing the accessed value(s). The returned array must have the same data type as ``self``. - .. note:: - 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. + Notes + ----- + + - 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. """ @@ -1081,7 +1082,7 @@ def __rshift__(self: array, other: Union[int, array], /) -> array: def __setitem__( self: array, key: Union[ - int, slice, ellipsis, Tuple[Union[int, slice, ellipsis], ...], array + int, slice, ellipsis, Tuple[Union[int, slice, ellipsis, array], ...], array ], value: Union[int, float, complex, bool, array], /, @@ -1089,13 +1090,11 @@ def __setitem__( """ Sets ``self[key]`` to ``value``. - See :ref:`indexing` for details on supported indexing semantics. - Parameters ---------- self: array array instance. - key: Union[int, slice, ellipsis, Tuple[Union[int, slice, ellipsis], ...], array] + key: Union[int, slice, ellipsis, Tuple[Union[int, slice, ellipsis, array], ...], array] index key. value: Union[int, float, complex, bool, array] value(s) to set. Must be compatible with ``self[key]`` (see :ref:`broadcasting`). @@ -1103,6 +1102,11 @@ def __setitem__( Notes ----- + - See :ref:`indexing` for details on supported indexing semantics. + + .. 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. + - Setting array values must not affect the data type of ``self``. - When ``value`` is a Python scalar (i.e., ``int``, ``float``, ``complex``, ``bool``), behavior must follow specification guidance on mixing arrays with Python scalars (see :ref:`type-promotion`). - When ``value`` is an ``array`` of a different data type than ``self``, how values are cast to the data type of ``self`` is implementation defined. From 315ee484d2f2ddc132809b6a2555446e6b2bf15c Mon Sep 17 00:00:00 2001 From: Athan Date: Fri, 21 Feb 2025 15:15:09 -0800 Subject: [PATCH 31/31] fix: update copy Co-authored-by: Evgeni Burovski --- spec/draft/API_specification/indexing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/draft/API_specification/indexing.rst b/spec/draft/API_specification/indexing.rst index b818e445f..058003c51 100644 --- a/spec/draft/API_specification/indexing.rst +++ b/spec/draft/API_specification/indexing.rst @@ -198,7 +198,7 @@ An array must support indexing by an indexing tuple which contains only integers .. note:: Conforming implementations of this standard may support integer arrays having other integer data types; however, consumers of this standard should be aware that integer arrays having uncommon array index data types such as ``int8`` and ``uint8`` may not be widely supported as index arrays across conforming array libraries. To dynamically resolve the default array index data type, including for that of the current device context, use the inspection API ``default_dtypes()``. -- Providing a zero-dimensional integer array ``tk`` containing an integer index must be equivalent to providing an integer index having the value ``tk[()]``. Conversely, each integer index ``tk`` must be equivalent to a zero-dimensional integer array containing the same value and be treated as such, including shape inference and broadcasting. Accordingly, if ``T`` consists of only integers and zero-dimensional integer arrays, the result must be equivalent to indexing multiple axes using integer indices. For example, if ``A`` is a two-dimensional array, ``T`` is the tuple ``(i, J)``, ``i`` is a valid integer index, and ``J`` is a zero-dimensional array containing a valid integer index ``j``, the result of ``A[T]`` must be equivalent to ``A[(i,j)]`` (see :ref:`indexing-multi-axis`). +- Providing a zero-dimensional integer array ``tk`` containing an integer index must be equivalent to providing an integer index having the value ``int(tk)``. Conversely, each integer index ``tk`` must be equivalent to a zero-dimensional integer array containing the same value and be treated as such, including shape inference and broadcasting. Accordingly, if ``T`` consists of only integers and zero-dimensional integer arrays, the result must be equivalent to indexing multiple axes using integer indices. For example, if ``A`` is a two-dimensional array, ``T`` is the tuple ``(i, J)``, ``i`` is a valid integer index, and ``J`` is a zero-dimensional array containing a valid integer index ``j``, the result of ``A[T]`` must be equivalent to ``A[(i,j)]`` (see :ref:`indexing-multi-axis`). - If ``tk`` is an integer array, each element in ``tk`` must independently satisfy the rules stated above for indexing a single-axis with an integer index (see :ref:`indexing-single-axis`).