feat(math, perfect squares): least number pefect squares that sum to n

[BrianLusina]

Describe your change:

Find least number of perfect squares that sum up to n

• Add an algorithm?
• Fix a bug or typo in an existing algorithm?
• 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. To ease review, please open separate PRs for separate algorithms.
• 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 have a URL in its comments that points to Wikipedia or other similar explanation.
• If this pull request resolves one or more open issues then the commit message contains Fixes: #{$ISSUE_NO}.

Summary by CodeRabbit

• New Features

  • Added typed perfect-square helpers and two methods to compute the minimum number of perfect squares for a given n.

• Documentation

  • Added a comprehensive README explaining the Perfect Squares problem, mathematical approach, and complexity notes.

• Tests

  • Added parameterized unit tests covering multiple cases for both implementations.

• Style

  • Reformatted import statements for consistency.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

Adds a perfect-squares module (two implementations: DP and number-theory reduction), README and parameterized tests; plus a non-functional import reformat in an unrelated binary search test.

Changes

Cohort / File(s)	Summary
Import formatting algorithms/search/binary_search/divide_chocolate/test_divide_chocolate.py	Reformatted a test import to a parenthesized multi-line form; no behavioral change.
Documentation pymath/perfect_square/README.md	Added detailed README explaining the Perfect Squares problem, algorithm approaches (Four-/Three-Square theorems), and complexity notes.
Core implementation pymath/perfect_square/__init__.py	Added type annotation to is_square; introduced is_perfect_square(n: int) -> bool, num_squares(n: int) -> int (DP), and num_squares_2(n: int) -> int (mathematical reduction).
Tests pymath/perfect_square/test_perfect_squares.py	New parameterized unittest module exercising num_squares() and num_squares_2() across multiple cases (note: a stray token in one assertion may need fix).

Sequence Diagram(s)

(omitted — changes do not introduce multi-component sequential interactions warranting a diagram)

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• feat(math, perfect squares): least number pefect squares that sum to n #127: Adds the same perfect-squares functions, tests, and README updates — strong overlap.
• feat(algorithms, binary-search): divide chocolate #126: Modifies the same divide_chocolate test import formatting also changed here.

Poem

🐰 I hop through squares both small and great,
Counting sums that numbers make.
DP paws, theorems trace the way,
Three or four — I skip and play.
Docs and tests, a cozy crate.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title describes the main feature added: finding the least number of perfect squares that sum to n, which aligns with the primary changes in the changeset.
Description check	✅ Passed	The PR description follows the template structure, includes all required sections, and all checklist items are addressed with appropriate selections.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 03003e8 and cf998dc.

📒 Files selected for processing (3)

• pymath/perfect_square/README.md
• pymath/perfect_square/__init__.py
• pymath/perfect_square/test_perfect_squares.py

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 5

🧹 Nitpick comments (2)

pymath/perfect_square/README.md (1)

22-22: Fix mathematical notation formatting.

The expression 4^a(8b+7) is ambiguous. It should be written as 4^a * (8b+7) or 4^a(8b+7) with clearer formatting to indicate multiplication between the power of 4 and the term (8b+7).

🔎 Proposed fix

-three squares, and these are exactly the numbers that look like 4^a(8b+7) That means, if a number (after dividing out
+three squares, and these are exactly the numbers that look like 4^a * (8b+7). That means, if a number (after dividing out

pymath/perfect_square/test_perfect_squares.py (1)

6-12: Add edge case tests and expand coverage.

The current test cases are valid but miss important edge cases:

1. n = 0 (if supported): Should return 0
2. n = 2: Requires 2 squares (1+1)
3. Larger values: Consider testing with values closer to the constraint boundary (near 10³)
4. Perfect squares: Additional cases like n=4, n=9, n=16 to verify they return 1

🔎 Suggested additional test cases

 TEST_CASES = [
     (1, 1),
+    (2, 2),
+    (4, 1),
+    (9, 1),
     (12, 3),
     (13, 2),
     (23, 4),
+    (100, 1),
     (997, 2),
 ]

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ce7438e and f9d1ab9.

📒 Files selected for processing (4)

• algorithms/search/binary_search/divide_chocolate/test_divide_chocolate.py
• pymath/perfect_square/README.md
• pymath/perfect_square/__init__.py
• pymath/perfect_square/test_perfect_squares.py

🧰 Additional context used

🧬 Code graph analysis (1)

pymath/perfect_square/test_perfect_squares.py (1)

pymath/perfect_square/__init__.py (1)

• num_squares (32-49)

🪛 LanguageTool

pymath/perfect_square/README.md

[style] ~22-~22: Consider an alternative for the overused word “exactly”.
Context: ...he sum of three squares, and these are exactly the numbers that look like 4^a(8b+7) Th...

(EXACTLY_PRECISELY)

🔇 Additional comments (6)

algorithms/search/binary_search/divide_chocolate/test_divide_chocolate.py (1)

4-7: Import reformatting looks good.

The multi-line parenthesized import format follows PEP 8 conventions and improves readability without affecting functionality or test behavior.

pymath/perfect_square/README.md (1)

1-51: Well-documented algorithm with clear explanation.

The documentation provides excellent coverage of the problem, mathematical foundations (Four-Square and Three-Square theorems), algorithm steps, and complexity analysis. This will help maintainers understand the mathematical approach.

pymath/perfect_square/__init__.py (3)

4-15: LGTM: Type hints and docstring added.

The function correctly checks for perfect squares with proper negative input handling. The type annotations and documentation improve code clarity.

---

40-47: Algorithm implementation is correct.

The dynamic programming approach correctly implements the recurrence relation: for each number i, it tries all perfect squares j² ≤ i and takes the minimum. The time complexity O(n√n) and space complexity O(n) are appropriate for this approach.

---

60-77: Algorithm correctly implements mathematical theorems.

The step-by-step approach based on Four-Square and Three-Square theorems is correctly implemented:

• Factor-of-4 reduction maintains the answer while simplifying computation
• The 8k+7 check correctly identifies numbers requiring 4 squares
• The perfect square and two-square checks follow the logical elimination process

Time complexity is O(√n) which is significantly better than the DP approach.

pymath/perfect_square/test_perfect_squares.py (1)

15-19: Test structure is well-organized.

The use of parameterized tests makes it easy to add new test cases and keeps the test code DRY. The test method correctly validates the expected output against the actual result.