Improving notes on priority queue.

Author: Clément

source/code/projects/PQueue_heap/PQueue/PQueue.cs

@@ -45,7 +45,6 @@ public void Clear()
         count = 0;
     }
 
-
     public TValue Peek()
     {
         if (IsEmpty()) throw new ApplicationException("Queue is empty, no most urgent value.");
@@ -71,7 +70,7 @@ public void Add(TPriority priorityP, TValue valueP)
             // and move the data at hole / 2 at hole.
         }
         // Once this is done, we can insert the new value.
-        mArray[hole] = new Cell(priorityP, aValue);
+        mArray[hole] = new Cell(priorityP, valueP);
     }
 
     public TValue Extract()
@@ -80,43 +79,53 @@ public TValue Extract()
             throw new ApplicationException("Queue is empty, cannot extract from it.");
 
         // Save the data to be returned.
-        TValue value = mArray[1].Value;
+        TValue cellValue = mArray[1].Value;
 
-        // put the last item in the tree in the root
+        // Move the "rightmost" cell from the 
+        // last level to the root.
         mArray[1] = mArray[count];
-        // We have one less element now
+        // We have one less element now.
         count--;
 
         // Move the lowest child up until we've found the right spot 
-        // for the item moved from the last level to the root.
+        // for the cell moved from the last level to the root.
         PercolateDown(1);
-
-        return value;
+        return cellValue;
     }
 
-    private void PercolateDown(int hole)
+    private void PercolateDown(int indexP)
     {
+        // "PercolateDown", starting at 
+        // indexP.
         int child;
-        // save the hole's cell in a tmp spot
-        Cell pTmp = mArray[hole];
+        // Save the hole's cell.
+        Cell cellValue = mArray[indexP];
 
-        // keep going down the tree until the last level
-        for (; hole * 2 <= count; hole = child)
+        bool found = false;
+        // Keep going down the tree until the last level
+        while(indexP * 2 <= count && !found)
         {
-            child = hole * 2;   // get right child
-                                // check right and left child and put lowest one in the child variable
+            child = indexP * 2;   // get right child
+                                  // check right and left child and put lowest one in the child variable
             if (child != count && mArray[child + 1].Priority.CompareTo(mArray[child].Priority) < 0)
+            {
                 child++;
+            }
             // put lowest child in hole
-            if (mArray[child].Priority.CompareTo(pTmp.Priority) < 0)
+            if (mArray[child].Priority.CompareTo(cellValue.Priority) < 0)
             {
-                mArray[hole] = mArray[child];
+                mArray[indexP] = mArray[child];
             }
             else
-                break;
+            {
+                found = true;
+            }
+            // If we are not done, 
+            // we update the value for indexP.
+            if (!found) { indexP = child; }
         }
         // found right spot of hole's original value, put it back into tree
-        mArray[hole] = pTmp;
+        mArray[indexP] = cellValue;
     }
 
     /// <summary>
@@ -134,7 +143,7 @@ public override string ToString()
         string returned = "";
         for (int i = 1; i <= count; i++)
         {
-            returned += mArray[i].Value.ToString() + "; ";
+            returned += mArray[i].ToString() + "; ";
         }
         return returned;
     }

source/code/projects/PQueue_heap/PQueue/Program.cs

@@ -4,6 +4,35 @@ class Program
 {
   static void Main(string[] args)
   {
-    PQueue<int, string> myQueue = new PQueue<int, string>(5);
+
+        PQueue<int, int> heapEx = new PQueue<int, int>(7);
+        for (int i = 6; i > 0; i--)
+        {
+            heapEx.Add(i, i);
+            Console.WriteLine(heapEx);
+        }
+        heapEx.Add(-1, -1);
+        Console.WriteLine(heapEx);
+
+        // Let us extract three values.
+        for (int i = 0; i < 3; i++)
+        {
+            Console.WriteLine("Lowest priority:" + heapEx.Extract());
+            Console.WriteLine(heapEx);
+        }
+        Console.WriteLine(heapEx);
+
+        /*
+         * 
+         * Level 1: Resuscitation
+         * Level 2: Emergent
+         * Level 3: Urgent
+         * Level 4: Semi-Urgent
+         * Level 5: Non-urgent
+         */
+        PQueue<int, string> myQueue = new PQueue<int, string>(5);
+    myQueue.Add(3, "Abdominal pain ");
+    Console.WriteLine(myQueue);
+
     }
 }

