From 17fcb9ad6676ac35ebf72c64c1c600ae89aefbaf Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 30 Nov 2023 03:27:19 -0800 Subject: [PATCH 1/6] Add `clamp` to the specification --- .../elementwise_functions.rst | 1 + .../_draft/elementwise_functions.py | 35 ++++++++++++++++++- 2 files changed, 35 insertions(+), 1 deletion(-) diff --git a/spec/draft/API_specification/elementwise_functions.rst b/spec/draft/API_specification/elementwise_functions.rst index 8048eb38a..ec38f00ca 100644 --- a/spec/draft/API_specification/elementwise_functions.rst +++ b/spec/draft/API_specification/elementwise_functions.rst @@ -33,6 +33,7 @@ Objects in API bitwise_right_shift bitwise_xor ceil + clamp conj copysign cos diff --git a/src/array_api_stubs/_draft/elementwise_functions.py b/src/array_api_stubs/_draft/elementwise_functions.py index e3988a09f..04ff392bf 100644 --- a/src/array_api_stubs/_draft/elementwise_functions.py +++ b/src/array_api_stubs/_draft/elementwise_functions.py @@ -15,6 +15,7 @@ "bitwise_right_shift", "bitwise_xor", "ceil", + "clamp", "conj", "copysign", "cos", @@ -62,7 +63,7 @@ ] -from ._types import array +from ._types import Optional, Union, array def abs(x: array, /) -> array: @@ -772,6 +773,38 @@ def ceil(x: array, /) -> array: """ +def clamp( + x: array, + /, + *, + min: Optional[Union[int, float, array]] = None, + max: Optional[Union[int, float, array]] = None, +) -> array: + r""" + Clamps each element ``x_i`` of the input array ``x`` to the range ``[min, max]``. + + Parameters + ---------- + x: array + input array. Should have a real-valued data type. + min: Optional[Union[int, float, array]] + lower-bound of the range to which to clamp. If ``None``, no lower bound must be applied. Must broadcast to the same shape as ``x`` (see :ref:`broadcasting`). Should have a real-valued data type. Default: ``None``. + max: Optional[Union[int, float, array]] + upper-bound of the range to which to clamp. If ``None``, no upper bound must be applied. Must broadcast to the same shape as ``x`` (see :ref:`broadcasting`). Should have a real-valued data type. Default: ``None``. + + Returns + ------- + out: array + an array containing element-wise results. The returned array must have the same shape as ``x`` and have a data type determined by :ref:`type-promotion`. + + Notes + ----- + + - If both ``min`` and ``max`` are ``None``, the elements of the returned array must equal the respective elements in ``x``. + - If a broadcasted element in ``min`` is greater than a corresponding broadcasted element in ``max``, behavior is unspecified and thus implementation-dependent. + """ + + def conj(x: array, /) -> array: """ Returns the complex conjugate for each element ``x_i`` of the input array ``x``. From 14b297f2634701b4f7c151a781dcb4baebd77f4b Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 30 Nov 2023 03:37:21 -0800 Subject: [PATCH 2/6] Allow broadcasting of the input array --- src/array_api_stubs/_draft/elementwise_functions.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/array_api_stubs/_draft/elementwise_functions.py b/src/array_api_stubs/_draft/elementwise_functions.py index 04ff392bf..fb1a2d32d 100644 --- a/src/array_api_stubs/_draft/elementwise_functions.py +++ b/src/array_api_stubs/_draft/elementwise_functions.py @@ -788,14 +788,14 @@ def clamp( x: array input array. Should have a real-valued data type. min: Optional[Union[int, float, array]] - lower-bound of the range to which to clamp. If ``None``, no lower bound must be applied. Must broadcast to the same shape as ``x`` (see :ref:`broadcasting`). Should have a real-valued data type. Default: ``None``. + lower-bound of the range to which to clamp. If ``None``, no lower bound must be applied. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Default: ``None``. max: Optional[Union[int, float, array]] - upper-bound of the range to which to clamp. If ``None``, no upper bound must be applied. Must broadcast to the same shape as ``x`` (see :ref:`broadcasting`). Should have a real-valued data type. Default: ``None``. + upper-bound of the range to which to clamp. If ``None``, no upper bound must be applied. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Default: ``None``. Returns ------- out: array - an array containing element-wise results. The returned array must have the same shape as ``x`` and have a data type determined by :ref:`type-promotion`. + an array containing element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. Notes ----- From f665701892a80fd0a75966869f52d4546ba3a808 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 10 Jan 2024 21:48:14 -0800 Subject: [PATCH 3/6] Rename function and change to return an output array of the same data type --- spec/draft/API_specification/elementwise_functions.rst | 2 +- src/array_api_stubs/_draft/elementwise_functions.py | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/draft/API_specification/elementwise_functions.rst b/spec/draft/API_specification/elementwise_functions.rst index ec38f00ca..cf0297948 100644 --- a/spec/draft/API_specification/elementwise_functions.rst +++ b/spec/draft/API_specification/elementwise_functions.rst @@ -33,7 +33,7 @@ Objects in API bitwise_right_shift bitwise_xor ceil - clamp + clip conj copysign cos diff --git a/src/array_api_stubs/_draft/elementwise_functions.py b/src/array_api_stubs/_draft/elementwise_functions.py index fb1a2d32d..cee972158 100644 --- a/src/array_api_stubs/_draft/elementwise_functions.py +++ b/src/array_api_stubs/_draft/elementwise_functions.py @@ -773,7 +773,7 @@ def ceil(x: array, /) -> array: """ -def clamp( +def clip( x: array, /, *, @@ -795,7 +795,7 @@ def clamp( Returns ------- out: array - an array containing element-wise results. The returned array must have a data type determined by :ref:`type-promotion`. + an array containing element-wise results. The returned array must have the same data type as ``x``. Notes ----- From 51b25e2a15a43870ae038ae67a495b4b135f2770 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 10 Jan 2024 21:59:23 -0800 Subject: [PATCH 4/6] Fix export name --- src/array_api_stubs/_draft/elementwise_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/array_api_stubs/_draft/elementwise_functions.py b/src/array_api_stubs/_draft/elementwise_functions.py index cee972158..6d9d2361c 100644 --- a/src/array_api_stubs/_draft/elementwise_functions.py +++ b/src/array_api_stubs/_draft/elementwise_functions.py @@ -15,7 +15,7 @@ "bitwise_right_shift", "bitwise_xor", "ceil", - "clamp", + "clip", "conj", "copysign", "cos", From 68239b01d88ada0c50a83e6c2e1697ae486b0a7f Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 11 Jan 2024 09:52:21 -0800 Subject: [PATCH 5/6] Allow `min` and `max` to be positional --- src/array_api_stubs/_draft/elementwise_functions.py | 1 - 1 file changed, 1 deletion(-) diff --git a/src/array_api_stubs/_draft/elementwise_functions.py b/src/array_api_stubs/_draft/elementwise_functions.py index 6d9d2361c..e305158f6 100644 --- a/src/array_api_stubs/_draft/elementwise_functions.py +++ b/src/array_api_stubs/_draft/elementwise_functions.py @@ -776,7 +776,6 @@ def ceil(x: array, /) -> array: def clip( x: array, /, - *, min: Optional[Union[int, float, array]] = None, max: Optional[Union[int, float, array]] = None, ) -> array: From ec9fd8250f53b3408e57b370237d048677666d08 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 11 Jan 2024 09:54:44 -0800 Subject: [PATCH 6/6] Add note regarding behavior when `x` and `min`/`max` are different data type kinds --- src/array_api_stubs/_draft/elementwise_functions.py | 1 + 1 file changed, 1 insertion(+) diff --git a/src/array_api_stubs/_draft/elementwise_functions.py b/src/array_api_stubs/_draft/elementwise_functions.py index e305158f6..3eb94a1ac 100644 --- a/src/array_api_stubs/_draft/elementwise_functions.py +++ b/src/array_api_stubs/_draft/elementwise_functions.py @@ -801,6 +801,7 @@ def clip( - If both ``min`` and ``max`` are ``None``, the elements of the returned array must equal the respective elements in ``x``. - If a broadcasted element in ``min`` is greater than a corresponding broadcasted element in ``max``, behavior is unspecified and thus implementation-dependent. + - If ``x`` and either ``min`` or ``max`` have different data type kinds (e.g., integer versus floating-point), behavior is unspecified and thus implementation-dependent. """