Adding some explanations on sorting algorithms.

Author: Clément

source/code/projects/Sorting/Sorting/Sorting.cs

@@ -53,25 +53,21 @@ private static int LeftChild(int i)
   {
     return 2 * i + 1;
   }
+    // Done with helper method for Heapsort
 
-  // Done with helper method for Heapsort
-
-  // Heapsort Algorithm
+  // Heapsort algorithm
   public static void Heapsort(List<T> listP)
   {
-    Heapsort(listP, listP.Count);
-  }
-
-  private static void Heapsort(List<T> listP, int N)
-  {
-    for (int i = N / 2; i >= 0; i--) /* BuildHeap */
-      PercDown(listP, i, N);
-    for (int i = N - 1; i > 0; i--)
-    {
-      Swap(listP, 0, i); /* DeleteMax */
-      PercDown(listP, 0, i);
+        // Step 1: heapify, or build heap.
+        for (int i = listP.Count / 2; i >= 0; i--)
+            PercDown(listP, i, listP.Count);
+        // Step 2: recursively extract the largest value.
+        for (int i = listP.Count - 1; i > 0; i--)
+        {
+            Swap(listP, 0, i);
+            PercDown(listP, 0, i);
+        }
     }
-  }
 
   private static void PercDown(List<T> listP, int i, int N)
   {
@@ -95,14 +91,14 @@ private static void PercDown(List<T> listP, int i, int N)
     listP[i] = current;
   }
 
