From f31fc5cf5408c6a151073455e0845dbf7005a283 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Tue, 20 Apr 2021 18:24:45 +0200 Subject: [PATCH 1/9] Update specification for arange Addresses comments in gh-85 and gh-107 --- spec/API_specification/creation_functions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 7ce12f5d9..4528c49ad 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -12,7 +12,7 @@ A conforming implementation of the array API standard must provide and support t (function-arange)= -### arange(start, /, *, stop=None, step=1, dtype=None, device=None) +### arange(start, /, stop=None, step=1, *, dtype=None, device=None) Returns evenly spaced values within the half-open interval `[start, stop)` as a one-dimensional array. @@ -33,11 +33,11 @@ This function cannot guarantee that the interval does not include the `stop` val - **step**: _Union\[ int, float ]_ - - the distance between two adjacent elements (`out[i+1] - out[i]`). Default: `1`. + - the distance between two adjacent elements (`out[i+1] - out[i]`). Must not be `0`; may be negative, this results in an empty array if `stop >= start`. Default: `1`. - **dtype**: _Optional\[ <dtype> ]_ - - output array data type. If `dtype` is `None`, the output array data type must be the default floating-point data type. Default: `None`. + - output array data type. If `dtype` is `None`, the output array data type must be inferred from `start`, `stop` and `step`. If those are all integers, the output array dtype must be the default integer dtype; if one or more have type `float`, then the output array dtype must be the default floating-point data type. Default: `None`. - **device**: _Optional\[ <device> ]_ @@ -47,7 +47,7 @@ This function cannot guarantee that the interval does not include the `stop` val - **out**: _<array>_ - - a one-dimensional array containing evenly spaced values. The length of the output array must be `ceil((stop-start)/step)`. + - a one-dimensional array containing evenly spaced values. The length of the output array must be `ceil((stop-start)/step)` if `stop - start` and `step` have the same sign, and length 0 otherwise. (function-asarray)= From 3691f8ca3bd34c71c5da256770b1d992c4620bbe Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Tue, 20 Apr 2021 18:31:49 +0200 Subject: [PATCH 2/9] Update the specification for `full` and `full_like` Addresses comments in gh-85 and gh-107 --- spec/API_specification/creation_functions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 4528c49ad..46b6e29af 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -190,7 +190,7 @@ Returns a new array containing the data from another (array) object with a `__dl ``` (function-full)= -### full(shape, fill_value, /, *, dtype=None, device=None) +### full(shape, fill_value, *, dtype=None, device=None) Returns a new array having a specified `shape` and filled with `fill_value`. @@ -206,7 +206,7 @@ Returns a new array having a specified `shape` and filled with `fill_value`. - **dtype**: _Optional\[ <dtype> ]_ - - output array data type. If `dtype` is `None`, the output array data type must be the default floating-point data type. Default: `None`. + - output array data type. If `dtype` is `None`, the output array data type must be inferred from `fill_value`. If it's an `int`, the output array dtype must be the default integer dtype; if it's a `float`, then the output array dtype must be the default floating-point data type; if it's a `bool` then the output array must have boolean dtype. Default: `None`. - **device**: _Optional\[ <device> ]_ @@ -219,7 +219,7 @@ Returns a new array having a specified `shape` and filled with `fill_value`. - an array where every element is equal to `fill_value`. (function-full_like)= -### full_like(x, fill_value, /, *, dtype=None, device=None) +### full_like(x, /, fill_value, *, dtype=None, device=None) Returns a new array filled with `fill_value` and having the same `shape` as an input array `x`. @@ -235,7 +235,7 @@ Returns a new array filled with `fill_value` and having the same `shape` as an i - **dtype**: _Optional\[ <dtype> ]_ - - output array data type. If `dtype` is `None`, the output array data type must be inferred from `x`. Default: `None`. + - output array data type. If `dtype` is `None`, the output array data type must be inferred from `fill_value` (see {ref}`function-full`). Default: `None`. - **device**: _Optional\[ <device> ]_ From 3cd1a25fae414f8bbf2cdd53a2593b0ae64fec14 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Tue, 20 Apr 2021 18:37:38 +0200 Subject: [PATCH 3/9] Update specification for `linspace` Addresses comments in gh-85 and gh-107 --- 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 46b6e29af..1c4adb715 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -248,7 +248,7 @@ Returns a new array filled with `fill_value` and having the same `shape` as an i - an array having the same shape as `x` and where every element is equal to `fill_value`. (function-linspace)= -### linspace(start, stop, num, /, *, dtype=None, device=None, endpoint=True) +### linspace(start, stop, /, num, *, dtype=None, device=None, endpoint=True) Returns evenly spaced numbers over a specified interval. From 87dd193ae8ad2e18d335059bc09bf29504b4e88d Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Tue, 20 Apr 2021 18:43:35 +0200 Subject: [PATCH 4/9] Update specification for `empty`, `ones`, `zeros` Addresses comments in gh-85 and gh-107 --- spec/API_specification/creation_functions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 1c4adb715..618330d68 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -86,7 +86,7 @@ Convert the input to an array. (function-empty)= -### empty(shape, /, *, dtype=None, device=None) +### empty(shape, *, dtype=None, device=None) Returns an uninitialized array having a specified `shape`. @@ -321,7 +321,7 @@ Returns coordinate matrices from coordinate vectors. The returned arrays must have a numeric data type determined by {ref}`type-promotion`. (function-ones)= -### ones(shape, /, *, dtype=None, device=None) +### ones(shape, *, dtype=None, device=None) Returns a new array having a specified `shape` and filled with ones. @@ -371,7 +371,7 @@ Returns a new array filled with ones and having the same `shape` as an input arr - an array having the same shape as `x` and filled with ones. (function-zeros)= -### zeros(shape, /, *, dtype=None, device=None) +### zeros(shape, *, dtype=None, device=None) Returns a new array having a specified `shape` and filled with zeros. From 09acbab1db57200f7b7c54eec7c1d519d5448d5f Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Tue, 20 Apr 2021 18:49:42 +0200 Subject: [PATCH 5/9] Update specification for `eye` This is useful/needed because `M` is not a descriptive name and that name does not match between different array libraries. --- 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 618330d68..405e37472 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -136,7 +136,7 @@ Returns an uninitialized array with the same `shape` as an input array `x`. - an array having the same shape as `x` and containing uninitialized data. (function-eye)= -### eye(N, /, *, M=None, k=0, dtype=None, device=None) +### eye(N, M=None, /, *, k=0, dtype=None, device=None) Returns a two-dimensional array with ones on the `k`th diagonal and zeros elsewhere. From fa900fa5d5f1c6ad4fcb7150e052eca1fec537b9 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Tue, 20 Apr 2021 18:53:40 +0200 Subject: [PATCH 6/9] Update specification for `expand_dims`, `roll` and `reshape` Address comment in gh-85 --- spec/API_specification/manipulation_functions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md index 29fca5a29..edb116139 100644 --- a/spec/API_specification/manipulation_functions.md +++ b/spec/API_specification/manipulation_functions.md @@ -39,7 +39,7 @@ Joins a sequence of arrays along an existing axis. ``` (function-expand_dims)= -### expand_dims(x, axis, /) +### expand_dims(x, /, *, axis) Expands the shape of an array by inserting a new axis (dimension) of size one at the position specified by `axis`. @@ -81,7 +81,7 @@ Reverses the order of elements in an array along the given axis. The shape of th - an output array having the same data type and shape as `x` and whose elements, relative to `x`, are reordered. (function-reshape)= -### reshape(x, shape, /) +### reshape(x, /, shape) Reshapes an array without changing its data. @@ -102,7 +102,7 @@ Reshapes an array without changing its data. - an output array having the same data type, elements, and underlying element order as `x`. (function-roll)= -### roll(x, shift, /, *, axis=None) +### roll(x, /, shift, *, axis=None) Rolls array elements along a specified axis. Array elements that roll beyond the last position are re-introduced at the first position. Array elements that roll beyond the first position are re-introduced at the last position. From a9473a4a8846e523c40ff5ac84fb734aaa2bda89 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Tue, 20 Apr 2021 20:11:19 +0200 Subject: [PATCH 7/9] One more change to `eye`, more descriptive positional arguments --- spec/API_specification/creation_functions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 405e37472..c07984d33 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -136,19 +136,19 @@ Returns an uninitialized array with the same `shape` as an input array `x`. - an array having the same shape as `x` and containing uninitialized data. (function-eye)= -### eye(N, M=None, /, *, k=0, dtype=None, device=None) +### eye(n_rows, n_cols=None, /, *, k=0, dtype=None, device=None) Returns a two-dimensional array with ones on the `k`th diagonal and zeros elsewhere. #### Parameters -- **N**: _int_ +- **n_rows**: _int_ - number of rows in the output array. -- **M**: _Optional\[ int ]_ +- **n_cols**: _Optional\[ int ]_ - - number of columns in the output array. If `None`, the default number of columns in the output array is `N`. Default: `None`. + - number of columns in the output array. If `None`, the default number of columns in the output array is equal to `n_rows`. Default: `None`. - **k**: _Optional\[ int ]_ From 23f16600433e5e51c1f4d68b1df3ceed5db61574 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Tue, 20 Apr 2021 21:54:58 +0200 Subject: [PATCH 8/9] Address the default integer dtype issue for 32/64-bit Python Closes gh-151 --- spec/API_specification/creation_functions.md | 2 +- spec/API_specification/data_types.md | 3 +-- spec/API_specification/set_functions.md | 4 ++-- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index c07984d33..3f926267e 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -68,7 +68,7 @@ Convert the input to an array. - **dtype**: _Optional\[ <dtype> ]_ - - output array data type. If `dtype` is `None`, the output array data type must be inferred from the data type(s) in `obj`. Default: `None`. + - output array data type. If `dtype` is `None`, the output array data type must be inferred from the data type(s) in `obj`. If all input values are Python scalars, then if they're all `bool` the output dtype will be `bool`; if they're a mix of `bool`s and `int` the output dtype will be the default integer data type; if they contain `float`s the output dtype will be the default floating-point data type. Default: `None`. - **device**: _Optional\[ <device> ]_ diff --git a/spec/API_specification/data_types.md b/spec/API_specification/data_types.md index b1c83b4d5..3788d8494 100644 --- a/spec/API_specification/data_types.md +++ b/spec/API_specification/data_types.md @@ -6,10 +6,9 @@ A conforming implementation of the array API standard must provide and support the following data types. -A conforming implementation of the array API standard must define a default floating-point data type (either `float32` or `float64`), as well as a default data type for an array index (either `int32` or `int64`). +A conforming implementation of the array API standard must define a default floating-point data type (either `float32` or `float64`), as well as a default integer data type (`int32` or `int64`). These default data types must be the same across platforms. The default integer data type may vary depending on whether Python is 32-bit or 64-bit. ```{note} - The default floating-point and array index integer data types should be clearly defined in a conforming library's documentation. ``` diff --git a/spec/API_specification/set_functions.md b/spec/API_specification/set_functions.md index 73d8338cc..c8d04cffa 100644 --- a/spec/API_specification/set_functions.md +++ b/spec/API_specification/set_functions.md @@ -51,11 +51,11 @@ Returns the unique elements of an input array `x`. - **indices**: _<array>_ - - an array containing the indices (first occurrences) of `x` that result in `unique`. The returned array must have the default array index data type. + - an array containing the indices (first occurrences) of `x` that result in `unique`. The returned array must have the default integer data type. - **inverse**: _<array>_ - - an array containing the indices of `unique` that reconstruct `x`. The returned array must have the default array index data type. + - an array containing the indices of `unique` that reconstruct `x`. The returned array must have the default integer data type. - **counts**: _<array>_ From 4050990b73d37352b06c1cec9ddefc166559b27e Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Tue, 20 Apr 2021 22:08:50 +0200 Subject: [PATCH 9/9] Update signature of `broadcast_to` Address a review comment; makes it consistent with other functions using `shape`. --- spec/API_specification/data_type_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md index 8df12d409..591f5b674 100644 --- a/spec/API_specification/data_type_functions.md +++ b/spec/API_specification/data_type_functions.md @@ -25,7 +25,7 @@ Broadcasts one or more arrays against one another. - a list of broadcasted arrays. Each array must have the same shape. Each array must have the same dtype as its corresponding input array. (function-broadcast-to)= -### broadcast_to(x, shape, /) +### broadcast_to(x, /, shape) Broadcasts an array to a specified shape.