From 08fc81cce4a4d1b1fba187f348d999a3835db6e2 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 Nov 2020 00:41:40 -0600 Subject: [PATCH 01/19] Add normative reference --- spec/purpose_and_scope.md | 1 + 1 file changed, 1 insertion(+) diff --git a/spec/purpose_and_scope.md b/spec/purpose_and_scope.md index b2afc7f39..0fc853dad 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. "Keys words for use in RFCs to Indicate Requirement Levels". RFC 2119. doi:[10.17487/rfc2119](https://tools.ietf.org/html/rfc2119). From 617a90ba7a113cd4fc4caaa5694968bb70157f87 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 Nov 2020 01:16:04 -0600 Subject: [PATCH 02/19] Update copy --- spec/API_specification/array_object.md | 81 ++++++++++++++------------ 1 file changed, 45 insertions(+), 36 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 34ac6e061..b98f134af 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 @@ -251,7 +260,7 @@ Transpose of the array. (method-__abs__)= ### \_\_abs\_\_(x, /) -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). +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). For floating-point operands, #### Special Cases @@ -279,7 +288,7 @@ 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`. For floating-point operands, #### Special Cases @@ -372,7 +381,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 +433,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 +464,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 +512,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 +522,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 +569,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,13 +626,13 @@ 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`. For floating-point operands, #### Special Cases - 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` and `x2_i` are not `NaN` and have the same mathematical sign, the result has a positive mathematical sign. +- If `x1_i` and `x2_i` are not `NaN` and 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` 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. @@ -756,7 +765,7 @@ Element-wise results must equal the results returned by the equivalent element-w (method-__pow__)= ### \_\_pow\_\_(x1, x2, /) -Calculates an implementation-dependent approximation of exponentiation by raising each element `x1_i` (the base) of an array instance `x1` to the power of `x2_i` (the exponent), where `x2_i` is the corresponding element of the array `x2`. +Calculates an implementation-dependent approximation of exponentiation by raising each element `x1_i` (the base) of an array instance `x1` to the power of `x2_i` (the exponent), where `x2_i` is the corresponding element of the array `x2`. For floating-point operands, #### Special Cases @@ -840,7 +849,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 thus governed by the same floating-point rules as addition (see [`__add__()`](#__add__x1-x2-)). #### Parameters @@ -866,7 +875,7 @@ 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`. For floating-point operands, #### Special Cases From a98b8cf05b08d26d0f3f0556f287c6bf7dafa257 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 Nov 2020 01:17:54 -0600 Subject: [PATCH 03/19] Add missing hyphens --- spec/API_specification/constants.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 From 3ace5bf8b13ea24f5c7e99ebbb732f1eb3bfd4f9 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 Nov 2020 01:21:15 -0600 Subject: [PATCH 04/19] Update copy --- spec/API_specification/creation_functions.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 80fb4c11f..109952a0a 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} + + Note: that the step size changes when `endpoint` is `False`. + ``` - **num**: _int_ From c6f5724d042b02f9a4ce146860f8bf6762232004 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 Nov 2020 03:22:49 -0600 Subject: [PATCH 05/19] Update copy --- spec/API_specification/array_object.md | 22 +++- .../elementwise_functions.md | 104 +++++++++++++----- 2 files changed, 94 insertions(+), 32 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index b98f134af..8cbadeb24 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -260,9 +260,11 @@ Transpose of the array. (method-__abs__)= ### \_\_abs\_\_(x, /) -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). For floating-point operands, +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`. @@ -288,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 operands, +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`. @@ -626,10 +630,12 @@ 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 operands, +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` are not `NaN` and have the same mathematical sign, the result has a positive mathematical sign. - If `x1_i` and `x2_i` are not `NaN` and have different mathematical signs, the result has a negative mathematical sign. @@ -765,10 +771,12 @@ Element-wise results must equal the results returned by the equivalent element-w (method-__pow__)= ### \_\_pow\_\_(x1, x2, /) -Calculates an implementation-dependent approximation of exponentiation by raising each element `x1_i` (the base) of an array instance `x1` to the power of `x2_i` (the exponent), where `x2_i` is the corresponding element of the array `x2`. For floating-point operands, +Calculates an implementation-dependent approximation of exponentiation by raising each element `x1_i` (the base) of an array instance `x1` to the power of `x2_i` (the exponent), where `x2_i` is the corresponding element of the array `x2`. #### 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`. @@ -849,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 must 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 @@ -875,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 operands, +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/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index 7cf30a149..d10cbb63b 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,18 +1005,20 @@ 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` and `x2_i` are not `NaN` and have the same mathematical sign, the result has a positive mathematical sign. +- If `x1_i` and `x2_i` are not `NaN` and 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` 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. @@ -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`. From 4adddc7c5fe96f4e4c6ceeec8433fc2ec2fd19e3 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 Nov 2020 03:29:19 -0600 Subject: [PATCH 06/19] Fix grammar --- spec/API_specification/function_and_method_signatures.md | 9 ++++----- spec/API_specification/indexing.md | 2 +- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/spec/API_specification/function_and_method_signatures.md b/spec/API_specification/function_and_method_signatures.md index 1c51b47ea..18e944629 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; hower, + 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 From 4fe67db98d3823aef76cc1e2cad05ed059d0860d Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 Nov 2020 03:33:55 -0600 Subject: [PATCH 07/19] Update copy --- .../linear_algebra_functions.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) 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 From 6642c53c3b53f98f015b275524873f65698dc218 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 Nov 2020 03:37:06 -0600 Subject: [PATCH 08/19] Update copy --- spec/API_specification/manipulation_functions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 From e298d19cd063eecb2e34d91ac43b4071baa73443 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 Nov 2020 03:40:31 -0600 Subject: [PATCH 09/19] Update copy --- spec/API_specification/sorting_functions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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_ From 03bd512a58657940026323751bc1425ad942da93 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 Nov 2020 03:50:24 -0600 Subject: [PATCH 10/19] Update copy --- spec/API_specification/type_promotion.md | 29 ++++++++++++------------ 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/spec/API_specification/type_promotion.md b/spec/API_specification/type_promotion.md index 3ec428f0a..b9d900bb8 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 arrays. When more than two arrays participate, +application of the promotion tables is associative (i.e., the result does not +depend on array 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. ``` From 4c6ce638ef20134db50c01d80d7435c333d2e716 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 Nov 2020 03:51:50 -0600 Subject: [PATCH 11/19] 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 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`. From fbec15a8b6739c738646e46aeaf7e22d73c231fd Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 Nov 2020 04:14:44 -0600 Subject: [PATCH 12/19] Update copy --- spec/future_API_evolution.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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. From 706cf4abee1658432bcdbe08ae7ae018884bbbc8 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 Nov 2020 04:17:52 -0600 Subject: [PATCH 13/19] Update note --- spec/API_specification/creation_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 109952a0a..741cff989 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -183,7 +183,7 @@ Returns evenly spaced numbers over a specified interval. ```{note} - Note: that the step size changes when `endpoint` is `False`. + The step size changes when `endpoint` is `False`. ``` - **num**: _int_ From 993ca629e69c5faa370c7bd2e36dd26f1454e9ed Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 Nov 2020 04:18:41 -0600 Subject: [PATCH 14/19] Fix typo --- spec/API_specification/function_and_method_signatures.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/function_and_method_signatures.md b/spec/API_specification/function_and_method_signatures.md index 18e944629..d199bcbb6 100644 --- a/spec/API_specification/function_and_method_signatures.md +++ b/spec/API_specification/function_and_method_signatures.md @@ -32,7 +32,7 @@ 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; hower, +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. From 41df02bf87f00ca3b2ef430bf7490e4d41386236 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 Nov 2020 04:19:21 -0600 Subject: [PATCH 15/19] Fix missing parenthesis --- spec/API_specification/type_promotion.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/type_promotion.md b/spec/API_specification/type_promotion.md index b9d900bb8..30abdb6e3 100644 --- a/spec/API_specification/type_promotion.md +++ b/spec/API_specification/type_promotion.md @@ -21,7 +21,7 @@ In code, use the data type objects specified in {ref}`data-types` (e.g., `int16` The following type promotion tables specify the casting behavior for operations involving two arrays. When more than two arrays participate, application of the promotion tables is associative (i.e., the result does not -depend on array order. +depend on array order). ### Signed integer type promotion table From 6cd9336442428aa7594b68175a6edff7fe3f1541 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 Nov 2020 04:20:14 -0600 Subject: [PATCH 16/19] Update copy --- spec/API_specification/type_promotion.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/type_promotion.md b/spec/API_specification/type_promotion.md index 30abdb6e3..73a025a2e 100644 --- a/spec/API_specification/type_promotion.md +++ b/spec/API_specification/type_promotion.md @@ -19,9 +19,9 @@ In code, use the data type objects specified in {ref}`data-types` (e.g., `int16` The following type promotion tables specify the casting behavior for -operations involving two arrays. When more than two arrays participate, -application of the promotion tables is associative (i.e., the result does not -depend on array order). +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 From 615511b784683b37e0a907dc24dd71217554c9f4 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 Nov 2020 04:56:14 -0600 Subject: [PATCH 17/19] Update special cases --- spec/API_specification/array_object.md | 4 ++-- spec/API_specification/elementwise_functions.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 8cbadeb24..b468576ab 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -637,10 +637,10 @@ Calculates the product for each element `x1_i` of an array instance `x1` with th For floating-point operands, - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. -- If `x1_i` and `x2_i` are not `NaN` and have the same mathematical sign, the result has a positive mathematical sign. -- If `x1_i` and `x2_i` are not `NaN` and 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` (in which case, 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` (in which case, 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. diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index d10cbb63b..6a30cf247 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -1017,10 +1017,10 @@ Calculates the product for each element `x1_i` of the input array `x1` with the For floating-point operands, - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. -- If `x1_i` and `x2_i` are not `NaN` and have the same mathematical sign, the result has a positive mathematical sign. -- If `x1_i` and `x2_i` are not `NaN` and 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` (in which case, 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` (in which case, 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. From c355941dbebca5e37efdb08b6dfa7ed3159529f2 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 Nov 2020 05:00:25 -0600 Subject: [PATCH 18/19] Update copy --- spec/API_specification/array_object.md | 4 ++-- spec/API_specification/elementwise_functions.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index b468576ab..cd6400745 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -639,8 +639,8 @@ 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 `+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` (in which case, 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` (in which case, the "sign" of `NaN` is implementation-defined). +- 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. diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index 6a30cf247..f8c3abaf0 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -1019,8 +1019,8 @@ 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 `+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` (in which case, 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` (in which case, the "sign" of `NaN` is implementation-defined). +- 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. From 51b7f7aedd6e091593c568f00921bf56550edc80 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 Nov 2020 12:00:15 -0600 Subject: [PATCH 19/19] Fix typo --- spec/purpose_and_scope.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/purpose_and_scope.md b/spec/purpose_and_scope.md index 0fc853dad..17eb6020a 100644 --- a/spec/purpose_and_scope.md +++ b/spec/purpose_and_scope.md @@ -432,4 +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. "Keys words for use in RFCs to Indicate Requirement Levels". RFC 2119. doi:[10.17487/rfc2119](https://tools.ietf.org/html/rfc2119). +- 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).