Add Tonelli-Shanks algorithm for modular square roots

[felipeofdev-ai]

Describe your change:

• Add an algorithm?
• Fix a bug or typo in an existing algorithm?
• Add or change doctests?
• Documentation change?

Checklist:

• I have read CONTRIBUTING.md.
• This pull request is all my own work -- I have not plagiarized.
• I know that pull requests will not be merged if they fail the automated tests.
• This PR only changes one algorithm file.
• All new Python files are placed inside an existing directory.
• All filenames are in all lowercase characters with no spaces or dashes.
• All functions and variable names follow Python naming conventions.
• All function parameters and return values are annotated with Python type hints.
• All functions have doctests that pass the automated testing.
• All new algorithms include at least one URL that points to Wikipedia or another similar explanation.
• If this pull request resolves one or more open issues then the description above includes the issue number(s) with a closing keyword.

Summary

Adds maths/tonelli_shanks.py implementing the Tonelli-Shanks algorithm to compute modular square roots modulo an odd prime.

• Includes legendre_symbol for quadratic-residue checks
• Fast path when prime ≡ 3 (mod 4)
• Full Tonelli-Shanks loop when prime ≡ 1 (mod 4)
• Returns the smaller non-negative root; raises ValueError for non-residues / invalid primes
• Doctests cover both residue classes, zero, and error cases (verified locally via python -m doctest)

Reference: https://en.wikipedia.org/wiki/Tonelli%E2%80%93Shanks_algorithm

— Felipe Fernandes · Systems & Agentic AI Engineer
https://github.com/felipeofdev-ai · https://felipeofdev-ai.github.io/

[felipeofdev-ai]

Thanks for reviewing — CI is green on my side. Happy to adjust anything you need.

— Felipe Fernandes · Systems & Agentic AI Engineer
https://github.com/felipeofdev-ai · https://felipeofdev-ai.github.io/