Implemented Introsort (#549)

Co-authored-by: ਗਗਨਦੀਪ ਸਿੰਘ (Gagandeep Singh) <gdp.1807@gmail.com>

Author: Kishan-Ved

.github/workflows/ci.yml

@@ -9,7 +9,7 @@ on:
 jobs:
   test-ubuntu-py38:
     runs-on: ${{matrix.os}}
-    timeout-minutes: 10
+    timeout-minutes: 20
     strategy:
       fail-fast: false
       matrix:
@@ -61,7 +61,7 @@ jobs:
 
   test-ubuntu-py39-py310:
     runs-on: ${{matrix.os}}
-    timeout-minutes: 10
+    timeout-minutes: 20
     strategy:
       fail-fast: false
       matrix:
@@ -101,7 +101,7 @@ jobs:
 
   test-macos:
     runs-on: ${{matrix.os}}
-    timeout-minutes: 10
+    timeout-minutes: 20
     strategy:
       fail-fast: false
       matrix:
@@ -142,7 +142,7 @@ jobs:
 
   test-windows:
     runs-on: ${{matrix.os}}
-    timeout-minutes: 15
+    timeout-minutes: 20
     strategy:
       fail-fast: false
       matrix:

docs/source/pydatastructs/linear_data_structures/algorithms.rst

@@ -44,3 +44,5 @@ Algorithms
 .. autofunction:: pydatastructs.binary_search
 
 .. autofunction:: pydatastructs.jump_search
+
+.. autofunction:: pydatastructs.intro_sort

pydatastructs/linear_data_structures/__init__.py

@@ -45,6 +45,7 @@
     binary_search,
     jump_search,
     selection_sort,
-    insertion_sort
+    insertion_sort,
+    intro_sort
 )
 __all__.extend(algorithms.__all__)

pydatastructs/linear_data_structures/algorithms.py

@@ -29,7 +29,8 @@
     'binary_search',
     'jump_search',
     'selection_sort',
-    'insertion_sort'
+    'insertion_sort',
+    'intro_sort'
 ]
 
 def _merge(array, sl, el, sr, er, end, comp):
@@ -1740,3 +1741,112 @@ def jump_search(array, value, **kwargs):
         prev += 1
 
     return None
+
+def intro_sort(array, **kwargs) -> Array:
+    """
+    Performs intro sort on the given array.
+
+    Parameters
+    ==========
+
+    array: Array
+        The array which is to be sorted.
+    start: int
+        The starting index of the portion
+        which is to be sorted.
+        Optional, by default 0
+    end: int
+        The ending index of the portion which
+        is to be sorted.
+        Optional, by default the index
+        of the last position filled.
+    maxdepth: Enables the user to define the maximum
+        recursion depth, takes value 2*log(length(A))
+        by default (ref: Wikipedia[1]).
+    ins_threshold: Threshold under which insertion
+        sort has to be performed, default value is
+        16 (ref: Wikipedia[1]).
+    backend: pydatastructs.Backend
+        The backend to be used.
+        Optional, by default, the best available
+        backend is used.
+
+    Returns
+    =======
+
+    output: Array
+        The sorted array.
+
+    Examples
+    ========
+
+    >>> from pydatastructs import OneDimensionalArray as ODA, intro_sort
+    >>> arr = ODA(int, [5, 78, 1, 0])
+    >>> out = intro_sort(arr)
+    >>> str(out)
+    '[0, 1, 5, 78]'
+    >>> arr = ODA(int, [21, 37, 5])
+    >>> out = intro_sort(arr)
+    >>> str(out)
+    '[5, 21, 37]'
+
+    Note
+    ====
+
+    This function does not support custom comparators as
+    is the case with other sorting functions in this file.
+    This is because of heapsort's limitation.
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Introsort
+    """
+    raise_if_backend_is_not_python(
+        intro_sort, kwargs.get('backend', Backend.PYTHON))
+
+    # Always sorts in increasing order, this is because of
+    # heapsort's limitation
+    comp = lambda u, v: u <= v
+    lower = kwargs.get('start', 0)
+    upper = kwargs.get('end', len(array) - 1)
+    n = upper - lower + 1
+    if n <= 0:
+        maxdepth = 0
+    else:
+        maxdepth = kwargs.get("maxdepth", int(2 * (log(n)/log(2))))
+
+    ins_threshold = kwargs.get("ins_threshold", 16)
+
+    def partition(array, lower, upper):
+        pivot = array[lower]
+        left = lower + 1
+        right = upper
+        done = False
+        while not done:
+            while left <= right and _comp(array[left], pivot, comp):
+                left += 1
+            while _comp(pivot, array[right], comp) and right >= left:
+                right -= 1
+            if right < left:
+                done = True
+            else:
+                array[left], array[right] = array[right], array[left]
+                left+=1
+                right-=1
+
+        array[lower], array[right] = array[right], array[lower]
+        return right
+
+    if n < ins_threshold:
+        return insertion_sort(array, start=lower, end=upper)
+    elif maxdepth == 0:
+        heapsort(array, start=lower, end=upper)
+        return array
+    else:
+        p = partition(array, lower, upper)
+
+        intro_sort(array, start=lower, end=p-1, maxdepth=maxdepth-1, ins_threshold=ins_threshold)
+        intro_sort(array, start=p+1, end=upper,  maxdepth=maxdepth-1, ins_threshold=ins_threshold)
+
+        return array

pydatastructs/linear_data_structures/tests/benchmarks/test_algorithms.py

@@ -41,6 +41,9 @@ def test_quick_sort():
 def test_bubble_sort():
     _test_common_sort(bubble_sort, size=2000)
 
+@pytest.mark.xfail
+def test_intro_sort():
+     _test_common_sort(intro_sort, size=2000)
 
 @pytest.mark.xfail
 def test_selection_sort():

pydatastructs/linear_data_structures/tests/test_algorithms.py

@@ -5,7 +5,7 @@
     cocktail_shaker_sort, quick_sort, longest_common_subsequence, is_ordered,
     upper_bound, lower_bound, longest_increasing_subsequence, next_permutation,
     prev_permutation, bubble_sort, linear_search, binary_search, jump_search,
-    selection_sort, insertion_sort, Backend)
+    selection_sort, insertion_sort, intro_sort, Backend)
 
 from pydatastructs.utils.raises_util import raises
 import random
@@ -115,6 +115,9 @@ def test_quick_sort():
     _test_common_sort(quick_sort)
     _test_common_sort(quick_sort, backend=Backend.CPP)
 
+def test_intro_sort():
+    _test_common_sort(intro_sort)
+
 def test_bubble_sort():
     _test_common_sort(bubble_sort)
     _test_common_sort(bubble_sort, backend=Backend.CPP)

pydatastructs/utils/tests/test_code_quality.py

@@ -174,7 +174,7 @@ def _apis():
     pyds.Trie, pyds.TrieNode, pyds.SkipList, pyds.RangeQueryStatic, pyds.RangeQueryDynamic, pyds.SparseTable,
     pyds.miscellaneous_data_structures.segment_tree.OneDimensionalArraySegmentTree,
     pyds.bubble_sort, pyds.linear_search, pyds.binary_search, pyds.jump_search,
-    pyds.selection_sort, pyds.insertion_sort, pyds.quick_sort]
+    pyds.selection_sort, pyds.insertion_sort, pyds.quick_sort, pyds.intro_sort]
 
 def test_public_api():
     pyds = pydatastructs