docs

Author: dg-pb

Misc/ACKS

@@ -685,6 +685,7 @@ Eddy De Greef
 Duane Griffin
 Grant Griffin
 Andrea Griffini
+Dominykas Grigonis
 Semyon Grigoryev
 Duncan Grisby
 Olivier Grisel

Objects/listobject.c

@@ -1801,7 +1801,8 @@ binarysort(MergeState *ms, const sortslice *ss, Py_ssize_t n, Py_ssize_t ok)
         ++ok;
 
 #if 1   // Adaptivity with post `count_run` optimization of 1st pivot
-    // 1. Known: a[ok] < a[ok - 1], as called after `count_run`
+    /* 1. Known: a[ok] < a[ok - 1], as called after `count_run`
+          This just insorts first element taking that into account */
     if (ok >= n)
         return 0;
     Py_ssize_t aL = 0;
@@ -1815,7 +1816,11 @@ binarysort(MergeState *ms, const sortslice *ss, Py_ssize_t n, Py_ssize_t ok)
 
     Py_ssize_t m = ok < 5 ? 11 : ok + 6;
     if (m < n) {
-        // 2. Small non-adaptive run to acquire good `std` estimate
+        /* 2. Small non-adaptive run to acquire good `std` estimate
+              Number of iterations (m) is chosen heuristically
+                and is subject to further calibration if needed.
+              It does minimum 6 iterations and up to 10 if pre-sorted part
+                is small as estimates of small integers are less reliable. */
         Py_ssize_t mu = aL;
         Py_ssize_t std = ok >> 1;
         for (; ok < m; ++ok) {
@@ -1832,7 +1837,15 @@ binarysort(MergeState *ms, const sortslice *ss, Py_ssize_t n, Py_ssize_t ok)
             mu = aL;
         }
 
-        // 3. Adaptive routine while `std` is small enough
+        /* 3. Adaptive routine while `std` is small enough
+              Take the last insertion point as the first midpoint
+                and do 2 subsequent step of size `std` trying to capture
+                the range into which new value falls in, potentially
+                locating insertion point faster than standard `binarysort`.
+              Continue until `std` (step size) is lower than
+                (size of sorted part) / 4.
+              If estimate from (2) is initially not small enough,
+                this does not execute a single time. */
         Py_ssize_t std_max = ok >> 2;
         for (; ok < n && std <= std_max; ++ok) {
             pivot = a[ok];
@@ -1885,7 +1898,7 @@ binarysort(MergeState *ms, const sortslice *ss, Py_ssize_t n, Py_ssize_t ok)
                     }
                 }
             }
-            // Binary Insertion
+            // Simple Binary Insertion Sort
             while (aL < aR) {
                 M = (aL + aR) >> 1;
                 IFLT(pivot, a[M])
@@ -1897,13 +1910,13 @@ binarysort(MergeState *ms, const sortslice *ss, Py_ssize_t n, Py_ssize_t ok)
             _binarysort_INSORT(aL, M)
 
             std += labs(aL - mu);
-            std /= 2;    // EWMA with alpha=0.5
+            std /= 2;               // EWMA with alpha=0.5
             mu = aL;
-            std_max += !(ok % 4);
+            std_max += !(ok % 4);   // Keep approximately equal to: ok / 4
         }
     }
 
-    // 4. Finish off with non-adaptive sort
+    // 4. Finish with non-adaptive sort
 #endif  // End of adaptivity
 
 

Objects/listsort.txt

@@ -839,6 +839,12 @@ reasonable minrun values.
 Additionally, "binary insertion sort" has implemented adaptivity procedure,
 which reduces the number of comparisons for cases where data is already
 sorted to high degree in either forward or reversed order.
+While "binary insertion sort" ensures optimal number of comparisons
+it looses best case of textbook insertion sort when data is highly sorted
+in correct order. Adaptivity addition brings that back and more at small cost.
+It adapts to any data where position of next element is close to the one of
+last element. Thus, it adapts to cases where it is highly sorted in correct
+order, reverse order or elements are being funneled into some mid-point.
 
 
 LEFT OR RIGHT