source/diag/gra/heap_example_1.txt

@@ -0,0 +1,8 @@
+%%% Heap example, represented as a complete binary tree
+
+A((1))-->B((3))
+A-->C((2))
+B-->D((6))
+B-->E((4))
+C-->F((5))
+C-->H((null))

source/lectures/data/priority_queue.md

@@ -27,6 +27,8 @@ Letting a greater priority means "more important" is called a *max-priority queu
 In both cases, a decision must be made if multiple elements have the same priority: we can decide arbitrarily, using the element value, take the "first one" in the structure, etc.
 
 Exactly like a people waiting **at the ER**, priority queues implement a **"most-important-in-first-out"** principle.
+Our examples will use the [Emergency Severity Index](https://en.wikipedia.org/wiki/Emergency_Severity_Index), which ranges from 1 (most urgent) to 5 (less urgent).
+
 
 ## Possible Implementation
 
@@ -37,7 +39,6 @@ Here is an implementation of priority queues using arrays:
 ```{download="./code/projects/PQueue_array.zip"}
 !include code/projects/PQueue_array/PQueue/PQueue.cs
 ```
-
 This implementation as the following performance:
 
 - `Add` is $O(n)$, it may take $n$ steps to find an empty slot,
@@ -57,11 +58,66 @@ A maximally efficient implementation of priority queues is given by [heaps](http
 
 Note that this is different from being a binary search tree.
 
+#### Representing complete binary trees using arrays
+
+A [binary heap](https://en.wikipedia.org/wiki/Binary_heap) is often [implemented as an array](https://en.wikipedia.org/wiki/Binary_heap#Heap_implementation).
+Consider the following binary tree (we will take the priority of the node to be its value in the following):
+
+!include diag/gra/heap_example_1.md
+
+It is a heap, but not a binary search tree. It can be represented as the following array:
+
+Index |     0 |   1 |   2 |   3 |   4 |   5 |   6 |   7 | 
+---   |   :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
+Node  |`null` |   1 |   3 |   2 |   6 |   4 |   5 | `null` |
+
+The reason why we start at index 1 and not 0 is because it makes the following calculation easier^[The difference can be looked up [on wikipedia](https://en.wikipedia.org/wiki/Binary_heap#Heap_implementation), it is mostly a matter of substracting or adding 1 at various places.].
+Indeed, each element at index $i$ has
+
+- its children at indices $2 \times i$ and $(2 \times i) + 1$,
+- its parent at index $\lfloor i/2 \rfloor$ for $\lfloor \cdot \rfloor$ the floor function (i.e., $\lfloor 1.5 \rfloor = 1$).
+
+#### Inserting into a heap
+
+To insert an element to a heap, we perform the following steps:
+
+1. Add the element to the bottom level of the heap at the leftmost open space (or "start" a new level if the last level is full).
+2. Compare the added element with its parent; if they are in the correct order, stop.
+3. If not, swap the element with its parent and return to the previous step.
+
+Imagine we want to insert $-1$ in our previous example, we would:
+
+- Add $-1$ as the right child of $2$, 
+- Swap $-1$ and $2$, 
+- Swap $-1$ and $1$,
+- Be done.
+
+In terms of array representation, we would obtain (with the values that changed **in bold**):
+
+Index |     0 |   1 |   2 |   3 |   4 |   5 |   6 |   7 | 
+---   |   :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
+Node  |`null` |  **-1** |   3 |   **1** |   6 |   4 |   5 | **2** |
+
+
+#### Deleting from a heap
+
+Extracting the element with the lowest priority is easy: it is located at the root of the tree, or at index 1 in the array representation. 
+The challenge is to restore "the heap property", which is done as follows:
+
+1. Replace the root of the heap with the last element on the last level.
+2. Compare the new root with its children; if they are in the correct order, stop.
+3. If not, swap the element with one of its children and return to the previous step. (Swap with its smaller child in a min-heap and its larger child in a max-heap.)
+
+The 2nd and 3rd steps are called "percolate-down".
+
+
 ```{download="./code/projects/PQueue_heap.zip"}
 !include code/projects/PQueue_heap/PQueue/PQueue.cs
 ```
 
 
+
+
 <!--
 
 - Index 0 is unused.