From ae4bc1cafc0c3b044306324a3d6b938006abac46 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 12 Jul 2023 23:27:13 -0700 Subject: [PATCH 1/5] Add specification for computing the cumulative sum --- .../statistical_functions.rst | 1 + .../_draft/statistical_functions.py | 62 ++++++++++++++++++- 2 files changed, 62 insertions(+), 1 deletion(-) diff --git a/spec/draft/API_specification/statistical_functions.rst b/spec/draft/API_specification/statistical_functions.rst index 23cd2cb1d..20e02b3f9 100644 --- a/spec/draft/API_specification/statistical_functions.rst +++ b/spec/draft/API_specification/statistical_functions.rst @@ -18,6 +18,7 @@ Objects in API :toctree: generated :template: method.rst + cumulative_sum max mean min diff --git a/src/array_api_stubs/_draft/statistical_functions.py b/src/array_api_stubs/_draft/statistical_functions.py index 93faaf31e..5a8e1aea3 100644 --- a/src/array_api_stubs/_draft/statistical_functions.py +++ b/src/array_api_stubs/_draft/statistical_functions.py @@ -1,6 +1,66 @@ from ._types import Optional, Tuple, Union, array, dtype +def cumulative_sum( + x: array, + /, + *, + axis: Optional[int] = None, + dtype: Optional[dtype] = None, + startpoint: bool = False, + endpoint: bool = True, +) -> array: + """ + Calculates the cumulative sum of elements in the input array ``x``. + + Parameters + ---------- + x: array + input array. Should have a numeric data type. + axis: Optional[int] + 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). + + 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. + + startpoint: bool + boolean indicating whether to include the initial value as the first value in the output. Default: ``False``. + endpoint: bool + boolean indicating whether to include the total sum as the last value in the output. Default: ``True``. + + Returns + ------- + out: array + an array containing the cumulative sums. The returned array must have a data type as described by the ``dtype`` parameter above. + + Let ``N`` be the size of the axis along which to compute the cumulative sum. The returned array must have a shape determined according to the following rules: + + - if ``startpoint`` and ``endpoint`` are ``True``, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N+1``. + - if only one of ``startpoint`` and ``endpoint`` is ``True``, the returned array must have the same shape as ``x``. + - if ``startpoint`` and ``endpoint`` are ``False``, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N-1``. + + Notes + ----- + + **Special Cases** + + For both real-valued and complex floating-point operands, special cases must be handled as if the operation is implemented by successive application of :func:`~array_api.add`. + """ + + def max( x: array, /, @@ -317,4 +377,4 @@ def var( """ -__all__ = ["max", "mean", "min", "prod", "std", "sum", "var"] +__all__ = ["cumulative_sum", "max", "mean", "min", "prod", "std", "sum", "var"] From 2e0b224466ed68ae0cbbac64dcd6ef179b4b9f58 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 27 Jul 2023 01:28:08 -0700 Subject: [PATCH 2/5] Rename kwargs and remove `endpoint` --- .../_draft/statistical_functions.py | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/src/array_api_stubs/_draft/statistical_functions.py b/src/array_api_stubs/_draft/statistical_functions.py index 5a8e1aea3..ac339f37b 100644 --- a/src/array_api_stubs/_draft/statistical_functions.py +++ b/src/array_api_stubs/_draft/statistical_functions.py @@ -7,8 +7,7 @@ def cumulative_sum( *, axis: Optional[int] = None, dtype: Optional[dtype] = None, - startpoint: bool = False, - endpoint: bool = True, + include_initial: bool = False, ) -> array: """ Calculates the cumulative sum of elements in the input array ``x``. @@ -36,10 +35,8 @@ def cumulative_sum( .. note:: keyword argument is intended to help prevent data type overflows. - startpoint: bool - boolean indicating whether to include the initial value as the first value in the output. Default: ``False``. - endpoint: bool - boolean indicating whether to include the total sum as the last value in the output. Default: ``True``. + 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``. Returns ------- @@ -48,9 +45,8 @@ def cumulative_sum( Let ``N`` be the size of the axis along which to compute the cumulative sum. The returned array must have a shape determined according to the following rules: - - if ``startpoint`` and ``endpoint`` are ``True``, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N+1``. - - if only one of ``startpoint`` and ``endpoint`` is ``True``, the returned array must have the same shape as ``x``. - - if ``startpoint`` and ``endpoint`` are ``False``, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N-1``. + - if ``include_initial`` is ``True``, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N+1``. + - if ``include_initial`` is ``False``, the returned array must have the same shape as ``x``. Notes ----- From 8083e5beeeb2ad39a57b52911608d9493092d15e Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Tue, 19 Sep 2023 14:16:56 -0700 Subject: [PATCH 3/5] Add guidance for empty arrays --- src/array_api_stubs/_draft/statistical_functions.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/array_api_stubs/_draft/statistical_functions.py b/src/array_api_stubs/_draft/statistical_functions.py index ffb5c8514..102d5b93e 100644 --- a/src/array_api_stubs/_draft/statistical_functions.py +++ b/src/array_api_stubs/_draft/statistical_functions.py @@ -48,7 +48,9 @@ def cumulative_sum( Let ``N`` be the size of the axis along which to compute the cumulative sum. The returned array must have a shape determined according to the following rules: - - if ``include_initial`` is ``True``, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N+1``. + - if ``include_initial`` is ``True``, + - if ``N`` is greater than zero, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N+1``. + - if ``N`` is zero (i.e., ``x`` is an empty array), the returned array must have the same shape as ``x``. - if ``include_initial`` is ``False``, the returned array must have the same shape as ``x``. Notes From 3228d4c70f0890d067df9d59446642392fc90df7 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 21 Sep 2023 01:40:57 -0700 Subject: [PATCH 4/5] Fix formatting --- src/array_api_stubs/_draft/statistical_functions.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/array_api_stubs/_draft/statistical_functions.py b/src/array_api_stubs/_draft/statistical_functions.py index 102d5b93e..81a124b0d 100644 --- a/src/array_api_stubs/_draft/statistical_functions.py +++ b/src/array_api_stubs/_draft/statistical_functions.py @@ -27,7 +27,9 @@ def cumulative_sum( 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. @@ -49,8 +51,10 @@ def cumulative_sum( Let ``N`` be the size of the axis along which to compute the cumulative sum. The returned array must have a shape determined according to the following rules: - if ``include_initial`` is ``True``, + - if ``N`` is greater than zero, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N+1``. - if ``N`` is zero (i.e., ``x`` is an empty array), the returned array must have the same shape as ``x``. + - if ``include_initial`` is ``False``, the returned array must have the same shape as ``x``. Notes From 756fc92a345a48874a857796e6a6013276e358d9 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 18 Oct 2023 18:12:44 -0700 Subject: [PATCH 5/5] Ensure consistent rules for when `include_initial` is `True` --- src/array_api_stubs/_draft/statistical_functions.py | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/src/array_api_stubs/_draft/statistical_functions.py b/src/array_api_stubs/_draft/statistical_functions.py index 81a124b0d..2b3758e01 100644 --- a/src/array_api_stubs/_draft/statistical_functions.py +++ b/src/array_api_stubs/_draft/statistical_functions.py @@ -50,11 +50,7 @@ def cumulative_sum( Let ``N`` be the size of the axis along which to compute the cumulative sum. The returned array must have a shape determined according to the following rules: - - if ``include_initial`` is ``True``, - - - if ``N`` is greater than zero, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N+1``. - - if ``N`` is zero (i.e., ``x`` is an empty array), the returned array must have the same shape as ``x``. - + - if ``include_initial`` is ``True``, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N+1``. - if ``include_initial`` is ``False``, the returned array must have the same shape as ``x``. Notes