[burgholzer]

🤖 AI text below 🤖

Description

Add semiclassical Shor order finding with reusable controlled modular arithmetic and a C++/Python factoring driver. shor.factor(21, run) generates order-finding circuits, verifies measured phases using exact continued fractions and gcds, retries bases when needed, and returns (3, 7). The callback controls compilation, device selection, shots, and execution seeds.

The benchmark accepts odd moduli up to 2**31 - 1, uses 2n+3 qubits and 2n phase bits in result, and uses exact Fourier arithmetic. Generation builds polynomial-size arithmetic tables without computing the order classically. The factoring driver handles even numbers, primes, and perfect powers without quantum execution. The README and walkthrough run the same factoring-21 example through Adaptive QIR and OpenQASM 3.

Raise QC import and payload-unrolling budgets to one billion operations, OpenQASM statement budgets to 100 million, and the DD conditional-loop budget to one billion iterations. The unrolling pass and native DD API expose budget overrides. Counted loops and total simulated gates remain uncapped; nesting, integer-width, and memory-safety checks remain separate. Mapped OpenQASM specializes physical-qubit indices; Adaptive QIR can retain indexed loops.

Fourier arithmetic is shared with the existing modular-multiplier benchmark. The benchmark uses the compiler contracts merged in #2546. Registry, JSON/CLI interfaces, Python bindings, generated stubs, and executable documentation are included.

Validation:

• Optimized Clang 23/ThinLTO native build and 3,602 native tests passed, with one expected Slurm skip.
• 118 Python benchmark and QDMI compilation tests passed; both DDSIM payload formats factor 15 and 21.
• Imported and verified a flat 20,000,001-gate OpenQASM program and simulated 20,000,001 counted-loop gates on a single qubit with the expected result. Budget-boundary tests use small explicit limits and cover cumulative cloning and overflow rejection.
• Arithmetic tests cover small valid basis inputs, coherent superpositions, inverse composition, and workspace cleanup. The native sampled-distribution check uses 15 to keep unoptimized coverage builds small; QIR/OpenQASM integration tests factor 15 and 21. Larger simulations remain separate timing measurements. The 31-bit case compiles to Adaptive QIR without simulating its 65-qubit state.
• Stub generation, whole-file C++ lint, executable documentation, and rendered-link checks passed. Repository lint passes except for 28 pre-existing diagnostics in unrelated untracked audit scripts; the pinned type checker passes with those scripts excluded.
• Completed one full Ponytail complexity review and addressed all three findings: removed stored phase-helper state, a redundant control-count branch, and a duplicate result lookup. Multiplication retains jeff compatibility.

The 31-bit input bound is a representation limit, not a simulation-capacity promise. Large programs still require sufficient memory and execution time.

Simulation execution times (64 shots, median of three runs on one DGX Spark
Cortex-X925 core on the shared host; native Clang 23/ThinLTO DDSIM, including
import/JIT, excluding compilation):

N	Qubits	Direct QCO DD	QIR via QDMI	OpenQASM via QDMI
15	11	0.697 s	0.306 s	0.253 s
21	13	2.875 s	1.976 s	2.317 s
35	15	17.185 s	11.660 s	20.656 s

Codex assisted with implementation, tests, documentation, and this description.

Checklist

• The pull request only contains commits that are focused and relevant to this change.
• I have added appropriate tests that cover the new/changed functionality.
• I have updated the documentation to reflect these changes.
• The changes follow the project's style guidelines and introduce no new warnings.
• The changes are fully tested and pass the CI checks.
• I have reviewed my own code changes.

If PR contains AI-assisted content:

• Any agent that created, edited, or submitted GitHub content was explicitly authorized for that scope, as required by our AI Usage Guidelines.
• Every agent-authored or agent-edited public text body begins with the visible disclosure 🤖 *AI text below* 🤖 (titles are exempt).
• I have disclosed AI assistance in the PR description.
• I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.

[codecov]

Codecov Report

❌ Patch coverage is 96.66667% with 12 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/bench/JSON.cpp	70.7%	12 Missing ⚠️

📢 Thoughts on this report? Let us know!

[burgholzer]

@denialhaag this is pretty cool in my opinion and an even better showcase example than QPE.
I walked through the code already and it looked pretty reasonable to me. Looking for a second opinion here. Feel free to push changes as you please, and if you are happy, merge afterwards.

[denialhaag]

Some high-level feedback:

[denialhaag]