feat(algorithms, top-k-elements): smallest range covering alements from k lists, two pointer and brute force

Author: BrianLusina

algorithms/top_k_elements/smallest_range_covering_k_lists/README.md

@@ -53,6 +53,69 @@ Output: [1,1]
 
 ### Optimal Brute Force
 
+We need to find the smallest range that contains at least one number from each of the k sorted lists. At first glance,
+a simple brute force solution comes to mind, i.e., checking every combination of elements from the lists to find the
+smallest range. However, that would involve too many comparisons and will lead to TLE. Instead, we can refine this
+process into something more manageable.
+
+At any moment, we need to select one number from each list. So, to find the smallest range, we need to minimize the
+difference between the largest and smallest numbers chosen at each step. The important point here is that, at any time,
+our range is defined by the smallest number chosen and the largest number chosen.
+
+So we need to select the smallest number among the current numbers picked from each list and move forward by choosing the
+next number from the same list that gave us this smallest number. This makes sense because moving forward in any other
+list would only increase the range, which we want to avoid. We repeat this process of updating the smallest number and
+checking if the new range is smaller than our previously found range. If it is, we update the range.
+
+We continue this until we reach the end of one of the lists because, at that point, it’s no longer possible to select a
+number from each list.
+
+Algorithm steps:
+
+- Initialize k to the number of lists in nums and create an array indices to keep track of the current index of each
+  list, initializing all to 0.
+- Initialize an array range to store the smallest range, starting with {0, INT_MAX}.
+- Enter an infinite loop:
+  - Initialize curMin to INT_MAX, curMax to INT_MIN, and minListIndex to 0. 
+  - Iterate over each list to find the current minimum and maximum values:
+    - For each list i, retrieve the current element using indices[i]. 
+    - Update curMin if the current element is less than curMin, and set minListIndex to i. 
+    - Update curMax if the current element is greater than curMax. 
+  - After checking all lists, if the difference curMax - curMin is smaller than the current range (range[1] - range[0]),
+    update range to {curMin, curMax}. 
+  - Move to the next element in the list that had the minimum value by incrementing indices[minListIndex]. 
+    - If the updated index equals the size of nums[minListIndex], break the loop (all elements have been processed). 
+- Return the smallest range stored in range.
+
+> Note: Due to Python's relatively slower execution speed, the optimal brute-force solution will lead to a Time Limit
+> Exceeded (TLE) error when using Python3. However, this same solution will perform adequately in other programming
+> languages.
+
+#### Complexity Analysis
+
+Let `n` be the total number of elements across all lists and k be the number of lists.
+
+##### Time Complexity
+
+In each iteration of the while (true) loop, we traverse all k lists to find the current minimum and maximum. This
+takes O(k) time.
+
+The loop continues until at least one of the lists is fully traversed. In the worst case, every element from every list
+is visited, and the total number of elements across all lists is n. Therefore, the loop runs O(n) times.
+
+Overall, the time complexity becomes O(n⋅k).
+
+##### Space Complexity
+
+The space complexity is dominated by the indices and range arrays, both of which have size proportional to k, the number
+of lists.
+
+The indices array stores the current index of each list, so it takes O(k) space.
+
+The range array also stores two integers, so it takes O(1) space.
+
+Hence, the overall space complexity is O(k).
+
 ### Heap (Priority Queue)
 
 The core idea of this solution is to find the smallest range that includes at least one number from each of the k sorted
@@ -140,3 +203,93 @@ the output range (two integers) is negligible and does not contribute to the ove
 
 ### Two-Pointer
 
