foxmath 0.6.2__tar.gz → 0.7.1__tar.gz

{foxmath-0.6.2/src/foxmath.egg-info → foxmath-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: foxmath
-Version: 0.6.2
+Version: 0.7.1
 Summary: Minimalist CLI for math & cryptography exploration 🦊
 Author-email: Abhrankan Chakrabarti <abhrankan@gmail.com>
 License: MIT
@@ -29,6 +29,7 @@ Built with curiosity — for students, tinkerers, and crypto/math enthusiasts.
 
 ## Features
 - Legendre symbol
+- Modular square root via Tonelli-Shanks (sqrtmod)
 - Euler/Hermann Machin-like π approximation
 - Elliptic curve point addition (over finite fields), including
   named curves (secp256k1) with on-curve result validation
@@ -38,8 +39,8 @@ Built with curiosity — for students, tinkerers, and crypto/math enthusiasts.
 - Continued fraction expansion and convergents
 - Challenge/quiz mode — practice problems with scoring, or a
   worksheet mode for self-study
-- Symlink-friendly (foxmath-legendre, foxmath-pi, foxmath-ecadd,
-  foxmath-ecmul, foxmath-crt, foxmath-cf, foxmath-challenge)
+- Symlink-friendly (foxmath-legendre, foxmath-sqrtmod, foxmath-pi,
+  foxmath-ecadd, foxmath-ecmul, foxmath-crt, foxmath-cf, foxmath-challenge)
 - JSON output mode
 
 ## Installation
@@ -60,7 +61,7 @@ Check which version you have installed:
 foxmath --version
 ```
 ```
-foxmath 0.6.2
+foxmath 0.7.1
 ```
 
 ## Usage Examples
@@ -79,6 +80,17 @@ foxmath legendre 5 17
 Legendre (5/17) = -1
 ```
 
+```bash
+foxmath sqrtmod 10 13
+```
+```
+sqrt(10) = +/-7 (mod 13)
+```
+
+`sqrtmod` uses the Tonelli-Shanks algorithm to find modular square roots
+when they exist. It reports an error when the input is a quadratic
+non-residue modulo the given odd prime.
+
 ```bash
 # Symlinks (optional)
 foxmath-ecadd --x1 1 --y1 2 --x2 3 --y2 4 --p 17

{foxmath-0.6.2 → foxmath-0.7.1}/README.md

@@ -10,6 +10,7 @@ Built with curiosity — for students, tinkerers, and crypto/math enthusiasts.
 
 ## Features
 - Legendre symbol
+- Modular square root via Tonelli-Shanks (sqrtmod)
 - Euler/Hermann Machin-like π approximation
 - Elliptic curve point addition (over finite fields), including
   named curves (secp256k1) with on-curve result validation
@@ -19,8 +20,8 @@ Built with curiosity — for students, tinkerers, and crypto/math enthusiasts.
 - Continued fraction expansion and convergents
 - Challenge/quiz mode — practice problems with scoring, or a
   worksheet mode for self-study
-- Symlink-friendly (foxmath-legendre, foxmath-pi, foxmath-ecadd,
-  foxmath-ecmul, foxmath-crt, foxmath-cf, foxmath-challenge)
+- Symlink-friendly (foxmath-legendre, foxmath-sqrtmod, foxmath-pi,
+  foxmath-ecadd, foxmath-ecmul, foxmath-crt, foxmath-cf, foxmath-challenge)
 - JSON output mode
 
 ## Installation
@@ -41,7 +42,7 @@ Check which version you have installed:
 foxmath --version
 ```
 ```
-foxmath 0.6.2
+foxmath 0.7.1
 ```
 
 ## Usage Examples
@@ -60,6 +61,17 @@ foxmath legendre 5 17
 Legendre (5/17) = -1
 ```
 
+```bash
+foxmath sqrtmod 10 13
+```
+```
+sqrt(10) = +/-7 (mod 13)
+```
+
+`sqrtmod` uses the Tonelli-Shanks algorithm to find modular square roots
+when they exist. It reports an error when the input is a quadratic
+non-residue modulo the given odd prime.
+
 ```bash
 # Symlinks (optional)
 foxmath-ecadd --x1 1 --y1 2 --x2 3 --y2 4 --p 17

{foxmath-0.6.2 → foxmath-0.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "foxmath"
-version = "0.6.2"
+version = "0.7.1"
 description = "Minimalist CLI for math & cryptography exploration 🦊"
 readme = "README.md"
 license = {text = "MIT"}
@@ -29,6 +29,7 @@ dependencies = []  # Pure stdlib for now
 [project.scripts]
 foxmath = "foxmath.foxmath:main"
 foxmath-legendre = "foxmath.foxmath:main"
+foxmath-sqrtmod = "foxmath.foxmath:main"
 foxmath-pi = "foxmath.foxmath:main"
 foxmath-ecadd = "foxmath.foxmath:main"
 foxmath-ecmul = "foxmath.foxmath:main"

{foxmath-0.6.2 → foxmath-0.7.1}/src/foxmath/foxmath.py

@@ -22,13 +22,107 @@ def _package_version() -> str:
 
 # ------------------- Math Functions -------------------
 
-def legendre_symbol(a: int, p: int) -> int:
-    """Compute Legendre symbol (a/p)"""
-    if p < 2 or p % 2 == 0:
+# First 13 primes. As Miller-Rabin bases they make the test *deterministic*
+# for every n below 3,317,044,064,679,887,385,961,981 (~3.3e24); 12 bases
+# would not be enough (399165290221 * 798330580441, ~3.2e23, fools them).
+_PRIME_TEST_BASES = (2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41)
+
+def _is_probable_prime(n: int) -> bool:
+    """Miller-Rabin primality test.
+
+    Exact for n < ~3.3e24. Above that it is a strong probable-prime test:
+    ordinary composites essentially never pass, but a composite built
+    specifically to fool these 13 bases could.
+    """
+    if n < 2:
+        return False
+    for sp in _PRIME_TEST_BASES:
+        if n == sp:
+            return True
+        if n % sp == 0:
+            return False
+    d, r = n - 1, 0
+    while d % 2 == 0:
+        d //= 2
+        r += 1
+    for a in _PRIME_TEST_BASES:
+        x = pow(a, d, n)
+        if x == 1 or x == n - 1:
+            continue
+        for _ in range(r - 1):
+            x = x * x % n
+            if x == n - 1:
+                break
+        else:
+            return False
+    return True
+
+def _require_odd_prime(p: int) -> None:
+    """Enforce the contract the Legendre symbol and Tonelli-Shanks rely on.
+
+    Euler's criterion is only meaningful for a prime modulus. On a composite
+    it returns garbage, and Tonelli-Shanks' search for a non-residue can loop
+    forever (mod 9 or mod 561, for example, there is none to find).
+    """
+    if p < 2 or p % 2 == 0 or not _is_probable_prime(p):
         raise ValueError("p must be an odd prime")
+
+def _legendre_unchecked(a: int, p: int) -> int:
     res = pow(a, (p - 1) // 2, p)
     return 1 if res == 1 else (-1 if res == p - 1 else 0)
 
+def legendre_symbol(a: int, p: int) -> int:
+    """Compute Legendre symbol (a/p). p must be an odd prime."""
+    _require_odd_prime(p)
+    return _legendre_unchecked(a, p)
+
+def sqrt_mod(a: int, p: int) -> tuple:
+    """Return the square root(s) of a modulo an odd prime p."""
+    _require_odd_prime(p)
+
+    a %= p
+    symbol = _legendre_unchecked(a, p)
+    if symbol == 0:
+        return (0,)
+    if symbol == -1:
+        raise ValueError(f"{a} has no square root modulo {p}")
+
+    # For p ≡ 3 (mod 4), the root is a^(p+1)/4.
+    if p % 4 == 3:
+        root = pow(a, (p + 1) // 4, p)
+    else:
+        # Tonelli-Shanks: write p - 1 = q * 2^s with q odd.
+        q, s = p - 1, 0
+        while q % 2 == 0:
+            q //= 2
+            s += 1
+
+        non_residue = 2
+        while _legendre_unchecked(non_residue, p) != -1:
+            non_residue += 1
+
+        c = pow(non_residue, q, p)
+        root = pow(a, (q + 1) // 2, p)
+        t = pow(a, q, p)
+        m = s
+
+        while t != 1:
+            i = 1
+            t_squared = (t * t) % p
+            while t_squared != 1:
+                t_squared = (t_squared * t_squared) % p
+                i += 1
+                if i == m:
+                    raise ValueError(f"{a} has no square root modulo {p}")
+            b = pow(c, 1 << (m - i - 1), p)
+            root = (root * b) % p
+            t = (t * b * b) % p
+            c = (b * b) % p
+            m = i
+
+    other = (-root) % p
+    return tuple(sorted({root, other}))
+
 def _arctan_series(inv_n: Decimal, terms: int) -> Decimal:
     """arctan(1/n) via its Taylor series, evaluated to `terms` terms. `inv_n` is 1/n."""
     total = Decimal(0)
@@ -283,6 +377,17 @@ def get_command():
     return None
 
 def main():
+    if hasattr(sys.stdout, "reconfigure"):
+        try:
+            sys.stdout.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+    if hasattr(sys.stderr, "reconfigure"):
+        try:
+            sys.stderr.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+
     cmd = get_command()
 
     # Handle --json independently of argparse subparser scoping: a subparser's
@@ -311,6 +416,10 @@ def main():
     leg.add_argument("a", type=int, help="Integer a")
     leg.add_argument("p", type=int, help="Odd prime p")
 
+    sqrt = subparsers.add_parser("sqrtmod", help="Square root(s) modulo an odd prime")
+    sqrt.add_argument("a", type=int, help="Integer a")
+    sqrt.add_argument("p", type=int, help="Odd prime p")
+
     # Pi
     pi_cmd = subparsers.add_parser("pi", help="Euler/Hermann Machin-like π approximation")
     pi_cmd.add_argument("--terms", type=int, default=100)
@@ -366,6 +475,15 @@ def main():
             if not json_output:
                 print(f"Legendre ({args.a}/{args.p}) = {ls}")
 
+        elif cmd == "sqrtmod" or args.command == "sqrtmod":
+            roots = sqrt_mod(args.a, args.p)
+            result.update({"command": "sqrtmod", "a": args.a, "p": args.p, "roots": list(roots)})
+            if not json_output:
+                if len(roots) == 1:
+                    print(f"sqrt({args.a}) = {roots[0]} (mod {args.p})")
+                else:
+                    print(f"sqrt({args.a}) = +/-{roots[1]} (mod {args.p})")
+
         elif cmd == "pi" or args.command == "pi":
             approx = euler_hermann_pi_approx(args.terms)
             result.update({"command": "pi", "terms": args.terms, "approx": str(approx)})

{foxmath-0.6.2 → foxmath-0.7.1/src/foxmath.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: foxmath
-Version: 0.6.2
+Version: 0.7.1
 Summary: Minimalist CLI for math & cryptography exploration 🦊
 Author-email: Abhrankan Chakrabarti <abhrankan@gmail.com>
 License: MIT
@@ -29,6 +29,7 @@ Built with curiosity — for students, tinkerers, and crypto/math enthusiasts.
 
 ## Features
 - Legendre symbol
+- Modular square root via Tonelli-Shanks (sqrtmod)
 - Euler/Hermann Machin-like π approximation
 - Elliptic curve point addition (over finite fields), including
   named curves (secp256k1) with on-curve result validation
@@ -38,8 +39,8 @@ Built with curiosity — for students, tinkerers, and crypto/math enthusiasts.
 - Continued fraction expansion and convergents
 - Challenge/quiz mode — practice problems with scoring, or a
   worksheet mode for self-study
-- Symlink-friendly (foxmath-legendre, foxmath-pi, foxmath-ecadd,
-  foxmath-ecmul, foxmath-crt, foxmath-cf, foxmath-challenge)
+- Symlink-friendly (foxmath-legendre, foxmath-sqrtmod, foxmath-pi,
+  foxmath-ecadd, foxmath-ecmul, foxmath-crt, foxmath-cf, foxmath-challenge)
 - JSON output mode
 
 ## Installation
@@ -60,7 +61,7 @@ Check which version you have installed:
 foxmath --version
 ```
 ```
-foxmath 0.6.2
+foxmath 0.7.1
 ```
 
 ## Usage Examples
@@ -79,6 +80,17 @@ foxmath legendre 5 17
 Legendre (5/17) = -1
 ```
 
+```bash
+foxmath sqrtmod 10 13
+```
+```
+sqrt(10) = +/-7 (mod 13)
+```
+
+`sqrtmod` uses the Tonelli-Shanks algorithm to find modular square roots
+when they exist. It reports an error when the input is a quadratic
+non-residue modulo the given odd prime.
+
 ```bash
 # Symlinks (optional)
 foxmath-ecadd --x1 1 --y1 2 --x2 3 --y2 4 --p 17

{foxmath-0.6.2 → foxmath-0.7.1}/src/foxmath.egg-info/entry_points.txt

@@ -7,3 +7,4 @@ foxmath-ecadd = foxmath.foxmath:main
 foxmath-ecmul = foxmath.foxmath:main
 foxmath-legendre = foxmath.foxmath:main
 foxmath-pi = foxmath.foxmath:main
+foxmath-sqrtmod = foxmath.foxmath:main

{foxmath-0.6.2 → foxmath-0.7.1}/tests/test_cli.py

@@ -16,7 +16,7 @@ SCRIPT = os.path.join(ROOT, "foxmath.py")
 def run(*args, script=SCRIPT, stdin_input=None):
     result = subprocess.run(
         [sys.executable, script, *args],
-        capture_output=True, text=True, timeout=15, input=stdin_input,
+        capture_output=True, text=True, encoding="utf-8", timeout=15, input=stdin_input,
     )
     return result.returncode, result.stdout, result.stderr
 
@@ -38,6 +38,16 @@ class TestJsonFlag(unittest.TestCase):
         self.assertEqual(code, 0)
         self.assertNotIn("{", out)
 
+    def test_sqrtmod(self):
+        code, out, err = run("sqrtmod", "10", "13")
+        self.assertEqual(code, 0)
+        self.assertIn("sqrt(10) = +/-7 (mod 13)", out)
+
+    def test_sqrtmod_json(self):
+        code, out, err = run("sqrtmod", "10", "13", "--json")
+        self.assertEqual(code, 0)
+        self.assertIn('"roots": [', out)
+
     def test_json_output_is_pure_json_no_preamble(self):
         # Regression check: --json used to still print the human-readable
         # line first, breaking anything piping stdout into a JSON parser.
@@ -66,6 +76,12 @@ class TestSymlinkInvocation(unittest.TestCase):
         self.assertEqual(code, 0)
         self.assertIn("Legendre (2/7) = 1", out)
 
+    def test_sqrtmod_symlink(self):
+        script = self._make_symlink_script("foxmath-sqrtmod")
+        code, out, err = run("10", "13", script=script)
+        self.assertEqual(code, 0)
+        self.assertIn("sqrt(10) = +/-7 (mod 13)", out)
+
     def test_pi_symlink(self):
         script = self._make_symlink_script("foxmath-pi")
         code, out, err = run("--terms", "10", script=script)
@@ -275,6 +291,26 @@ class TestNormalUsage(unittest.TestCase):
         self.assertEqual(code, 1)
         self.assertIn("Error", err)
 
+    def test_sqrtmod_non_residue_errors(self):
+        code, out, err = run("sqrtmod", "5", "17")
+        self.assertEqual(code, 1)
+        self.assertIn("no square root", err)
+
+    def test_sqrtmod_zero(self):
+        code, out, err = run("sqrtmod", "0", "17")
+        self.assertEqual(code, 0)
+        self.assertIn("sqrt(0) = 0 (mod 17)", out)
+
+    def test_legendre_composite_p_errors(self):
+        code, out, err = run("legendre", "2", "9")
+        self.assertEqual(code, 1)
+        self.assertIn("p must be an odd prime", err)
+
+    def test_sqrtmod_composite_p_errors(self):
+        code, out, err = run("sqrtmod", "2", "9")
+        self.assertEqual(code, 1)
+        self.assertIn("p must be an odd prime", err)
+
 
 if __name__ == "__main__":
     unittest.main()

{foxmath-0.6.2 → foxmath-0.7.1}/tests/test_foxmath.py

@@ -13,9 +13,9 @@ from decimal import Decimal
 sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "src")))
 
 from foxmath.foxmath import (
-    legendre_symbol, euler_hermann_pi_approx, ec_point_add, ec_mul, crt_solve,
+    legendre_symbol, sqrt_mod, euler_hermann_pi_approx, ec_point_add, ec_mul, crt_solve,
     continued_fraction, cf_convergents, CURVES, is_on_curve,
-    generate_problem,
+    generate_problem, _is_probable_prime,
 )
 import random
 
@@ -51,6 +51,80 @@ class TestLegendreSymbol(unittest.TestCase):
         with self.assertRaises(ValueError):
             legendre_symbol(3, 1)
 
+    def test_rejects_composite_odd_p(self):
+        for comp in (9, 15, 21, 25, 27, 33, 35, 561):
+            with self.subTest(p=comp):
+                with self.assertRaises(ValueError):
+                    legendre_symbol(2, comp)
+
+
+class TestSqrtMod(unittest.TestCase):
+    def test_tonelli_shanks_returns_both_roots(self):
+        roots = sqrt_mod(10, 13)
+        self.assertEqual(roots, (6, 7))
+        self.assertTrue(all((root * root - 10) % 13 == 0 for root in roots))
+
+    def test_fast_path_for_prime_three_mod_four(self):
+        self.assertEqual(sqrt_mod(9, 11), (3, 8))
+
+    def test_zero_has_one_root(self):
+        self.assertEqual(sqrt_mod(0, 17), (0,))
+
+    def test_rejects_non_residue(self):
+        with self.assertRaises(ValueError):
+            sqrt_mod(5, 17)
+
+    def test_rejects_even_p(self):
+        with self.assertRaises(ValueError):
+            sqrt_mod(1, 2)
+
+    def test_rejects_p_less_than_2(self):
+        with self.assertRaises(ValueError):
+            sqrt_mod(1, 1)
+        with self.assertRaises(ValueError):
+            sqrt_mod(1, -5)
+
+    def test_normalizes_a_greater_than_p(self):
+        self.assertEqual(sqrt_mod(10 + 26, 13), (6, 7))
+
+    def test_negative_a(self):
+        self.assertEqual(sqrt_mod(-3, 13), (6, 7))
+
+    def test_larger_primes_tonelli_shanks(self):
+        roots_41 = sqrt_mod(8, 41)
+        self.assertEqual(roots_41, (7, 34))
+        self.assertTrue(all((r * r - 8) % 41 == 0 for r in roots_41))
+
+        roots_97 = sqrt_mod(2, 97)
+        self.assertEqual(roots_97, (14, 83))
+        self.assertTrue(all((r * r - 2) % 97 == 0 for r in roots_97))
+
+    def test_rejects_composite_odd_p(self):
+        for comp in (9, 15, 25, 561):
+            with self.subTest(p=comp):
+                with self.assertRaises(ValueError):
+                    sqrt_mod(4, comp)
+
+
+class TestPrimality(unittest.TestCase):
+    def test_small_primes(self):
+        for p in (2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 97, 193):
+            with self.subTest(p=p):
+                self.assertTrue(_is_probable_prime(p))
+
+    def test_small_composites(self):
+        for c in (0, 1, 4, 6, 8, 9, 10, 12, 14, 15, 16, 18, 20, 21, 25, 27):
+            with self.subTest(c=c):
+                self.assertFalse(_is_probable_prime(c))
+
+    def test_carmichael_numbers_rejected(self):
+        for cn in (561, 1105, 1729):
+            with self.subTest(cn=cn):
+                self.assertFalse(_is_probable_prime(cn))
+
+    def test_mersenne_prime(self):
+        self.assertTrue(_is_probable_prime(2147483647))
+
 
 class TestEulerHermannPiApprox(unittest.TestCase):
     def test_converges_to_pi(self):