From fee2c985ea902e0743860e7e8dcc0bb592e0a04d Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 7 Sep 2020 09:25:05 -0700 Subject: [PATCH 01/12] Add arange signature --- spec/API_specification/creation_functions.md | 40 ++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 spec/API_specification/creation_functions.md diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md new file mode 100644 index 000000000..13c7e7fd9 --- /dev/null +++ b/spec/API_specification/creation_functions.md @@ -0,0 +1,40 @@ +# Creation Functions + +> Array API specification for creating arrays. + +A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions. + +- Positional parameters must be [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order. +- Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments. + + + +### # arange(start, /, *, stop=None, step=1, dtype=None) + +Returns evenly spaced values within the half-open interval `[start, stop)` as a one-dimensional array. + +#### Parameters + +- **start**: _Union\[ int, float ]_ + + - if `stop` is specified, the start of interval (inclusive); otherwise, the end of the interval (exclusive). If `stop` is not specified, the default starting value is `0`. + +- **stop**: _Optional\[ Union\[ int, float ] ]_ + + - the end of the interval. Default: `None`. + + _Note: this function cannot guarantee that the interval does not include the `stop` value in those cases where `step` is not an integer and floating-point rounding errors affect the length of the output array._ + +- **step**: _Union\[ int, float ]_ + + - the distance between two adjacent elements (`out[i+1] - out[i]`). Default: `1`. + +- **dtype**: _Optional\[ TODO ]_ + + - output array data type. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - a one-dimensional array containing evenly spaced values. The length of the output array must be `ceil((stop-start)/step)`. From f153638dadd9cabc0c81af90e4fe86847ecb9d3c Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 7 Sep 2020 09:25:53 -0700 Subject: [PATCH 02/12] Update index --- spec/API_specification/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/spec/API_specification/index.rst b/spec/API_specification/index.rst index 72aac7729..9ef137132 100644 --- a/spec/API_specification/index.rst +++ b/spec/API_specification/index.rst @@ -12,5 +12,6 @@ API specification casting broadcasting out_keyword + creation_functions elementwise_functions statistical_functions From 73a50a7865a6bffa72588ec202237b3d8c9defb3 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 7 Sep 2020 09:33:24 -0700 Subject: [PATCH 03/12] Add function signatures --- spec/API_specification/creation_functions.md | 40 ++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 13c7e7fd9..06da8ac97 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -38,3 +38,43 @@ Returns evenly spaced values within the half-open interval `[start, stop)` as a - **out**: _<array>_ - a one-dimensional array containing evenly spaced values. The length of the output array must be `ceil((stop-start)/step)`. + +### # empty(shape, /, *, dtype=None) + +Returns an uninitialized array of given `shape` and data type. + +#### Parameters + +- **shape**: _Optional\[ Union\[ int, Tuple\[ int, ... ] ] ]_ + + - output array shape. + +- **dtype**: _Optional\[ TODO ]_ + + - output array data type. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an array containing uninitialized data. + +### # empty_like(x, /, *, dtype=None) + +Returns an uninitialized array with the same `shape` as an input array `x`. + +#### Parameters + +- **x**: _<array>_ + + - input array from which to derive the output array shape. If `dtype` is not provided, the output array data type must be inferred from `x`. + +- **dtype**: _Optional\[ TODO ]_ + + - output array data type. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an array having the same shape as `x` and containing uninitialized data. From 58237401ddde5a0c20d8e3336300282c5c87d243 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 7 Sep 2020 09:40:34 -0700 Subject: [PATCH 04/12] Add eye signature --- spec/API_specification/creation_functions.md | 28 ++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 06da8ac97..b2ca7d628 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -78,3 +78,31 @@ Returns an uninitialized array with the same `shape` as an input array `x`. - **out**: _<array>_ - an array having the same shape as `x` and containing uninitialized data. + +### # eye(N, /, *, M=None, k=0, dtype=None) + +Returns a two-dimensional array with ones on the `k`th diagonal and zeros elsewhere. + +#### Parameters + +- **N**: _int_ + + - number of rows in the output array. + +- **M**: _Optional\[ int ]_ + + - number of columns in the output array. If `None`, the default number of columns in the output array is `N`. Default: `None`. + +- **k**: _Optional\[ int ]_ + + - index of the diagonal. A positive value refers to an upper diagonal, a negative value to a lower diagonal, and `0` to the main diagonal. Default: `0`. + +- **dtype**: _Optional\[ TODO ]_ + + - output array data type. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an array where all elements are equal to zero, except for the `k`th diagonal, whose values are equal to one. From 2420fd94cd9ff5a6dbb7d49ed4bbed7175e17d97 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 7 Sep 2020 09:46:17 -0700 Subject: [PATCH 05/12] Add full signature --- spec/API_specification/creation_functions.md | 28 ++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index b2ca7d628..1358e0e5b 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -41,11 +41,11 @@ Returns evenly spaced values within the half-open interval `[start, stop)` as a ### # empty(shape, /, *, dtype=None) -Returns an uninitialized array of given `shape` and data type. +Returns an uninitialized array having a specified `shape`. #### Parameters -- **shape**: _Optional\[ Union\[ int, Tuple\[ int, ... ] ] ]_ +- **shape**: _Union\[ int, Tuple\[ int, ... ] ]_ - output array shape. @@ -106,3 +106,27 @@ Returns a two-dimensional array with ones on the `k`th diagonal and zeros elsewh - **out**: _<array>_ - an array where all elements are equal to zero, except for the `k`th diagonal, whose values are equal to one. + +### # full(shape, fill_value, /, *, dtype=None) + +Returns a new array having a specified `shape` and filled with `fill_value`. + +#### Parameters + +- **shape**: _Union\[ int, Tuple\[ int, ... ] ]_ + + - output array shape. + +- **fill_value**: _Union\[ int, float ] ]_ + + - fill value. + +- **dtype**: _Optional\[ TODO ]_ + + - output array data type. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an array where every element is equal to `fill_value`. From c5565ee683df441671ea4844e0ec0df557b3f0b5 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 7 Sep 2020 09:48:22 -0700 Subject: [PATCH 06/12] Add full_like signature --- spec/API_specification/creation_functions.md | 24 ++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 1358e0e5b..f81f93774 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -130,3 +130,27 @@ Returns a new array having a specified `shape` and filled with `fill_value`. - **out**: _<array>_ - an array where every element is equal to `fill_value`. + +### # full_like(x, fill_value, /, *, dtype=None) + +Returns a new array with the same `shape` as an input array `x` and filled with `fill_value`. + +#### Parameters + +- **x**: _<array>_ + + - input array from which to derive the output array shape. If `dtype` is not provided, the output array data type must be inferred from `x`. + +- **fill_value**: _Union\[ int, float ] ]_ + + - fill value. + +- **dtype**: _Optional\[ TODO ]_ + + - output array data type. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an array having the same shape as `x` and where every element is equal to `fill_value`. From 9ca3682c60ec31e2b26492223ea41b675b2432ee Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 7 Sep 2020 10:10:49 -0700 Subject: [PATCH 07/12] Add linspace signature --- spec/API_specification/creation_functions.md | 34 ++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index f81f93774..ca0030d07 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -154,3 +154,37 @@ Returns a new array with the same `shape` as an input array `x` and filled with - **out**: _<array>_ - an array having the same shape as `x` and where every element is equal to `fill_value`. + +### # linspace(start, stop, /, *, num=50, dtype=None, endpoint=True) + +Returns evenly spaced numbers over a specified interval. + +#### Parameters + +- **start**: _Union\[ int, float ]_ + + - the start of the interval. + +- **stop**: _Union\[ int, float ]_ + + - 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`._ + +- **num**: _Optional\[ int ]_ + + - number of samples. Must be a non-negative value; otherwise, throw an exception. Default: `50`. + +- **dtype**: _Optional\[ TODO ]_ + + - output array data type. Default: `None`. + +- **endpoint**: _Optional\[ bool ]_ + + - boolean indicating whether to include `stop` in the interval. Default: `True`. + +#### Returns + +- **out**: _<array>_ + + - a one-dimensional array containing evenly spaced values. From c15d40c8242bcac208e613f9c2737aa339623060 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 7 Sep 2020 10:53:00 -0700 Subject: [PATCH 08/12] Add ones signatures --- spec/API_specification/creation_functions.md | 50 ++++++++++++++++++-- 1 file changed, 45 insertions(+), 5 deletions(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index ca0030d07..2ae56804b 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -41,7 +41,7 @@ Returns evenly spaced values within the half-open interval `[start, stop)` as a ### # empty(shape, /, *, dtype=None) -Returns an uninitialized array having a specified `shape`. +Returns an uninitialized array having a specified `shape`. #### Parameters @@ -67,11 +67,11 @@ Returns an uninitialized array with the same `shape` as an input array `x`. - **x**: _<array>_ - - input array from which to derive the output array shape. If `dtype` is not provided, the output array data type must be inferred from `x`. + - input array from which to derive the output array shape. - **dtype**: _Optional\[ TODO ]_ - - output array data type. Default: `None`. + - output array data type. If `dtype` is `None`, the output array data type must be inferred from `x`. Default: `None`. #### Returns @@ -139,7 +139,7 @@ Returns a new array with the same `shape` as an input array `x` and filled with - **x**: _<array>_ - - input array from which to derive the output array shape. If `dtype` is not provided, the output array data type must be inferred from `x`. + - input array from which to derive the output array shape. - **fill_value**: _Union\[ int, float ] ]_ @@ -147,7 +147,7 @@ Returns a new array with the same `shape` as an input array `x` and filled with - **dtype**: _Optional\[ TODO ]_ - - output array data type. Default: `None`. + - output array data type. If `dtype` is `None`, the output array data type must be inferred from `x`. Default: `None`. #### Returns @@ -188,3 +188,43 @@ Returns evenly spaced numbers over a specified interval. - **out**: _<array>_ - a one-dimensional array containing evenly spaced values. + +### # ones(shape, /, *, dtype=None) + +Returns a new array having a specified `shape` and filled with ones. + +#### Parameters + +- **shape**: _Union\[ int, Tuple\[ int, ... ] ]_ + + - output array shape. + +- **dtype**: _Optional\[ TODO ]_ + + - output array data type. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an array containing ones. + +### # ones_like(x, /, *, dtype=None) + +Returns a new array with the same `shape` as an input array `x` and filled with ones. + +#### Parameters + +- **x**: _<array>_ + + - input array from which to derive the output array shape. + +- **dtype**: _Optional\[ TODO ]_ + + - output array data type. If `dtype` is `None`, the output array data type must be inferred from `x`. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an array having the same shape as `x` and filled with ones. From f129dd1a72e9f496df6683312cbe53d04b1a78d4 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 7 Sep 2020 10:56:06 -0700 Subject: [PATCH 09/12] Add zeros signatures --- spec/API_specification/creation_functions.md | 44 +++++++++++++++++++- 1 file changed, 42 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 2ae56804b..847f12354 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -133,7 +133,7 @@ Returns a new array having a specified `shape` and filled with `fill_value`. ### # full_like(x, fill_value, /, *, dtype=None) -Returns a new array with the same `shape` as an input array `x` and filled with `fill_value`. +Returns a new array filled with `fill_value` and having the same `shape` as an input array `x`. #### Parameters @@ -211,7 +211,7 @@ Returns a new array having a specified `shape` and filled with ones. ### # ones_like(x, /, *, dtype=None) -Returns a new array with the same `shape` as an input array `x` and filled with ones. +Returns a new array filled with ones and having the same `shape` as an input array `x`. #### Parameters @@ -228,3 +228,43 @@ Returns a new array with the same `shape` as an input array `x` and filled with - **out**: _<array>_ - an array having the same shape as `x` and filled with ones. + +### # zeros(shape, /, *, dtype=None) + +Returns a new array having a specified `shape` and filled with zeros. + +#### Parameters + +- **shape**: _Union\[ int, Tuple\[ int, ... ] ]_ + + - output array shape. + +- **dtype**: _Optional\[ TODO ]_ + + - output array data type. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an array containing zeros. + +### # zeros_like(x, /, *, dtype=None) + +Returns a new array filled with zeros and having the same `shape` as an input array `x`. + +#### Parameters + +- **x**: _<array>_ + + - input array from which to derive the output array shape. + +- **dtype**: _Optional\[ TODO ]_ + + - output array data type. If `dtype` is `None`, the output array data type must be inferred from `x`. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an array having the same shape as `x` and filled with zeros. From 75354a119639fa90ae44b88957bd012f3bfeedca Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 10 Sep 2020 01:04:37 -0700 Subject: [PATCH 10/12] Make `num` positional parameter --- 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 847f12354..da777cb6a 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -155,7 +155,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`. -### # linspace(start, stop, /, *, num=50, dtype=None, endpoint=True) +### # linspace(start, stop, num, /, *, dtype=None, endpoint=True) Returns evenly spaced numbers over a specified interval. @@ -171,9 +171,9 @@ Returns evenly spaced numbers over a specified interval. _Note: that the step size changes when `endpoint` is `False`._ -- **num**: _Optional\[ int ]_ +- **num**: _int_ - - number of samples. Must be a non-negative value; otherwise, throw an exception. Default: `50`. + - number of samples. Must be a non-negative integer value; otherwise, the function must throw an exception. - **dtype**: _Optional\[ TODO ]_ From 64d349d8343b55287c240d3f88790b833f82e202 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 10 Sep 2020 01:16:05 -0700 Subject: [PATCH 11/12] Update copy --- 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 da777cb6a..0c8122980 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -173,7 +173,7 @@ Returns evenly spaced numbers over a specified interval. - **num**: _int_ - - number of samples. Must be a non-negative integer value; otherwise, the function must throw an exception. + - number of samples. Must be a non-negative integer value; otherwise, the function must raise an exception. - **dtype**: _Optional\[ TODO ]_ From 49976bc0976efca0bc3ec4e2273a5aa3e721cb4d Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 13 Sep 2020 20:23:52 -0700 Subject: [PATCH 12/12] Resolve TODOs --- spec/API_specification/creation_functions.md | 22 ++++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 0c8122980..a1af2d353 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -29,7 +29,7 @@ Returns evenly spaced values within the half-open interval `[start, stop)` as a - the distance between two adjacent elements (`out[i+1] - out[i]`). Default: `1`. -- **dtype**: _Optional\[ TODO ]_ +- **dtype**: _Optional\[ _<dtype>_ ]_ - output array data type. Default: `None`. @@ -49,7 +49,7 @@ Returns an uninitialized array having a specified `shape`. - output array shape. -- **dtype**: _Optional\[ TODO ]_ +- **dtype**: _Optional\[ _<dtype>_ ]_ - output array data type. Default: `None`. @@ -69,7 +69,7 @@ Returns an uninitialized array with the same `shape` as an input array `x`. - input array from which to derive the output array shape. -- **dtype**: _Optional\[ TODO ]_ +- **dtype**: _Optional\[ _<dtype>_ ]_ - output array data type. If `dtype` is `None`, the output array data type must be inferred from `x`. Default: `None`. @@ -97,7 +97,7 @@ Returns a two-dimensional array with ones on the `k`th diagonal and zeros elsewh - index of the diagonal. A positive value refers to an upper diagonal, a negative value to a lower diagonal, and `0` to the main diagonal. Default: `0`. -- **dtype**: _Optional\[ TODO ]_ +- **dtype**: _Optional\[ _<dtype>_ ]_ - output array data type. Default: `None`. @@ -121,7 +121,7 @@ Returns a new array having a specified `shape` and filled with `fill_value`. - fill value. -- **dtype**: _Optional\[ TODO ]_ +- **dtype**: _Optional\[ _<dtype>_ ]_ - output array data type. Default: `None`. @@ -145,7 +145,7 @@ Returns a new array filled with `fill_value` and having the same `shape` as an i - fill value. -- **dtype**: _Optional\[ TODO ]_ +- **dtype**: _Optional\[ _<dtype>_ ]_ - output array data type. If `dtype` is `None`, the output array data type must be inferred from `x`. Default: `None`. @@ -175,7 +175,7 @@ Returns evenly spaced numbers over a specified interval. - number of samples. Must be a non-negative integer value; otherwise, the function must raise an exception. -- **dtype**: _Optional\[ TODO ]_ +- **dtype**: _Optional\[ _<dtype>_ ]_ - output array data type. Default: `None`. @@ -199,7 +199,7 @@ Returns a new array having a specified `shape` and filled with ones. - output array shape. -- **dtype**: _Optional\[ TODO ]_ +- **dtype**: _Optional\[ _<dtype>_ ]_ - output array data type. Default: `None`. @@ -219,7 +219,7 @@ Returns a new array filled with ones and having the same `shape` as an input arr - input array from which to derive the output array shape. -- **dtype**: _Optional\[ TODO ]_ +- **dtype**: _Optional\[ _<dtype>_ ]_ - output array data type. If `dtype` is `None`, the output array data type must be inferred from `x`. Default: `None`. @@ -239,7 +239,7 @@ Returns a new array having a specified `shape` and filled with zeros. - output array shape. -- **dtype**: _Optional\[ TODO ]_ +- **dtype**: _Optional\[ _<dtype>_ ]_ - output array data type. Default: `None`. @@ -259,7 +259,7 @@ Returns a new array filled with zeros and having the same `shape` as an input ar - input array from which to derive the output array shape. -- **dtype**: _Optional\[ TODO ]_ +- **dtype**: _Optional\[ _<dtype>_ ]_ - output array data type. If `dtype` is `None`, the output array data type must be inferred from `x`. Default: `None`.