From 7d119e9140dd2b1a419558ee065ed3b8a57553a3 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 5 Feb 2025 21:15:12 -0800 Subject: [PATCH 1/5] docs: fix allowed data types for the matmul operator (including backport) --- spec/2023.12/API_specification/array_object.rst | 2 +- spec/draft/API_specification/array_object.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/2023.12/API_specification/array_object.rst b/spec/2023.12/API_specification/array_object.rst index f8a586ade..6a41d4016 100644 --- a/spec/2023.12/API_specification/array_object.rst +++ b/spec/2023.12/API_specification/array_object.rst @@ -87,7 +87,7 @@ A conforming implementation of the array API standard must provide and support a - `operator.matmul(x1, x2) `_ - `operator.__matmul__(x1, x2) `_ -The matmul ``@`` operator should be defined for arrays having real-valued data types. +The matmul ``@`` operator should be defined for arrays having numeric data types. Bitwise Operators ~~~~~~~~~~~~~~~~~ diff --git a/spec/draft/API_specification/array_object.rst b/spec/draft/API_specification/array_object.rst index f8a586ade..6a41d4016 100644 --- a/spec/draft/API_specification/array_object.rst +++ b/spec/draft/API_specification/array_object.rst @@ -87,7 +87,7 @@ A conforming implementation of the array API standard must provide and support a - `operator.matmul(x1, x2) `_ - `operator.__matmul__(x1, x2) `_ -The matmul ``@`` operator should be defined for arrays having real-valued data types. +The matmul ``@`` operator should be defined for arrays having numeric data types. Bitwise Operators ~~~~~~~~~~~~~~~~~ From 7c7577707fe1051cdee7707c683ee19b49d73e3d Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 5 Feb 2025 21:35:28 -0800 Subject: [PATCH 2/5] docs: add note concerning libraries which do not support mutation --- spec/draft/API_specification/array_object.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/spec/draft/API_specification/array_object.rst b/spec/draft/API_specification/array_object.rst index 6a41d4016..185c87357 100644 --- a/spec/draft/API_specification/array_object.rst +++ b/spec/draft/API_specification/array_object.rst @@ -169,12 +169,15 @@ For backward compatibility, conforming implementations may support complex numbe In-place Operators ~~~~~~~~~~~~~~~~~~ -A conforming implementation of the array API standard must provide and support an array object supporting the following in-place Python operators. +A conforming implementation of the array API standard must provide and support an array object supporting the following "in-place" Python operators. An in-place operation must not change the data type or shape of the in-place array as a result of :ref:`type-promotion` or :ref:`broadcasting`. An in-place operation must have the same behavior (including special cases) as its respective binary (i.e., two operand, non-assignment) operation. For example, after in-place addition ``x1 += x2``, the modified array ``x1`` must always equal the result of the equivalent binary arithmetic operation ``x1 = x1 + x2``. +.. note:: + This specification refers to the following operators as "in-place" as that is what these operators are called in `Python `. However, conforming array libraries which do not support array mutation may choose to not explicitly implement in-place Python operators. When a library does not implement a method corresponding to an in-place Python operator, Python falls back to the equivalent method for the corresponding binary arithmetic operation. Accordingly, the guidance above requiring equivalent results (i.e., ``x1 += x2`` must always equal ``x1 = x1 + x2``) only applies when the promoted result type (see :ref:`type-promotion`) equals the data type of ``x1``. When this is not true (e.g., if ``x2`` is ``float64`` and ``x1`` is ``float32``), behavior is unspecified and thus implementation-defined. + .. note:: In-place operators must be supported as discussed in :ref:`copyview-mutability`. From 04779fe4557a6d1ef16a3c194e911a5d0ee43fbd Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 17 Feb 2025 01:45:54 -0800 Subject: [PATCH 3/5] docs: update copy --- spec/draft/API_specification/array_object.rst | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/spec/draft/API_specification/array_object.rst b/spec/draft/API_specification/array_object.rst index 185c87357..d100e631f 100644 --- a/spec/draft/API_specification/array_object.rst +++ b/spec/draft/API_specification/array_object.rst @@ -169,17 +169,28 @@ For backward compatibility, conforming implementations may support complex numbe In-place Operators ~~~~~~~~~~~~~~~~~~ +.. note:: + In-place operations must be supported as discussed in :ref:`copyview-mutability`. + A conforming implementation of the array API standard must provide and support an array object supporting the following "in-place" Python operators. +.. note:: + This specification refers to the following operators as "in-place" as that is what these operators are called in `Python `. However, conforming array libraries which do not support array mutation may choose to not explicitly implement in-place Python operators. When a library does not implement a method corresponding to an in-place Python operator, Python falls back to the equivalent method for the corresponding binary arithmetic operation. + An in-place operation must not change the data type or shape of the in-place array as a result of :ref:`type-promotion` or :ref:`broadcasting`. -An in-place operation must have the same behavior (including special cases) as its respective binary (i.e., two operand, non-assignment) operation. For example, after in-place addition ``x1 += x2``, the modified array ``x1`` must always equal the result of the equivalent binary arithmetic operation ``x1 = x1 + x2``. +Let ``x1 += x2`` be a representative in-place operation. If, after applying type promotion (see :ref:`type-promotion`) to in-place operands ``x1`` and ``x2``, the resulting data type is the same as the data type of the array on the left-hand side of the operation (i.e., ``x1``), then an in-place operation must have the same behavior (including special cases) as the respective binary (i.e., two operand, non-assignment) operation. In this case, for the in-place addition ``x1 += x2``, the modified array ``x1`` must always equal the result of the equivalent binary arithmetic operation ``x1[...] = x1 + x2``. -.. note:: - This specification refers to the following operators as "in-place" as that is what these operators are called in `Python `. However, conforming array libraries which do not support array mutation may choose to not explicitly implement in-place Python operators. When a library does not implement a method corresponding to an in-place Python operator, Python falls back to the equivalent method for the corresponding binary arithmetic operation. Accordingly, the guidance above requiring equivalent results (i.e., ``x1 += x2`` must always equal ``x1 = x1 + x2``) only applies when the promoted result type (see :ref:`type-promotion`) equals the data type of ``x1``. When this is not true (e.g., if ``x2`` is ``float64`` and ``x1`` is ``float32``), behavior is unspecified and thus implementation-defined. +If, however, after applying type promotion (see :ref:`type-promotion`) to in-place operands, the resulting data type is not the same as the data type of the array on the left-hand side of the operation, then a conforming implementation may return results which differ from the respective binary operation due to casting behavior and selection of the operation's intermediate precision. .. note:: - In-place operators must be supported as discussed in :ref:`copyview-mutability`. + Let ``x1`` be the operand on the left-hand side and ``x2`` be the operand on the right-hand side of an in-place operation. Consumers of the array API standard are advised of the following considerations when using in-place operations: + + 1. In-place operations do not guarantee in-place mutation. A conforming library may or may not support in-place mutation. + 2. If, after applying broadcasting (see :ref:`broadcasting`) to in-place operands, the resulting shape is not the same as the shape of ``x1``, in-place operators may raise an exception. + 3. If, after applying type promotion (see :ref:`type-promotion`) to in-place operands, the resulting data type is not the same as the data type of ``x1``, the resulting data type may not be the same as ``x1`` and the operation's intermediate precision may be that of ``x1``, even if the promoted data type between ``x1`` and ``x2`` would have higher precision. + + In general, for in-place operations, ensure operands are the same data type and broadcast to the shape of the operand on the left-hand side of the operation in order to maximize portability. Arithmetic Operators """""""""""""""""""" From 6b081a6f87cb5303b60c8f34538feb3ac411c4e9 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 17 Feb 2025 01:49:22 -0800 Subject: [PATCH 4/5] docs: update copy --- spec/draft/API_specification/array_object.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/draft/API_specification/array_object.rst b/spec/draft/API_specification/array_object.rst index d100e631f..9fe48c27c 100644 --- a/spec/draft/API_specification/array_object.rst +++ b/spec/draft/API_specification/array_object.rst @@ -179,9 +179,9 @@ A conforming implementation of the array API standard must provide and support a An in-place operation must not change the data type or shape of the in-place array as a result of :ref:`type-promotion` or :ref:`broadcasting`. -Let ``x1 += x2`` be a representative in-place operation. If, after applying type promotion (see :ref:`type-promotion`) to in-place operands ``x1`` and ``x2``, the resulting data type is the same as the data type of the array on the left-hand side of the operation (i.e., ``x1``), then an in-place operation must have the same behavior (including special cases) as the respective binary (i.e., two operand, non-assignment) operation. In this case, for the in-place addition ``x1 += x2``, the modified array ``x1`` must always equal the result of the equivalent binary arithmetic operation ``x1[...] = x1 + x2``. +Let ``x1 += x2`` be a representative in-place operation. If, after applying type promotion (see :ref:`type-promotion`) to in-place operands ``x1`` and ``x2``, the resulting data type is equal to the data type of the array on the left-hand side of the operation (i.e., ``x1``), then an in-place operation must have the same behavior (including special cases) as the respective binary (i.e., two operand, non-assignment) operation. In this case, for the in-place addition ``x1 += x2``, the modified array ``x1`` must always equal the result of the equivalent binary arithmetic operation ``x1[...] = x1 + x2``. -If, however, after applying type promotion (see :ref:`type-promotion`) to in-place operands, the resulting data type is not the same as the data type of the array on the left-hand side of the operation, then a conforming implementation may return results which differ from the respective binary operation due to casting behavior and selection of the operation's intermediate precision. +If, however, after applying type promotion (see :ref:`type-promotion`) to in-place operands, the resulting data type is not equal to the data type of the array on the left-hand side of the operation, then a conforming implementation may return results which differ from the respective binary operation due to casting behavior and selection of the operation's intermediate precision. The choice of casting behavior and intermediate precision is unspecified and thus implementation-defined. .. note:: Let ``x1`` be the operand on the left-hand side and ``x2`` be the operand on the right-hand side of an in-place operation. Consumers of the array API standard are advised of the following considerations when using in-place operations: From 2af81764f012edbfce8cc73d104a9f93802c450d Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 17 Feb 2025 01:51:44 -0800 Subject: [PATCH 5/5] docs: update copy --- spec/draft/API_specification/array_object.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/draft/API_specification/array_object.rst b/spec/draft/API_specification/array_object.rst index 9fe48c27c..e3c7e8ae6 100644 --- a/spec/draft/API_specification/array_object.rst +++ b/spec/draft/API_specification/array_object.rst @@ -187,10 +187,10 @@ If, however, after applying type promotion (see :ref:`type-promotion`) to in-pla Let ``x1`` be the operand on the left-hand side and ``x2`` be the operand on the right-hand side of an in-place operation. Consumers of the array API standard are advised of the following considerations when using in-place operations: 1. In-place operations do not guarantee in-place mutation. A conforming library may or may not support in-place mutation. - 2. If, after applying broadcasting (see :ref:`broadcasting`) to in-place operands, the resulting shape is not the same as the shape of ``x1``, in-place operators may raise an exception. - 3. If, after applying type promotion (see :ref:`type-promotion`) to in-place operands, the resulting data type is not the same as the data type of ``x1``, the resulting data type may not be the same as ``x1`` and the operation's intermediate precision may be that of ``x1``, even if the promoted data type between ``x1`` and ``x2`` would have higher precision. + 2. If, after applying broadcasting (see :ref:`broadcasting`) to in-place operands, the resulting shape is not equal to the shape of ``x1``, in-place operators may raise an exception. + 3. If, after applying type promotion (see :ref:`type-promotion`) to in-place operands, the resulting data type is not equal to the data type of ``x1``, the resulting data type may not equal the data type of ``x1`` and the operation's intermediate precision may be that of ``x1``, even if the promoted data type between ``x1`` and ``x2`` would have higher precision. - In general, for in-place operations, ensure operands are the same data type and broadcast to the shape of the operand on the left-hand side of the operation in order to maximize portability. + In general, for in-place operations, consumers of the array API standard are advised to ensure operands have the same data type and broadcast to the shape of the operand on the left-hand side of the operation in order to maximize portability. Arithmetic Operators """"""""""""""""""""