Add Fast Walsh-Hadamard Transform (FWHT) for bitwise convolutions

[Clear20-22]

Summary of Changes

• Added maths/fast_walsh_hadamard_transform.py implementing the Fast Walsh-Hadamard Transform (FWHT) and inverse transforms.
• Implemented bitwise XOR, AND, and OR convolutions in $\mathcal{O}(N \log N)$ time complexity.
• Added comprehensive type hints and doctests testing both valid inputs and error conditions (ValueError for non-power-of-two lengths and mismatched inputs).
• All tests pass with pytest, ruff check, and mypy.

References

• https://en.wikipedia.org/wiki/Fast_Walsh%E2%80%93Hadamard_transform
• https://cp-algorithms.com/algebra/walsh-hadamard-transform.html

Checklist

• I have read the CONTRIBUTING.md guidelines.
• This pull request is all my own work.
• All functions include doctests and type annotations.
• All doctests and tests pass locally.

[Copilot]

Pull request overview

This PR introduces a Fast Walsh–Hadamard Transform (FWHT) implementation to support fast bitwise (XOR/OR/AND) convolutions in the maths module, enabling (\mathcal{O}(N \log N)) convolution for power-of-two sized inputs.

Changes:

• Added FWHT XOR/OR/AND forward and inverse transforms.
• Added XOR/OR/AND convolution helpers built on the transforms.
• Included doctest examples for core behavior and some error cases.

Suppressed comments (1)

maths/fast_walsh_hadamard_transform.py:152

• fwht_and raises ValueError for empty input (length 0), but unlike fwht_xor this edge case isn't exercised by a doctest in the docstring. Adding an explicit fwht_and([]) doctest would improve coverage for error handling.

    >>> fwht_and([1, 2, 3])
    Traceback (most recent call last):
        ...
    ValueError: Length of sequence must be a positive power of 2.
    """

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

maths/fast_walsh_hadamard_transform.py:8

• The module docstring says this works on "numeric" sequences, but the public API is annotated as list[int] and fwht_xor(..., inverse=True) relies on integer-only operations (% divisibility check and // scaling). This mismatch is likely to confuse users and can break when passing floats/decimals.

This issue also appears on line 14 of the same file.

Computes bitwise XOR, AND, and OR convolutions of two numeric sequences in O(N log N)
time, where N is a positive power of 2.

maths/fast_walsh_hadamard_transform.py:16

• fwht_xor(..., inverse=True) currently performs integer division and requires exact divisibility by N. The docstring doesn’t mention this constraint, which makes the inverse behavior easy to misinterpret as a general numeric inverse transform.

    Perform Fast Walsh-Hadamard Transform (or inverse) for XOR operation.

    Time Complexity: O(N log N)

[priya-sundaram-dev]

Reviewed as part of the maths/ triage (#15081). Recommendation: ready to merge.

Verified locally:

• All 17 doctests pass.
• Randomized cross-check against a brute-force O(N²) reference: 3,000 cases per operation (XOR / AND / OR), sizes N ∈ {1,2,4,8,16}, values in [-9, 9] — every *_convolution output matches exactly. Zero mismatches.

Nicely done and consistent with repo style: no type-hint gaps, clear names (half_block, block_start), power-of-2 guard via n & (n-1), and the inverse-XOR divisibility guard is a thoughtful touch with a doctested error path. The XOR / AND / OR variants are cleanly separated with their own transforms and convolutions.

No functional issues found — 👍 from me.