From 935b75815723f2cd8ac57b86f17c8ebb2bbe0126 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 24 Sep 2020 01:07:27 -0700 Subject: [PATCH 1/2] Add any and all specifications --- spec/API_specification/index.rst | 1 + spec/API_specification/utility_functions.md | 62 +++++++++++++++++++++ 2 files changed, 63 insertions(+) create mode 100644 spec/API_specification/utility_functions.md diff --git a/spec/API_specification/index.rst b/spec/API_specification/index.rst index 46b7c9366..b56d2da2e 100644 --- a/spec/API_specification/index.rst +++ b/spec/API_specification/index.rst @@ -19,4 +19,5 @@ API specification linear_algebra_functions searching_functions set_functions + utility_functions constants diff --git a/spec/API_specification/utility_functions.md b/spec/API_specification/utility_functions.md new file mode 100644 index 000000000..d2f33f765 --- /dev/null +++ b/spec/API_specification/utility_functions.md @@ -0,0 +1,62 @@ +# Utility Functions + +> Array API specification for utility functions. + +A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions. + +- Positional parameters must be [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order. +- Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments. +- Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`. +- Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. +- Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`. +- Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019. + + + +### # all(x, /, *, axis=None, keepdims=False) + +Tests whether all input array elements evaluate to `True` along a specified axis. + +#### Parameters + +- **x**: _<array>_ + + - input array. + +- **axis**: _Optional\[ Union\[ int, Tuple\[ int, ... ] ] ]_ + + - axis or axes along which to perform a logical AND reduction. By default, a logical AND reduction must be performed over the entire array. If a tuple of integers, logical AND reductions must be performed over multiple axes. 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`. + +#### Returns + +- **out**: _<array>_ + + - if a logical AND reduction was performed over the entire array, a zero-dimensional array containing the test result; otherwise, a non-zero-dimensional array containing the test results. The returned array must be a boolean array (i.e., an array whose underlying data type is `bool`). + +### # any(x, /, *, axis=None, keepdims=False) + +Tests whether any input array element evaluates to `True` along a specified axis. + +#### Parameters + +- **x**: _<array>_ + + - input array. + +- **axis**: _Optional\[ Union\[ int, Tuple\[ int, ... ] ] ]_ + + - axis or axes along which to perform a logical OR reduction. By default, a logical OR reduction must be performed over the entire array. If a tuple of integers, logical OR reductions must be performed over multiple axes. 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`. + +#### Returns + +- **out**: _<array>_ + + - if a logical OR reduction was performed over the entire array, a zero-dimensional array containing the test result; otherwise, a non-zero-dimensional array containing the test results. The returned array must be a boolean array (i.e., an array whose underlying data type is `bool`). \ No newline at end of file From 9cd2a7054c6a034fcb38a60e77343da55ef6de09 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 24 Sep 2020 01:31:49 -0700 Subject: [PATCH 2/2] Update copy --- spec/API_specification/utility_functions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/utility_functions.md b/spec/API_specification/utility_functions.md index d2f33f765..b93ae9fdf 100644 --- a/spec/API_specification/utility_functions.md +++ b/spec/API_specification/utility_functions.md @@ -25,7 +25,7 @@ Tests whether all input array elements evaluate to `True` along a specified axis - **axis**: _Optional\[ Union\[ int, Tuple\[ int, ... ] ] ]_ - - axis or axes along which to perform a logical AND reduction. By default, a logical AND reduction must be performed over the entire array. If a tuple of integers, logical AND reductions must be performed over multiple axes. Default: `None`. + - axis or axes along which to perform a logical AND reduction. By default, a logical AND reduction must be performed over the entire array. If a tuple of integers, logical AND reductions must be performed over multiple axes. A valid `axis` must be an integer on the interval `[-N, N)`, where `N` is the rank (number of dimensions) of `x`. If an `axis` is specified as a negative integer, the function must determine the axis along which to perform a reduction by counting backward from the last dimension (where `-1` refers to the last dimension). If provided an invalid `axis`, the function must raise an exception. Default: `None`. - **keepdims**: _bool_ @@ -49,7 +49,7 @@ Tests whether any input array element evaluates to `True` along a specified axis - **axis**: _Optional\[ Union\[ int, Tuple\[ int, ... ] ] ]_ - - axis or axes along which to perform a logical OR reduction. By default, a logical OR reduction must be performed over the entire array. If a tuple of integers, logical OR reductions must be performed over multiple axes. Default: `None`. + - axis or axes along which to perform a logical OR reduction. By default, a logical OR reduction must be performed over the entire array. If a tuple of integers, logical OR reductions must be performed over multiple axes. A valid `axis` must be an integer on the interval `[-N, N)`, where `N` is the rank (number of dimensions) of `x`. If an `axis` is specified as a negative integer, the function must determine the axis along which to perform a reduction by counting backward from the last dimension (where `-1` refers to the last dimension). If provided an invalid `axis`, the function must raise an exception. Default: `None`. - **keepdims**: _bool_