Merge pull request #75 from 4ndrelim/branch-RoutineCleanUp

euchangxian · web-flow · commit e4895d8e2ea5 · 2024-02-06T21:32:01.000+08:00
docs: Improve clarity and clean-up some parts
diff --git a/README.md b/README.md
@@ -108,8 +108,28 @@ Gradle is used for development.
     * Prim's
     * Kruskal's
 
-## Running Custom Inputs
-See [here](scripts/README.md).
+## Set-up 
+If you are a CS2040s student, your IDEA configurations should already be compatible with this project structure. So, 
+feel free to clone and use it as you see fit. Note, below configuration is as per CS2040s PS1 set-up guide.
+
+1. Choose Java Version 11.0.XX for Project SDK. You can download it [here](https://www.oracle.com/java/technologies/downloads/#java11)
+   - Create account and login if necessary
+   - Make sure to download the correct one compatible with your hardware
+2. Download IntelliJ (Community Edition) [here](https://www.jetbrains.com/idea/download/?section=mac) if you do not have it.
+3. Fork the repo and clone it on your local device
+4. Launch IntelliJ on your device and under the `Projects` tab, and click `open`. Navigate to where the local repo is 
+cloned 
+   1. Configure to Java SDK (if not done) by first heading to `File` on the top-left panel,
+   2. Click on `Project Structure...`
+   3. Apply the desired Java SDK in the `SDK:` dropdown. Remember to click `Apply`.
+5. You can test if everything is properly set-up with the command: <br/>
+`./gradlew clean test` <br/>
+All files should be compiled and all testcases should pass.
+
+## Usage
+The resources here can be directly viewed from GitHub interface, but it is advisable for you to fork and clone 
+it to your local desktop, especially if you wish to tweak or play with custom inputs. There is a folder where you can 
+import and run the algorithms/structures here for your own input. See [here](scripts/README.md).
 
 ## Disclaimer
 While our team of TAs and students have diligently verified the correctness of our code, there might still be
diff --git a/docs/team/profiles.md b/docs/team/profiles.md
@@ -1,11 +1,11 @@
 # Team Profile
 
-| Name      | Description/About                                                                                                                | Website (LinkedIn/GitHub/Personal)                                                                   | Contributions                                               |
-|-----------|----------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|-------------------------------------------------------------|
-| Andre     | Aspiring ML engineer. My stint as a CS2040s TA has convinced several capable and passionate students to develop this together :) | You can find me [here](https://4ndrelim.github.io)!                                                  | Team lead                                                   |
-| Kai ting  | ...                                                                                                                              | ...                                                                                                  | Cool sorting and obscure trees! B-Trees, ORS..              |
-| Changxian | ...                                                                                                                              | ...                                                                                                  | Hashing variants! BTS DevOps - configure Gradle & workflows |
-| Shu Heng  | Interested in ML, aspiring researcher.                                                                                           | No website but here's my [Linkedin](https://www.linkedin.com/in/yeoshuheng), please give me a job :< | CS Fundamentals! Stacks and queues! RB-tree.                |
-| Junneng   | Aspiring tech entrepreneur.                                                                                                      | [LinkedIn](https://www.linkedin.com/in/soo-jun-neng/)                                                | Binary Search variants, Minimum Spanning Trees!             |
-| Amadeus   | ...                                                                                                                              | ...                                                                                                  | Graphs!                                                     |
-| Owen      | ...                                                                                                                              | ...                                                                                                  | Graphs and confusing mazes                                  |
+| Name      | Description/About                                                 | Website (LinkedIn/GitHub/Personal)                                                                   | Contributions                                               |
+|-----------|-------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|-------------------------------------------------------------|
+| Andre     | Aspiring ML engineer. Developing this with wonderful ex-students. | You can find me [here](https://4ndrelim.github.io)!                                                  | Team lead                                                   |
+| Kai ting  | Likes algorithms and a committed TA!                              | [Hi](https://www.linkedin.com/in/kai-ting-ho-425181268/)                                             | Cool sorting and obscure trees! B-Trees, ORS..              |
+| Changxian | DevOps is right up his alley!                                     | ...                                                                                                  | Hashing variants! BTS DevOps - configure Gradle & workflows |
+| Shu Heng  | Interested in ML, aspiring researcher.                            | No website but here's my [Linkedin](https://www.linkedin.com/in/yeoshuheng), please give me a job :< | CS Fundamentals! Stacks and queues! RB-tree.                |
+| Junneng   | Aspiring tech entrepreneur.                                       | [LinkedIn](https://www.linkedin.com/in/soo-jun-neng/)                                                | Binary Search variants, Minimum Spanning Trees!             |
+| Amadeus   | ...                                                               | ...                                                                                                  | Graphs!                                                     |
+| Owen      | ...                                                               | ...                                                                                                  | Graphs and confusing mazes                                  |
diff --git a/scripts/README.md b/scripts/README.md
@@ -1,5 +1,8 @@
 # Running On Custom Inputs
 
-This folder allows you to pass user input and view the output after running the desired algorithm.
+This folder allows you to run the algorithm/structures on any custom input you pass in.
 
-Simply run the file via IntelliJ in the respective folder.
+Simply create a file of the similar structure as in the src/ folder or import the respective package to call the
+algorithm/structure in the `main` method of the file you create. Then, run the file via IntelliJ as per normal.
+
+Some samples are shown.
diff --git a/scripts/algorithms/sorting/countingSort/RunCountingSort.java b/scripts/algorithms/sorting/countingSort/RunCountingSort.java
@@ -1,6 +1,4 @@
-package algorithms.sorting;
-
-import algorithms.sorting.countingSort.CountingSort;
+package algorithms.sorting.countingSort;
 
 /**
  * Script to run Counting Sort.
@@ -15,8 +13,8 @@ public class RunCountingSort {
     //\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//
 
     public static void main(String[] args) {
-        toSort = CountingSort.sort(toSort);
-        display(toSort);
+        int[] sorted = CountingSort.sort(toSort);
+        display(sorted);
     }
 
     /**
diff --git a/scripts/algorithms/sorting/insertionSort/RunInsertionSort.java b/scripts/algorithms/sorting/insertionSort/RunInsertionSort.java
@@ -0,0 +1,33 @@
+package algorithms.sorting.insertionSort;
+
+/**
+ * Script to run Insertion Sort.
+ */
+public class RunInsertionSort {
+
+    //\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//
+    //////////////////////////////////////////   This section is for user input   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
+    private static int[] toSort =
+        new int[] {3, 4, 2, 65, 76, 93, 22, 1, 5, 7, 88, 54, 44, 7, 5, 6, 2, 64, 43, 22, 27, 33, 59, 64, 76, 99, 37, 7};
+
+    //\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//\\//
+
+    public static void main(String[] args) {
+        int[] sorted = InsertionSort.sort(toSort);
+        display(sorted);
+    }
+
+    /**
+     * Prints the string representation of the array.
+     *
+     * @param arr the given array.
+     */
+    public static void display(int[] arr) {
+        StringBuilder toDisplay = new StringBuilder("[");
+        for (int num : arr) {
+            toDisplay.append(String.format("%d ", num));
+        }
+        toDisplay = toDisplay.replace(toDisplay.length() - 1, toDisplay.length(), "]");
+        System.out.println(toDisplay);
+    }
+}
diff --git a/src/main/java/algorithms/sorting/quickSort/lomuto/QuickSort.java b/src/main/java/algorithms/sorting/quickSort/lomuto/QuickSort.java
@@ -51,18 +51,18 @@ private static int partition(int[] arr, int start, int end) {
 
         swap(arr, start, pIdx); // swap the pivot to the start of the array
 
-        int less = start + 1;
+        int idx = start + 1; // interpret: at the end, all elements at indices less than this var is <= pivot
 
         for (int i = start + 1; i <= end; i++) {
             if (arr[i] <= pivot) {
-                swap(arr, less, i);
-                less++;
+                swap(arr, idx, i);
+                idx++;
             }
         }
 
-        swap(arr, less - 1, start); // swap the pivot to its correct position
+        swap(arr, idx - 1, start); // swap the pivot to its correct position
 
-        return less - 1;
+        return idx - 1;
     }
 
     /**
diff --git a/src/main/java/algorithms/sorting/quickSort/paranoid/README.md b/src/main/java/algorithms/sorting/quickSort/paranoid/README.md
@@ -1,7 +1,7 @@
 # Paranoid QuickSort
 
 ## Background 
-Paranoid Quicksort is the naive quicksort with an additional check to guarantee a good pivot.
+Paranoid Quicksort is the naive quicksort with that allow additional attempts to guarantee a good pivot selection.
 
 ![ParanoidQuickSort](../../../../../../../docs/assets/images/ParanoidQuickSort.jpeg)
 
diff --git a/src/main/java/algorithms/sorting/quickSort/threeWayPartitioning/README.md b/src/main/java/algorithms/sorting/quickSort/threeWayPartitioning/README.md
@@ -1,13 +1,17 @@
 # Three-Way Partitioning
 
 ## Background
-Three-way partitioning is used in QuickSort to tackle the scenario where there are many duplicate elements in the
-array being sorted.
+Three-way partitioning is an improved partitioning scheme, used in QuickSort, to tackle the scenario where there are 
+many duplicate elements. This partitioning scheme will resolve the infinite loop error possibly faced by 
+Paranoid Quicksort.
 
 The idea behind three-way partitioning is to divide the array into three sections: elements less than the pivot,
 elements equal to the pivot, and elements greater than the pivot. By doing so, we can avoid unnecessary comparisons
 and swaps with duplicate elements, making the sorting process more efficient.
 
+Note that during the partitioning process, there would be a 4th region - 'In Progress' region that will hold elements
+that haven't yet been placed in the right section (see below).
+
 ![ThreeWayPartitioning](../../../../../../../docs/assets/images/ThreeWayPartitioning.jpeg)
 
 ## Implementation Invariant:
diff --git a/src/main/java/dataStructures/bTree/README.md b/src/main/java/dataStructures/bTree/README.md
@@ -1,18 +1,5 @@
 # B-Trees
 
-### Table of Contents
-- [Background](#background)
-- [(a,b) trees](#-ab--trees)
-  - [Implementation Invariants/(a,b) Tree Rules](#implementation-invariants--ab--tree-rules)
-  - [Complexity Analysis](#complexity-analysis)
-- [How do B Trees relate to (a,b) trees?](#how-do-b-trees-relate-to--ab--trees)
-- [Search Operation](#search-operation)
-- [Insert Operation](#insert-operation)
-  - [Split Child Method](#split-child-method)
-- [Delete Operation](#delete-operation)
-- [Application](#application)
-
-
 ## Background
 Is the fastest way to search for data to store them in an array, sort them and perform binary search? No. This will
 incur minimally O(nlogn) sorting cost, and O(n) cost per insertion to maintain sorted order. <br>
@@ -76,7 +63,7 @@ Rule #3: Leaf depth
 All leaf nodes must be at the same depth from root. 
 - This property forces the tree to be balanced. 
 
-### Complexity Analysis
+## Complexity Analysis
 
 **Search, Insertion, Deletion Time**:  O(bloga(n)) = O(logn)
 
@@ -90,20 +77,22 @@ where n is the number of elements (whatever the structure, it must store at leas
 ## How do B Trees relate to (a,b) trees?
 A B-Tree is an (a,b) tree with a = ceil(b/2).
 
-There are varying definitions of B-trees but we will be following the CLRS definition: a B tree is parameterized by
+There are varying definitions of B-trees, but we will be following the CLRS definition: a B tree is parameterized by
 a value t >= 2, known as its minimum degree. 
 - Every internal node other than the root has at least t children. 
 - Following this definition, t = a in the naming convention of (a,b) trees. 
 
-## Search Operation 
+## Operations
+
+### Search Operation 
 Here is an outline of the search operation:
 1. Begin the search at the root of the B tree. 
 2. If the key being searched for is in the current node, return true (i.e. found). 
 3. Else, determine the child node where the key might be located based on comparison with the keys in the current node. 
 4. Recursively perform the search operation in the determined child node. 
 5. If the search reaches a leaf node, and the key is not found, return false (i.e. not found). 
 
-## Insert Operation
+### Insert Operation
 You can read more about how the insert operation works 
 [here](https://www.geeksforgeeks.org/insert-operation-in-b-tree/).
 
@@ -121,7 +110,7 @@ datasets by optimizing disk accesses.
 
 Large amounts of data have to be stored on the disk. But disk I/O operations are slow and not knowing where to look 
 for the data can drastically worsen search time. B-Tree is used as an index structure to efficiently locate the 
-desired data. Note, the B-Tree itself can be partially stored in RAM (higher levels) and and partially on disk 
+desired data. Note, the B-Tree itself can be partially stored in RAM (higher levels) and partially on disk 
 (lower, less freq accessed levels).
 
 Consider a database of all the CS modules offered in NUS. Suppose there is a column "Code" (module code) in the 
@@ -134,7 +123,7 @@ data can be found. For e.g., a key for "CS2040s" would have a pointer to the dis
 and find the disk location of the desired data without having to scan the whole "CS Modules" table.
 
 The choice of t will impact the height of the tree, and hence how fast the query is. Trade-off would be space, as a 
-higher t means more keys in each node and they would have to be (if not already) loaded to RAM.
+higher t means more keys in each node, and they would have to be (if not already) loaded to RAM.
 
 ## References
-This description heavily references CS2040S Recitation Sheet 4. 
+This description heavily references CS2040S Recitation Sheet 4. 
diff --git a/src/main/java/dataStructures/disjointSet/README.md b/src/main/java/dataStructures/disjointSet/README.md
@@ -5,8 +5,7 @@
 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 introduced in the context of checking for dynamic connectivity. For instance, Kruskal's algorithm
+In CS2040s, this is introduced in the context of checking for dynamic connectivity. For instance, Kruskal's algorithm
 in graph theory to find minimum spanning tree of a graph utilizes disjoint set to efficiently
 query if there already exists a path between 2 nodes.
 
@@ -42,4 +41,4 @@ Because of its efficiency and simplicity in implementing, Disjoint Set structure
 
 ## Notes
 Disjoint Set is a data structure designed to keep track of a set of elements partitioned into a number of 
-non-overlapping subsets. **It is not suited for handling duplicates** and so our implementation ignores duplicates.
+non-overlapping subsets. **It is not suited for handling duplicates**, so our implementation ignores duplicates.
diff --git a/src/main/java/dataStructures/disjointSet/weightedUnion/README.md b/src/main/java/dataStructures/disjointSet/weightedUnion/README.md
@@ -3,8 +3,9 @@ If you wish to jump to [weighted union](#Weighted-Union).
 ## Background
 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 identity / is a representative of all elements in the same component. <br>
+that at any given point, we might have a forest of trees, and that's perfectly fine. A forests of trees would simply be
+interpreted as different components, with elements in the same tree belonging to the same component.
+The root node of each tree is used as the identity for all elements in the same component. <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.
 
@@ -55,11 +56,10 @@ _Note: n = 2^(logn)_
 ### Implementation Details
 The concept introduces the idea of constructing trees and forests and certainly, one can similarly implement a 
 Node wrapper class to represent objects as nodes in a tree. <br>
-But notice that the operations only need knowledge of the parent node and the size of the tree 
-(which is tracked by the root). In other words, using internal lists and arrays to track is sufficient to 
-simulate the construction of trees.
+But notice that the operations only need knowledge of the parent node and the size of the tree. 
+In other words, using internal arrays or hash maps to track is sufficient to simulate the construction of trees.
 
-Our implementation does this.
+Our implementation uses hash map to account for arbitrary object type.
 
 ## Complexity Analysis
 **Time**: O(log(n)) for Union and Find operations.
diff --git a/src/main/java/dataStructures/disjointSet/weightedUnion/Union.java b/src/main/java/dataStructures/disjointSet/weightedUnion/Union.java

Original file line number	Diff line number	Diff line change
`@@ -51,18 +51,18 @@ private static int partition(int[] arr, int start, int end) {`
`51`	`51`
`52`	`52`	`swap(arr, start, pIdx); // swap the pivot to the start of the array`
`53`	`53`
`54`		`- int less = start + 1;`
	`54`	`+ int idx = start + 1; // interpret: at the end, all elements at indices less than this var is <= pivot`
`55`	`55`
`56`	`56`	`for (int i = start + 1; i <= end; i++) {`
`57`	`57`	`if (arr[i] <= pivot) {`
`58`		`- swap(arr, less, i);`
`59`		`- less++;`
	`58`	`+ swap(arr, idx, i);`
	`59`	`+ idx++;`
`60`	`60`	`}`
`61`	`61`	`}`
`62`	`62`
`63`		`- swap(arr, less - 1, start); // swap the pivot to its correct position`
	`63`	`+ swap(arr, idx - 1, start); // swap the pivot to its correct position`
`64`	`64`
`65`		`- return less - 1;`
	`65`	`+ return idx - 1;`
`66`	`66`	`}`
`67`	`67`
`68`	`68`	`/**`