diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 6aec9e82e..fcfedd234 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -33,7 +33,7 @@ Returns evenly spaced values within the half-open interval `[start, stop)` as a - **dtype**: _Optional\[ <dtype> ]_ - - output array data type. Default: `None`. + - output array data type. If `dtype` is `None`, the output array data type must be the default floating-point data type. Default: `None`. #### Returns @@ -53,7 +53,7 @@ Returns an uninitialized array having a specified `shape`. - **dtype**: _Optional\[ <dtype> ]_ - - output array data type. Default: `None`. + - output array data type. If `dtype` is `None`, the output array data type must be the default floating-point data type. Default: `None`. #### Returns @@ -101,7 +101,7 @@ Returns a two-dimensional array with ones on the `k`th diagonal and zeros elsewh - **dtype**: _Optional\[ <dtype> ]_ - - output array data type. Default: `None`. + - output array data type. If `dtype` is `None`, the output array data type must be the default floating-point data type. Default: `None`. #### Returns @@ -125,7 +125,7 @@ Returns a new array having a specified `shape` and filled with `fill_value`. - **dtype**: _Optional\[ <dtype> ]_ - - output array data type. Default: `None`. + - output array data type. If `dtype` is `None`, the output array data type must be the default floating-point data type. Default: `None`. #### Returns @@ -179,7 +179,7 @@ Returns evenly spaced numbers over a specified interval. - **dtype**: _Optional\[ <dtype> ]_ - - output array data type. Default: `None`. + - output array data type. If `dtype` is `None`, the output array data type must be the default floating-point data type. Default: `None`. - **endpoint**: _Optional\[ bool ]_ @@ -203,7 +203,7 @@ Returns a new array having a specified `shape` and filled with ones. - **dtype**: _Optional\[ <dtype> ]_ - - output array data type. Default: `None`. + - output array data type. If `dtype` is `None`, the output array data type must be the default floating-point data type. Default: `None`. #### Returns @@ -243,7 +243,7 @@ Returns a new array having a specified `shape` and filled with zeros. - **dtype**: _Optional\[ <dtype> ]_ - - output array data type. Default: `None`. + - output array data type. If `dtype` is `None`, the output array data type must be the default floating-point data type. Default: `None`. #### Returns diff --git a/spec/API_specification/data_types.md b/spec/API_specification/data_types.md index 3bde5a1a9..0d6f6d99d 100644 --- a/spec/API_specification/data_types.md +++ b/spec/API_specification/data_types.md @@ -6,16 +6,28 @@ A conforming implementation of the array API standard must provide and support the following data types. +.. note:: + + Data types ("dtypes") are objects that can be used as `dtype` specifiers in functions and methods (e.g., `zeros((2, 3), dtype=float32)`). A conforming implementation may add methods or attributes to data type objects; however, these methods and attributes are not included in this specification. + +.. note:: + + Implementations may provide other ways to specify data types (e.g., + `zeros((2, 3), dtype='f4')`); however, these are not included in this specification. + A conforming implementation of the array API standard may provide and support additional data types beyond those described in this specification. +A conforming implementation of the array API standard must define a default floating-point data type (either `float32` or `float64`). + .. note:: - These dtypes are objects that can be used as dtype specifiers in functions and methods (e.g., `zeros((2, 3), dtype=float32)`). A conforming implementation may add methods or attributes to dtype objects; these are not part of this specification however. + The default floating-point data type should be clearly defined in a conforming library's documentation. + +A conforming implementation of the array API standard must define a default data type for an array index (either `int32` or `int64`). .. note:: - Implementations may provide others ways to specify dtypes (e.g., - `zeros((2, 3), dtype='f4')`); these are not part of this specification however. + The default array index data type should be clearly defined in a conforming library's documentation. ## bool diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index 454363488..cd27d0b0f 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -34,7 +34,7 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e - **out**: _<array>_ - - an array containing the absolute value of each element in `x`. + - an array containing the absolute value of each element in `x`. The returned array must have the same data type as `x`. ### # acos(x, /) @@ -57,7 +57,7 @@ Calculates an implementation-dependent approximation of the principal value of t - **out**: _<array>_ - - an array containing the inverse cosine of each element in `x`. + - an array containing the inverse cosine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # acosh(x, /) @@ -80,7 +80,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c - **out**: _<array>_ - - an array containing the inverse hyperbolic cosine of each element in `x`. + - an array containing the inverse hyperbolic cosine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # add(x1, x2, /) @@ -124,7 +124,7 @@ Calculates the sum for each element `x1_i` of the input array `x1` with the resp - **out**: _<array>_ - - an array containing the element-wise sums. + - an array containing the element-wise sums. The returned array must have a data type determined by :ref:`type-promotion` rules. ### # asin(x, /) @@ -148,7 +148,7 @@ Calculates an implementation-dependent approximation of the principal value of t - **out**: _<array>_ - - an array containing the inverse sine of each element in `x`. + - an array containing the inverse sine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # asinh(x, /) @@ -172,7 +172,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic s - **out**: _<array>_ - - an array containing the inverse hyperbolic sine of each element in `x`. + - an array containing the inverse hyperbolic sine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # atan(x, /) @@ -196,7 +196,7 @@ Calculates an implementation-dependent approximation of the principal value of t - **out**: _<array>_ - - an array containing the inverse tangent of each element in `x`. + - an array containing the inverse tangent of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # atan2(x1, x2, /) @@ -250,7 +250,7 @@ By IEEE 754 convention, the inverse tangent of the quotient `x1/x2` is defined f - **out**: _<array>_ - - an array containing the inverse tangent of the quotient `x1/x2`. + - an array containing the inverse tangent of the quotient `x1/x2`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # atanh(x, /) @@ -276,7 +276,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic t - **out**: _<array>_ - - an array containing the inverse hyperbolic tangent of each element in `x`. + - an array containing the inverse hyperbolic tangent of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # bitwise_and(x1, x2, /) @@ -296,7 +296,7 @@ Computes the bitwise AND of the underlying binary representation of each element - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion` rules. ### # bitwise_left_shift(x1, x2, /) @@ -310,13 +310,13 @@ Shifts the bits of each element `x1_i` of the input array `x1` to the left by ap - **x2**: _<array>_ - - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). Must have an integer or boolean data type. Each element must be greater than or equal to `0`. + - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). Must have an integer data type. Each element must be greater than or equal to `0`. #### Returns - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have the same data type as `x1`. ### # bitwise_invert(x, /) @@ -332,7 +332,7 @@ Inverts (flips) each bit for each element `x_i` of the input array `x`. - **out**: _<array>_ - - an array containing the element-wise results. Must have the same data type as `x`. + - an array containing the element-wise results. The returned array must have the same data type as `x`. ### # bitwise_or(x1, x2, /) @@ -352,7 +352,7 @@ Computes the bitwise OR of the underlying binary representation of each element - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion` rules. ### # bitwise_right_shift(x1, x2, /) @@ -366,13 +366,13 @@ Shifts the bits of each element `x1_i` of the input array `x1` to the right acco - **x2**: _<array>_ - - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). Must have an integer or boolean data type. Each element must be greater than or equal to `0`. + - second input array. Must be compatible with `x1` (see :ref:`broadcasting`). Must have an integer data type. Each element must be greater than or equal to `0`. #### Returns - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have the same data type as `x1`. ### # bitwise_xor(x1, x2, /) @@ -392,7 +392,7 @@ Computes the bitwise XOR of the underlying binary representation of each element - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion` rules. ### # ceil(x, /) @@ -412,7 +412,7 @@ Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest - **out**: _<array>_ - - an array containing the rounded result for each element in `x`. + - an array containing the rounded result for each element in `x`. The returned array must have the same data type as `x`. ### # cos(x, /) @@ -436,7 +436,7 @@ Calculates an implementation-dependent approximation to the cosine, having domai - **out**: _<array>_ - - an array containing the cosine of each element in `x`. + - an array containing the cosine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # cosh(x, /) @@ -458,7 +458,7 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine, h - **out**: _<array>_ - - an array containing the hyperbolic cosine of each element in `x`. + - an array containing the hyperbolic cosine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # divide(x1, x2, /) @@ -492,7 +492,7 @@ Calculates the division for each element `x1_i` of the input array `x1` with the - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # equal(x1, x2, /) @@ -512,7 +512,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. + - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). ### # exp(x, /) @@ -536,7 +536,7 @@ Calculates an implementation-dependent approximation to the exponential function - **out**: _<array>_ - - an array containing the evaluated exponential function result for each element in `x`. + - an array containing the evaluated exponential function result for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # expm1(x, /) @@ -564,7 +564,7 @@ Calculates an implementation-dependent approximation to `exp(x)-1`, having domai - **out**: _<array>_ - - an array containing the evaluated result for each element in `x`. + - an array containing the evaluated result for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # floor(x, /) @@ -584,7 +584,7 @@ Rounds each element `x_i` of the input array `x` to the greatest (i.e., closest - **out**: _<array>_ - - an array containing the rounded result for each element in `x`. + - an array containing the rounded result for each element in `x`. The returned array must have the same data type as `x`. ### # floor_divide(x1, x2, /) @@ -604,7 +604,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. + - an array containing the element-wise results. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # greater(x1, x2, /) @@ -624,7 +624,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. + - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). ### # greater_equal(x1, x2, /) @@ -644,7 +644,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. + - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). ### # isfinite(x, /) @@ -660,7 +660,7 @@ Tests each element `x_i` of the input array `x` to determine if finite (i.e., no - **out**: _<array>_ - - an array, whose underlying data type is `bool`, containing test results. An element `out_i` is `True` if `x_i` is finite and `False` otherwise. + - 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). ### # isinf(x, /) @@ -676,7 +676,7 @@ Tests each element `x_i` of the input array `x` to determine if equal to positiv - **out**: _<array>_ - - an array, whose underlying data type is `bool`, containing test results. An element `out_i` is `True` if `x_i` is either positive or negative infinity and `False` otherwise. + - 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). ### # isnan(x, /) @@ -692,7 +692,7 @@ Tests each element `x_i` of the input array `x` to determine whether the element - **out**: _<array>_ - - an array, whose underlying data type is `bool`, containing test results. An element `out_i` is `True` if `x_i` is `NaN` and `False` otherwise. + - 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). ### # less(x1, x2, /) @@ -712,7 +712,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. + - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). ### # less_equal(x1, x2, /) @@ -732,7 +732,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. + - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). ### # log(x, /) @@ -756,7 +756,7 @@ Calculates an implementation-dependent approximation to the natural (base `e`) l - **out**: _<array>_ - - an array containing the evaluated natural logarithm for each element in `x`. + - an array containing the evaluated natural logarithm for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # log1p(x, /) @@ -785,7 +785,7 @@ Calculates an implementation-dependent approximation to `log(1+x)`, where `log` - **out**: _<array>_ - - an array containing the evaluated result for each element in `x`. + - an array containing the evaluated result for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # log2(x, /) @@ -809,7 +809,7 @@ Calculates an implementation-dependent approximation to the base `2` logarithm, - **out**: _<array>_ - - an array containing the evaluated base `2` logarithm for each element in `x`. + - an array containing the evaluated base `2` logarithm for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # log10(x, /) @@ -833,7 +833,7 @@ Calculates an implementation-dependent approximation to the base `10` logarithm, - **out**: _<array>_ - - an array containing the evaluated base `10` logarithm for each element in `x`. + - an array containing the evaluated base `10` logarithm for each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # logical_and(x1, x2, /) @@ -853,7 +853,7 @@ 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. + - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). ### # logical_not(x, /) @@ -869,7 +869,7 @@ 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. + - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). ### # logical_or(x1, x2, /) @@ -889,7 +889,7 @@ 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. + - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). ### # logical_xor(x1, x2, /) @@ -909,7 +909,7 @@ 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. + - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). ### # multiply(x1, x2, /) @@ -945,7 +945,7 @@ Calculates the product for each element `x1_i` of the input array `x1` with the - **out**: _<array>_ - - an array containing the element-wise products. + - an array containing the element-wise products. The returned array must have a data type determined by :ref:`type-promotion` rules. ### # negative(x, /) @@ -961,7 +961,7 @@ Computes the numerical negative of each element `x_i` (i.e., `y_i = -x_i`) of th - **out**: _<array>_ - - an array containing the evaluated result for each element in `x`. The returned array must have a supported numerical data type. + - an array containing the evaluated result for each element in `x`. The returned array must have a data type determined by :ref:`type-promotion` rules. ### # not_equal(x1, x2, /) @@ -981,7 +981,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. + - an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array). ### # positive(x, /) @@ -997,7 +997,7 @@ Computes the numerical positive of each element `x_i` (i.e., `y_i = +x_i`) of th - **out**: _<array>_ - - an array containing the evaluated result for each element in `x`. The returned array must have a supported numerical data type. + - an array containing the evaluated result for each element in `x`. The returned array must have the same data type as `x`. ### # pow(x1, x2, /) @@ -1044,7 +1044,7 @@ Calculates an implementation-dependent approximation of exponentiation by raisin - **out**: _<array>_ - - an array containing the element-wise results. + - an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion` rules. ### # remainder(x1, x2, /) @@ -1064,7 +1064,7 @@ Returns the remainder of division for each element `x1_i` of the input array `x1 - **out**: _<array>_ - - an array containing the element-wise results. Each element-wise result must have the same sign as the respective element `x2_i`. + - an array containing the element-wise results. Each element-wise result must have the same sign as the respective element `x2_i`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # round(x, /) @@ -1085,7 +1085,7 @@ Rounds each element `x_i` of the input array `x` to the nearest integer-valued n - **out**: _<array>_ - - an array containing the rounded result for each element in `x`. + - an array containing the rounded result for each element in `x`. The returned array must have the same data type as `x`. ### # sign(x, /) @@ -1107,7 +1107,7 @@ Returns an indication of the sign of a number for each element `x_i` of the inpu - **out**: _<array>_ - - an array containing the evaluated result for each element in `x`. + - an array containing the evaluated result for each element in `x`. The returned array must have the same data type as `x`. ### # sin(x, /) @@ -1130,7 +1130,7 @@ Calculates an implementation-dependent approximation to the sine, having domain - **out**: _<array>_ - - an array containing the sine of each element in `x`. + - an array containing the sine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # sinh(x, /) @@ -1154,7 +1154,7 @@ Calculates an implementation-dependent approximation to the hyperbolic sine, hav - **out**: _<array>_ - - an array containing the hyperbolic sine of each element in `x`. + - an array containing the hyperbolic sine of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # square(x, /) @@ -1170,7 +1170,7 @@ Squares (`x_i * x_i`) each element `x_i` of the input array `x`. - **out**: _<array>_ - - an array containing the evaluated result for each element in `x`. + - an array containing the evaluated result for each element in `x`. The returned array must have a data type determined by :ref:`type-promotion` rules. ### # sqrt(x, /) @@ -1194,7 +1194,7 @@ Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +in - **out**: _<array>_ - - an array containing the square root of each element in `x`. + - an array containing the square root of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # subtract(x1, x2, /) @@ -1214,7 +1214,7 @@ Calculates the difference for each element `x1_i` of the input array `x1` with t - **out**: _<array>_ - - an array containing the element-wise differences. + - an array containing the element-wise differences. The returned array must have a data type determined by :ref:`type-promotion` rules. ### # tan(x, /) @@ -1237,7 +1237,7 @@ Calculates an implementation-dependent approximation to the tangent, having doma - **out**: _<array>_ - - an array containing the tangent of each element in `x`. + - an array containing the tangent of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # tanh(x, /) @@ -1261,7 +1261,7 @@ Calculates an implementation-dependent approximation to the hyperbolic tangent, - **out**: _<array>_ - - an array containing the hyperbolic tangent of each element in `x`. + - an array containing the hyperbolic tangent of each element in `x`. The returned array must have a floating-point data type determined by :ref:`type-promotion` rules. ### # trunc(x, /) @@ -1281,4 +1281,4 @@ Rounds each element `x_i` of the input array `x` to the integer-valued number th - **out**: _<array>_ - - an array containing the rounded result for each element in `x`. + - an array containing the rounded result for each element in `x`. The returned array must have the same data type as `x`. diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 79a59ab5c..464dddeee 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -25,11 +25,11 @@ Returns the cross product of 3-element vectors. If `x1` and `x2` are multi-dimen - **x1**: _<array>_ - - first input array. + - first input array. Must have a data type of either `float32` or `float64`. - **x2**: _<array>_ - - second input array. Must have the same shape as `x1`. + - second input array. Must have the same shape as `x1`. Must have a data type of either `float32` or `float64`. - **axis**: _int_ @@ -39,7 +39,7 @@ Returns the cross product of 3-element vectors. If `x1` and `x2` are multi-dimen - **out**: _<array>_ - - an array containing the cross products. + - an array containing the cross products. The returned array must have a data type determined by :ref:`type-promotion` rules. ### # det(x, /) @@ -47,15 +47,15 @@ Returns the determinant of a square matrix (or stack of square matrices) `x`. #### Parameters -- **a**: _<array>_ +- **x**: _<array>_ - - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. + - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Must have a data type of either `float32` or `float64`. #### Returns - **out**: _<array>_ - - if `x` is a two-dimensional array, a zero-dimensional array containing the determinant; otherwise, a non-zero dimensional array containing the determinant for each square matrix. + - if `x` is a two-dimensional array, a zero-dimensional array containing the determinant; otherwise, a non-zero dimensional array containing the determinant for each square matrix. The returned array must have a data type determined by :ref:`type-promotion` rules. ### # diagonal(x, /, *, axis1=0, axis2=1, offset=0) @@ -89,7 +89,7 @@ Returns the specified diagonals. If `x` has more than two dimensions, then the a - **out**: _<array>_ - - if `x` is a two-dimensional array, a one-dimensional array containing the diagonal; otherwise, a multi-dimensional array containing the diagonals and whose shape is determined by removing `axis1` and `axis2` and appending a dimension equal to the size of the resulting diagonals. Must have the same data type as `x`. + - if `x` is a two-dimensional array, a one-dimensional array containing the diagonal; otherwise, a multi-dimensional array containing the diagonals and whose shape is determined by removing `axis1` and `axis2` and appending a dimension equal to the size of the resulting diagonals. The returned array must have the same data type as `x`. ### # dot() @@ -115,13 +115,13 @@ Computes the multiplicative inverse of a square matrix (or stack of square matri - **x**: _<array>_ - - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. + - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Must have a data type of either `float32` or `float64`. #### Returns - **out**: _<array>_ - - an array containing the multiplicative inverses. Must have the same data type and shape as `x`. + - an array containing the multiplicative inverses. The returned array must have the same data type and shape as `x`. ### # lstsq() @@ -147,7 +147,7 @@ Computes the matrix or vector norm of `x`. - **x**: _<array>_ - - input array. + - input array. Must have a data type of either `float32` or `float64`. - **axis**: _Optional\[ Union\[ int, Tuple\[ int, int ] ] ]_ @@ -215,7 +215,7 @@ Computes the matrix or vector norm of `x`. - **out**: _<array>_ - - an array containing the norms. Must have the same data type as `x`. 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`. + - 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`. ### # outer(x1, x2, /) @@ -225,17 +225,17 @@ Computes the outer product of two vectors `x1` and `x2`. - **x1**: _<array>_ - - first one-dimensional input array of size `N`. + - first one-dimensional input array of size `N`. Must have a data type of either `float32` or `float64`. - **x2**: _<array>_ - - second one-dimensional input array of size `M`. + - second one-dimensional input array of size `M`. Must have a data type of either `float32` or `float64`. #### Returns - **out**: _<array>_ - - a two-dimensional array containing the outer product and whose shape is `NxM`. + - a two-dimensional array containing the outer product and whose shape is `NxM`. The returned array must have a data type determined by :ref:`type-promotion` rules. ### # pinv() @@ -297,6 +297,8 @@ Returns the sum along the specified diagonals. If `x` has more than two dimensio out[i, j, k, ..., l] = trace(a[i, j, k, ..., l, :, :]) ``` + The returned array must have the same data type as `x`. + ### # transpose(x, /, *, axes=None) Transposes (or permutes the axes (dimensions)) of an array `x`. @@ -315,4 +317,4 @@ Transposes (or permutes the axes (dimensions)) of an array `x`. - **out**: _<array>_ - - an array containing the transpose. Must have the same data type as `x`. \ No newline at end of file + - an array containing the transpose. The returned array must have the same data type as `x`. \ No newline at end of file diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md index 96be715d1..6e168a242 100644 --- a/spec/API_specification/manipulation_functions.md +++ b/spec/API_specification/manipulation_functions.md @@ -28,7 +28,7 @@ Joins a sequence of arrays along an existing axis. - **out**: _<array>_ - - an output array containing the concatenated values. If the input arrays have different data types, normal [type promotion rules](type_promotion.md) apply. If the input arrays have the same data type, the output array must have the same data type as the input arrays. + - an output array containing the concatenated values. If the input arrays have different data types, normal [type promotion rules](type_promotion.md) must apply. If the input arrays have the same data type, the output array must have the same data type as the input arrays. .. note:: @@ -156,7 +156,7 @@ Joins a sequence of arrays along a new axis. - **out**: _<array>_ - - an output array having rank `N+1`, where `N` is the rank (number of dimensions) of `x`. If the input arrays have different data types, normal [type promotion rules](type_promotion.md) apply. If the input arrays have the same data type, the output array must have the same data type as the input arrays. + - an output array having rank `N+1`, where `N` is the rank (number of dimensions) of `x`. If the input arrays have different data types, normal [type promotion rules](type_promotion.md) must apply. If the input arrays have the same data type, the output array must have the same data type as the input arrays. .. note:: diff --git a/spec/API_specification/searching_functions.md b/spec/API_specification/searching_functions.md index 0d30b58f5..6798ec6db 100644 --- a/spec/API_specification/searching_functions.md +++ b/spec/API_specification/searching_functions.md @@ -34,7 +34,7 @@ Returns the indices of the maximum values along a specified axis. When the maxim - **out**: _<array>_ - - if `axis` is `None`, a zero-dimensional array containing the index of the first occurrence of the maximum value; otherwise, a non-zero-dimensional array containing the indices of the maximum values. + - if `axis` is `None`, a zero-dimensional array containing the index of the first occurrence of the maximum value; otherwise, a non-zero-dimensional array containing the indices of the maximum values. The returned array must have be the default array index data type. ### # argmin(x, /, *, axis=None, keepdims=False) @@ -58,7 +58,7 @@ Returns the indices of the minimum values along a specified axis. When the minim - **out**: _<array>_ - - if `axis` is `None`, a zero-dimensional array containing the index of the first occurrence of the minimum value; otherwise, a non-zero-dimensional array containing the indices of the minimum values. + - if `axis` is `None`, a zero-dimensional array containing the index of the first occurrence of the minimum value; otherwise, a non-zero-dimensional array containing the indices of the minimum values. The returned array must have the default array index data type. ### # nonzero(x, /) @@ -74,7 +74,7 @@ Returns the indices of the array elements which are non-zero. - **out**: _Tuple\[ <array>, ... ]_ - - a tuple of `k` arrays, one for each dimension of `x` and each of size `n` (where `n` is the total number of non-zero elements), containing the indices of the non-zero elements in that dimension. The indices must be returned in row-major, C-style order. + - a tuple of `k` arrays, one for each dimension of `x` and each of size `n` (where `n` is the total number of non-zero elements), containing the indices of the non-zero elements in that dimension. The indices must be returned in row-major, C-style order. The returned array must have the default array index data type. ### # where(condition, x1, x2, /) @@ -98,4 +98,4 @@ Returns elements chosen from `x1` or `x2` depending on `condition`. - **out**: _<array>_ - - an array with elements from `x1` where `condition` is `True`, and elements from `x2` elsewhere. \ No newline at end of file + - an array with elements from `x1` where `condition` is `True`, and elements from `x2` elsewhere. The returned array must have a data type determined by :ref:`type-promotion` rules. \ No newline at end of file diff --git a/spec/API_specification/set_functions.md b/spec/API_specification/set_functions.md index c147388fc..3e7c95898 100644 --- a/spec/API_specification/set_functions.md +++ b/spec/API_specification/set_functions.md @@ -46,16 +46,18 @@ Returns the unique elements of an input array `x`. - **unique**: _<array>_ - - an array containing the set of unique elements in `x`. + - an array containing the set of unique elements in `x`. The returned array must have the same data type as `x`. - **indices**: _<array>_ - - an array containing the indices (first occurrences) of `x` that result in `unique`. + - an array containing the indices (first occurrences) of `x` that result in `unique`. The returned array must have the default array index data type. - **inverse**: _<array>_ - - an array containing the indices of `unique` that reconstruct `x`. + - an array containing the indices of `unique` that reconstruct `x`. The returned array must have the default array index data type. - **counts**: _<array>_ - - an array containing the number of times each unique element occurs in `x`. \ No newline at end of file + - an array containing the number of times each unique element occurs in `x`. + + _TODO: should this be `int64`? This probably makes sense for most hardware; however, may be undesirable for older hardware and/or embedded systems._ diff --git a/spec/API_specification/statistical_functions.md b/spec/API_specification/statistical_functions.md index 6578a4e70..c4c034761 100644 --- a/spec/API_specification/statistical_functions.md +++ b/spec/API_specification/statistical_functions.md @@ -35,7 +35,7 @@ Calculates the maximum value of the input array `x`. - **out**: _<array>_ - - if the maximum value was computed over the entire array, a zero-dimensional array containing the maximum value; otherwise, a non-zero-dimensional array containing the maximum values. + - if the maximum value was computed over the entire array, a zero-dimensional array containing the maximum value; otherwise, a non-zero-dimensional array containing the maximum values. The returned array must have the same data type as `x`. ### # mean(x, /, *, axis=None, keepdims=False) @@ -59,7 +59,7 @@ Calculates the arithmetic mean of the input array `x`. - **out**: _<array>_ - - if the arithmetic mean was computed over the entire array, a zero-dimensional array containing the arithmetic mean; otherwise, a non-zero-dimensional array containing the arithmetic means. + - if the arithmetic mean was computed over the entire array, a zero-dimensional array containing the arithmetic mean; otherwise, a non-zero-dimensional array containing the arithmetic means. The returned array must have be the default floating-point data type. ### # min(x, /, *, axis=None, keepdims=False) @@ -83,7 +83,7 @@ Calculates the minimum value of the input array `x`. - **out**: _<array>_ - - if the minimum value was computed over the entire array, a zero-dimensional array containing the minimum value; otherwise, a non-zero-dimensional array containing the minimum values. + - if the minimum value was computed over the entire array, a zero-dimensional array containing the minimum value; otherwise, a non-zero-dimensional array containing the minimum values. The returned array must have the same data type as `x`. ### # prod(x, /, *, axis=None, keepdims=False) @@ -107,7 +107,7 @@ Calculates the product of input array `x` elements. - **out**: _<array>_ - - if the product was computed over the entire array, a zero-dimensional array containing the product; otherwise, a non-zero-dimensional array containing the products. + - if the product was computed over the entire array, a zero-dimensional array containing the product; otherwise, a non-zero-dimensional array containing the products. The returned array must have the same data type as `x`. ### # std(x, /, *, axis=None, correction=0.0, keepdims=False) @@ -135,7 +135,7 @@ Calculates the standard deviation of the input array `x`. - **out**: _<array>_ - - if the standard deviation was computed over the entire array, a zero-dimensional array containing the standard deviation; otherwise, a non-zero-dimensional array containing the standard deviations. + - if the standard deviation was computed over the entire array, a zero-dimensional array containing the standard deviation; otherwise, a non-zero-dimensional array containing the standard deviations. The returned array must have the default floating-point data type. ### # sum(x, /, *, axis=None, keepdims=False) @@ -159,7 +159,7 @@ Calculates the sum of the input array `x`. - **out**: _<array>_ - - if the sum was computed over the entire array, a zero-dimensional array containing the sum; otherwise, an array containing the sums. + - if the sum was computed over the entire array, a zero-dimensional array containing the sum; otherwise, an array containing the sums. The returned array must have the same data type as `x`. ### # var(x, /, *, axis=None, correction=0.0, keepdims=False) @@ -187,4 +187,4 @@ Calculates the variance of the input array `x`. - **out**: _<array>_ - - if the variance was computed over the entire array, a zero-dimensional array containing the variance; otherwise, a non-zero-dimensional array containing the variances. \ No newline at end of file + - if the variance was computed over the entire array, a zero-dimensional array containing the variance; otherwise, a non-zero-dimensional array containing the variances. The returned array must have the default floating-point data type. \ No newline at end of file diff --git a/spec/API_specification/type_promotion.md b/spec/API_specification/type_promotion.md index ce0909df8..c2831e04c 100644 --- a/spec/API_specification/type_promotion.md +++ b/spec/API_specification/type_promotion.md @@ -10,8 +10,8 @@ A conforming implementation of the array API standard may support additional typ .. note:: - Type codes are used here to keep tables readable, they are not part of the standard. - In code, use the dtype objects specified in :ref:`data-types` (e.g., `int16` rather than `'i2'`). + Type codes are used here to keep tables readable; they are not part of the standard. + In code, use the data type objects specified in :ref:`data-types` (e.g., `int16` rather than `'i2'`). ## Rules @@ -72,10 +72,11 @@ A conforming implementation of the array API standard may support additional typ ## 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. -- Non-array ("scalar") operands are **not** permitted to participate in type promotion. +- 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. .. note:: Mixed integer and floating-point type promotion rules are not specified - because behaviour varies between implementations. \ No newline at end of file + because behavior varies between implementations. \ No newline at end of file diff --git a/spec/API_specification/utility_functions.md b/spec/API_specification/utility_functions.md index b93ae9fdf..a6bbe2939 100644 --- a/spec/API_specification/utility_functions.md +++ b/spec/API_specification/utility_functions.md @@ -35,7 +35,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 be a boolean array (i.e., an array whose underlying data type is `bool`). + - 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). ### # any(x, /, *, axis=None, keepdims=False) @@ -59,4 +59,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 be a boolean array (i.e., an array whose underlying data type is `bool`). \ No newline at end of file + - 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). \ No newline at end of file