✨ Add reusable quantum functions to QC and QCO

[burgholzer]

🤖 AI text below 🤖

Description

Add a frontend-neutral function model for reusable quantum helpers:

• mark unitary func.func definitions with mqt.unitary and represent their calls with qc.call or qco.call;
• expose complete callback-based function and call APIs in both program builders;
• use one positional QCO ABI: ordinary results first, then the updated value of each borrowed scalar qubit argument;
• preserve supported functions and calls across QC/QCO conversion while rejecting representations that would lose information; and
• treat generic func.call operations as local wire-analysis boundaries, avoiding speculative interprocedural mapping and caches.

The deliberately narrow unitary contract covers gate definitions needed by future OpenQASM, Qiskit, and jeff integrations without result annotations, recursive matrix synthesis, or a new function abstraction. This branch is based directly on main and is independent of #2196 and its stack.

Validation

• Full Debug and Release C++ suites: 3,840 passed and one expected skip each.
• uvx nox -s cpp-lint, uvx nox -s lint, and git diff --check passed.
• Doxygen output retains the full documentation for all 90 generated gate methods in each builder, with no new warnings relative to main. The @file summary is retained.
• The latest documentation correction changes no non-comment C++ tokens. Existing trailing Doxygen syntax and inline unused-parameter comments are preserved.

Build and C++ lint validation used #2352's dependency and test-RPATH fixes as a temporary local overlay. That overlay was removed afterward and is not part of this PR; both PRs remain based on main.

Codex assisted with implementation, documentation restoration, and local validation.

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

❌ Patch coverage is 92.42857% with 53 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
mlir/lib/Dialect/QCO/Builder/QCOProgramBuilder.cpp	86.5%	17 Missing ⚠️
mlir/lib/Conversion/QCOToQC/QCOToQC.cpp	91.8%	10 Missing ⚠️
mlir/lib/Conversion/QCToQCO/QCToQCO.cpp	92.5%	10 Missing ⚠️
mlir/lib/Dialect/MQT/IR/MQTDialect.cpp	93.9%	8 Missing ⚠️
mlir/lib/Dialect/QC/Builder/QCProgramBuilder.cpp	89.8%	7 Missing ⚠️
mlir/lib/Dialect/QC/IR/Operations/CallOp.cpp	96.0%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[burgholzer]

@MatthiasReumann @DRovara I haven't looked through all the details here yet, but this PR may be interesting for the both of you.
Matthias, it addresses some of the concerns that you may have had on the WireIterator call handling.
Damian, this was mostly inspired by the lack of any production user/consumers of the IPO passes and multiple function handling. This triggered me, which eventually led to the implementation here which feels quite nice already and actually rather close to some of the things we also had in the original RFC for the dialect rewrite but never got to so far. I plan to add the respect new capabilities to all the supported formats in follow-up PRs.
This is more so an FYI than a call for action.

[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.}

[DRovara]

Awesome, this looks pretty cool. I like the idea of the unitary marker for unitary functions.

I have to admit I am a bit behind and still haven't fully grasped the idea behind the MQT dialect here (unitary functions aren't necessarily MQT-exclusive), but I also understand just having that as a joint source to avoid duplication.

I have a few minor comments and one major concern regarding the IPO passes, where we will have to think of some solution.

[burgholzer]

Alright, I believe this is as clean as it gets for now. Tagging this for auto-merge so that the other depending PRs can be updated over night.