From 026fe26766ead236457e266a65ce356a0abea629 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Sat, 10 Feb 2024 17:12:40 +0100 Subject: [PATCH 1/2] Change dtype=None behavior in sum/prod/cumulative_sum/linalg.trace Closes gh-731. This is a backwards-incompatible change. It seems justified and necessary because array libraries all behave like the required behavior described in this commit, are not planning to change, and the initial rationale for the "upcast float" requirement wasn't strong. See discussion in gh-731 for more details. --- src/array_api_stubs/_draft/linalg.py | 15 ++---- .../_draft/statistical_functions.py | 50 ++++++------------- 2 files changed, 19 insertions(+), 46 deletions(-) diff --git a/src/array_api_stubs/_draft/linalg.py b/src/array_api_stubs/_draft/linalg.py index d05b53a9f..559a6d75a 100644 --- a/src/array_api_stubs/_draft/linalg.py +++ b/src/array_api_stubs/_draft/linalg.py @@ -742,19 +742,12 @@ def trace(x: array, /, *, offset: int = 0, dtype: Optional[dtype] = None) -> arr Default: ``0``. dtype: Optional[dtype] - data type of the returned array. If ``None``, + data type of the returned array. If ``None``, the returned array must have the same data type as ``x``, unless ``x`` has an integer dtype supporting a smaller range of values than the default integer dtype (e.g., ``x`` has an ``int16`` or ``uint32`` dtype and the default integer dtype is ``int64``). In those latter cases: - - if the default data type corresponding to the data type "kind" (integer, real-valued floating-point, or complex floating-point) of ``x`` has a smaller range of values than the data type of ``x`` (e.g., ``x`` has data type ``int64`` and the default data type is ``int32``, or ``x`` has data type ``uint64`` and the default data type is ``int64``), the returned array must have the same data type as ``x``. - - if the default data type corresponding to the data type "kind" of ``x`` has the same or a larger range of values than the data type of ``x``, - - if ``x`` has a real-valued floating-point data type, the returned array must have the default real-valued floating-point data type. - - if ``x`` has a complex floating-point data type, the returned array must have the default complex floating-point data type. - - if ``x`` has a signed integer data type (e.g., ``int16``), the returned array must have the default integer data type. - - if ``x`` has an unsigned integer data type (e.g., ``uint16``), the returned array must have an unsigned integer data type having the same number of bits as the default integer data type (e.g., if the default integer data type is ``int32``, the returned array must have a ``uint32`` data type). + - if ``x`` has a signed integer data type (e.g., ``int16``), the returned array must have the default integer data type. + - if ``x`` has an unsigned integer data type (e.g., ``uint16``), the returned array must have an unsigned integer data type having the same number of bits as the default integer data type (e.g., if the default integer data type is ``int32``, the returned array must have a ``uint32`` data type). - If the data type (either specified or resolved) differs from the data type of ``x``, the input array should be cast to the specified data type before computing the sum. Default: ``None``. - - .. note:: - keyword argument is intended to help prevent data type overflows. + If the data type (either specified or resolved) differs from the data type of ``x``, the input array should be cast to the specified data type before computing the sum (rationale: the ``dtype`` keyword argument is intended to help prevent overflows). Default: ``None``. Returns ------- diff --git a/src/array_api_stubs/_draft/statistical_functions.py b/src/array_api_stubs/_draft/statistical_functions.py index 14952402c..319fca283 100644 --- a/src/array_api_stubs/_draft/statistical_functions.py +++ b/src/array_api_stubs/_draft/statistical_functions.py @@ -23,22 +23,14 @@ def cumulative_sum( axis along which a cumulative sum must be computed. If ``axis`` is negative, the function must determine the axis along which to compute a cumulative sum by counting from the last dimension. If ``x`` is a one-dimensional array, providing an ``axis`` is optional; however, if ``x`` has more than one dimension, providing an ``axis`` is required. - dtype: Optional[dtype] - data type of the returned array. If ``None``, - - - if the default data type corresponding to the data type "kind" (integer, real-valued floating-point, or complex floating-point) of ``x`` has a smaller range of values than the data type of ``x`` (e.g., ``x`` has data type ``int64`` and the default data type is ``int32``, or ``x`` has data type ``uint64`` and the default data type is ``int64``), the returned array must have the same data type as ``x``. - - - if the default data type corresponding to the data type "kind" of ``x`` has the same or a larger range of values than the data type of ``x``, - - if ``x`` has a real-valued floating-point data type, the returned array must have the default real-valued floating-point data type. - - if ``x`` has a complex floating-point data type, the returned array must have the default complex floating-point data type. - - if ``x`` has a signed integer data type (e.g., ``int16``), the returned array must have the default integer data type. - - if ``x`` has an unsigned integer data type (e.g., ``uint16``), the returned array must have an unsigned integer data type having the same number of bits as the default integer data type (e.g., if the default integer data type is ``int32``, the returned array must have a ``uint32`` data type). + dtype: Optional[dtype] + data type of the returned array. If ``None``, the returned array must have the same data type as ``x``, unless ``x`` has an integer dtype supporting a smaller range of values than the default integer dtype (e.g., ``x`` has an ``int16`` or ``uint32`` dtype and the default integer dtype is ``int64``). In those latter cases: - If the data type (either specified or resolved) differs from the data type of ``x``, the input array should be cast to the specified data type before computing the sum. Default: ``None``. + - if ``x`` has a signed integer data type (e.g., ``int16``), the returned array must have the default integer data type. + - if ``x`` has an unsigned integer data type (e.g., ``uint16``), the returned array must have an unsigned integer data type having the same number of bits as the default integer data type (e.g., if the default integer data type is ``int32``, the returned array must have a ``uint32`` data type). - .. note:: - keyword argument is intended to help prevent data type overflows. + If the data type (either specified or resolved) differs from the data type of ``x``, the input array should be cast to the specified data type before computing the sum (rationale: the ``dtype`` keyword argument is intended to help prevent overflows). Default: ``None``. include_initial: bool boolean indicating whether to include the initial value as the first value in the output. By convention, the initial value must be the additive identity (i.e., zero). Default: ``False``. @@ -200,20 +192,14 @@ def prod( input array. Should have a numeric data type. axis: Optional[Union[int, Tuple[int, ...]]] axis or axes along which products must be computed. By default, the product must be computed over the entire array. If a tuple of integers, products must be computed over multiple axes. Default: ``None``. - dtype: Optional[dtype] - data type of the returned array. If ``None``, - - if the default data type corresponding to the data type "kind" (integer, real-valued floating-point, or complex floating-point) of ``x`` has a smaller range of values than the data type of ``x`` (e.g., ``x`` has data type ``int64`` and the default data type is ``int32``, or ``x`` has data type ``uint64`` and the default data type is ``int64``), the returned array must have the same data type as ``x``. - - if the default data type corresponding to the data type "kind" of ``x`` has the same or a larger range of values than the data type of ``x``, - - if ``x`` has a real-valued floating-point data type, the returned array must have the default real-valued floating-point data type. - - if ``x`` has a complex floating-point data type, the returned array must have the default complex floating-point data type. - - if ``x`` has a signed integer data type (e.g., ``int16``), the returned array must have the default integer data type. - - if ``x`` has an unsigned integer data type (e.g., ``uint16``), the returned array must have an unsigned integer data type having the same number of bits as the default integer data type (e.g., if the default integer data type is ``int32``, the returned array must have a ``uint32`` data type). + dtype: Optional[dtype] + data type of the returned array. If ``None``, the returned array must have the same data type as ``x``, unless ``x`` has an integer dtype supporting a smaller range of values than the default integer dtype (e.g., ``x`` has an ``int16`` or ``uint32`` dtype and the default integer dtype is ``int64``). In those latter cases: - If the data type (either specified or resolved) differs from the data type of ``x``, the input array should be cast to the specified data type before computing the product. Default: ``None``. + - if ``x`` has a signed integer data type (e.g., ``int16``), the returned array must have the default integer data type. + - if ``x`` has an unsigned integer data type (e.g., ``uint16``), the returned array must have an unsigned integer data type having the same number of bits as the default integer data type (e.g., if the default integer data type is ``int32``, the returned array must have a ``uint32`` data type). - .. note:: - This keyword argument is intended to help prevent data type overflows. + If the data type (either specified or resolved) differs from the data type of ``x``, the input array should be cast to the specified data type before computing the sum (rationale: the ``dtype`` keyword argument is intended to help prevent overflows). Default: ``None``. keepdims: bool if ``True``, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see :ref:`broadcasting`). Otherwise, if ``False``, the reduced axes (dimensions) must not be included in the result. Default: ``False``. @@ -298,20 +284,14 @@ def sum( input array. Should have a numeric data type. axis: Optional[Union[int, Tuple[int, ...]]] axis or axes along which sums must be computed. By default, the sum must be computed over the entire array. If a tuple of integers, sums must be computed over multiple axes. Default: ``None``. - dtype: Optional[dtype] - data type of the returned array. If ``None``, - - if the default data type corresponding to the data type "kind" (integer, real-valued floating-point, or complex floating-point) of ``x`` has a smaller range of values than the data type of ``x`` (e.g., ``x`` has data type ``int64`` and the default data type is ``int32``, or ``x`` has data type ``uint64`` and the default data type is ``int64``), the returned array must have the same data type as ``x``. - - if the default data type corresponding to the data type "kind" of ``x`` has the same or a larger range of values than the data type of ``x``, - - if ``x`` has a real-valued floating-point data type, the returned array must have the default real-valued floating-point data type. - - if ``x`` has a complex floating-point data type, the returned array must have the default complex floating-point data type. - - if ``x`` has a signed integer data type (e.g., ``int16``), the returned array must have the default integer data type. - - if ``x`` has an unsigned integer data type (e.g., ``uint16``), the returned array must have an unsigned integer data type having the same number of bits as the default integer data type (e.g., if the default integer data type is ``int32``, the returned array must have a ``uint32`` data type). + dtype: Optional[dtype] + data type of the returned array. If ``None``, the returned array must have the same data type as ``x``, unless ``x`` has an integer dtype supporting a smaller range of values than the default integer dtype (e.g., ``x`` has an ``int16`` or ``uint32`` dtype and the default integer dtype is ``int64``). In those latter cases: - If the data type (either specified or resolved) differs from the data type of ``x``, the input array should be cast to the specified data type before computing the sum. Default: ``None``. + - if ``x`` has a signed integer data type (e.g., ``int16``), the returned array must have the default integer data type. + - if ``x`` has an unsigned integer data type (e.g., ``uint16``), the returned array must have an unsigned integer data type having the same number of bits as the default integer data type (e.g., if the default integer data type is ``int32``, the returned array must have a ``uint32`` data type). - .. note:: - keyword argument is intended to help prevent data type overflows. + If the data type (either specified or resolved) differs from the data type of ``x``, the input array should be cast to the specified data type before computing the sum (rationale: the ``dtype`` keyword argument is intended to help prevent overflows). Default: ``None``. keepdims: bool if ``True``, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see :ref:`broadcasting`). Otherwise, if ``False``, the reduced axes (dimensions) must not be included in the result. Default: ``False``. From 3fefddaf9cfbf4aa15ab43d8908e275413abf5b3 Mon Sep 17 00:00:00 2001 From: Athan Date: Mon, 12 Feb 2024 22:54:29 -0800 Subject: [PATCH 2/2] Apply suggestions from code review --- src/array_api_stubs/_draft/linalg.py | 2 +- src/array_api_stubs/_draft/statistical_functions.py | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/array_api_stubs/_draft/linalg.py b/src/array_api_stubs/_draft/linalg.py index 559a6d75a..c66258c7b 100644 --- a/src/array_api_stubs/_draft/linalg.py +++ b/src/array_api_stubs/_draft/linalg.py @@ -742,7 +742,7 @@ def trace(x: array, /, *, offset: int = 0, dtype: Optional[dtype] = None) -> arr Default: ``0``. dtype: Optional[dtype] - data type of the returned array. If ``None``, the returned array must have the same data type as ``x``, unless ``x`` has an integer dtype supporting a smaller range of values than the default integer dtype (e.g., ``x`` has an ``int16`` or ``uint32`` dtype and the default integer dtype is ``int64``). In those latter cases: + data type of the returned array. If ``None``, the returned array must have the same data type as ``x``, unless ``x`` has an integer data type supporting a smaller range of values than the default integer data type (e.g., ``x`` has an ``int16`` or ``uint32`` data type and the default integer data type is ``int64``). In those latter cases: - if ``x`` has a signed integer data type (e.g., ``int16``), the returned array must have the default integer data type. - if ``x`` has an unsigned integer data type (e.g., ``uint16``), the returned array must have an unsigned integer data type having the same number of bits as the default integer data type (e.g., if the default integer data type is ``int32``, the returned array must have a ``uint32`` data type). diff --git a/src/array_api_stubs/_draft/statistical_functions.py b/src/array_api_stubs/_draft/statistical_functions.py index 319fca283..496440535 100644 --- a/src/array_api_stubs/_draft/statistical_functions.py +++ b/src/array_api_stubs/_draft/statistical_functions.py @@ -25,7 +25,7 @@ def cumulative_sum( If ``x`` is a one-dimensional array, providing an ``axis`` is optional; however, if ``x`` has more than one dimension, providing an ``axis`` is required. dtype: Optional[dtype] - data type of the returned array. If ``None``, the returned array must have the same data type as ``x``, unless ``x`` has an integer dtype supporting a smaller range of values than the default integer dtype (e.g., ``x`` has an ``int16`` or ``uint32`` dtype and the default integer dtype is ``int64``). In those latter cases: + data type of the returned array. If ``None``, the returned array must have the same data type as ``x``, unless ``x`` has an integer data type supporting a smaller range of values than the default integer data type (e.g., ``x`` has an ``int16`` or ``uint32`` data type and the default integer data type is ``int64``). In those latter cases: - if ``x`` has a signed integer data type (e.g., ``int16``), the returned array must have the default integer data type. - if ``x`` has an unsigned integer data type (e.g., ``uint16``), the returned array must have an unsigned integer data type having the same number of bits as the default integer data type (e.g., if the default integer data type is ``int32``, the returned array must have a ``uint32`` data type). @@ -194,7 +194,7 @@ def prod( axis or axes along which products must be computed. By default, the product must be computed over the entire array. If a tuple of integers, products must be computed over multiple axes. Default: ``None``. dtype: Optional[dtype] - data type of the returned array. If ``None``, the returned array must have the same data type as ``x``, unless ``x`` has an integer dtype supporting a smaller range of values than the default integer dtype (e.g., ``x`` has an ``int16`` or ``uint32`` dtype and the default integer dtype is ``int64``). In those latter cases: + data type of the returned array. If ``None``, the returned array must have the same data type as ``x``, unless ``x`` has an integer data type supporting a smaller range of values than the default integer data type (e.g., ``x`` has an ``int16`` or ``uint32`` data type and the default integer data type is ``int64``). In those latter cases: - if ``x`` has a signed integer data type (e.g., ``int16``), the returned array must have the default integer data type. - if ``x`` has an unsigned integer data type (e.g., ``uint16``), the returned array must have an unsigned integer data type having the same number of bits as the default integer data type (e.g., if the default integer data type is ``int32``, the returned array must have a ``uint32`` data type). @@ -286,7 +286,7 @@ def sum( axis or axes along which sums must be computed. By default, the sum must be computed over the entire array. If a tuple of integers, sums must be computed over multiple axes. Default: ``None``. dtype: Optional[dtype] - data type of the returned array. If ``None``, the returned array must have the same data type as ``x``, unless ``x`` has an integer dtype supporting a smaller range of values than the default integer dtype (e.g., ``x`` has an ``int16`` or ``uint32`` dtype and the default integer dtype is ``int64``). In those latter cases: + data type of the returned array. If ``None``, the returned array must have the same data type as ``x``, unless ``x`` has an integer data type supporting a smaller range of values than the default integer data type (e.g., ``x`` has an ``int16`` or ``uint32`` data type and the default integer data type is ``int64``). In those latter cases: - if ``x`` has a signed integer data type (e.g., ``int16``), the returned array must have the default integer data type. - if ``x`` has an unsigned integer data type (e.g., ``uint16``), the returned array must have an unsigned integer data type having the same number of bits as the default integer data type (e.g., if the default integer data type is ``int32``, the returned array must have a ``uint32`` data type).