From eebe84d449f45a31acc9d7ed175461d5350590d5 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 14 Sep 2020 09:45:32 -0700 Subject: [PATCH 01/14] Add concat --- .../manipulation_functions.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 spec/API_specification/manipulation_functions.md diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md new file mode 100644 index 000000000..959e9e8a6 --- /dev/null +++ b/spec/API_specification/manipulation_functions.md @@ -0,0 +1,30 @@ +# Manipulation Functions + +> Array API specification for manipulating 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. + + + +### # concat(arrays, /, *, axis=0) + +Joins a sequence of arrays along an existing axis. + +#### Parameters + +- **arrays**: _Sequence\[ <array> ]_ + + - input arrays to join. The arrays must have the same shape, except in the dimension specified by `axis`. + +- **axis**: _Optional\[ int ]_ + + - axis along which the arrays will be joined. If `axis` is `None`, arrays are flattened before concatenation. A negative `axis` is interpreted as counting from last dimension (i.e., `axis+rank(arrays)`-th dimension). Default: `0`. + +#### Returns + +- **out**: _<array>_ + + - an output array containing the concatenated values. \ No newline at end of file From e6fa8ef397c745690e9ffbf1d4043d6ffdd25f96 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 14 Sep 2020 09:53:31 -0700 Subject: [PATCH 02/14] Add flip --- .../manipulation_functions.md | 24 +++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md index 959e9e8a6..385e56329 100644 --- a/spec/API_specification/manipulation_functions.md +++ b/spec/API_specification/manipulation_functions.md @@ -21,10 +21,30 @@ Joins a sequence of arrays along an existing axis. - **axis**: _Optional\[ int ]_ - - axis along which the arrays will be joined. If `axis` is `None`, arrays are flattened before concatenation. A negative `axis` is interpreted as counting from last dimension (i.e., `axis+rank(arrays)`-th dimension). Default: `0`. + - axis along which the arrays will be joined. If `axis` is `None`, arrays are flattened before concatenation. If `axis` is negative, the function must count from last dimension. Default: `0`. #### Returns - **out**: _<array>_ - - an output array containing the concatenated values. \ No newline at end of file + - an output array containing the concatenated values. + +### # flip(x, /, *, axis=None) + +Reverses the order of elements in an array along the given axis. The shape of the array must be preserved. + +#### Parameters + +- **x**: _<array>_ + + - input array. + +- **axis**: _Optional\[ int, Tuple\[ int ] ]_ + + - axis (or axes) along which to flip. If `axis` is `None`, the function must flip all input array axes. If `axis` is negative, the function must count from the last dimension. If provided more than one axis, the function must flip only the specified axes. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an output array having the same data type as `x` and whose axes, relative to `x`, are flipped. \ No newline at end of file From 71aa0b4f33e2d435a8acc5126411d1a67eb2bde4 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 14 Sep 2020 10:02:37 -0700 Subject: [PATCH 03/14] Add reshape --- .../manipulation_functions.md | 24 +++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md index 385e56329..8f37dbd38 100644 --- a/spec/API_specification/manipulation_functions.md +++ b/spec/API_specification/manipulation_functions.md @@ -39,7 +39,7 @@ Reverses the order of elements in an array along the given axis. The shape of th - input array. -- **axis**: _Optional\[ int, Tuple\[ int ] ]_ +- **axis**: _Optional\[ Union\[ int, Tuple\[ int, ... ] ] ]_ - axis (or axes) along which to flip. If `axis` is `None`, the function must flip all input array axes. If `axis` is negative, the function must count from the last dimension. If provided more than one axis, the function must flip only the specified axes. Default: `None`. @@ -47,4 +47,24 @@ Reverses the order of elements in an array along the given axis. The shape of th - **out**: _<array>_ - - an output array having the same data type as `x` and whose axes, relative to `x`, are flipped. \ No newline at end of file + - an output array having the same data type as `x` and whose axes, relative to `x`, are flipped. + +### # reshape(x, shape, /) + +Reshapes an array without changing its data. + +#### Parameters + +- **x**: _<array>_ + + - input array to reshape. + +- **shape**: _Union\[ int, Tuple\[ int, ... ] ]_ + + - a new shape compatible with the original shape. If `shape` is an integer, then the result must be a one-dimensional array of that length. One shape dimension is allowed to be `-1`. When a shape dimension is `-1`, the corresponding output array shape dimension must be inferred from the length of the array and the remaining dimensions. + +#### Returns + +- **out**: _<array>_ + + - an output array having the same data type, elements, and underlying element order as `x`. \ No newline at end of file From 220459024890a7597eecc27e5e0cef4b6a28c020 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 14 Sep 2020 10:33:31 -0700 Subject: [PATCH 04/14] Add roll --- .../manipulation_functions.md | 28 ++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md index 8f37dbd38..92ee9036e 100644 --- a/spec/API_specification/manipulation_functions.md +++ b/spec/API_specification/manipulation_functions.md @@ -67,4 +67,30 @@ Reshapes an array without changing its data. - **out**: _<array>_ - - an output array having the same data type, elements, and underlying element order as `x`. \ No newline at end of file + - an output array having the same data type, elements, and underlying element order as `x`. + +### # 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. + +#### Parameters + +- **x**: _<array>_ + + - input array. + +- **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`. + +- **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`. + +#### Returns + +- **out**: _<array>_ + + - an output array having the same data type as `x` and whose elements, relative to `x`, have shifted. \ No newline at end of file From 08905087ce6a80a95e0352fb01d16890b0b3ef5a Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 14 Sep 2020 11:10:31 -0700 Subject: [PATCH 05/14] Add stack --- .../manipulation_functions.md | 46 +++++++++++++++++-- 1 file changed, 42 insertions(+), 4 deletions(-) diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md index 92ee9036e..fbd9caa0a 100644 --- a/spec/API_specification/manipulation_functions.md +++ b/spec/API_specification/manipulation_functions.md @@ -71,9 +71,7 @@ Reshapes an array without changing its data. ### # 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. +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. #### Parameters @@ -93,4 +91,44 @@ Array elements that roll beyond the last position are re-introduced at the first - **out**: _<array>_ - - an output array having the same data type as `x` and whose elements, relative to `x`, have shifted. \ No newline at end of file + - an output array having the same data type as `x` and whose elements, relative to `x`, have shifted. + +### # squeeze(x, /, *, axis=None) + +Removes singleton dimensions (axes) from `x`. + +#### Parameters + +- **x**: _<array>_ + + - input array. + +- **axis**: _Optional\[ Union\[ int, Tuple\[ int, ... ] ] ]_ + + - axis (or axes) to squeeze. If provided, only the specified axes must be squeezed. If `axis` is `None`, all singleton dimensions (axes) must be removed. If a specified axis has a size greater than one, the specified axis must be left unchanged. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an output array having the same data type and elements as `x`. + +### # stack(arrays, /, *, axis=0) + +Joins a sequence of arrays along a new axis. + +#### Parameters + +- **arrays**: _Sequence\[ <array> ]_ + + - input arrays to join. The arrays must have the same shape, except in the dimension specified by `axis`. + +- **axis**: _Optional\[ int ]_ + + - axis along which the arrays will be joined. Providing an `axis` specifies the index of the new axis in the dimensions of the result. For example, if `axis` is `0`, the new axis will be the first dimension and the output array will have shape `(N, A, B, C)`; if `axis` is `1`, the new axis will be the second dimension and the output array will have shape `(A, N, B, C)`; and, if `axis` is `-1`, the new axis will be the last dimension and the output array will have shape `(A, B, C, N)`. A valid `axis` must be on the interval `[-N, N)`, where `N` is the rank (number of dimensions) of `x`. If provided an `axis` outside of the required interval, the function must raise an exception. Default: `0`. + +#### Returns + +- **out**: _<array>_ + + - an output array having rank `N+1`, where `N` is the rank (number of dimensions) of `x`. \ No newline at end of file From 297af721dd64056c1c1cdbe1021959ad6a55208a Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 14 Sep 2020 11:12:02 -0700 Subject: [PATCH 06/14] Fix description --- spec/API_specification/manipulation_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md index fbd9caa0a..b357b16a1 100644 --- a/spec/API_specification/manipulation_functions.md +++ b/spec/API_specification/manipulation_functions.md @@ -121,7 +121,7 @@ Joins a sequence of arrays along a new axis. - **arrays**: _Sequence\[ <array> ]_ - - input arrays to join. The arrays must have the same shape, except in the dimension specified by `axis`. + - input arrays to join. Each array must have the same shape. - **axis**: _Optional\[ int ]_ From 448e769cf8166c67fdf4ade615d577436a38b1c8 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 14 Sep 2020 11:12:43 -0700 Subject: [PATCH 07/14] Update copy --- spec/API_specification/manipulation_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md index b357b16a1..60c514754 100644 --- a/spec/API_specification/manipulation_functions.md +++ b/spec/API_specification/manipulation_functions.md @@ -21,7 +21,7 @@ Joins a sequence of arrays along an existing axis. - **axis**: _Optional\[ int ]_ - - axis along which the arrays will be joined. If `axis` is `None`, arrays are flattened before concatenation. If `axis` is negative, the function must count from last dimension. Default: `0`. + - axis along which the arrays will be joined. If `axis` is `None`, arrays must be flattened before concatenation. If `axis` is negative, the function must count from last dimension. Default: `0`. #### Returns From a42f9842e8c1470c09d0a02decc7215ecc4f4e4f Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 14 Sep 2020 11:13:31 -0700 Subject: [PATCH 08/14] Update copy --- spec/API_specification/manipulation_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md index 60c514754..ff00e66fe 100644 --- a/spec/API_specification/manipulation_functions.md +++ b/spec/API_specification/manipulation_functions.md @@ -21,7 +21,7 @@ Joins a sequence of arrays along an existing axis. - **axis**: _Optional\[ int ]_ - - axis along which the arrays will be joined. If `axis` is `None`, arrays must be flattened before concatenation. If `axis` is negative, the function must count from last dimension. Default: `0`. + - axis along which the arrays will be joined. If `axis` is `None`, arrays must be flattened before concatenation. If `axis` is negative, the function must determine the axis along which to join by counting from the last dimension. Default: `0`. #### Returns From 45cbc1643d778e75a1cba801faf95f57de5067f9 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 14 Sep 2020 11:15:26 -0700 Subject: [PATCH 09/14] Update copy --- spec/API_specification/manipulation_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md index ff00e66fe..e5f4e4f6b 100644 --- a/spec/API_specification/manipulation_functions.md +++ b/spec/API_specification/manipulation_functions.md @@ -47,7 +47,7 @@ Reverses the order of elements in an array along the given axis. The shape of th - **out**: _<array>_ - - an output array having the same data type as `x` and whose axes, relative to `x`, are flipped. + - an output array having the same data type and shape as `x` and whose axes, relative to `x`, are flipped. ### # reshape(x, shape, /) From d7c6758bcd26db7fae049f9c3f4e9f5336e4b544 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 14 Sep 2020 11:16:24 -0700 Subject: [PATCH 10/14] Update copy --- spec/API_specification/manipulation_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md index e5f4e4f6b..404d2ed98 100644 --- a/spec/API_specification/manipulation_functions.md +++ b/spec/API_specification/manipulation_functions.md @@ -47,7 +47,7 @@ Reverses the order of elements in an array along the given axis. The shape of th - **out**: _<array>_ - - an output array having the same data type and shape as `x` and whose axes, relative to `x`, are flipped. + - an output array having the same data type and shape as `x` and whose elements, relative to `x`, are reordered. ### # reshape(x, shape, /) From 7cd4c089eeef0aa75d706a00d3e3c15833adbebd Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 14 Sep 2020 11:17:53 -0700 Subject: [PATCH 11/14] Update copy --- spec/API_specification/manipulation_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md index 404d2ed98..36ceaf2ba 100644 --- a/spec/API_specification/manipulation_functions.md +++ b/spec/API_specification/manipulation_functions.md @@ -91,7 +91,7 @@ Rolls array elements along a specified axis. Array elements that roll beyond the - **out**: _<array>_ - - an output array having the same data type as `x` and whose elements, relative to `x`, have shifted. + - an output array having the same data type as `x` and whose elements, relative to `x`, are shifted. ### # squeeze(x, /, *, axis=None) From 2072f30f2d9f9894174795773f083c316eaf1d44 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 14 Sep 2020 11:59:24 -0700 Subject: [PATCH 12/14] Change Sequence to Tuple for consistency elsewhere --- 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 36ceaf2ba..6e5ac8726 100644 --- a/spec/API_specification/manipulation_functions.md +++ b/spec/API_specification/manipulation_functions.md @@ -15,7 +15,7 @@ Joins a sequence of arrays along an existing axis. #### Parameters -- **arrays**: _Sequence\[ <array> ]_ +- **arrays**: _Tuple\[ <array> ]_ - input arrays to join. The arrays must have the same shape, except in the dimension specified by `axis`. @@ -119,7 +119,7 @@ Joins a sequence of arrays along a new axis. #### Parameters -- **arrays**: _Sequence\[ <array> ]_ +- **arrays**: _Tuple\[ <array> ]_ - input arrays to join. Each array must have the same shape. From db52cbdf6ecf35706196b3834e8b46525b48bd2b Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 21 Sep 2020 01:27:18 -0700 Subject: [PATCH 13/14] Address PR feedback --- .../API_specification/manipulation_functions.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md index 6e5ac8726..1889ae5a3 100644 --- a/spec/API_specification/manipulation_functions.md +++ b/spec/API_specification/manipulation_functions.md @@ -6,6 +6,7 @@ A conforming implementation of the array API standard must provide and support t - 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. +- Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`. @@ -27,7 +28,11 @@ Joins a sequence of arrays along an existing axis. - **out**: _<array>_ - - an output array containing the concatenated values. + - 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. + + .. note:: + + This specification leaves type promotion between data type families (i.e., `intxx` and `floatxx`) unspecified. ### # flip(x, /, *, axis=None) @@ -59,9 +64,9 @@ Reshapes an array without changing its data. - input array to reshape. -- **shape**: _Union\[ int, Tuple\[ int, ... ] ]_ +- **shape**: _Tuple\[ int, ... ]_ - - a new shape compatible with the original shape. If `shape` is an integer, then the result must be a one-dimensional array of that length. One shape dimension is allowed to be `-1`. When a shape dimension is `-1`, the corresponding output array shape dimension must be inferred from the length of the array and the remaining dimensions. + - a new shape compatible with the original shape. One shape dimension is allowed to be `-1`. When a shape dimension is `-1`, the corresponding output array shape dimension must be inferred from the length of the array and the remaining dimensions. #### Returns @@ -131,4 +136,8 @@ 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`. \ No newline at end of file + - 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. + + .. note:: + + This specification leaves type promotion between data type families (i.e., `intxx` and `floatxx`) unspecified. \ No newline at end of file From 95c5b1a9420fa2beda1f3ce66f0b84aaebaccd55 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 21 Sep 2020 01:48:31 -0700 Subject: [PATCH 14/14] Add expand_dims --- .../manipulation_functions.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md index 1889ae5a3..96be715d1 100644 --- a/spec/API_specification/manipulation_functions.md +++ b/spec/API_specification/manipulation_functions.md @@ -34,6 +34,26 @@ Joins a sequence of arrays along an existing axis. This specification leaves type promotion between data type families (i.e., `intxx` and `floatxx`) unspecified. +### # 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`. + +#### Parameters + +- **x**: _<array>_ + + - input array. + +- **axis**: _int_ + + - axis position. Must follow Python's indexing rules: zero-based and negative indices must be counted backward from the last dimension. If `x` has rank `N`, a valid `axis` must reside on the interval `[-N-1, N+1]`. An `IndexError` exception must be raised if provided an invalid `axis` position. + +#### Returns + +- **out**: _<array>_ + + - an expanded output array having the same data type and shape as `x`. + ### # flip(x, /, *, axis=None) Reverses the order of elements in an array along the given axis. The shape of the array must be preserved.