Add IQPE benchmark

[kpassito]

Description

This PR adds an iqpe benchmark for Iterative Quantum Phase Estimation.

The circuit uses one reusable measurement qubit and num_qubits - 1 target qubits. The num_bits parameter controls the number of measured phase bits.

Fixes #797

Tests

I added coverage for the IQPE circuit structure, invalid parameters, num_bits scaling, num_qubits scaling, and invalid qubit counts.

Local checks:

• python -m pytest -o addopts='' tests/test_bench.py: 203 passed
• ruff check src/mqt/bench/benchmarks/iqpe.py tests/test_bench.py: passed
• ruff format --check src/mqt/bench/benchmarks/iqpe.py tests/test_bench.py: passed
• git diff --check: passed

AI disclosure

Codex assisted with implementation and local testing. I reviewed the changes and take responsibility for the submitted code.

The commits include the required footer:

Assisted-by: GPT-5 Codex via Codex

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.
• I have added entries to the changelog for any noteworthy additions, changes, fixes, or removals.
• I have added migration instructions to the upgrade guide (if needed).
• 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:

• I have disclosed the use of AI tools in the PR description.
• AI-assisted commits include an Assisted-by: [Model Name] via [Tool Name] footer.
• I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[flowerthrower]

Dear @kpassito, thanks for the initial draft. Currently this looks like heavily AI generated. Please review our AI guidelines. I left a first quick review that you might want to address personally.

[flowerthrower]

why constrain to 2 qubits only? should be possible for larger sizes too

[flowerthrower]

this should not be the dynamic size of the benchmark (it should be num_qubits)

[kpassito]

Thanks @flowerthrower, I went through the PR again and addressed the review points.

I removed the extra benchmark selection docs section, updated iqpe so num_qubits controls the circuit width, and fixed the changelog entry with the PR number and author.

I also reran the local checks listed in the PR description.

[flowerthrower]

Dear @kpassito, thank you for your continued efforts. Please give us some time to review. We are currently internally discussing the best way forward for this Benchmark.

[flowerthrower]

Dear @kpassito, thank you for your patience. We have now reached an internal agreement on the best approach to this benchmark. We have decided that we want to make this benchmark equivalent to the already implemented qpe variants after all. This does mean that num_qubits should remain a parameter limited to 2 qubits (for now) - sorry for the back-and-forth; ideally, that could have been avoided with a short discussion prior to implementation, as suggested in the original issue description. The result accuracy scales with num_bits, and the equivalence/trade-off between circuit width (normal qpe) and circuit depth (iterative version) should be highlighted in the benchmark description.