[burgholzer]

🤖 AI text below 🤖

Description

Add W-state preparation to the existing C++, Python, and CLI benchmark interfaces. The generator keeps its controlled-RY/CX sweep in structured loops and computes each rotation angle inside the loop. The DD interpreter uses MLIR's existing constant folder to evaluate acos; no angle table is needed. Evaluation reuses the existing probability and counts APIs: each single-excitation outcome has ideal probability 1/n.

Based directly on current upstream main. This PR contains only the W-state addition, with no RTTI, exception-handling, or shared budget changes. Main already supports the counted loops used here; no changes from #2605 or dependency on #2545 are needed.

The 1,024-qubit regression checks jeff serialization, reload, and amplitudes through the existing DD simulator without dense extraction. Documentation includes executable 3- and 256-qubit examples.

Validation:

• Optimized native build; 65 benchmark, 33 generation, and 200 QCO utility tests; benchmark CLI CTest.
• 228 focused Python tests and regenerated stubs.
• Full-file C++ lint against main, repository lint, and complete executable documentation with local link checks.

Codex assisted implementation, rebasing, validation, 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 94.44444% with 5 lines in your changes missing coverage. Please review.

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

📢 Thoughts on this report? Let us know!

[burgholzer]

@denialhaag This feels pretty straight-forward and a nice addition to the benchmarks. Also contains a bit of runtime math, which the entire toolchain can now handle 🙌🏼
I'll investigate whether we can drop the phase tables in a couple more of the algorithms to simplify the overall algorithm descriptions. Will file a follow up issue.

[denialhaag]

Some high-level feedback:

[denialhaag]