foxmath 0.6.2__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: foxmath
-Version: 0.6.2
+Version: 0.7.0
 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.0
 ```
 
 ## 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.0}/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.0
 ```
 
 ## 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.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "foxmath"
-version = "0.6.2"
+version = "0.7.0"
 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.0}/src/foxmath/foxmath.py

@@ -29,6 +29,54 @@ def legendre_symbol(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 sqrt_mod(a: int, p: int) -> tuple:
+    """Return the square root(s) of a modulo an odd prime p."""
+    if p < 2 or p % 2 == 0:
+        raise ValueError("p must be an odd prime")
+
+    a %= p
+    symbol = legendre_symbol(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_symbol(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 +331,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 +370,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 +429,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.0/src/foxmath.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: foxmath
-Version: 0.6.2
+Version: 0.7.0
 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.0
 ```
 
 ## 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.0}/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.0}/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,16 @@ 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)
+
 
 if __name__ == "__main__":
     unittest.main()

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

@@ -13,7 +13,7 @@ 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,
 )
@@ -52,6 +52,48 @@ class TestLegendreSymbol(unittest.TestCase):
             legendre_symbol(3, 1)
 
 
+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))
+
+
 class TestEulerHermannPiApprox(unittest.TestCase):
     def test_converges_to_pi(self):
         # Regression check: this used to converge to 16*arctan(1/2) =~ 7.418,