Add modulus parameter to ModularAdderGate (API only, synthesis follow-up) < Issue: Modular Arithmetic Libraries #13608

[janrockdev]

Implements the modulus half of the API ShellyGarion proposed in #13608 (comment)

ModularAdderGate(num_state_qubits, label=None, modulus=None), when modulus is None (the default) or equals 2**num_state_qubits, behaviour is byte-for-byte identical to before this PR. A smaller modulus is accepted and validated, but has no synthesis method yet: requesting its definition, or synthesizing it through HighLevelSynthesis, raises/declines rather than producing an incorrect circuit. The four existing ModularAdder plugins (V17, C04, V95, D00) are updated to explicitly decline non-default moduli.

adder_modular_s21 (the ancilla-free arbitrary-modulus synthesis method named in the same comment) is deliberately not part of this PR. arXiv:2112.10537 (Seidel et al.), which the name refers to, only formulates arithmetic modulo 2**n (semi-boolean polynomials over Z/2^nZ) — it does not contain a construction for an arbitrary modulus. An ancilla-free, register-register adder for arbitrary N is a real derivation rather than a transcription, so I'm following up with that separately rather than rushing an unverified circuit into this PR.

Testing

• New unit tests for modulus validation, default-equivalence, the not-yet-synthesizable error path, and the plugin guards.
• Full existing adder test module passes unmodified (55 tests).
• test_high_level_synthesis.py, test_arithmetic_counts.py, test_gate_definitions.py all pass unchanged (433 tests).
• black / ruff clean.

Part of #13608.

AI/LLM disclosure

• No part of this submission is LLM generated.
• Some written text was generated by:
• Some submitted code was generated by:

[qiskit-bot]

Thank you for opening a new pull request.

Before your PR can be merged it will first need to pass continuous integration tests and be reviewed. Sometimes the review process can be slow, so please be patient.

While you're waiting, please feel free to review other open PRs. While only a subset of people are authorized to approve pull requests for merging, everyone is encouraged to review open pull requests. Doing reviews helps reduce the burden on the core team and helps make the project's code better for everyone.

One or more of the following people are relevant to this code:

• @Cryoris
• @Qiskit/terra-core
• @ajavadia

[CLAassistant]

All committers have signed the CLA.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}