@@ -953,10 +953,10 @@ def sort(a, axis=-1, kind=None, order=None, *, stable=None, descending=np._NoVal
953953 Axis along which to sort. If None, the array is flattened before
954954 sorting. The default is -1, which sorts along the last axis.
955955 kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, optional
956- Sorting algorithm. The default is 'quicksort'. Note that both 'stable'
957- and 'mergesort' use timsort or radix sort under the covers and,
958- in general, the actual implementation will vary with data type.
959- The 'mergesort' option is retained for backwards compatibility .
956+ Please use the `stable` parameter instead. This argument is retained
957+ for backwards compatibility and provides no additional control.
958+ 'quicksort' and 'heapsort' are equivalent to ``stable=False``, while
959+ 'mergesort' and 'stable' are equivalent to ``stable=True`` .
960960 order : str or list of str, optional
961961 When `a` is an array with fields defined, this argument specifies
962962 which fields to compare first, second, etc. A single field can
@@ -993,24 +993,19 @@ def sort(a, axis=-1, kind=None, order=None, *, stable=None, descending=np._NoVal
993993
994994 Notes
995995 -----
996- The various sorting algorithms are characterized by their average speed,
997- worst case performance, work space size, and whether they are stable. A
998- stable sort keeps items with the same key in the same relative
999- order. The four algorithms implemented in NumPy have the following
1000- properties:
1001-
1002- =========== ======= ============= ============ ========
1003- kind speed worst case work space stable
1004- =========== ======= ============= ============ ========
1005- 'quicksort' 1 O(n^2) 0 no
1006- 'heapsort' 3 O(n*log(n)) 0 no
1007- 'mergesort' 2 O(n*log(n)) ~n/2 yes
1008- 'timsort' 2 O(n*log(n)) ~n/2 yes
1009- =========== ======= ============= ============ ========
1010-
1011- .. note:: The datatype determines which of 'mergesort' or 'timsort'
1012- is actually used, even if 'mergesort' is specified. User selection
1013- at a finer scale is not currently available.
996+ NumPy uses different sorting algorithms depending on whether the sort is
997+ stable and which data types are used. These are characterized by their
998+ worst case performance, work space size, and whether they are stable.
999+ A stable sort keeps items with the same key in the same relative
1000+ order. NumPy chooses between three algorithms:
1001+
1002+ ======== ============ ============= ============ ================================
1003+ stable algorithm worst case work space note
1004+ ======== ============ ============= ============ ================================
1005+ no Introsort O(n*log(n)) 0
1006+ yes Timsort O(n*log(n)) ~n/2
1007+ yes Radix sort O(n) n bools and narrow integers [1]_
1008+ ======== ============ ============= ============ ================================
10141009
10151010 For performance, ``sort`` makes a temporary copy if needed to make the data
10161011 `contiguous <https://numpy.org/doc/stable/glossary.html#term-contiguous>`_
@@ -1034,32 +1029,20 @@ def sort(a, axis=-1, kind=None, order=None, *, stable=None, descending=np._NoVal
10341029 placements are sorted according to the non-nan part if it exists.
10351030 Non-nan values are sorted as before.
10361031
1037- quicksort has been changed to:
1038- `introsort <https://en.wikipedia.org/wiki/Introsort>`_.
1039- When sorting does not make enough progress it switches to
1040- `heapsort <https://en.wikipedia.org/wiki/Heapsort>`_.
1041- This implementation makes quicksort O(n*log(n)) in the worst case.
1032+ NumPy uses `introsort <https://en.wikipedia.org/wiki/Introsort>`_
1033+ by default for unstable sorting.
10421034
1043- 'stable' automatically chooses the best stable sorting algorithm
1044- for the data type being sorted.
1045- It, along with 'mergesort' is currently mapped to
1046- `timsort <https://en.wikipedia.org/wiki/Timsort>`_
1035+ For stable sorting, NumPy automatically chooses the best stable sorting
1036+ algorithm for the data type being sorted.
1037+ It is currently mapped to `timsort <https://en.wikipedia.org/wiki/Timsort>`_
10471038 or `radix sort <https://en.wikipedia.org/wiki/Radix_sort>`_
1048- depending on the data type.
1049- API forward compatibility currently limits the
1050- ability to select the implementation and it is hardwired for the different
1051- data types.
1052-
1053- Timsort is added for better performance on already or nearly
1054- sorted data. On random data timsort is almost identical to
1055- mergesort. It is now used for stable sort while quicksort is still the
1056- default sort if none is chosen. For timsort details, refer to
1057- `CPython listsort.txt
1058- <https://github.com/python/cpython/blob/3.7/Objects/listsort.txt>`_
1059- 'mergesort' and 'stable' are mapped to radix sort for integer data types.
1060- Radix sort is an O(n) sort instead of O(n log n).
1061-
1062- NaT now sorts to the end of arrays for consistency with NaN.
1039+ for bools and integer types with a width of 16 bits or less.
1040+
1041+ For numerical sorts, NaT and NaN always sort to the end of the array for
1042+ both ascending and descending sort order.
1043+
1044+ .. [1] Radix sort is used for stable sorting of bools and narrow integer
1045+ types (up to 16 bits). For these it performs better than Timsort.
10631046
10641047 Examples
10651048 --------
@@ -1131,10 +1114,10 @@ def argsort(a, axis=-1, kind=None, order=None, *, stable=None, descending=np._No
11311114 Axis along which to sort. The default is -1 (the last axis). If None,
11321115 the flattened array is used.
11331116 kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, optional
1134- Sorting algorithm. The default is 'quicksort'. Note that both 'stable'
1135- and 'mergesort' use timsort under the covers and, in general, the
1136- actual implementation will vary with data type. The 'mergesort' option
1137- is retained for backwards compatibility .
1117+ Please use the `stable` parameter instead. This argument is retained
1118+ for backwards compatibility and provides no additional control.
1119+ 'quicksort' and 'heapsort' are equivalent to ``stable=False``, while
1120+ 'mergesort' and 'stable' are equivalent to ``stable=True`` .
11381121 order : str or list of str, optional
11391122 When `a` is an array with fields defined, this argument specifies
11401123 which fields to compare first, second, etc. A single field can
0 commit comments