diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 34ac6e061..cd6400745 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -134,30 +134,34 @@ A conforming implementation of the array API standard must provide and support a - [`operator.__rshift__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__rshift__) -### In-place operators +### 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: + +- `+=`. May be implemented via `__iadd__`. +- `-=`. May be implemented via `__isub__`. +- `*=`. May be implemented via `__imul__`. +- `/=`. May be implemented via `__idiv__`. +- `//=`. May be implemented via `__ifloordiv__`. +- `**=`. May be implemented via `__ipow__`. +- `@=`. May be implemented via `__imatmul__`. +- `%=`. May be implemented via `__imod__`. +- `&=`. May be implemented via `__iand__`. +- `|=`. May be implemented via `__ior__`. +- `^=`. May be implemented via `__ixor__`. +- `<<=`. May be implemented via `__ilshift__`. +- `>>=`. May be implemented via `__irshift__`. -As discussed in {ref}`copyview-mutability`, in-place operators need to be -supported. The following operators must be supported: - -- `+=`. May be (but does not have to be) implemented via `__iadd__`. -- `-=`. May be (but does not have to be) implemented via `__isub__`. -- `*=`. May be (but does not have to be) implemented via `__imul__`. -- `/=`. May be (but does not have to be) implemented via `__idiv__`. -- `//=`. May be (but does not have to be) implemented via `__ifloordiv__`. -- `**=`. May be (but does not have to be) implemented via `__ipow__`. -- `@=`. May be (but does not have to be) implemented via `__imatmul__`. -- `%=`. May be (but does not have to be) implemented via `__imod__`. -- `&=`. May be (but does not have to be) implemented via `__iand__`. -- `|=`. May be (but does not have to be) implemented via `__ior__`. -- `^=`. May be (but does not have to be) implemented via `__ixor__`. -- `<<=`. May be (but does not have to be) implemented via `__ilshift__`. -- `>>=`. May be (but does not have to be) implemented via `__irshift__`. +```{note} +In-place operators must be supported as discussed in {ref}`copyview-mutability`. +``` -### Right-hand side dunder methods +### Reflected Operators -All supported operators for which `array scalar` is implemented also need a right-hand -size dunder method. The following methods must be supported: +A conforming implementation of the array API standard must provide and support +an array object supporting the following reflected operators: - `__radd__` - `__rsub__` @@ -173,7 +177,12 @@ size dunder method. The following methods must be supported: - `__rlshift__` - `__rrshift__` -For the expected numerical behaviour, see their left-hand equivalents. +The results of applying reflected operators must match their non-reflected equivalents. + +```{note} + +All operators for which `array scalar` is implemented must have an equivalent reflected operator implementation. +``` * * * @@ -221,7 +230,7 @@ _TODO: need to more carefully consider this in order to accommodate, e.g., graph (attribute-size)= ### size -Number of elements in an array. This should equal the product of the array's dimensions. +Number of elements in an array. This must equal the product of the array's dimensions. #### Returns @@ -254,6 +263,8 @@ Transpose of the array. Calculates the absolute value for each element `x_i` of an array instance `x` (i.e., the element-wise result has the same magnitude as the respective element in `x` but has positive sign). #### Special Cases + +For floating-point operands, - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `-0`, the result is `+0`. @@ -279,10 +290,12 @@ Element-wise results must equal the results returned by the equivalent element-w (method-__add__)= ### \_\_add\_\_(x1, x2, /) -Calculates the sum for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, +Calculates the sum for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. #### Special Cases +For floating-point operands, + - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. - If `x1_i` is `+infinity` and `x2_i` is `-infinity`, the result is `NaN`. - If `x1_i` is `-infinity` and `x2_i` is `+infinity`, the result is `NaN`. @@ -372,7 +385,7 @@ Computes the truth value of `x1_i == x2_i` for each element `x1_i` of an array i - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). + - an array containing the element-wise results. The returned array must have a data type of `bool`. ```{note} @@ -424,7 +437,7 @@ Computes the truth value of `x1_i >= x2_i` for each element `x1_i` of an array i - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). + - an array containing the element-wise results. The returned array must have a data type of `bool`. ```{note} @@ -455,7 +468,7 @@ Computes the truth value of `x1_i > x2_i` for each element `x1_i` of an array in - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). + - an array containing the element-wise results. The returned array must have a data type of `bool`. ```{note} @@ -503,7 +516,7 @@ Computes the truth value of `x1_i <= x2_i` for each element `x1_i` of an array i - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). + - an array containing the element-wise results. The returned array must have a data type of `bool`. ```{note} @@ -513,7 +526,7 @@ Element-wise results must equal the results returned by the equivalent element-w (method-__len__)= ### \_\_len\_\_(x, /) -_TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where a shape may be dynamic._ +_TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where a shape may be dynamic. Furthermore, not clear whether this should be implemented, as, e.g., NumPy's behavior of returning the size of the first dimension is not necessarily intuitive, as opposed to, say, the total number of elements._ (method-__lshift__)= ### \_\_lshift\_\_(x1, x2, /) @@ -560,7 +573,7 @@ Computes the truth value of `x1_i < x2_i` for each element `x1_i` of an array in - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). + - an array containing the element-wise results. The returned array must have a data type of `bool`. ```{note} @@ -617,15 +630,17 @@ Element-wise results must equal the results returned by the equivalent element-w (method-__mul__)= ### \_\_mul\_\_(x1, x2, /) -Calculates the product for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, +Calculates the product for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. #### Special Cases +For floating-point operands, + - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. -- If `x1_i` and `x2_i` have the same mathematical sign, the result has a positive mathematical sign. -- If `x1_i` and `x2_i` have different mathematical signs, the result has a negative mathematical sign. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+0` or `-0`, the result is `NaN`. - If `x1_i` is either `+0` or `-0` and `x2_i` is either `+infinity` or `-infinity`, the result is `NaN`. +- If `x1_i` and `x2_i` have the same mathematical sign, the result has a positive mathematical sign, unless the result is `NaN`. If the result is `NaN`, the "sign" of `NaN` is implementation-defined. +- If `x1_i` and `x2_i` have different mathematical signs, the result has a negative mathematical sign, unless the result is `NaN`. If the result is `NaN`, the "sign" of `NaN` is implementation-defined. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the mathematical sign determined by the rule already stated above. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is a nonzero finite number, the result is a signed infinity with the mathematical sign determined by the rule already stated above. - If `x1_i` is a nonzero finite number and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the mathematical sign determined by the rule already stated above. @@ -760,6 +775,8 @@ Calculates an implementation-dependent approximation of exponentiation by raisin #### Special Cases +For floating-point operands, + - If `x1_i` is not equal to `1` and `x2_i` is `NaN`, the result is `NaN`. - If `x2_i` is `+0`, the result is `1`, even if `x1_i` is `NaN`. - If `x2_i` is `-0`, the result is `1`, even if `x1_i` is `NaN`. @@ -840,7 +857,7 @@ _TODO: dependent on the indexing specification._ (method-__sub__)= ### \_\_sub\_\_(x1, x2, /) -Calculates the difference for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. The result of `x1_i - x2_i` must be the same as `x1_i + (-x2_i)` and is thus governed by the same floating-point rules as addition (see [`__add__()`](#__add__x1-x2-)). +Calculates the difference for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. The result of `x1_i - x2_i` must be the same as `x1_i + (-x2_i)` and must be governed by the same floating-point rules as addition (see [`__add__()`](#__add__x1-x2-)). #### Parameters @@ -866,10 +883,12 @@ Element-wise results must equal the results returned by the equivalent element-w (method-__truediv__)= ### \_\_truediv\_\_(x1, x2, /) -Evaluates `x1_i / x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. For floating-point arithmetic, +Evaluates `x1_i / x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. #### Special Cases +For floating-point operands, + - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is `NaN`. - If `x1_i` is either `+0` or `-0` and `x2_i` is either `+0` or `-0`, the result is `NaN`. diff --git a/spec/API_specification/constants.md b/spec/API_specification/constants.md index 4a1aac5f6..4a9cd040f 100644 --- a/spec/API_specification/constants.md +++ b/spec/API_specification/constants.md @@ -20,12 +20,12 @@ e = 2.71828182845904523536028747135266249775724709369995... (constant-inf)= ### inf -IEEE 754 floating point representation of (positive) infinity. +IEEE 754 floating-point representation of (positive) infinity. (constant-nan)= ### nan -IEEE 754 floating point representation of Not a Number (`NaN`). +IEEE 754 floating-point representation of Not a Number (`NaN`). (constant-pi)= ### pi diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 80fb4c11f..741cff989 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -181,7 +181,10 @@ Returns evenly spaced numbers over a specified interval. - the end of the interval. If `endpoint` is `False`, the function must generate a sequence of `num+1` evenly spaced numbers starting with `start` and ending with `stop` and exclude the `stop` from the returned array such that the returned array consists of evenly spaced numbers over the half-open interval `[start, stop)`. If `endpoint` is `True`, the output array must consist of evenly spaced numbers over the closed interval `[start, stop]`. Default: `True`. - _Note: that the step size changes when `endpoint` is `False`._ + ```{note} + + The step size changes when `endpoint` is `False`. + ``` - **num**: _int_ diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index 7cf30a149..f8c3abaf0 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -25,6 +25,8 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e #### Special Cases +For floating-point operands, + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `-0`, the result is `+0`. - If `x_i` is `-infinity`, the result is `+infinity`. @@ -48,6 +50,8 @@ Calculates an implementation-dependent approximation of the principal value of t #### Special Cases +For floating-point operands, + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is greater than `1`, the result is `NaN`. - If `x_i` is less than `-1`, the result is `NaN`. @@ -72,6 +76,8 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c #### Special Cases +For floating-point operands, + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `1`, the result is `NaN`. - If `x_i` is `1`, the result is `+0`. @@ -92,10 +98,12 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c (function-add)= ### add(x1, x2, /) -Calculates the sum for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. For floating-point arithmetic, +Calculates the sum for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. #### Special Cases +For floating-point operands, + - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. - If `x1_i` is `+infinity` and `x2_i` is `-infinity`, the result is `NaN`. - If `x1_i` is `-infinity` and `x2_i` is `+infinity`, the result is `NaN`. @@ -142,6 +150,8 @@ Calculates an implementation-dependent approximation of the principal value of t #### Special Cases +For floating-point operands, + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is greater than `1`, the result is `NaN`. - If `x_i` is less than `-1`, the result is `NaN`. @@ -167,6 +177,8 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic s #### Special Cases +For floating-point operands, + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. - If `x_i` is `-0`, the result is `-0`. @@ -192,6 +204,8 @@ Calculates an implementation-dependent approximation of the principal value of t #### Special Cases +For floating-point operands, + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. - If `x_i` is `-0`, the result is `-0`. @@ -226,6 +240,8 @@ By IEEE 754 convention, the inverse tangent of the quotient `x1/x2` is defined f #### Special Cases +For floating-point operands, + - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. - If `x1_i` is greater than `0` and `x2_i` is `+0`, the result is an implementation-dependent approximation to `+π/2`. - If `x1_i` is greater than `0` and `x2_i` is `-0`, the result is an implementation-dependent approximation to `+π/2`. @@ -273,6 +289,8 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic t #### Special Cases +For floating-point operands, + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `-1`, the result is `NaN`. - If `x_i` is greater than `1`, the result is `NaN`. @@ -443,6 +461,8 @@ Calculates an implementation-dependent approximation to the cosine, having domai #### Special Cases +For floating-point operands, + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `1`. - If `x_i` is `-0`, the result is `1`. @@ -466,6 +486,10 @@ Calculates an implementation-dependent approximation to the cosine, having domai Calculates an implementation-dependent approximation to the hyperbolic cosine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` in the input array `x`. +#### Special Cases + +For floating-point operands, + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `1`. - If `x_i` is `-0`, the result is `1`. @@ -487,10 +511,12 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine, h (function-divide)= ### divide(x1, x2, /) -Calculates the division for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. For floating-point arithmetic, +Calculates the division for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. #### Special Cases +For floating-point operands, + - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is `NaN`. - If `x1_i` is either `+0` or `-0` and `x2_i` is either `+0` or `-0`, the result is `NaN`. @@ -549,7 +575,7 @@ Computes the truth value of `x1_i == x2_i` for each element `x1_i` of the input - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). + - an array containing the element-wise results. The returned array must have a data type of `bool`. (function-exp)= ### exp(x, /) @@ -558,6 +584,8 @@ Calculates an implementation-dependent approximation to the exponential function #### Special Cases +For floating-point operands, + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `1`. - If `x_i` is `-0`, the result is `1`. @@ -588,6 +616,8 @@ The purpose of this function is to calculate `exp(x)-1.0` more accurately when ` #### Special Cases +For floating-point operands, + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. - If `x_i` is `-0`, the result is `-0`. @@ -646,7 +676,7 @@ Rounds the result of dividing each element `x1_i` of the input array `x1` by the - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a floating-point data type determined by {ref}`type-promotion`. + - an array containing the element-wise results. The returned array must have a data type determined by {ref}`type-promotion`. (function-greater)= ### greater(x1, x2, /) @@ -667,7 +697,7 @@ Computes the truth value of `x1_i > x2_i` for each element `x1_i` of the input a - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). + - an array containing the element-wise results. The returned array must have a data type of `bool`. (function-greater_equal)= ### greater_equal(x1, x2, /) @@ -688,7 +718,7 @@ Computes the truth value of `x1_i >= x2_i` for each element `x1_i` of the input - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). + - an array containing the element-wise results. The returned array must have a data type of `bool`. (function-isfinite)= ### isfinite(x, /) @@ -705,7 +735,7 @@ Tests each element `x_i` of the input array `x` to determine if finite (i.e., no - **out**: _<array>_ - - an array containing test results. An element `out_i` is `True` if `x_i` is finite and `False` otherwise. The returned array must have a data type of `bool` (i.e., must be a boolean array). + - an array containing test results. An element `out_i` is `True` if `x_i` is finite and `False` otherwise. The returned array must have a data type of `bool`. (function-isinf)= ### isinf(x, /) @@ -722,7 +752,7 @@ Tests each element `x_i` of the input array `x` to determine if equal to positiv - **out**: _<array>_ - - an array containing test results. An element `out_i` is `True` if `x_i` is either positive or negative infinity and `False` otherwise. The returned array must have a data type of `bool` (i.e., must be a boolean array). + - an array containing test results. An element `out_i` is `True` if `x_i` is either positive or negative infinity and `False` otherwise. The returned array must have a data type of `bool`. (function-isnan)= ### isnan(x, /) @@ -739,7 +769,7 @@ Tests each element `x_i` of the input array `x` to determine whether the element - **out**: _<array>_ - - an array containing test results. An element `out_i` is `True` if `x_i` is `NaN` and `False` otherwise. The returned array must have a data type of `bool` (i.e., must be a boolean array). + - an array containing test results. An element `out_i` is `True` if `x_i` is `NaN` and `False` otherwise. The returned array must have a data type of `bool`. (function-less)= ### less(x1, x2, /) @@ -760,7 +790,7 @@ Computes the truth value of `x1_i < x2_i` for each element `x1_i` of the input a - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). + - an array containing the element-wise results. The returned array must have a data type of `bool`. (function-less_equal)= ### less_equal(x1, x2, /) @@ -781,7 +811,7 @@ Computes the truth value of `x1_i <= x2_i` for each element `x1_i` of the input - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). + - an array containing the element-wise results. The returned array must have a data type of `bool`. (function-log)= ### log(x, /) @@ -790,6 +820,8 @@ Calculates an implementation-dependent approximation to the natural (base `e`) l #### Special Cases +For floating-point operands, + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `0`, the result is `NaN`. - If `x_i` is either `+0` or `-0`, the result is `-infinity`. @@ -820,6 +852,8 @@ The purpose of this function is to calculate `log(1+x)` more accurately when `x` #### Special Cases +For floating-point operands, + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `-1`, the result is `NaN`. - If `x_i` is `-1`, the result is `-infinity`. @@ -846,6 +880,8 @@ Calculates an implementation-dependent approximation to the base `2` logarithm, #### Special Cases +For floating-point operands, + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `0`, the result is `NaN`. - If `x_i` is either `+0` or `-0`, the result is `-infinity`. @@ -871,6 +907,8 @@ Calculates an implementation-dependent approximation to the base `10` logarithm, #### Special Cases +For floating-point operands, + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `0`, the result is `NaN`. - If `x_i` is either `+0` or `-0`, the result is `-infinity`. @@ -892,7 +930,7 @@ Calculates an implementation-dependent approximation to the base `10` logarithm, (function-logical_and)= ### logical_and(x1, x2, /) -Computes the logical AND for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. Zeros should be considered the equivalent of `False`, while non-zeros should be considered the equivalent of `True`. +Computes the logical AND for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. Zeros are considered the equivalent of `False`, while non-zeros are considered the equivalent of `True`. #### Parameters @@ -908,12 +946,12 @@ Computes the logical AND for each element `x1_i` of the input array `x1` with th - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). + - an array containing the element-wise results. The returned array must have a data type of `bool`. (function-logical_not)= ### logical_not(x, /) -Computes the logical NOT for each element `x_i` of the input array `x`. Zeros should be considered the equivalent of `False`, while non-zeros should be considered the equivalent of `True`. +Computes the logical NOT for each element `x_i` of the input array `x`. Zeros are considered the equivalent of `False`, while non-zeros are considered the equivalent of `True`. #### Parameters @@ -925,12 +963,12 @@ Computes the logical NOT for each element `x_i` of the input array `x`. Zeros sh - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). + - an array containing the element-wise results. The returned array must have a data type of `bool`. (function-logical_or)= ### logical_or(x1, x2, /) -Computes the logical OR for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. Zeros should be considered the equivalent of `False`, while non-zeros should be considered the equivalent of `True`. +Computes the logical OR for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. Zeros are considered the equivalent of `False`, while non-zeros are considered the equivalent of `True`. #### Parameters @@ -946,12 +984,12 @@ Computes the logical OR for each element `x1_i` of the input array `x1` with the - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). + - an array containing the element-wise results. The returned array must have a data type of `bool`. (function-logical_xor)= ### logical_xor(x1, x2, /) -Computes the logical XOR for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. Zeros should be considered the equivalent of `False`, while non-zeros should be considered the equivalent of `True`. +Computes the logical XOR for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. Zeros are considered the equivalent of `False`, while non-zeros are considered the equivalent of `True`. #### Parameters @@ -967,20 +1005,22 @@ Computes the logical XOR for each element `x1_i` of the input array `x1` with th - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). + - an array containing the element-wise results. The returned array must have a data type of `bool`. (function-multiply)= ### multiply(x1, x2, /) -Calculates the product for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. For floating-point arithmetic, +Calculates the product for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. #### Special Cases +For floating-point operands, + - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. -- If `x1_i` and `x2_i` have the same mathematical sign, the result has a positive mathematical sign. -- If `x1_i` and `x2_i` have different mathematical signs, the result has a negative mathematical sign. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+0` or `-0`, the result is `NaN`. - If `x1_i` is either `+0` or `-0` and `x2_i` is either `+infinity` or `-infinity`, the result is `NaN`. +- If `x1_i` and `x2_i` have the same mathematical sign, the result has a positive mathematical sign, unless the result is `NaN`. If the result is `NaN`, the "sign" of `NaN` is implementation-defined. +- If `x1_i` and `x2_i` have different mathematical signs, the result has a negative mathematical sign, unless the result is `NaN`. If the result is `NaN`, the "sign" of `NaN` is implementation-defined. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the mathematical sign determined by the rule already stated above. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is a nonzero finite number, the result is a signed infinity with the mathematical sign determined by the rule already stated above. - If `x1_i` is a nonzero finite number and `x2_i` is either `+infinity` or `-infinity`, the result is a signed infinity with the mathematical sign determined by the rule already stated above. @@ -1043,7 +1083,7 @@ Computes the truth value of `x1_i != x2_i` for each element `x1_i` of the input - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). + - an array containing the element-wise results. The returned array must have a data type of `bool`. (function-positive)= ### positive(x, /) @@ -1069,6 +1109,8 @@ Calculates an implementation-dependent approximation of exponentiation by raisin #### Special Cases +For floating-point operands, + - If `x1_i` is not equal to `1` and `x2_i` is `NaN`, the result is `NaN`. - If `x2_i` is `+0`, the result is `1`, even if `x1_i` is `NaN`. - If `x2_i` is `-0`, the result is `1`, even if `x1_i` is `NaN`. @@ -1183,6 +1225,8 @@ Calculates an implementation-dependent approximation to the sine, having domain #### Special Cases +For floating-point operands, + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. - If `x_i` is `-0`, the result is `-0`. @@ -1207,6 +1251,8 @@ Calculates an implementation-dependent approximation to the hyperbolic sine, hav #### Special Cases +For floating-point operands, + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. - If `x_i` is `-0`, the result is `-0`. @@ -1245,10 +1291,12 @@ Squares (`x_i * x_i`) each element `x_i` of the input array `x`. (function-sqrt)= ### sqrt(x, /) -Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +infinity]`, for each element `x_i` of the input array `x`. After rounding, each result should be indistinguishable from the infinitely precise result (as required by IEEE 754). +Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +infinity]`, for each element `x_i` of the input array `x`. After rounding, each result must be indistinguishable from the infinitely precise result (as required by IEEE 754). #### Special Cases +For floating-point operands, + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is less than `0`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. @@ -1270,7 +1318,7 @@ Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +in (function-subtract)= ### subtract(x1, x2, /) -Calculates the difference for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. The result of `x1_i - x2_i` must be the same as `x1_i + (-x2_i)` and is thus governed by the same floating-point rules as addition (see [`add()`](#addx1-x2-)). +Calculates the difference for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. The result of `x1_i - x2_i` must be the same as `x1_i + (-x2_i)` and must be governed by the same floating-point rules as addition (see [`add()`](#addx1-x2-)). #### Parameters @@ -1295,6 +1343,8 @@ Calculates an implementation-dependent approximation to the tangent, having doma #### Special Cases +For floating-point operands, + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. - If `x_i` is `-0`, the result is `-0`. @@ -1304,7 +1354,7 @@ Calculates an implementation-dependent approximation to the tangent, having doma - **x**: _<array>_ - - input array whose elements are each expressed in radians. + - input array whose elements are expressed in radians. #### Returns @@ -1319,6 +1369,8 @@ Calculates an implementation-dependent approximation to the hyperbolic tangent, #### Special Cases +For floating-point operands, + - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `+0`, the result is `+0`. - If `x_i` is `-0`, the result is `-0`. diff --git a/spec/API_specification/function_and_method_signatures.md b/spec/API_specification/function_and_method_signatures.md index 1c51b47ea..d199bcbb6 100644 --- a/spec/API_specification/function_and_method_signatures.md +++ b/spec/API_specification/function_and_method_signatures.md @@ -32,10 +32,9 @@ Function signatures in this standard adhere to the following: is called `x`. For functions that have multiple array parameters, those parameters are called `xi` with `i = 1, 2, ...` (i.e., `x1`, `x2`). -4. Type annotations are left out of the signatures themselves for readability; - they are added to the descriptions of individual parameters however. In code - which aims to adhere to the standard, adding type annotations is strongly - recommended. +4. Type annotations are left out of the signatures themselves for readability; however, + they are added to individual parameter descriptions. For code which aims to + adhere to the standard, adding type annotations is strongly recommended. A function signature and description will look like: @@ -59,5 +58,5 @@ funcname(x1, x2, /, *, key1=-1, key2=None) description ``` -Method signatures will follow the same conventions and, modulo the addition of +Method signatures will follow the same conventions modulo the addition of `self`. diff --git a/spec/API_specification/indexing.md b/spec/API_specification/indexing.md index b1fd6b171..09e73aa24 100644 --- a/spec/API_specification/indexing.md +++ b/spec/API_specification/indexing.md @@ -61,7 +61,7 @@ A[i:j:k] ```{note} -Slice syntax can be equivalently achieved using the Python built-in [`slice()`](https://docs.python.org/3/library/functions.html#slice) API. From the perspective from `A`, the behavior of `A[i:j:k]` and `A[slice(i, j, k)]` is indistinguishable (i.e., both retrieve the same set of items from `__getitem__`). +Slice syntax can be equivalently achieved using the Python built-in [`slice()`](https://docs.python.org/3/library/functions.html#slice) API. From the perspective of `A`, the behavior of `A[i:j:k]` and `A[slice(i, j, k)]` is indistinguishable (i.e., both retrieve the same set of items from `__getitem__`). ``` Using a slice to index a single array axis must select `m` elements with index values diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index e99877255..ba92aa7b0 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -173,9 +173,9 @@ Computes the matrix or vector norm of `x`. If `None`, - - if `x` is one-dimensional, the function computes the vector norm. - - if `x` is two-dimensional, the function computes the matrix norm. - - if `x` has more than two dimensions, the function computes the vector norm over all array values (i.e., equivalent to computing the vector norm of a flattened array). + - if `x` is one-dimensional, the function must compute the vector norm. + - if `x` is two-dimensional, the function must compute the matrix norm. + - if `x` has more than two dimensions, the function must compute the vector norm over all array values (i.e., equivalent to computing the vector norm of a flattened array). Negative indices must be supported. Default: `None`. @@ -222,8 +222,8 @@ Computes the matrix or vector norm of `x`. If `None`, - - if matrix (or matrices), the function computes the Frobenius norm. - - if vector (or vectors), the function computes the L2-norm (Euclidean norm). + - if matrix (or matrices), the function must compute the Frobenius norm. + - if vector (or vectors), the function must compute the L2-norm (Euclidean norm). Default: `None`. @@ -231,7 +231,7 @@ Computes the matrix or vector norm of `x`. - **out**: _<array>_ - - an array containing the norms. If `axis` is `None`, the output array is a zero-dimensional array containing a vector norm. If `axis` is a scalar value (`int` or `float`), the output array has a rank which is one less than the rank of `x`. If `axis` is a 2-tuple, the output array has a rank which is two less than the rank of `x`. The returned array must have the same data type as `x`. + - an array containing the norms. If `axis` is `None`, the output array must be a zero-dimensional array containing a vector norm. If `axis` is a scalar value (`int` or `float`), the output array must have a rank which is one less than the rank of `x`. If `axis` is a 2-tuple, the output array must have a rank which is two less than the rank of `x`. The returned array must have the same data type as `x`. (function-outer)= ### outer(x1, x2, /) @@ -312,7 +312,7 @@ Returns the sum along the specified diagonals. If `x` has more than two dimensio - **out**: _<array>_ - - if `x` is a two-dimensional array, a zero-dimensional array containing the trace; otherwise, a multi-dimensional array containing the traces. + - if `x` is a two-dimensional array, the returned array must be a zero-dimensional array containing the trace; otherwise, the returned array must be a multi-dimensional array containing the traces. The shape of a multi-dimensional output array is determined by removing `axis1` and `axis2` and storing the traces in the last array dimension. For example, if `x` has rank `k` and shape `(I, J, K, ..., L, M, N)` and `axis1=-2` and `axis1=-1`, then a multi-dimensional output array has rank `k-2` and shape `(I, J, K, ..., L)` where @@ -335,7 +335,7 @@ Transposes (or permutes the axes (dimensions)) of an array `x`. - **axes**: _Optional\[ Tuple\[ int, ... ] ]_ - - tuple containing a permutation of `(0, 1, ..., N-1)` where `N` is the number of axes (dimensions) of `x`. If `None`, the axes (dimensions) are permuted in reverse order (i.e., equivalent to setting `axes=(N-1, ..., 1, 0)`). Default: `None`. + - tuple containing a permutation of `(0, 1, ..., N-1)` where `N` is the number of axes (dimensions) of `x`. If `None`, the axes (dimensions) must be permuted in reverse order (i.e., equivalent to setting `axes=(N-1, ..., 1, 0)`). Default: `None`. #### Returns diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md index 9714e6d59..3243c2830 100644 --- a/spec/API_specification/manipulation_functions.md +++ b/spec/API_specification/manipulation_functions.md @@ -114,11 +114,11 @@ Rolls array elements along a specified axis. Array elements that roll beyond the - **shift**: _Union\[ int, Tuple\[ int, ... ] ]_ - - number of places by which the elements are shifted. If `shift` is a tuple, then `axis` must be a tuple of the same size, and each of the given axes must be shifted by the corresponding element in `shift`. If `shift` is an `int` and `axis` a tuple, then the same `shift` is used for all specified axes. If a shift is positive, then array elements are shifted positively (toward larger indices) along the dimension of `axis`. If a shift is negative, then array elements are shifted negatively (toward smaller indices) along the dimension of `axis`. + - number of places by which the elements are shifted. If `shift` is a tuple, then `axis` must be a tuple of the same size, and each of the given axes must be shifted by the corresponding element in `shift`. If `shift` is an `int` and `axis` a tuple, then the same `shift` must be used for all specified axes. If a shift is positive, then array elements must be shifted positively (toward larger indices) along the dimension of `axis`. If a shift is negative, then array elements must be shifted negatively (toward smaller indices) along the dimension of `axis`. - **axis**: _Optional\[ Union\[ int, Tuple\[ int, ... ] ] ]_ - - axis (or axes) along which elements to shift. If `axis` is `None`, the array is flattened, shifted, and then restored to its original shape. Default: `None`. + - axis (or axes) along which elements to shift. If `axis` is `None`, the array must be flattened, shifted, and then restored to its original shape. Default: `None`. #### Returns diff --git a/spec/API_specification/sorting_functions.md b/spec/API_specification/sorting_functions.md index 1d8cc1e27..f88b01a17 100644 --- a/spec/API_specification/sorting_functions.md +++ b/spec/API_specification/sorting_functions.md @@ -25,7 +25,7 @@ Returns the indices that sort an array `x` along a specified axis. - **axis**: _int_ - - axis along which to sort. If set to `-1`, the function sorts along the last axis. Default: `-1`. + - axis along which to sort. If set to `-1`, the function must sort along the last axis. Default: `-1`. - **descending**: _bool_ @@ -54,11 +54,11 @@ Returns a sorted copy of an input array `x`. - **axis**: _int_ - - axis along which to sort. If set to `-1`, the function sorts along the last axis. Default: `-1`. + - axis along which to sort. If set to `-1`, the function must sort along the last axis. Default: `-1`. - **descending**: _bool_ - - sort order. If `True`, the array is sorted in descending order (by value). If `False`, the array is sorted in ascending order (by value). Default: `False`. + - sort order. If `True`, the array must be sorted in descending order (by value). If `False`, the array must be sorted in ascending order (by value). Default: `False`. - **stable**: _bool_ diff --git a/spec/API_specification/type_promotion.md b/spec/API_specification/type_promotion.md index 3ec428f0a..73a025a2e 100644 --- a/spec/API_specification/type_promotion.md +++ b/spec/API_specification/type_promotion.md @@ -18,10 +18,10 @@ In code, use the data type objects specified in {ref}`data-types` (e.g., `int16` -The following type promotion tables specify the casting behaviour for -operations involving two arrays. In situations where more than two arrays -participate, the table can be used repeatedy on pairs of input arrays (the -result does not depend on the order in which the arrays are given). +The following type promotion tables specify the casting behavior for +operations involving two array operands. When more than two array operands +participate, application of the promotion tables is associative (i.e., the +result does not depend on operand order). ### Signed integer type promotion table @@ -77,7 +77,7 @@ where ### Notes -- Type promotion rules **strictly** apply when determining the common result type for two **array** operands during an arithmetic operation, regardless of array dimension. Accordingly, zero-dimensional arrays are subject to the same type promotion rules as dimensional arrays. +- Type promotion rules must apply when determining the common result type for two **array** operands during an arithmetic operation, regardless of array dimension. Accordingly, zero-dimensional arrays must be subject to the same type promotion rules as dimensional arrays. - Type promotion of non-numerical data types to numerical data types is unspecified (e.g., `bool` to `intxx` or `floatxx`). - Non-array ("scalar") operands must not participate in type promotion. @@ -90,15 +90,16 @@ because behavior varies between implementations. ### Mixing arrays with Python scalars -Using Python scalars (i.e. instances of `bool`, `int`, `float`) together with arrays must be supported for: +Using Python scalars (i.e., instances of `bool`, `int`, `float`) together with +arrays must be supported for: -- `array scalar`, -- `scalar array`, +- `array scalar` +- `scalar array` where `` is a built-in operator (see {ref}`operators` for operators -supported by the array object), and `scalar` is of the same kind as the array -dtype (e.g. a `float` scalar if the array's dtype is `float32` or `float64`). -The expected behaviour is then equivalent to: +supported by the array object) and `scalar` is of the same kind as the array +dtype (e.g., a `float` scalar if the array's dtype is `float32` or `float64`). +The expected behavior is then equivalent to: 1. Convert the scalar to a 0-D array with the same dtype as that of the array used in the expression. @@ -107,7 +108,7 @@ The expected behaviour is then equivalent to: ```{note} -Note again that mixed integer and floating-point behaviour is not specified. -Mixing an integer array with a Python float may give `float32`, `float64`, -or raise an exception - behaviour of implementations will differ. +Mixed integer and floating-point behavior is not specified. Mixing an integer +array with a Python float may give `float32`, `float64`, or raise an exception - +behavior of implementations will differ. ``` diff --git a/spec/API_specification/utility_functions.md b/spec/API_specification/utility_functions.md index 53086979a..aad65a71b 100644 --- a/spec/API_specification/utility_functions.md +++ b/spec/API_specification/utility_functions.md @@ -38,7 +38,7 @@ Tests whether all input array elements evaluate to `True` along a specified axis - **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 have a data type of `bool` (i.e., must be a boolean array). + - if a logical AND reduction was performed over the entire array, the returned array must be a zero-dimensional array containing the test result; otherwise, the returned array must be a non-zero-dimensional array containing the test results. The returned array must have a data type of `bool`. (function-any)= ### any(x, /, *, axis=None, keepdims=False) @@ -63,4 +63,4 @@ Tests whether any input array element evaluates to `True` along a specified axis - **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 have a data type of `bool` (i.e., must be a boolean array). + - if a logical OR reduction was performed over the entire array, the returned array must be a zero-dimensional array containing the test result; otherwise, the returned array must be a non-zero-dimensional array containing the test results. The returned array must have a data type of `bool`. diff --git a/spec/future_API_evolution.md b/spec/future_API_evolution.md index 5a5ffcdd5..719b554e3 100644 --- a/spec/future_API_evolution.md +++ b/spec/future_API_evolution.md @@ -15,13 +15,13 @@ and real-world experience from use of those implementations is available. ## Backwards compatibility -Functions, objects, keywords and specified behaviour are added to this API standard +Functions, objects, keywords and specified behavior are added to this API standard only if those are already present in multiple existing array libraries, and if there is data that those APIs are used. Therefore it is highly unlikely that future versions of this standard will make backwards-incompatible changes. The aim is for future versions to be 100% backwards compatible with older versions. -Any exceptions must have strong rationales, and be clearly documented in the updated +Any exceptions must have strong rationales and be clearly documented in the updated API specification. diff --git a/spec/purpose_and_scope.md b/spec/purpose_and_scope.md index b2afc7f39..17eb6020a 100644 --- a/spec/purpose_and_scope.md +++ b/spec/purpose_and_scope.md @@ -432,3 +432,4 @@ a one-dimensional array. The following referenced documents are indispensable for the application of this specification. - __IEEE 754-2019: IEEE Standard for Floating-Point Arithmetic.__ Institute of Electrical and Electronic Engineers, New York (2019). +- Scott Bradner. 1997. "Key words for use in RFCs to Indicate Requirement Levels". RFC 2119. doi:[10.17487/rfc2119](https://tools.ietf.org/html/rfc2119).