feat(puzzles): find bitonic peak using binary search

This adds a new function to find a bitonic peak in a given list of integers.
This is a variation of find_peak_element and achieves the same outcome with the same
time and space complexity of O(1) and O(log(n)).

Additional tests and comments have been added for clarity to make the algorithm easier to
understand and reason about.

Author: BrianLusina

puzzles/find_fixed_number/README.md renamed to puzzles/search/binary_search/find_fixed_number/README.md

@@ -1,4 +1,4 @@
-# Find Peak Element
+# Find Peak Element(or Find Bitonic Peak)
 
 A peak element is an element that is strictly greater than its neighbors.
 

puzzles/find_fixed_number/__init__.py renamed to puzzles/search/binary_search/find_fixed_number/__init__.py

@@ -1,7 +1,7 @@
-from typing import List
+from typing import List, Optional
 
 
-def find_peak_element(nums: List[int]) -> int:
+def find_peak_element(nums: List[int]) -> Optional[int]:
     """Finds a peak element's index in the provided list of integers
 
     Algorithm:
@@ -25,14 +25,21 @@ def find_peak_element(nums: List[int]) -> int:
     Returns:
         int: index of a peak element(i.e. element that is greater than its adjacent neighbours)
     """
+    # we require at least 3 numbers to form a bitonic peak
+    if len(nums) < 3:
+        return None
+
     left = 0
     right = len(nums) - 1
     peak_index = -1
 
     while left <= right:
         mid = (left + right) >> 1
 
-        # check that the potential peak element is within bounds or is greater than both its neighbours
+        # check that the potential peak element is within bounds or is greater than both its neighbours. The
+        # `mid==len(nums)-1` check is to ensure we are not at the end of the list. The potential_peak > nums[mid + 1]
+        # checks if the peak is greater than the next number. If either condition evaluates to true, the peak index is
+        # set to the middle and the right boundary is moved to the middle minus 1, this removes the right half
         potential_peak = nums[mid]
         if mid == len(nums) - 1 or potential_peak > nums[mid + 1]:
             peak_index = mid
@@ -41,3 +48,51 @@ def find_peak_element(nums: List[int]) -> int:
             left = mid + 1
 
     return peak_index
+
+
+def find_bitonic_peak(nums: List[int]) -> Optional[int]:
+    """
+    Finds the bitonic peak or the peak element in a list of numbers. A bitonic peak is an integer whose value is greater
+    thant its neighbours on both the immediate left and the immediate right.
+
+    Complexity:
+
+    - Time complexity O(log n): Where n is the number of elements in the nums vector.
+    - Space Complexity O(1): Since it uses a constant amount of extra space.
+
+    Args:
+        nums (List): list of integers
+    Returns:
+        int: index of a peak element(i.e. element that is greater than its adjacent neighbours)
+    """
+    # we require at least 3 numbers to form a bitonic peak
+    if len(nums) < 3:
+        return None
+
+    left = 0
+    right = len(nums) - 1
+
+    while left <= right:
+        mid = (left + right) >> 1
+
+        # we assign the mid_left and mid_right based on the middle index. If the middle index - 1(i.e. left of the middle
+        # is greater than or equal to 0, we assign that value to mid_left, else we assign it a negative infinity value.
+        # the negative infinity indicates that the value is out of bounds of the list.
+        # On the other hand, if the middle index + 1 (i.e. the right of the middle index) is less than the length of the
+        # list, then we assign it that value to the mid_right. If not, we give the mid_right a value of positive infinity
+        # indicating that this is out of bounds of the list
+        mid_left = nums[mid - 1] if mid - 1 >= 0 else float("-inf")
+        mid_right = nums[mid + 1] if mid + 1 < len(nums) else float("inf")
+
+        # if the mid_left is less than the middle value and the mid_right is greater than the middle value, we move the
+        # left pointer to 1 value greater than the middle index
+        if mid_left < nums[mid] < mid_right:
+            left = mid + 1
+        elif mid_left > nums[mid] > mid_right:
+            # we move the right pointer to middle index minus 1
+            right = mid - 1
+        elif mid_left < nums[mid] and mid_right < nums[mid]:
+            # else we return the middle value
+            return mid
+
+    return None

puzzles/find_fixed_number/test_find_fixed_number.py renamed to puzzles/search/binary_search/find_fixed_number/test_find_fixed_number.py

