[SnehalRaj]

This PR addresses #79 and follows the discussion in #47. It reduces modular register addition and subtraction from 2n−2 to 2n−3 Toffolis for n≥2. The constant wrappers inherit the saving.

Cuccaro, Draper, Kutin, and Moulton describe the reference algorithm in A new quantum ripple-carry addition circuit (2004), Section 4.1 and Table 1, arXiv:quant-ph/0410184. They add the lower n−1 bits, write the carry into the highest sum bit, and complete that bit with a CNOT. They give the 2n−3 Toffoli count for n≥3. Section 3, improvement 5, explains the direct carry calculation.

The existing circuit computes the last required carry into an operand bit, copies it into the sum, and then uncomputes it. For four distinct wires, the local replacement is:

# Before
x.ctrl(u, v, w)
cx(w, t)
x.ctrl(u, v, w)

# After
cx(w, t)
x.ctrl(u, v, t)

Both sequences leave w unchanged and map t to t XOR w XOR (u AND v). After commuting the top-bit CNOT past this sequence, the replacement saves one Toffoli.

In _arithmetic.py, the ordinary carry sweep stops one position earlier. subtract_register reverses every gate explicitly. The one-bit case remains a CNOT; the two-bit case uses one Toffoli and two CNOTs. The docstrings state the new costs and the operand contracts: equal-width, disjoint little-endian registers, a clean carry on entry, and restoration on exit.

The surrounding documentation changes keep the agent references consistent with the implementation:

• skills/cudaq-algorithms/references/primitives/primitives-arithmetic.md: update the formulas and carry explanation. Fix the test selector to include the renamed register resource tests and the constant resource tests.
• skills/cudaq-algorithms/references/primitives/primitives.md: update the arithmetic cost summary.
• skills/cudaq-algorithms/references/conventions/resource-levels.md: update the logical Toffoli formulas while preserving the distinction from synthesized T-gate and hardware costs.

In tests/python/test_primitives_arithmetic.py:

• Retain the fixed-b, superposed-a correctness tests at widths 1–5.
• Retain the exhaustive small-width constant tests, including workspace cleanup, and the existing inverse checks.
• Add seeded complex-input tests against independent classical arithmetic permutations.
• Add superposed-control tests against independent expected states.
• Compare full statevectors to check the arithmetic result, preservation of a, clean workspace, and relative phase.
• Assert 0, 1, 3, 5, 13, 509 logical Toffolis at widths 1, 2, 3, 4, 8, and 256 for both directions and constant wrappers.
• Check CNOT and allocated-qubit counts. Reuse one resource estimate per case and remove the redundant slope test.

The 256-bit cases use resource estimation only.

Local validation on CUDA-Q 0.16.0, qpp-cpu, fp64:

PYTHONPATH=python CUDAQ_DEFAULT_SIMULATOR=qpp-cpu \
python -m pytest tests/python/test_primitives_arithmetic.py \
  tests/python/test_primitives_composition.py -q

• 133 passed, no skips, with one CUDA-Q API FutureWarning.
• The corrected reference command passed 40 tests, including all 24 register and constant resource cases.
• Skill routing and packaging tests passed 768 tests and 3 subtests.
• YAPF 0.43.0 and git diff --check passed.

Full CI remains pending maintainer approval. The broader local suite has no completed result. Two failures reproduce on unchanged upstream code: a numerical comparison in double factorization and an example that requires the missing qsppack package. The remaining failures still need investigation.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.