+Since we need a range that includes one number from each of the k lists, we can think of this as a subarray problem.
+However, the numbers are spread across multiple lists. To simplify, we can combine all the lists into a single sorted
+list of numbers. When merging, we also keep track of which list each number came from, since the problem requires at
+least one number from each original list in the final range.
+
+Once we have the merged list, the problem becomes finding the smallest range (or subarray) in this list that contains at
+least one element from each of the original k lists. This is a common scenario for a sliding window or two-pointer
+approach: we want to expand and shrink the window (subarray) dynamically to find the minimum range that meets the criteria.
+
+The right pointer will expand the window by moving forward in the merged list, and the left pointer will shrink the
+window once we know the window contains at least one element from each list.
+
+As the right pointer moves through the merged list, we need to ensure that the current subarray includes at least one
+number from each list. So we keep track of how many lists are "covered" by the current subarray (i.e., how many of the
+k lists have at least one number in the current window).
+
+Once all lists are covered, the window between the left and right pointers represents a valid range. We then check if
+this range is the smallest we've found so far.
+
+After finding a valid range, we need to shrink the window (move the left pointer forward) to see if we can make the range
+even smaller while still keeping one number from each list in the subarray. As we move the left pointer forward, we check
+if we lose coverage from any list. If we do, we stop shrinking and start expanding the window again by moving the right
+pointer.
+
+We will continue this until we can no longer expand the window (i.e., the right pointer reaches the end of the merged list).
+By this point, we have explored all possible ranges, and the smallest valid range is our final answer.
+
+![Solution 2.1](./images/solutions/smallest_range_covering_elements_from_k_lists_two_pointer_solution_1.png)
+![Solution 2.2](./images/solutions/smallest_range_covering_elements_from_k_lists_two_pointer_solution_2.png)
+![Solution 2.3](./images/solutions/smallest_range_covering_elements_from_k_lists_two_pointer_solution_3.png)
+![Solution 2.4](./images/solutions/smallest_range_covering_elements_from_k_lists_two_pointer_solution_4.png)
+![Solution 2.5](./images/solutions/smallest_range_covering_elements_from_k_lists_two_pointer_solution_5.png)
+![Solution 2.6](./images/solutions/smallest_range_covering_elements_from_k_lists_two_pointer_solution_6.png)
+![Solution 2.7](./images/solutions/smallest_range_covering_elements_from_k_lists_two_pointer_solution_7.png)
+![Solution 2.8](./images/solutions/smallest_range_covering_elements_from_k_lists_two_pointer_solution_8.png)
+![Solution 2.9](./images/solutions/smallest_range_covering_elements_from_k_lists_two_pointer_solution_9.png)
+
+Algorithm steps:
+
+- Initialize an empty array `merged` to store pairs of numbers and their respective list indices.
+- Merge all lists into `merged`:
+  - For each list in `nums`, iterate through its numbers and add each number along with its list index to merged.
+- Sort the `merged` array to facilitate the two-pointer technique.
+- Initialize a frequency map `freq` to keep track of how many times each list is represented in the current window.
+- Set the `left` pointer to 0, `count` to 0, and initialize `rangeStart` to 0 and `rangeEnd` to INT_MAX.
+- Use a `right` pointer to iterate through the merged array:
+  - Increment the count for the list index in `freq` for `merged[right]`.
+  - If the count for this list index becomes 1, increment `count` (indicating a new list is represented).
+- When all lists are represented (i.e., `count == nums.size()`):
+  - Calculate the current range as `curRange = merged[right].first - merged[left].first`.
+  - If `curRange` is smaller than the previously found range (`rangeEnd - rangeStart`):
+    - Update rangeStart and rangeEnd to the current numbers.
+  - Decrement the frequency count for the leftmost number (i.e., `merged[left]`).
+  - If this list index's frequency becomes 0, decrement `count` (indicating that a list is no longer represented).
+  - Move the `left` pointer to the right to attempt shrinking the window.
+- After completing the iteration, return the smallest range as a array containing `rangeStart` and `rangeEnd`.
+
+#### Complexity Analysis
+
+Let `n` be the total number of elements across all lists and `k` be the number of lists.
+
+##### Time Complexity
+
+The first nested loop iterates over `k` lists, and for each list, it iterates through its elements. In the worst case,
+this requires `O(n)` time since we are processing all elements once.
+
+After merging, we sort the merged array which contains n elements. Sorting has a time complexity of `O(nlog(n))`.
+
+The two-pointer approach iterates through the merged list once (with the right pointer) and may also move the left
+pointer forward multiple times. In total, each pointer will traverse the merged list at most `n` times.
+
+Combining these steps, the overall time complexity is: `O(nlog(n))`
+
+##### Space Complexity
+
+We create a merged array to hold n elements, which requires `O(n)` space.
+
+We use an unordered map (`freq`) that can potentially store `k` elements (one for each list). Thus, this requires `O(k)`
+space.
+
+Some extra space is used when we sort an array. The space complexity of the sorting algorithm (S) depends on the
+programming language.
+
+- In Python, the sort method sorts a list using the Timsort algorithm which is a combination of Merge Sort and Insertion
+  Sort and has a space complexity of `O(n)`.
+- In C++, the sort() function is implemented as a hybrid of Quick Sort, Heap Sort, and Insertion Sort, with a worst-case
+  space complexity of `O(log(n))`. 
+- In Java, Arrays.sort() is implemented using a variant of the Quick Sort algorithm which has a space complexity of `O(log(n))`. 
+
+Combining these, the overall space complexity is: `O(n)`