-  // Done with heapsort Algorithm
+  // Done with heapsort algorithm
 
   // Bubble Algorithm
   public static void BubbleSort(List<T> listP)
   {
     for (int i = listP.Count - 1; i >= 0; i--)
     {
-      for (int j = 0; j < listP.Count - 1; j++)
+      for (int j = 0; j < i; j++)
       {
         if (listP[j].CompareTo(listP[j + 1]) > 0)
           Swap(listP, j, j + 1);

source/lectures/misc/sorting.md

@@ -51,17 +51,28 @@ We start by defining two simple "helper" methods:
 
 ## Insertion Sort Algorithm
 
+### Implementation
+
 This algorithm is [nicely explained and illustrated on wikipedia](https://en.wikipedia.org/wiki/Insertion_sort), and can be implemented as follows:
 
 ```
 !include`snippetStart="// Insertion Algorithm", snippetEnd="// Done with insertion Algorithm"` code/projects/Sorting/Sorting/Sorting.cs
 ```
 
+### Description
+
+This algorithm moves the `bar` from the beginning of the list to the end, one by one.
+At every step, it position a `slot` on the bar and look *back*, moving the value at the `slot` earlier and earlier on as long as its predecessor is smaller than itself.
+
+### Complexity
+
 [As explained on wikipedia](https://en.wikipedia.org/wiki/Insertion_sort#Best,_worst,_and_average_cases), the simplest worst case input is an array sorted in reverse order. 
-With an array sorted in reverse order, every iteration of the inner loop will scan and shift the entire sorted subsection of the array before inserting the next element. This gives insertion sort a quadratic running time (i.e., $O(n^2)$). 
+With an array sorted in reverse order, every iteration of the inner loop will scan and shift the entire sorted subsection of the array (i.e., from `bar` to the beginning) before inserting the next element. This gives a quadratic running time (i.e., $O(n^2)$). 
 
 ## Heapsort Algorithm
 
+### Implementation
+
 We first define some helper methods:
 
 ```
@@ -71,25 +82,89 @@ We first define some helper methods:
 and then leverage the heap structure to sort:
 
 ```
-!include`snippetStart="// Heapsort Algorithm", snippetEnd="// Done with heapsort Algorithm"` code/projects/Sorting/Sorting/Sorting.cs
+!include`snippetStart="// Heapsort algorithm", snippetEnd="// Done with heapsort algorithm"` code/projects/Sorting/Sorting/Sorting.cs
 ```
 
 Note that `PercDown` builds a *max heap*: once the values are "pre-sorted **greater value first**", removing the first one to move it to the *end* of the list makes the list sorted from smallest to greatest value once we are done.
 
-The `PercDown` is first called $N / 2$ times, which is equivalent to $O(n)$.
-Its complexity is $O(\log(n))$, and it is called a second time $O(n)$ times.
-So, we get an overall performance of $O((n + n) \times \log n) = O(n \times \log(n))$. 
+### Description
+
+This algorithm works in two steps:
+
+- First, it constructs the heap "in-place", by arranging the elements from the last-to-lower level (`listP.Count / 2` corresponds to "the last parent") to the first level (`i >=0`), in increasing order (i.e., this is a max heap, the greater value is first),
+- Then, it recursively extract the first element, and place it after the end of the heap: note that `PercDown(listP, 0, i)` makes it so that the heap is considered to stop at index `i`, as it decreases in size by 1 at every iteration.
+
+### Complexity
+
+- The `PercDown` method has complexity $O(\log(n))$, since it iterates through the tree from top to bottom, i.e., it is relative to the tree height, which is $O(\log(n))$.
+- The first step calls `PercDown` $n / 2$ times, which is equivalent to $O(n)$, so overall this first step is $O(n \times \log(n))$.
+- The second step also calls `PercDown` $n$ times, so it is overall $O(n \times \log(n))$ as well.
+
+Hence, the complexity of heapsort is $O(n \times \log(n))$ by [the sum rule](./docs/programming_and_computer_usage/complexity#simplifications).
 
 ## Bubble Algorithm
 
+### Implementation
 
 ```
 !include`snippetStart="// Bubble Algorithm", snippetEnd="// Done with bubble algorithm."` code/projects/Sorting/Sorting/Sorting.cs
 ```
 
+### Description
+
+The nested loop accomplishes the following: "from the beginning of the list to where I stopped the last time -1, go through the elements one by one and swap them if needed".
+
+### Complexity
+
+Since both loops depends on the size of the list, $n$, the algorithm is overall $O(n^2)$: we need to perform $n$ times $n$ operations.
+
 ## ShellSort Algorithm
 
+### Implementation
+
 ```
 !include`snippetStart="// ShellSort Algorithm", snippetEnd="// Done with shellSort algorithm."` code/projects/Sorting/Sorting/Sorting.cs
 ```
 
+### Description
+
+Consider a list of size 30, we have (assuming `current.CompareTo(listP[slot - gap]) < 0` is always `true`):
+
+`gap` | `next`  | `slot`  | `slot - gap`
+  ----     |  ----       | -----       | -----       |
+11 | 11 | 11 | 0
+" | 12 | 12 | 1
+" | 13 | 13 | 2
+… | … | … | … |
+" | 22 | 22 | 11
+" | " | 11 | 0
+" | 23 | 23 | 12
+" | " | 12  | 1
+… | … | … | … |
+11 | 30 | 30 | 19
+" | " | 19 | 8
+5 | 5 | 5 | 0
+" | " | 6 | 1 
+" | " | 7 | 2
+… | … | … | … |
+" | 10 | 10 | 5
+" | 10 | 5 | 0
+" | 11 | 11 | 6
+" | " | 6 | 1 
+… | … | … | … |
+2 | 
+… | … | … | 
+1 | 
+
+The important point is to understand that we generate the sequences
+- *Gap of 11*: (11, 0), (12, 1), (13, 2), … (22, 11), (11, 0),  (23, 12), (12, 1), (30, 19), (19, 8), 
+- *Gap of 5*: (5, 0), (11, 6), (6, 1), …
+
+which are sequences of values we are comparing. 
+After we are done going through "the $i$ gap", we know that all values $i$ indices apart are sorted.
+Reducing the value of $i$ to $1$ makes it so that the whole array is sorted.
+
+
+### Complexity
+
+