✨ Add inspection methods to QCProgram

[denialhaag]

Description

🤖 AI text below 🤖

This PR adds inspection methods to QCProgram that are all exposed to Python.

We need the functionality of counting two-qubit gates to benchmark mqt-cc against other compilers in ucc-bench.

The methods count static gate occurrences in the entry-point IR. They count gates in each structured control-flow region once, regardless of how often the region executes. Operations within gate modifiers are not counted recursively, and barriers are skipped.

AI notice

This PR and its contents were created with the assistance of Opus 5 via Claude Code and GPT-5.6 Sol 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:

• 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

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[denialhaag]

While working on this, I noticed that we have QCProgram.from_qasm_str(), QCProgram.from_qasm_file(), and QCProgram.to_openqasm3(). We should probably align those a bit.

[burgholzer]

Just one fairly general observation while looking at this.

[burgholzer]

Follow-up thought from above: we likely also want further convenience functions for the programs

• single-qubit gates
• gates
• depth (?)
• gate counts (like Qiskit's operation dictionary that carries the frequency of particular operations)

For straight-line programs, these are easy to compute. As soon as SCF is involved, it becomes much harder. Especially with loops. Should still be possible though.
The gate dictionary is a bit tough, because of how one handles/tracks modifiers.

[denialhaag]

Follow-up thought from above: we likely also want further convenience functions for the programs

• single-qubit gates
• gates
• depth (?)
• gate counts (like Qiskit's operation dictionary that carries the frequency of particular operations)

For straight-line programs, these are easy to compute. As soon as SCF is involved, it becomes much harder. Especially with loops. Should still be possible though.
The gate dictionary is a bit tough, because of how one handles/tracks modifiers.

Good points! Progress:

• Handle SCF operations
• Number of gates
• Number of single-qubit gates
• Depth (postponed to #2260)
• Gate counts (postponed to #2260)

[denialhaag]

🤖 AI text below 🤖

The gate-counting methods report static gate counts for the entry-point IR. They count gates in every SCF region once: both branches of scf.if, every scf.index_switch case, and all regions of scf.for and scf.while, regardless of the runtime path or iteration count. This matches static instruction counting in classical compilers. A dynamic gate count depends on runtime branches and loop iterations, so it would be a separate resource-estimation metric based on known bounds, runtime inputs, or profile data.

[denialhaag]

@burgholzer, apart from the missing changelog entry, this should be ready now. I postponed the other two methods to a follow-up PR in case they require some more iteration.

To save CI resources, I'm intentionally leaving the PR as a draft until we actually want to merge it.

[coderabbitai]

Important

Approval pending

CodeRabbit has no unresolved comments, but it has not reviewed the latest commit.

Use the checkbox below to review the latest commit. CodeRabbit will approve the changes if it finds no blocking issues.

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[burgholzer]

Pushed two simplification commits. Otherwise I think this can go in!
A thought that came to mind, but is not important for this PR is that we likely want to also introduce such functionality for QCO to inform some passes with quality metrics. That's a future topic though.