Code comments from JS version; minor doc updates

Author: haukex

README.md

@@ -32,10 +32,15 @@ Please choose 'B' or 'A': B
 **References**
 
 1. Ford, L. R., & Johnson, S. M. (1959). A Tournament Problem.
-   The American Mathematical Monthly, 66(5), 387-389. <[https://doi.org/10.1080/00029890.1959.11989306](https://doi.org/10.1080/00029890.1959.11989306)>
+   The American Mathematical Monthly, 66(5), 387-389. [https://doi.org/10.1080/00029890.1959.11989306](https://doi.org/10.1080/00029890.1959.11989306)
 2. Knuth, D. E. (1998). The Art of Computer Programming: Volume 3: Sorting and Searching (2nd ed.).
-   Addison-Wesley. <[https://cs.stanford.edu/~knuth/taocp.html#vol3](https://cs.stanford.edu/~knuth/taocp.html#vol3)>
-3. <[https://en.wikipedia.org/wiki/Merge-insertion_sort](https://en.wikipedia.org/wiki/Merge-insertion_sort)>
+   Addison-Wesley. [https://cs.stanford.edu/~knuth/taocp.html#vol3](https://cs.stanford.edu/~knuth/taocp.html#vol3)
+3. [https://en.wikipedia.org/wiki/Merge-insertion_sort](https://en.wikipedia.org/wiki/Merge-insertion_sort)
+
+## See Also
+
+* JavaScript / TypeScript version: [https://www.npmjs.com/package/merge-insertion](https://www.npmjs.com/package/merge-insertion)
+* This algorithm in action: [https://haukex.github.io/pairrank/](https://haukex.github.io/pairrank/) (select “Efficient”)
 
 ## API
 
@@ -53,7 +58,7 @@ alias of TypeVar(‘T’)
 ### merge_insertion.Comparator
 
 A user-supplied async function to compare two items.
-The argument is a tuple of the two items to be compared; they must not be equal.
+The single argument is a tuple of the two items to be compared; they must not be equal.
 Must return 0 if the first item is ranked higher, or 1 if the second item is ranked higher.
 
 <a id="merge_insertion.merge_insertion_sort"></a>
@@ -63,8 +68,8 @@ Must return 0 if the first item is ranked higher, or 1 if the second item is ran
 Merge-Insertion Sort (Ford-Johnson algorithm) with async comparison.
 
 * **Parameters:**
-  * **array** – Array of to sort. Duplicate items are not allowed.
-  * **comparator** – Async comparison function.
+  * **array** – Array to sort. **Duplicate items are not allowed.**
+  * **comparator** – Async comparison function as described in [`Comparator`](#merge_insertion.Comparator).
 * **Returns:**
   A shallow copy of the array sorted in ascending order.
 

merge_insertion/__init__.py

@@ -30,19 +30,24 @@
 **References**
 
 1. Ford, L. R., & Johnson, S. M. (1959). A Tournament Problem.
-   The American Mathematical Monthly, 66(5), 387-389. <https://doi.org/10.1080/00029890.1959.11989306>
+   The American Mathematical Monthly, 66(5), 387-389. https://doi.org/10.1080/00029890.1959.11989306
 2. Knuth, D. E. (1998). The Art of Computer Programming: Volume 3: Sorting and Searching (2nd ed.).
-   Addison-Wesley. <https://cs.stanford.edu/~knuth/taocp.html#vol3>
-3. <https://en.wikipedia.org/wiki/Merge-insertion_sort>
+   Addison-Wesley. https://cs.stanford.edu/~knuth/taocp.html#vol3
+3. https://en.wikipedia.org/wiki/Merge-insertion_sort
+
+See Also
+--------
+
+* JavaScript / TypeScript version: https://www.npmjs.com/package/merge-insertion
+
+* This algorithm in action: https://haukex.github.io/pairrank/ (select "Efficient")
 
 API
 ---
 
 .. autoclass:: merge_insertion.T
-    :members:
 
 .. autoclass:: merge_insertion.Comparator
-    :members:
 
 .. autofunction:: merge_insertion.merge_insertion_sort
 
@@ -69,15 +74,15 @@
 from typing import TypeVar, Literal
 from math import floor, ceil, log2
 
-# NOTICE: This file contains very few code comments because it is a port of
-# https://github.com/haukex/merge-insertion.js/blob/main/src/merge-insertion.ts
-# Please see that file for detailed code comments and explanations.
-
 #: A type of object that can be compared by a :class:`Comparator` and therefore sorted by
 #: :func:`merge_insertion_sort`. Must have sensible support for the equality operators.
 T = TypeVar('T')
 
+# Helper that generates the group sizes for _make_groups.
 def _group_sizes() -> Generator[int, None, None]:
+    # <https://en.wikipedia.org/wiki/Merge-insertion_sort>:
+    # "... the sums of sizes of every two adjacent groups form a sequence of powers of two."
+    # <https://oeis.org/A014113>: a(0) = 0 and if n>=1, a(n) = 2^n - a(n-1).
     prev :int = 0
     i :int = 1
     while True:
@@ -86,6 +91,8 @@ def _group_sizes() -> Generator[int, None, None]:
         prev = cur
         i += 1
 
+# Helper function to group and reorder items to be inserted via binary search.
+# See also the description within the code of merge_insertion_sort.
 def _make_groups(array :Sequence[T]) -> Sequence[tuple[int, T]]:
     items = list(enumerate(array))
     rv :list[tuple[int, T]] = []
@@ -102,10 +109,12 @@ def _make_groups(array :Sequence[T]) -> Sequence[tuple[int, T]]:
     return rv
 
 #: A user-supplied async function to compare two items.
-#: The argument is a tuple of the two items to be compared; they must not be equal.
+#: The single argument is a tuple of the two items to be compared; they must not be equal.
 #: Must return 0 if the first item is ranked higher, or 1 if the second item is ranked higher.
 Comparator = Callable[[tuple[T, T]], Awaitable[Literal[0, 1]]]
 
+# Helper function to insert an item into a sorted array via binary search.
+# Returns the index **before** which to insert the new item, e.g. `array.insert(index, item)`
 async def _bin_insert_index(array :Sequence[T], item :T, comp :Comparator) -> int:
     if not array:
         return 0
@@ -122,6 +131,7 @@ async def _bin_insert_index(array :Sequence[T], item :T, comp :Comparator) -> in
             left = mid + 1
     return left
 
+# Finds the index of an object in an array by object identity (instead of equality).
 def _ident_find(array :Sequence[T], item :T) -> int:
     for i,e in enumerate(array):
         if e is item:
@@ -135,6 +145,7 @@ async def merge_insertion_sort(array :Sequence[T], comparator :Comparator) -> Se
     :param comparator: Async comparison function as described in :class:`Comparator`.
     :return: A shallow copy of the array sorted in ascending order.
     """
+    # Special cases and error checking
     if len(array)<1:
         return []
     if len(array)==1:
@@ -144,30 +155,84 @@ async def merge_insertion_sort(array :Sequence[T], comparator :Comparator) -> Se
     if len(array)==2:
         return list(array) if await comparator((array[0], array[1])) else [array[1], array[0]]
 
-    pairs :dict[T, T] = {}
+    # Algorithm description adapted and expanded from <https://en.wikipedia.org/wiki/Merge-insertion_sort>:
+    # 1. Group the items into ⌊n/2⌋ pairs of elements, arbitrarily, leaving one element unpaired if there is an odd number of elements.
+    # 2. Perform ⌊n/2⌋ comparisons, one per pair, to determine the larger of the two elements in each pair.
+    pairs :dict[T, T] = {}  # keys are the larger items, values the smaller ones
     for i in range(0, len(array)-1, 2):
         if await comparator((array[i], array[i+1])):
             pairs[array[i+1]] = array[i]
         else:
             pairs[array[i]] = array[i+1]
 
+    # 3. Recursively sort the ⌊n/2⌋ larger elements from each pair, creating an initial sorted output sequence
+    #    of ⌊n/2⌋ of the input elements, in ascending order, using the merge-insertion sort.
     larger = await merge_insertion_sort(list(pairs), comparator)
 
+    # Build the "main chain" data structure we will use to insert items into (explained a bit more below), while also:
+    # 4. Insert at the start of the sorted sequence the element that was paired with
+    #    the first and smallest element of the sorted sequence.
+    # Note that we know the main chain has at least one item here due to the special cases at the beginning of this function.
     main_chain :list[list[T]] = [ [ pairs[larger[0]] ], [ larger[0] ] ] + [ [ la, pairs[la] ] for la in larger[1:] ]
     assert all( len(i)==2 for i in main_chain[2:] )
 
+    # 5. Insert the remaining ⌈n/2⌉−1 items that are not yet in the sorted output sequence into that sequence,
+    #    one at a time, with a specially chosen insertion ordering, as follows:
+    #
+    # a. Partition the un-inserted elements yᵢ into groups with contiguous indexes.
+    #    There are two elements y₃ and y₄ in the first group¹, and the sums of sizes of every two adjacent
+    #    groups form a sequence of powers of two. Thus, the sizes of groups are: 2, 2, 6, 10, 22, 42, ...
+    # b. Order the un-inserted elements by their groups (smaller indexes to larger indexes), but within each
+    #    group order them from larger indexes to smaller indexes. Thus, the ordering becomes:
+    #      y₄, y₃, y₆, y₅, y₁₂, y₁₁, y₁₀, y₉, y₈, y₇, y₂₂, y₂₁, ...
+    # c. Use this ordering to insert the elements yᵢ into the output sequence. For each element yᵢ,
+    #    use a binary search from the start of the output sequence up to but not including xᵢ to determine
+    #    where to insert yᵢ.²
+    #
+    # ¹ My explanation: The items already in the sorted output sequence (the larger elements of each pair) are
+    # labeled xᵢ and the yet unsorted (smaller) elements are labeled yᵢ, with i starting at 1. However, due
+    # to step 4 above, the item that would have been labeled y₁ has actually already become element x₁, and
+    # therefore the element that would have been x₁ is now x₂ and no longer has a paired yᵢ element. It
+    # follows that the first paired elements are x₃ and y₃, and so the first unsorted element to be inserted
+    # into the output sequence is y₃. Also noteworthy is that if the input had an odd number of elements,
+    # the leftover unpaired element is treated as the last yᵢ element.
+    #
+    # ² In my opinion, this is lacking detail, and this seems to be true for the other two sources (Ford-Johnson
+    # and Knuth) as well. So here is my attempt at adding more details to the explanation: The "main chain" is
+    # always kept in sorted order, therefore, for each item of the main chain that has an associated `smaller`
+    # item, we know that this smaller item must be inserted *before* that main chain item. The problem I see
+    # with the various descriptions is that they don't explicitly explain that the insertion process shifts all
+    # the indices of the array, and due to the nonlinear insertion order, this makes it tricky to keep track of
+    # the correct array indices over which to perform the insertion search. So instead, below, I use a linear
+    # search to find the main chain item being operated on each time, which is expensive, but much easier. It
+    # should also be noted that the leftover unpaired element, if there is one, gets inserted across the whole
+    # main chain as it exists at the time of its insertion - it may not be inserted last. So even though there
+    # is still some optimization potential, this algorithm is used in cases where the comparisons are much more
+    # expensive than the rest of the algorithm, so the cost is acceptable for now.
+
+    # Iterate over the groups to be inserted, which are built from the main chain as explained above (in the
+    # current implementation we don't need the original indices returned by _make_groups). Also, if there was
+    # a leftover item from an odd input length, treat it as the last "smaller" item. We'll use the fact that
+    # at this point, all main_chain items contain two elements, so we'll mark the leftover item as a special
+    # case by having it be the only item with one element.
     for _,pair in _make_groups( main_chain[2:] + ( [[array[-1]]] if len(array) % 2 else [] ) ):
-        if len(pair)==1:
+        # Determine which item to insert and where.
+        if len(pair)==1:  # See explanation of this special case above.
+            # This is the leftover item, it gets inserted into the current whole main chain.
             item = pair[0]
             idx = await _bin_insert_index([ i[0] for i in main_chain ], item, comparator)
         else:
             assert len(pair)==2
+            # Locate the pair we're about to insert in the main chain, to limit the extent of the binary search (see also explanation above).
             pair_idx = _ident_find(main_chain, pair)
             item = pair.pop()
+            # Locate the index in the main chain where the pair's smaller item needs to be inserted.
             idx = await _bin_insert_index([ i[0] for i in main_chain[:pair_idx] ], item, comparator)
+        # Actually do the insertion.
         main_chain.insert(idx, [item])
     assert all( len(i)==1 for i in main_chain )
 
+    # Turn the "main chain" data structure back into an array of values.
     return [ i[0] for i in main_chain ]
 
 def merge_insertion_max_comparisons(n :int) -> int:
@@ -178,4 +243,5 @@ def merge_insertion_max_comparisons(n :int) -> int:
     """
     if n<0:
         raise ValueError("must specify zero or more items")
+    # Formula from https://en.wikipedia.org/wiki/Merge-insertion_sort (the sum version should work too)
     return n*ceil(log2(3*n/4)) - floor((2**floor(log2(6*n)))/3) + floor(log2(6*n)/2) if n else 0

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "merge-insertion"
 description = "The merge-insertion sort (aka the Ford-Johnson algorithm) is optimized for using few comparisons."
-version = "1.1.0"
+version = "1.1.1"
 authors = [ { name="Hauke Dämpfling", email="haukex@zero-g.net" } ]
 readme = "README.md"
 requires-python = ">=3.10"