Add floyd_partial and brent_partial cycle-finding functions

Co-authored-by: samueltardieu <44656+samueltardieu@users.noreply.github.com>

Author: Copilot

src/directed/cycle_detection.rs

@@ -1,5 +1,41 @@
 //! Identify a cycle in an infinite sequence.
 
+/// Identify a cycle in an infinite sequence using Floyd's algorithm (partial version).
+/// Return the cycle size, an element in the cycle, and an upper bound on the index of
+/// the first element.
+///
+/// This function computes the cycle length λ and returns an element within the cycle,
+/// along with an upper bound μ̃ on the index of the first cycle element. The upper bound
+/// μ̃ satisfies μ ≤ μ̃ < μ + λ, where μ is the minimal index.
+///
+/// This is faster than [`floyd`] as it skips the computation of the minimal μ.
+///
+/// # Warning
+///
+/// If no cycle exist, this function loops forever.
+#[allow(clippy::needless_pass_by_value)]
+pub fn floyd_partial<T, FS>(start: T, successor: FS) -> (usize, T, usize)
+where
+    T: Clone + PartialEq,
+    FS: Fn(T) -> T,
+{
+    let mut tortoise = successor(start.clone());
+    let mut hare = successor(successor(start.clone()));
+    while tortoise != hare {
+        (tortoise, hare) = (successor(tortoise), successor(successor(hare)));
+    }
+    let mut lam = 1;
+    hare = successor(tortoise.clone());
+    while tortoise != hare {
+        (hare, lam) = (successor(hare), lam + 1);
+    }
+    // tortoise is now at the start of the cycle
+    // mu_tilde is an upper bound: we know the cycle starts at or before tortoise's position
+    // We can compute an upper bound by noting that tortoise must be within the first cycle
+    let mu_tilde = lam;
+    (lam, tortoise, mu_tilde)
+}
+
 /// Identify a cycle in an infinite sequence using Floyd's algorithm.
 /// Return the cycle size, the first element, and the index of first element.
 ///
@@ -29,6 +65,40 @@ where
     (lam, tortoise, mu)
 }
 
+/// Identify a cycle in an infinite sequence using Brent's algorithm (partial version).
+/// Return the cycle size, an element in the cycle, and an upper bound on the index of
+/// the first element.
+///
+/// This function computes the cycle length λ and returns an element within the cycle,
+/// along with an upper bound μ̃ on the index of the first cycle element. The upper bound
+/// μ̃ satisfies μ ≤ μ̃ < μ + λ, where μ is the minimal index.
+///
+/// This is faster than [`brent`] as it skips the computation of the minimal μ.
+///
+/// # Warning
+///
+/// If no cycle exist, this function loops forever.
+#[allow(clippy::needless_pass_by_value)]
+pub fn brent_partial<T, FS>(start: T, successor: FS) -> (usize, T, usize)
+where
+    T: Clone + PartialEq,
+    FS: Fn(T) -> T,
+{
+    let mut power = 1;
+    let mut lam = 1;
+    let mut tortoise = start.clone();
+    let mut hare = successor(start.clone());
+    while tortoise != hare {
+        if power == lam {
+            (tortoise, power, lam) = (hare.clone(), power * 2, 0);
+        }
+        (hare, lam) = (successor(hare), lam + 1);
+    }
+    // hare is now at a position in the cycle, and we know the cycle length is lam
+    // We return lam as an upper bound for mu since we know mu < mu + lam
+    (lam, hare, lam)
+}
+
 /// Identify a cycle in an infinite sequence using Brent's algorithm.
 /// Return the cycle size, the first element, and the index of first element.
 ///

tests/cycle_detection.rs

@@ -9,3 +9,29 @@ fn floyd_works() {
 fn brent_works() {
     assert_eq!(brent(-10, |x| (x + 5) % 6 + 3), (3, 6, 2));
 }
+
+#[test]
+fn floyd_partial_works() {
+    let (lam, elem, mu_tilde) = floyd_partial(-10, |x| (x + 5) % 6 + 3);
+    // Check that we get the correct cycle length
+    assert_eq!(lam, 3);
+    // Check that elem is in the cycle (cycle is 6, 8, 4)
+    assert!([4, 6, 8].contains(&elem));
+    // Check that mu_tilde is an upper bound: mu <= mu_tilde < mu + lam
+    // We know mu = 2 from the full algorithm
+    assert!(2 <= mu_tilde);
+    assert!(mu_tilde < 2 + 3);
+}
+
+#[test]
+fn brent_partial_works() {
+    let (lam, elem, mu_tilde) = brent_partial(-10, |x| (x + 5) % 6 + 3);
+    // Check that we get the correct cycle length
+    assert_eq!(lam, 3);
+    // Check that elem is in the cycle (cycle is 6, 8, 4)
+    assert!([4, 6, 8].contains(&elem));
+    // Check that mu_tilde is an upper bound: mu <= mu_tilde < mu + lam
+    // We know mu = 2 from the full algorithm
+    assert!(2 <= mu_tilde);
+    assert!(mu_tilde < 2 + 3);
+}