Make a difference between measures of disorder and measures of presortedness

Author: Morwenn

README.md

@@ -41,7 +41,7 @@ of the library:
 * Sorters can be wrapped in [sorter adapters](https://github.com/Morwenn/cpp-sort/wiki/Sorter-adapters) to augment their behaviour
 * The library provides a [sorter facade](https://github.com/Morwenn/cpp-sort/wiki/Sorter-facade) to easily build sorters
 * [Fixed-size sorters](https://github.com/Morwenn/cpp-sort/wiki/Fixed-size-sorters) can be used to efficiently sort tiny fixed-size collections
-* [Measures of presortedness](https://github.com/Morwenn/cpp-sort/wiki/Measures-of-presortedness) can be used to evaluate the disorder in a collection
+* [Measures of disorder](https://github.com/Morwenn/cpp-sort/wiki/Measures-of-disorder) can be used to evaluate the disorder in a collection
 
 Here is a more complete example of what can be done with the library:
 

benchmarks/benchmarking-tools/distributions.h

@@ -374,7 +374,7 @@ namespace dist
     };
 
     ////////////////////////////////////////////////////////////
-    // Distributions: testing measures of presortedness
+    // Distributions: testing measures of disorder
 
     struct inv:
         base_distribution<inv>

…ks/presortedness/bench-presortedness.cpp benchmarks/disorder/bench-disorder.cppbenchmarks/presortedness/bench-presortedness.cpp renamed to benchmarks/disorder/bench-disorder.cpp benchmarks/presortedness/bench-presortedness.cpp renamed to benchmarks/disorder/bench-disorder.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2020-2024 Morwenn
+ * Copyright (c) 2020-2025 Morwenn
  * SPDX-License-Identifier: MIT
  */
 #include <algorithm>
@@ -89,10 +89,10 @@ int main(int argc, char* argv[])
             double factor = 0.01 * idx;
             auto distribution = dist::inv(factor);
 
-            // Compute presortedness
+            // Compute disorder
             collection_t collection;
             distribution(std::back_inserter(collection), size);
-            auto presortedness = cppsort::probe::inv(collection);
+            auto disorder = cppsort::probe::inv(collection);
 
             // Compute the time it took
             std::vector<std::uint64_t> cycles;
@@ -109,8 +109,8 @@ int main(int argc, char* argv[])
             }
 
             // Compute and display stats & numbers
-            output_file << presortedness << ",";
-            std::cout << presortedness << ",";
+            output_file << disorder << ",";
+            std::cout << disorder << ",";
             auto it = cycles.begin();
             output_file << *it;
             std::cout << *it;

…rks/presortedness/check-distribution.cpp …nchmarks/disorder/check-distribution.cppbenchmarks/presortedness/check-distribution.cpp renamed to benchmarks/disorder/check-distribution.cpp benchmarks/presortedness/check-distribution.cpp renamed to benchmarks/disorder/check-distribution.cpp

@@ -17,8 +17,8 @@
 // Distribution
 using dist_t = dist::runs;
 
-// Measure of presortedness
-auto mop = cppsort::probe::runs;
+// Measure of disorder
+auto measure = cppsort::probe::runs;
 
 // Size of the collections to check
 constexpr std::size_t size = 1'000'000;
@@ -28,7 +28,7 @@ constexpr std::size_t size = 1'000'000;
 //
 // The raison d'être of this script is to be able to visualize
 // the aspects of the distributions used to test whether some
-// sorter adapt to given measures of presortedness: for example
+// sorter adapt to given measures of disorder: for example
 // dist::inv, when given a percentage pct, should be able to
 // create a random collection X such as:
 //    prove::inv(X) = pct * probe::inv.max_for_size(|X|)
@@ -45,21 +45,21 @@ int main()
     // Print metadata about the check
     std::cout << dist_t::name << ','
               << size << ','
-              << mop.max_for_size(size) << ','
+              << measure.max_for_size(size) << ','
               << seed << std::endl;
 
     for (int idx = 0; idx <= 100; ++idx) {
         // Generate data distribution
         double factor = 0.01 * idx;
         auto distribution = dist_t(factor);
 
-        // Compute presortedness
+        // Compute disorder
         std::vector<int> collection;
         collection.reserve(size);
         distribution(std::back_inserter(collection), size);
-        auto presortedness = mop(collection);
+        auto disorder = measure(collection);
 
         // Display results
-        std::cout << idx << ',' << presortedness << std::endl;
+        std::cout << idx << ',' << disorder << std::endl;
     }
 }

…marks/presortedness/plot-distribution.py benchmarks/disorder/plot-distribution.pybenchmarks/presortedness/plot-distribution.py renamed to benchmarks/disorder/plot-distribution.py benchmarks/presortedness/plot-distribution.py renamed to benchmarks/disorder/plot-distribution.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-# Copyright (c) 2023 Morwenn
+# Copyright (c) 2023-2025 Morwenn
 # SPDX-License-Identifier: MIT
 
 import argparse
@@ -22,7 +22,7 @@
 
     with path.open() as fd:
         # Read metadata from the first line
-        mop_name, _, max_disorder, _ = fd.readline().strip().split(',')
+        mod_name, _, max_disorder, _ = fd.readline().strip().split(',')
 
         # Read the rest of the file
         percentages = []
@@ -40,10 +40,10 @@
     axes.ticklabel_format(style='plain')
     # Add a tick for the maximum disorder possible
     axes2.axhline(int(max_disorder), linestyle=':', color='gray')
-    axes2.set_yticks([int(max_disorder)], [f"$max({mop_name.capitalize()}(X))$"])
+    axes2.set_yticks([int(max_disorder)], [f"$max({mod_name.capitalize()}(X))$"])
 
-    pyplot.title(f"${mop_name.capitalize()}(X)$ generated by dist::{mop_name}")
-    axes.set_ylabel(mop_name.capitalize())
+    pyplot.title(f"${mod_name.capitalize()}(X)$ generated by dist::{mod_name}")
+    axes.set_ylabel(mod_name.capitalize())
 
     pyplot.tight_layout()
     pyplot.xlim(left=0, right=100)

benchmarks/presortedness/plot.py benchmarks/disorder/plot.pybenchmarks/presortedness/plot.py renamed to benchmarks/disorder/plot.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-# Copyright (c) 2020-2024 Morwenn
+# Copyright (c) 2020-2025 Morwenn
 # SPDX-License-Identifier: MIT
 
 import argparse
@@ -43,7 +43,7 @@
         disorders = []
         with result_file.open() as fd:
             # Read metadata from the first line
-            algo_name, mop_name, size = fd.readline().strip().split(',')
+            algo_name, mod_name, size = fd.readline().strip().split(',')
 
             # Read the rest of the file
             for line in fd:
@@ -71,7 +71,7 @@
     pyplot.title("Sorting std::vector<int> with $10^{}$ elements".format(
         round(math.log(int(size), 10)))
     )
-    pyplot.xlabel(f"${mop_name}$")
+    pyplot.xlabel(f"${mod_name}$")
     pyplot.ylabel("Cycles (lower is better)")
     pyplot.legend()
 

docs/Benchmarks.md

@@ -4,7 +4,7 @@
 * *1.16.0 for slow O(n log n) sorts*
 * *1.14.0 for small array sorts*
 * *1.13.1 for unstable random-access sorts, forward sorts, and the expensive move/cheap comparison benchmark*
-* *1.12.0 for measures of presortedness*
+* *1.12.0 for measures of disorder*
 * *1.9.0 otherwise*
 
 Benchmarking is hard and I might not be doing it right. Moreover, benchmarking sorting algorithms highlights that the time needed to sort a collection of elements depends on several things: the type to sort, the size of the collection, the cost of comparing two values, the cost of moving an element, the patterns formed by the distribution of the values in the collection to sort, the type of the collection itself, etc. The aim of this page is to help you choose a sorting algorithm depending on your needs. You can find two main kinds of benchmarks: the ones that compare algorithms against shuffled collections of different sizes, and the ones that compare algorithms against different data patterns for a given collection size.
@@ -170,23 +170,23 @@ We can see several trends in these benchmarks, rather consistant across `int` an
 * [`low_comparisons_sorter`][low-comparisons-sorter] is second-best here but has a very limited range.
 * [`selection_sorter`][selection-sorter] and [`low_moves_sorter`][low-moves-sorter] are the worst contenders here. They are both different flavours of selection sorts, and as a results are pretty similar.
 
-# Measures of presortedness
+# Measures of disorder
 
-This benchmark for [measures of presortedness][measures-of-presortedness] is small and only intends to show the cost that these tools might incur. It is not meant to be exhaustive in any way.
+This benchmark for [measures of disorder][Measures-of-disorder] is small and only intends to show the cost that these tools might incur. It is not meant to be exhaustive in any way.
 
-![Benchmark speed of measures of presortedness for increasing size for std::vector<int>](https://i.imgur.com/pjc7zJF.png)
+![Benchmark speed of measures of disorder for increasing size for std::vector<int>](https://i.imgur.com/pjc7zJF.png)
 
 It makes rather easy to see the different groups of complexities:
 * *Run(X)* and *Mono(X)* are obvious O(n) algorithms.
 * *Dis(X)* is a more involved O(n) algorithm.
-* All of the other measures of presortedness run in O(n log n) time.
+* All of the other measures of disorder run in O(n log n) time.
 
 
   [fixed-size-sorters]: Fixed-size-sorters.md
   [insertion-sorter]: Sorters.md#insertion_sorter
   [low-comparisons-sorter]: Fixed-size-sorters.md#low_comparisons_sorter
   [low-moves-sorter]: Fixed-size-sorters.md#low_moves_sorter
-  [measures-of-presortedness]: Measures-of-presortedness.md
+  [Measures-of-disorder]: Measures-of-disorder.md
   [merge-exchange-network-sorter]: Fixed-size-sorters.md#merge_exchange_network_sorter
   [selection-sorter]: Sorters.md#selection_sorter
   [sorting-network-sorter]: Fixed-size-sorters.md#sorting_network_sorter

docs/Library-nomenclature.md

@@ -24,9 +24,11 @@
 
     Note that the *sorters* (and virtually bery algorithm) in **cpp-sort** accept iterators that do not implement post-increment and post-decrement operations. The iterator categories accepted by the library are thus less restrictive than the ones mandated for the standard library.
 
-* *Measure of presortedness*: also known as a *measure of disorder*, it corresponds to an algorithm telling how much a collection is already sorted. There isn't a single way to tell how much a collection is already sorted, one can for example count the number of inversions or the number of elements to remove to get a sorted subsequence. The main advantage of measures of presortedness are that some algorithms, known as *adaptative algorithms*, are known to be optimal for some of these measures, which means that they can advantage of the order that already exists in the collection in some way. **cpp-sort** provides a number of [measures of presortedness][measures-of-presortedness] in the namespace `cppsort::probe`:
+* *Measure of disorder*: a function used to estimate the amount of disorder in a sequence. There are many different to do that, such as counting the number of inversions in the sequence, or the number of elements to remove to get a sorted subsequence. **cpp-sort** provides a number of [measures of disorder][Measures-of-disorder] in the namespace `cppsort::probe`.
 
-        auto max_inversion = cppsort::probe::dis(collection);
+        auto max_inversions = cppsort::probe::dis(collection);
+
+* *Measure of presortedness*: a special kind of *measure of disorder* that satisfies a specific set of additional properties (see the page on *measures of disorder*). The overarching goal of those measures is to be able to estimate and reason about the number of steps required to sort a sequence of elements. Most notably, they allow to formally reason about *adaptive sorting algorithms*: given a measure of presortedness $M$, an $M$-adaptive (or $M$-optimal) sorting algorithm is an algorithm that can sort a sequence with a number of steps that is without a constant bound of the estimated minimal number of steps for the estimated disorder.
 
 * *Metric*: as special kind of *sorter adapter* that returns information about sorted collections. See [the corresponding page][metrics] for additional information.
 
@@ -65,7 +67,7 @@
 
 * *Type-specific sorter*: some non-comparison sorters such as the [`spread_sorter`][spread-sorter] implement specific sorting algorithms which only work with some specific types (for example integers or strings).
 
-* *Unified sorting interface*: *sorters*, *sorter adapters*, *measures of presortedness* and a few other components of the library accept a range or a pair of iterators, and optionally a comparison function and/or a comparison function. Those components typically rely on the library's [`sorter_facade`][sorter-facade] which handles the dispatching to the component's implementation and to handle a number of special cases. For simplicity, what is accepted by the `operator()` of such components is referred to as the *unified sorting interface* in the rest of the library.
+* *Unified sorting interface*: *sorters*, *sorter adapters*, *measures of disorder* and a few other components of the library accept a range or a pair of iterators, and optionally a comparison function and/or a comparison function. Those components typically rely on the library's [`sorter_facade`][sorter-facade] which handles the dispatching to the component's implementation and to handle a number of special cases. For simplicity, what is accepted by the `operator()` of such components is referred to as the *unified sorting interface* in the rest of the library.
 
 
   [comparators]: Comparators.md
@@ -75,7 +77,7 @@
   [iterator-categories]: https://en.cppreference.com/w/cpp/iterator
   [iterator-category]: Sorter-traits.md#iterator_category
   [iterator-tags]: https://en.cppreference.com/w/cpp/iterator/iterator_tags
-  [measures-of-presortedness]: Measures-of-presortedness.md
+  [Measures-of-disorder]: Measures-of-disorder.md
   [metrics]: Metrics.md
   [p0022]: https://wg21.link/P0022
   [radix-sort]: https://en.wikipedia.org/wiki/Radix_sort