feat(searches): Add Floyd's Cycle-Finding Algorithm

Signed-off-by: Aditya Kumar <aditya.kumar60@infosys.com>

Author: AdityaK60

searches/floyds_cycle_finding.py

@@ -0,0 +1,80 @@
+"""
+An implementation of Floyd's Cycle-Finding Algorithm.
+Also known as the "tortoise and the hare" algorithm.
+
+This algorithm is used to detect a cycle in a sequence of iterated function values.
+It can also find the starting index and length of the cycle.
+
+Wikipedia: https://en.wikipedia.org/wiki/Cycle_detection#Floyd's_tortoise_and_hare
+"""
+from typing import Any, Callable, Optional, Tuple
+
+
+def floyds_cycle_finding(
+    f: Callable[[Any], Any], x0: Any
+) -> Optional[Tuple[int, int]]:
+    """
+    Finds a cycle in the sequence of values generated by the function f.
+
+    Args:
+        f: A function that takes a value and returns the next value in the sequence.
+        x0: The starting value of the sequence.
+
+    Returns:
+        A tuple containing the index of the first element of the cycle (mu)
+        and the length of the cycle (lam), or None if no cycle is found.
+
+    Doctest examples:
+    >>> # Example with a cycle
+    >>> f = lambda x: (2 * x + 3) % 17
+    >>> floyds_cycle_finding(f, 0)
+    (0, 8)
+
+    >>> # Example with a different starting point and cycle
+    >>> f = lambda x: [1, 2, 3, 4, 5, 3][x]
+    >>> floyds_cycle_finding(f, 0)
+    (2, 3)
+
+    >>> # Example with no cycle (sequence terminates)
+    >>> nodes = {0: 1, 1: 2, 2: 3, 3: None}
+    >>> f = lambda x: nodes.get(x)
+    >>> floyds_cycle_finding(f, 0)
+
+    """
+    # Main phase of the algorithm: finding a repetition x_i = x_2i.
+    # The hare moves twice as fast as the tortoise.
+    tortoise = f(x0)
+    hare = f(f(x0))
+    while tortoise != hare:
+        # If the hare reaches the end of the sequence, there is no cycle.
+        if hare is None or f(hare) is None:
+            return None
+        tortoise = f(tortoise)
+        hare = f(f(hare))
+
+    # At this point, the tortoise and hare have met.
+    # Now, find the position of the first repetition.
+    # The distance from the start to the cycle's beginning is mu.
+    mu = 0
+    tortoise = x0
+    while tortoise != hare:
+        tortoise = f(tortoise)
+        hare = f(hare)
+        mu += 1
+
+    # Finally, find the length of the cycle.
+    # The hare moves one step at a time while the tortoise stays put.
+    # The number of steps until they meet again is the cycle length (lam).
+    lam = 1
+    hare = f(tortoise)
+    while tortoise != hare:
+        hare = f(hare)
+        lam += 1
+
+    return mu, lam
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()