@@ -1,5 +1,5 @@
 import unittest
-from . import find_peak_element
+from . import find_peak_element, find_bitonic_peak
 
 
 class FindPeakElementTestCase(unittest.TestCase):
@@ -88,6 +88,121 @@ def test_9(self):
         actual = find_peak_element(nums)
         self.assertEqual(expected, actual)
 
+    def test_10(self):
+        """should return 3 from [1, 2, 3, 4, 1]"""
+        nums = [1, 2, 3, 4, 1]
+        expected = 3
+        actual = find_peak_element(nums)
+        self.assertEqual(expected, actual)
+
+    def test_11(self):
+        """should return 3 from [1, 6, 5, 4, 3, 2, 1]"""
+        nums = [1, 6, 5, 4, 3, 2, 1]
+        expected = 1
+        actual = find_peak_element(nums)
+        self.assertEqual(expected, actual)
+
+
+class FindBitonicPeakTestCases(unittest.TestCase):
+    def test_1(self):
+        """should return 2 for nums = [1,2,3,1]"""
+        nums = [1, 2, 3, 1]
+        expected = 2
+        actual = find_bitonic_peak(nums)
+        self.assertEqual(expected, actual)
+
+    def test_2(self):
+        """should return either 5 or 1 for nums = [1,2,1,3,5,6,4]"""
+        nums = [1, 2, 1, 3, 5, 6, 4]
+        expected_5 = 5
+        expected_1 = 1
+        actual = find_bitonic_peak(nums)
+        self.assertIn(actual, [expected_1, expected_5])
+
+    def test_3(self):
+        """should return either 3 for nums = [0, 1, 2, 3, 2, 1, 0]"""
+        nums = [0, 1, 2, 3, 2, 1, 0]
+        expected = 3
+        actual = find_bitonic_peak(nums)
+        self.assertEqual(actual, expected)
+
+    def test_4(self):
+        """should return 1 from 0 10 3 2 1 0"""
+        nums = [0, 10, 3, 2, 1, 0]
+        expected = 1
+        actual = find_bitonic_peak(nums)
+        self.assertEqual(expected, actual)
+
+    def test_5(self):
+        """should return 1 from 0 10 0"""
+        nums = [0, 10, 0]
+        expected = 1
+        actual = find_bitonic_peak(nums)
+        self.assertEqual(expected, actual)
+
+    def test_6(self):
+        """should return 16 from 0 1 2 12 22 32 42 52 62 72 82 92 102 112 122 132 133 132 111 0"""
+        nums = [
+            0,
+            1,
+            2,
+            12,
+            22,
+            32,
+            42,
+            52,
+            62,
+            72,
+            82,
+            92,
+            102,
+            112,
+            122,
+            132,
+            133,
+            132,
+            111,
+            0,
+        ]
+        expected = 16
+        actual = find_bitonic_peak(nums)
+        self.assertEqual(expected, actual)
+
+    def test_7(self):
+        """should return 1 from 0, 10, 5, 2"""
+        nums = [0, 10, 5, 2]
+        expected = 1
+        actual = find_bitonic_peak(nums)
+        self.assertEqual(expected, actual)
+
+    def test_8(self):
+        """should return 1 from 0, 2, 1, 0"""
+        nums = [0, 2, 1, 0]
+        expected = 1
+        actual = find_bitonic_peak(nums)
+        self.assertEqual(expected, actual)
+
+    def test_9(self):
+        """should return 1 from 0, 1, 0"""
+        nums = [0, 1, 0]
+        expected = 1
+        actual = find_bitonic_peak(nums)
+        self.assertEqual(expected, actual)
+
+    def test_10(self):
+        """should return 3 from [1, 2, 3, 4, 1]"""
+        nums = [1, 2, 3, 4, 1]
+        expected = 3
+        actual = find_bitonic_peak(nums)
+        self.assertEqual(expected, actual)
+
+    def test_11(self):
+        """should return 3 from [1, 6, 5, 4, 3, 2, 1]"""
+        nums = [1, 6, 5, 4, 3, 2, 1]
+        expected = 1
+        actual = find_bitonic_peak(nums)
+        self.assertEqual(expected, actual)
+
 
 if __name__ == "__main__":
     unittest.main()