merging

Merge branch 'main' into branch-quickSort

Author: kaitinghh

src/algorithms/patternFinding/README.md

@@ -6,6 +6,12 @@ in text editors when searching for a pattern, in computational biology sequence
 in NLP problems, and even for looking for file patterns for effective file management.
 It is hence crucial that we develop an efficient algorithm.
 
+![KMP](../../../assets/kmp.png)
+Image Source: GeeksforGeeks
+
+## Analysis
+**Time complexity**:
+
 Naively, we can look for patterns in a given sequence in O(nk) where n is the length of the sequence and k
 is the length of the pattern. We do this by iterating every character of the sequence, and look at the 
 immediate k-1 characters that come after it. This is not a big issue if k is known to be small, but there's
@@ -15,9 +21,9 @@ KMP does this in O(n+k) by making use of previously identified sub-patterns. It
 by first processing the pattern input in O(k) time, allowing identification of patterns in
 O(n) traversal of the sequence. More details found in the src code.
 
-![KMP](../../../assets/kmp.png)
-Image Source: GeeksforGeeks
-
+**Space complexity**: O(k) auxiliary space to store suffix that matches with prefix of the pattern string
 
-If you have trouble understanding the implementation, 
-here is a good [video](https://www.youtube.com/watch?v=EL4ZbRF587g). 
+## Notes
+A detailed illustration of how the algorithm works is shown in the code. 
+But if you have trouble understanding the implementation, 
+here is a good [video](https://www.youtube.com/watch?v=EL4ZbRF587g) as well. 

src/algorithms/sorting/bubbleSort/BubbleSort.java

@@ -15,23 +15,7 @@
  *
  * At the kth iteration of the outer loop, we only require (n-k) adjacent comparisons to get the kth largest
  * element to its correct position.
- *
- * Complexity Analysis:
- * Time:
- * - Worst case (reverse sorted array): O(n^2)
- * - Average case: O(n^2)
- * - Best case (sorted array): O(n)
- * In the worst case, during each iteration of the outer loop, the number of adjacent comparisons is upper-bounded
- * by n. Since BubbleSort requires (n-1) iterations of the outer loop to sort the entire array, the total number
- * of comparisons performed can be upper-bounded by (n-1) * n ≈ n^2.
- *
- * This implementation of BubbleSort terminates the outer loop once there are no swaps within one iteration of the
- * outer loop. This improves the best case time complexity to O(n) for an already sorted array.
- *
- * Space:
- * - O(1) since sorting is done in-place
  */
-
 public class BubbleSort {
     /**
      * Sorts the given array in-place in non-decreasing order.
@@ -40,7 +24,7 @@ public class BubbleSort {
      */
     public static int[] sort(int[] arr) {
         int n = arr.length;
-        boolean swapped; //tracks of the presence of swaps within one iteration of the outer loop to
+        boolean swapped; // tracks of the presence of swaps within one iteration of the outer loop to
         // facilitate early termination
         for (int i = 0; i < n - 1; i++ ) { //outer loop which supports the invariant
             swapped = false;

src/algorithms/sorting/bubbleSort/README.md

@@ -1 +1,21 @@
-![bubble sort img](../../../../assets/BubbleSort.jpeg)
+# Bubble Sort
+Bubble sort is one of the more intuitive comparison-based sorting algorithms.
+It makes repeated comparisons between neighbouring elements, 'bubbling' (side-by-side swaps)
+largest (or smallest) element in the unsorted region to the sorted region (often the front or the back).
+
+![bubble sort img](../../../../assets/BubbleSort.jpeg)
+
+## Complexity Analysis
+**Time**:
+  - Worst case (reverse sorted array): O(n^2)
+  - Average case: O(n^2)
+  - Best case (sorted array): O(n)
+
+In the worst case, during each iteration of the outer loop, the number of adjacent comparisons is upper-bounded
+by n. Since BubbleSort requires (n-1) iterations of the outer loop to sort the entire array, the total number
+of comparisons performed can be upper-bounded by (n-1) * n ≈ n^2.
+
+This implementation of BubbleSort terminates the outer loop once there are no swaps within one iteration of the
+outer loop. This improves the best case time complexity to O(n) for an already sorted array.
+
+**Space**: O(1) since sorting is done in-place

src/algorithms/sorting/countingSort/CountingSort.java

@@ -1,45 +1,34 @@
 package src.algorithms.sorting.countingSort;
 
 /**
- * Stable implementation of Counting Sort.
- * 
- * <p></p>
+ * <p></p> Stable implementation of Counting Sort.
  *
- * Brief Description: <br>
+ * <p></p> Brief Description: <br>
  * Counting sort is a non-comparison based sorting algorithm and isn't bounded by the O(nlogn) lower-bound
  * of most sorting algorithms. <br>
  * It first obtains the frequency map of all elements (ie counting the occurrence of every element), then
  * computes the prefix sum for the map. This prefix map tells us which position an element should be inserted. <br>
  * Ultimately, each group of elements will be placed together, and the groups in succession, in the sorted output.
  *
- * <p></p>
- *
- * Assumption for use: <br>
+ * <p></p> Assumption for use: <br>
  * To perform counting sort, the elements must first have total ordering and their rank must be known.
  *
- * <p></p>
- *
- * Implementation Invariant: <br>
+ * <p></p> Implementation Invariant: <br>
  * At the end of the ith iteration, the ith element from the back will be placed in its rightful position.
  *
  * <p></p>
- *
  * COMMON MISCONCEPTION: Counting sort does not require total ordering of elements since it is non-comparison based.
  * This is incorrect. It requires total ordering of elements to determine their relative positions in the sorted output.
  * In fact, in conventional implementation, the total ordering property is reflected by virtue of the structure
  * of the frequency map.
  *
- * <p></p>
- *
- * Complexity Analysis: <br>
+ * <p></p> Complexity Analysis: <br>
  * Time: O(k+n)=O(max(k,n)) where k is the value of the largest element and n is the number of elements. <br>
  * Space: O(k+n)=O(max(k,n)) <br>
  * Counting sort is most efficient if the range of input values do not exceed the number of input values. <br>
  * Counting sort is NOT AN IN-PLACE algorithm. For one, it requires additional space to store freq map. <br>
  *
- * <p></p>
- *
- * Note: Implementation deals with integers but the idea is the same and can be generalised to other objects,
+ * <p></p> Note: Implementation deals with integers but the idea is the same and can be generalised to other objects,
  * as long as what was discussed above remains true.
  */
 public class CountingSort {

src/algorithms/sorting/countingSort/README.md

@@ -0,0 +1,21 @@
+# Counting Sort
+
+Counting sort is a non-comparison-based sorting algorithm and isn't bounded by the O(nlogn) lower-bound 
+of most sorting algorithms. <br>
+It first obtains the frequency map of all elements (ie counting the occurrence of every element), then
+computes the prefix sum for the map. This prefix map tells us which position an element should be inserted.
+Ultimately, each group of elements will be placed together, and the groups in succession, in the sorted output.
+
+## Complexity Analysis
+Time: O(k+n)=O(max(k,n)) where k is the value of the largest element and n is the number of elements. <br>
+Space: O(k+n)=O(max(k,n)) <br>
+Counting sort is most efficient if the range of input values do not exceed the number of input values. <br>
+Counting sort is NOT AN IN-PLACE algorithm. For one, it requires additional space to store freq map. <br>
+
+## Notes
+COMMON MISCONCEPTION: Counting sort does not require total ordering of elements since it is non-comparison based.
+This is incorrect. It requires total ordering of elements to determine their relative positions in the sorted output.
+In fact, in conventional implementation, the total ordering property is reflected by virtue of the structure
+of the frequency map.
+
+Supplementary: Here is a [video](https://www.youtube.com/watch?v=OKd534EWcdk) if you are still having troubles.

src/algorithms/sorting/insertionSort/InsertionSort.java

@@ -3,33 +3,13 @@
 /** Here, we are implementing InsertionSort where we sort the array in increasing (or more precisely, non-decreasing)
  * order.
  *
- * Brief Description:
- * InsertionSort is a simple comparison-based sorting algorithm that builds the final sorted array one element at a
- * time. It works by repeatedly taking an element from the unsorted portion of the array and inserting it into its
- * correct position within the sorted portion. At the kth iteration, we take the element arr[k] and insert
- * it into arr[0, k-1] following sorted order, returning us arr[0, k] in sorted order.
- *
  * Implementation Invariant:
  * The loop invariant is: at the end of kth iteration, the first (k+1) items in the array are in sorted order.
  * At the end of the (n-1)th iteration, all n items in the array will be in sorted order.
- * (Note: the loop invariant here slightly differs from the lecture slides as we are using 0-based indexing.)
- *
- * Complexity Analysis:
- * Time:
- * - Worst case (reverse sorted array): O(n^2)
- * - Average case: O(n^2)
- * - Best case (sorted array): O(n)
- *
- * In the worst case, inserting an element into the sorted array of length m requires us to iterate through the
- * entire array, requiring O(m) time. Since InsertionSort does this insertion (n - 1) times, the time complexity
- * of InsertionSort in the worst case is 1 + 2 + ... + (n-2) + (n-1) = O(n^2).
- *
- * In the best case of an already sorted array, inserting an element into the sorted array of length m requires
- * O(1) time as we insert it directly behind the first position of the pointer in the sorted array. Since InsertionSort
- * does this insertion (n-1) times, the time complexity of InsertionSort in the best case is O(1) * (n-1) = O(n).
  *
- * Space:
- * - O(1) since sorting is done in-place
+ * Note:
+ *      1. the loop invariant here slightly differs from the lecture slides as we are using 0-based indexing
+ *      2. Insertion into the sorted portion is done byb 'bubbling' elements as in bubble sort
  */
 
 public class InsertionSort {

src/algorithms/sorting/insertionSort/README.md

@@ -1,3 +1,36 @@
+# Insertion Sort
+
+Insertion sort is a comparison-based sorting algorithm that builds the final sorted array one element at a
+time. It works by repeatedly taking an element from the unsorted portion of the array and 
+inserting it correctly (portion remains sorted) into the sorted portion. Note that the position is not final 
+since subsequent elements from unsorted portion may displace previously inserted elements. What's important is 
+the sorted region remains sorted. More succinctly: <br>
+At the kth iteration, we take the element arr[k] and insert
+it into arr[0, k-1] following sorted order, returning us arr[0, k] in sorted order.
+
 ![InsertionSort](../../../../assets/InsertionSort.png)
 
+## Complexity Analysis
+**Time**:
+  - Worst case (reverse sorted array): O(n^2)
+  - Average case: O(n^2)
+  - Best case (sorted array): O(n)
+
+In the worst case, inserting an element into the sorted array of length m requires us to iterate through the
+entire array, requiring O(m) time. Since InsertionSort does this insertion (n - 1) times, the time complexity
+of InsertionSort in the worst case is 1 + 2 + ... + (n-2) + (n-1) = O(n^2).
+
+In the best case of an already sorted array, inserting an element into the sorted array of length m requires
+O(1) time as we insert it directly behind the first position of the pointer in the sorted array. Since InsertionSort
+does this insertion (n-1) times, the time complexity of InsertionSort in the best case is O(1) * (n-1) = O(n).
+
+**Space**: O(1) since sorting is done in-place
+
+## Notes
+### Common Misconception
+Its invariant is often confused with selection sort's. In selection sort, an element in the unsorted region will 
+be immediately placed in its correct and final position as it would be in the sorted array. This is not the case
+for insertion sort. However, it is because of this 'looser' invariant that allows for a better best case time complexity
+for insertion sort.
+
 Image Source: https://www.hackerrank.com/challenges/correctness-invariant/problem

src/algorithms/sorting/selectionSort/README.md

@@ -1,3 +1,22 @@
+# Selection Sort
+
+Selection sort is another intuitive comparison-based sorting algorithm. It works similarly to other sorting algorithms 
+like bubble and insertion in the sense that it maintains a sorted and unsorted region. It does so by repeatedly finding
+smallest (or largest) element in the unsorted region, and places the element in the correct and final position as it 
+would be in the sorted array.
+
 ![SelectionSort](../../../../assets/SelectionSort.png)
 
+## Complexity Analysis
+**Time**:
+  - Worst case: O(n^2)
+  - Average case: O(n^2)
+  - Best case: O(n^2)
+
+Regardless of how sorted the input array is, selectionSort will run the minimum element finding algorithm (n-1)
+times. For an input array of length m, finding the minimum element necessarily takes O(m) time. Therefore, the
+time complexity of selectionSort is n + (n-1) + (n-2) + ... + 2 = O(n^2)
+
+**Space**: O(1) since sorting is done in-place
+
 Image Source: https://www.hackerearth.com/practice/algorithms/sorting/selection-sort/tutorial/

src/algorithms/sorting/selectionSort/SelectionSort.java

@@ -3,26 +3,15 @@
 /** Here, we are implementing SelectionSort where we sort the array in increasing (or more precisely, non-decreasing)
  * order.
  *
- * Brief Description and Implementation Invariant:
- * Let the array to be sorted be A of length n. SelectionSort works by finding the minimum element A[j] in A[i...n],
- * then swapping A[i] with A[j], for i in [0, n-1). The loop invariant is: at the end of the kth iteration, the
- * smallest k items are correctly sorted in the first k positions of the array.
+ * Implementation Invariant:
+ * Let the array of length n to be sorted be A.
+ * The loop invariant is:
+ * At the end of the kth iteration, the smallest k items are correctly sorted in the first k positions of the array.
  *
- * At the end of the (n-1)th iteration of the loop, the smallest (n-1) items are correctly sorted in the first (n-1)
+ * So, at the end of the (n-1)th iteration of the loop, the smallest (n-1) items are correctly sorted in the first (n-1)
  * positions of the array, leaving the last item correctly positioned in the last index of the array. Therefore,
  * (n-1) iterations of the loop is sufficient.
  *
- * Complexity Analysis:
- * Time:
- * - Worst case: O(n^2)
- * - Average case: O(n^2)
- * - Best case: O(n^2)
- * Regardless of how sorted the input array is, selectionSort will run the minimum element finding algorithm (n-1)
- * times. For an input array of length m, finding the minimum element necessarily takes O(m) time. Therefore, the
- * time complexity of selectionSort is n + (n-1) + (n-2) + ... + 2 = O(n^2)
- *
- * Space:
- * - O(1) since sorting is done in-place
  */
 
 public class SelectionSort {

src/dataStructures/disjointSet/README.md

@@ -0,0 +1,84 @@
+# Union Find / Disjoint Set
+
+A disjoint-set structure also known as a union-find or merge-find set, is a data structure 
+keeps track of a partition of a set into disjoint (non-overlapping) subsets. In CS2040s, this 
+is primarily used to check for dynamic connectivity. For instance, Kruskal's algorithm 
+in graph theory to find minimum spanning tree of the graph utilizes disjoint set to efficiently
+query if there exists a path between 2 nodes. <br>
+It supports 2 main operations:
+1. Union: Join two subsets into a single subset
+2. Find: Determine which subset a particular element is in. In practice, this is often done to check
+if two  elements are in the same subset or component.
+
+The Disjoint Set structure is often introduced in 3 parts, with each iteration being better than the
+previous in terms of time and space complexity. Below is a brief overview:
+
+## Quick Find
+Every object will be assigned a component identity. The implementation of Quick Find often involves 
+an underlying array that tracks the component identity of each object.
+
+**Union**: Between the two components, decide on the component d, to represent the combined set. Let the other
+component's identity be d'. Simply iterate over the component identifier array, and for any element with 
+identity d', assign it to d.
+
+**Find**: Simply use the component identifier array to query for the component identity of the two elements
+and check if they are equal. This is why this implementation is known as "Quick Find". 
+
+#### Analysis
+Let n be the number of elements in consideration.
+
+**Time**: O(n) for Union and O(1) for Find operations
+
+**Space**: O(n) auxiliary space for the component identifier
+
+
+## Quick Union
+Here, we consider a completely different approach. We consider the use of trees. Every element can be
+thought of as a tree node and starts off in its own component. Under this representation, it is likely 
+that at any given point, we might have a forest of trees, and that's perfectly fine. The root node of each tree
+simply represents the component / set of all elements in the same set. <br>
+Note that the trees here are not necessarily binary trees. In fact, more often than not, we will have nodes
+with multiple children nodes.
+
+**Union**: Between the two components, decide on the component to represent the combined set as before.
+Now, union is simply assigning the root node of one tree to be the child of the root node of another. Hence, its name. 
+One thing to note is that to identify the component of the object involves traversing to the root node of the
+tree.
+
+**Find**: For each of the node, we traverse up the tree from the current node until the root. Check if the
+two roots are the same
+
+#### Analysis
+**Time**: O(n) for Union and Find operations. While union-ing is indeed quick, it is possibly undermined
+by O(n) traversal in the case of a degenerate tree. Note that at this stage, there is nothing to ensure the trees
+are balanced.
+
+**Space**: O(n), implementation still involves wrapping the n elements with some structure / wrapper.
+
+
+## Weighted Union
+Now, we augment and improve upon the Quick Union structure by ensuring trees constructed are 'balanced'. Balanced
+trees have a nice property that the height of the tree will be upper-bounded by O(log(n)). This considerably speeds 
+up Union operations. <br>
+We additionally track the size of each tree and ensure that whenever there is a union between 2 elements, the smaller
+tree will be the child of a larger tree. It can be mathematically shown the height of the tree is bounded by O(log(n)).
+
+#### Analysis
+**Time**: O(log(n)) for Union and Find operations.
+
+**Space**: Remains at O(n)
+
+
+### Path Compression
+We can further improve on the time complexity of Weighted Union by introducing path compression. Specifically, during
+the traversal of a node up to the root, we re-assign each node's parent to be the root (or as shown in CS2040s, 
+assigning to its grandparent actually suffice and yield the same big-O upper-bound! This allows path compression to be
+done in a single pass.). By doing so, we greatly reduce the height of the trees formed.
+
+#### Analysis
+The analysis is a bit trickier here and talks about the inverse-Ackermann function. Interested readers can find out more 
+[here](https://dl.acm.org/doi/pdf/10.1145/321879.321884)
+
+**Time**: O(alpha)
+
+**Space**: O(n)