From a416b032306413f53a8e616c32818b6250a83aa0 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 24 Aug 2020 00:03:08 -0700 Subject: [PATCH 1/6] Add specifications for sorting functions --- spec/API_specification/index.rst | 1 + spec/API_specification/sorting_functions.md | 51 +++++++++++++++++++++ 2 files changed, 52 insertions(+) create mode 100644 spec/API_specification/sorting_functions.md diff --git a/spec/API_specification/index.rst b/spec/API_specification/index.rst index c256627b6..60224a958 100644 --- a/spec/API_specification/index.rst +++ b/spec/API_specification/index.rst @@ -13,3 +13,4 @@ API specification broadcasting out_keyword elementwise_functions + sorting_functions \ No newline at end of file diff --git a/spec/API_specification/sorting_functions.md b/spec/API_specification/sorting_functions.md new file mode 100644 index 000000000..5c995f388 --- /dev/null +++ b/spec/API_specification/sorting_functions.md @@ -0,0 +1,51 @@ +# Sorting Functions + +> Array API specification for sorting functions. + +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. +- Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. + + + +### # argsort(x, /, *, axis=-1) + +Returns the indices that sort an array `x` along a specified axis. + +#### Parameters + +- **x**: _<array>_ + + - input array. + +- **axis**: _int_ + + - axis along which to sort. If set to `-1`, the function sorts along the last axis. Default: `-1`. + +#### Returns + +- **out**: _<array>_ + + - an array of indices having the same shape as `x`. + +### # sort(x, /, *, axis=-1) + +Returns a sorted copy of an input array `x`. + +#### Parameters + +- **x**: _<array>_ + + - input array. + +- **axis**: _int_ + + - axis along which to sort. If set to `-1`, the function sorts along the last axis. Default: `-1`. + +#### Returns + +- **out**: _<array>_ + + - a sorted array having the same data type and shape as `x`. From dde12bb087d1ab4b3fedb06e7e6382ee51c5f16e Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 24 Aug 2020 14:35:59 -0700 Subject: [PATCH 2/6] Specify sort order --- spec/API_specification/sorting_functions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/sorting_functions.md b/spec/API_specification/sorting_functions.md index 5c995f388..0d59e061f 100644 --- a/spec/API_specification/sorting_functions.md +++ b/spec/API_specification/sorting_functions.md @@ -12,7 +12,7 @@ A conforming implementation of the array API standard must provide and support t ### # argsort(x, /, *, axis=-1) -Returns the indices that sort an array `x` along a specified axis. +Returns the indices that sort an array `x` in ascending order along a specified axis. #### Parameters @@ -32,7 +32,7 @@ Returns the indices that sort an array `x` along a specified axis. ### # sort(x, /, *, axis=-1) -Returns a sorted copy of an input array `x`. +Returns a sorted (in ascending order) copy of an input array `x`. #### Parameters From 492b26fe82d347edf9ccd791a2e9f84a5d6e2b7b Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 24 Aug 2020 15:59:01 -0700 Subject: [PATCH 3/6] Add `descending` keyword argument --- spec/API_specification/sorting_functions.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/spec/API_specification/sorting_functions.md b/spec/API_specification/sorting_functions.md index 0d59e061f..9cab37440 100644 --- a/spec/API_specification/sorting_functions.md +++ b/spec/API_specification/sorting_functions.md @@ -10,9 +10,9 @@ A conforming implementation of the array API standard must provide and support t -### # argsort(x, /, *, axis=-1) +### # argsort(x, /, *, axis=-1, descending=False) -Returns the indices that sort an array `x` in ascending order along a specified axis. +Returns the indices that sort an array `x` along a specified axis. #### Parameters @@ -24,15 +24,19 @@ Returns the indices that sort an array `x` in ascending order along a specified - axis along which to sort. If set to `-1`, the function sorts along the last axis. Default: `-1`. +- **descending**: _bool_ + + - sort order. If `True`, the returned indices sort `x` in descending order (by value). If `False`, the returned indices sort `x` in ascending order (by value). Default: `False`. + #### Returns - **out**: _<array>_ - - an array of indices having the same shape as `x`. + - an array of indices. Must have the same shape as `x`. -### # sort(x, /, *, axis=-1) +### # sort(x, /, *, axis=-1, descending=False) -Returns a sorted (in ascending order) copy of an input array `x`. +Returns a sorted copy of an input array `x`. #### Parameters @@ -44,8 +48,12 @@ Returns a sorted (in ascending order) copy of an input array `x`. - axis along which to sort. If set to `-1`, the function sorts along the last axis. Default: `-1`. +- **descending**: _bool_ + + - sort order. If `True`, the array is sorted in descending order (by value). If `False`, the array is sorted in ascending order (by value). Default: `False`. + #### Returns - **out**: _<array>_ - - a sorted array having the same data type and shape as `x`. + - a sorted array. Must have the same data type and shape as `x`. From b25a163148284f202cf07a5c0b88d070c71e4a27 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 8 Nov 2020 09:24:13 -0600 Subject: [PATCH 4/6] Add `stable` keyword --- spec/API_specification/sorting_functions.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/sorting_functions.md b/spec/API_specification/sorting_functions.md index 9cab37440..ba8c57c2f 100644 --- a/spec/API_specification/sorting_functions.md +++ b/spec/API_specification/sorting_functions.md @@ -10,7 +10,7 @@ A conforming implementation of the array API standard must provide and support t -### # argsort(x, /, *, axis=-1, descending=False) +### # argsort(x, /, *, axis=-1, descending=False, stable=True) Returns the indices that sort an array `x` along a specified axis. @@ -28,13 +28,17 @@ Returns the indices that sort an array `x` along a specified axis. - sort order. If `True`, the returned indices sort `x` in descending order (by value). If `False`, the returned indices sort `x` in ascending order (by value). Default: `False`. +- **stable**: _bool_ + + - sort stability. If `True`, the returned indices must maintain the relative order of `x` values which compare as equal. If `False`, the returned indices may or may not maintain the relative order of `x` values which compare as equal (i.e., the relative order of `x` values which compare as equal is implementation-dependent). Default: `True`. + #### Returns - **out**: _<array>_ - an array of indices. Must have the same shape as `x`. -### # sort(x, /, *, axis=-1, descending=False) +### # sort(x, /, *, axis=-1, descending=False, stable=True) Returns a sorted copy of an input array `x`. @@ -52,6 +56,10 @@ Returns a sorted copy of an input array `x`. - sort order. If `True`, the array is sorted in descending order (by value). If `False`, the array is sorted in ascending order (by value). Default: `False`. +- **stable**: _bool_ + + - sort stability. If `True`, the returned array must maintain the relative order of `x` values which compare as equal. If `False`, the returned indices may or may not maintain the relative order of `x` values which compare as equal (i.e., the relative order of `x` values which compare as equal is implementation-dependent). Default: `True`. + #### Returns - **out**: _<array>_ From 15dca88071373d92c50c8775c003ec71121e200a Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 8 Nov 2020 09:28:58 -0600 Subject: [PATCH 5/6] Fix copy --- spec/API_specification/sorting_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/sorting_functions.md b/spec/API_specification/sorting_functions.md index ba8c57c2f..be45a5c43 100644 --- a/spec/API_specification/sorting_functions.md +++ b/spec/API_specification/sorting_functions.md @@ -58,7 +58,7 @@ Returns a sorted copy of an input array `x`. - **stable**: _bool_ - - sort stability. If `True`, the returned array must maintain the relative order of `x` values which compare as equal. If `False`, the returned indices may or may not maintain the relative order of `x` values which compare as equal (i.e., the relative order of `x` values which compare as equal is implementation-dependent). Default: `True`. + - sort stability. If `True`, the returned array must maintain the relative order of `x` values which compare as equal. If `False`, the returned array may or may not maintain the relative order of `x` values which compare as equal (i.e., the relative order of `x` values which compare as equal is implementation-dependent). Default: `True`. #### Returns From 06bdb45bc1e3a072a16310f9588ab23da261759c Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 8 Nov 2020 09:31:40 -0600 Subject: [PATCH 6/6] Specify output array data types --- spec/API_specification/sorting_functions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/sorting_functions.md b/spec/API_specification/sorting_functions.md index be45a5c43..2cc31a082 100644 --- a/spec/API_specification/sorting_functions.md +++ b/spec/API_specification/sorting_functions.md @@ -36,7 +36,7 @@ Returns the indices that sort an array `x` along a specified axis. - **out**: _<array>_ - - an array of indices. Must have the same shape as `x`. + - an array of indices. The returned array must have the same shape as `x`. The returned array must have the default array index data type. ### # sort(x, /, *, axis=-1, descending=False, stable=True) @@ -64,4 +64,4 @@ Returns a sorted copy of an input array `x`. - **out**: _<array>_ - - a sorted array. Must have the same data type and shape as `x`. + - a sorted array. The returned array must have the same data type and shape as `x`.