algorithms/top_k_elements/smallest_range_covering_k_lists/__init__.py

@@ -1,4 +1,5 @@
-from typing import List, Tuple
+from collections import defaultdict
+from typing import List, Tuple, DefaultDict
 import heapq
 
 
@@ -44,3 +45,78 @@ def smallest_range(nums: List[List[int]]) -> List[int]:
 
     # Return the smallest range found
     return [range_start, range_end]
+
+
+def smallest_range_two_pointer(nums: List[List[int]]) -> List[int]:
+    merged: List[Tuple[int, int]] = []
+
+    # merge all lists with their list index
+    for list_idx, num_list in enumerate(nums):
+        for num in num_list:
+            merged.append((num, list_idx))
+
+    # sor the merged list
+    merged.sort()
+
+    # Two pointers to track the smallest range
+    freq: DefaultDict[int, int] = defaultdict(int)
+    left, count = 0, 0
+    range_start, range_end = 0, float("inf")
+
+    for right in range(len(merged)):
+        val = merged[right][1]
+        freq[val] += 1
+        if freq[val] == 1:
+            count += 1
+
+        # when all lists are represented, try to shrink the window
+        while count == len(nums):
+            current_range = merged[right][0] - merged[left][0]
+            if current_range < range_end - range_start:
+                range_start = merged[left][0]
+                range_end = merged[right][0]
+
+            freq[merged[left][1]] -= 1
+            if freq[merged[left][1]] == 0:
+                count -= 1
+
+            left += 1
+
+    return [range_start, range_end]
+
+
+def smallest_range_brute_force(nums: List[List[int]]) -> List[int]:
+    k = len(nums)
+    # Stores the current index of each list
+    indices = [0] * k
+    # To track the smallest range
+    range_list = [0, float("inf")]
+
+    while True:
+        cur_min, cur_max = float("inf"), float("-inf")
+        min_list_index = 0
+
+        # Find the current minimum and maximum values across the lists
+        for i in range(k):
+            current_element = nums[i][indices[i]]
+
+            # Update the current minimum
+            if current_element < cur_min:
+                cur_min = current_element
+                min_list_index = i
+
+            # Update the current maximum
+            if current_element > cur_max:
+                cur_max = current_element
+
+        # Update the range if a smaller one is found
+        if cur_max - cur_min < range_list[1] - range_list[0]:
+            range_list[0] = cur_min
+            range_list[1] = cur_max
+
+        # Move to the next element in the list that had the minimum value
+        indices[min_list_index] += 1
+        if indices[min_list_index] == len(nums[min_list_index]):
+            break
+
+    return range_list