Refactor ExtendedEuclideanAlgorithm and ModularInverse: add docs, clean up

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: williamfiset

README.md

@@ -242,7 +242,7 @@ $ java -cp classes com.williamfiset.algorithms.search.BinarySearch
 - [[UNTESTED] Chinese remainder theorem](src/main/java/com/williamfiset/algorithms/math/ChineseRemainderTheorem.java)
 - [Prime number sieve (sieve of Eratosthenes)](src/main/java/com/williamfiset/algorithms/math/SieveOfEratosthenes.java) **- O(nlog(log(n)))**
 - [Prime number sieve (sieve of Eratosthenes, compressed)](src/main/java/com/williamfiset/algorithms/math/CompressedPrimeSieve.java) **- O(nlog(log(n)))**
-- [Totient function (phi function, relatively prime number count)](src/main/java/com/williamfiset/algorithms/math/EulerTotientFunction.java) **- O(n<sup>1/4</sup>)**
+- [Totient function (phi function, relatively prime number count)](src/main/java/com/williamfiset/algorithms/math/EulerTotientFunction.java) **- O(√n)**
 - [Totient function using sieve (phi function, relatively prime number count)](src/main/java/com/williamfiset/algorithms/math/EulerTotientFunctionWithSieve.java) **- O(nlog(log(n)))**
 - [Extended euclidean algorithm](src/main/java/com/williamfiset/algorithms/math/ExtendedEuclideanAlgorithm.java) **- ~O(log(a + b))**
 - [Greatest Common Divisor (GCD)](src/main/java/com/williamfiset/algorithms/math/Gcd.java) **- ~O(log(a + b))**

src/main/java/com/williamfiset/algorithms/math/ExtendedEuclideanAlgorithm.java

@@ -1,21 +1,39 @@
-/** Time Complexity ~O(log(a + b)) */
+/**
+ * Extended Euclidean Algorithm. Given two integers a and b, computes gcd(a, b) and finds integers x
+ * and y such that ax + by = gcd(a, b). Useful for finding modular inverses and solving linear
+ * Diophantine equations.
+ *
+ * <p>Time: ~O(log(a + b))
+ *
+ * @author William Fiset, william.alexandre.fiset@gmail.com
+ */
 package com.williamfiset.algorithms.math;
 
 public class ExtendedEuclideanAlgorithm {
 
-  // This function performs the extended euclidean algorithm on two numbers a and b.
-  // The function returns the gcd(a,b) as well as the numbers x and y such
-  // that ax + by = gcd(a,b). This calculation is important in number theory
-  // and can be used for several things such as finding modular inverses and
-  // solutions to linear Diophantine equations.
+  /**
+   * Performs the extended Euclidean algorithm on a and b.
+   *
+   * @return an array [gcd(a, b), x, y] such that ax + by = gcd(a, b).
+   */
   public static long[] egcd(long a, long b) {
-    if (b == 0) return new long[] {a, 1, 0};
-    else {
-      long[] ret = egcd(b, a % b);
-      long tmp = ret[1] - ret[2] * (a / b);
-      ret[1] = ret[2];
-      ret[2] = tmp;
-      return ret;
-    }
+    if (b == 0)
+      return new long[] {a, 1, 0};
+    long[] ret = egcd(b, a % b);
+    long tmp = ret[1] - ret[2] * (a / b);
+    ret[1] = ret[2];
+    ret[2] = tmp;
+    return ret;
+  }
+
+  public static void main(String[] args) {
+    // egcd(35, 15) = [5, 1, -2] because gcd(35,15)=5 and 35*1 + 15*(-2) = 5.
+    long[] result = egcd(35, 15);
+    System.out.printf("gcd(%d, %d) = %d, x = %d, y = %d\n", 35, 15, result[0], result[1], result[2]);
+
+    // Finding modular inverse: 7^(-1) mod 11 = 8 because 7*8 mod 11 = 1.
+    long[] inv = egcd(7, 11);
+    long modInverse = ((inv[1] % 11) + 11) % 11;
+    System.out.printf("7^(-1) mod 11 = %d\n", modInverse);
   }
 }

src/main/java/com/williamfiset/algorithms/math/ModularInverse.java

@@ -1,46 +1,51 @@
-/** Time Complexity ~O(log(a + b)) */
+/**
+ * Computes the modular inverse of a number using the Extended Euclidean Algorithm.
+ *
+ * <p>The modular inverse of 'a' mod 'm' is a value x such that a*x ≡ 1 (mod m). It exists if and
+ * only if gcd(a, m) = 1 (i.e. a and m are coprime).
+ *
+ * <p>Time: ~O(log(a + m))
+ *
+ * @author William Fiset, william.alexandre.fiset@gmail.com
+ */
 package com.williamfiset.algorithms.math;
 
 public class ModularInverse {
 
-  // This function performs the extended euclidean algorithm on two numbers a and b.
-  // The function returns the gcd(a,b) as well as the numbers x and y such
-  // that ax + by = gcd(a,b). This calculation is important in number theory
-  // and can be used for several things such as finding modular inverses and
-  // solutions to linear Diophantine equations.
+  /**
+   * Returns the modular inverse of 'a' mod 'm', or null if it does not exist.
+   *
+   * @param a the value to invert.
+   * @param m the modulus (must be positive).
+   * @return the modular inverse, or null if gcd(a, m) != 1.
+   * @throws ArithmeticException if m is not positive.
+   */
+  public static Long modInv(long a, long m) {
+    if (m <= 0)
+      throw new ArithmeticException("mod must be > 0");
+    a = ((a % m) + m) % m;
+    long[] v = egcd(a, m);
+    if (v[0] != 1)
+      return null;
+    return ((v[1] % m) + m) % m;
+  }
+
+  // Returns [gcd(a, b), x, y] such that ax + by = gcd(a, b).
   private static long[] egcd(long a, long b) {
-    if (b == 0) return new long[] {a, 1L, 0L};
+    if (b == 0)
+      return new long[] {a, 1, 0};
     long[] v = egcd(b, a % b);
     long tmp = v[1] - v[2] * (a / b);
     v[1] = v[2];
     v[2] = tmp;
     return v;
   }
 
-  // Returns the modular inverse of 'a' mod 'm' if it exists.
-  // Make sure m > 0 and 'a' & 'm' are relatively prime.
-  public static Long modInv(long a, long m) {
-
-    if (m <= 0) throw new ArithmeticException("mod must be > 0");
-
-    // Avoid a being negative
-    a = ((a % m) + m) % m;
-
-    long[] v = egcd(a, m);
-    long gcd = v[0];
-    long x = v[1];
-
-    if (gcd != 1) return null;
-    return ((x + m) % m) % m;
-  }
-
   public static void main(String[] args) {
-
-    // Prints 3 since 2*3 mod 5 = 1
+    // 2*3 mod 5 = 1, so modInv(2, 5) = 3.
     System.out.println(modInv(2, 5));
 
-    // Prints null because there is no
-    // modular inverse such that 4*x mod 18 = 1
+    // gcd(4, 18) != 1, so no inverse exists.
     System.out.println(modInv(4, 18));
   }
 }