♻️ Define target compilation with payload specifications

[burgholzer]

🤖 AI text below 🤖

Lead: @simon1hofmann. Cross-repository coordination: @burgholzer.

Description

Keep the compiler-only selected-program capability prototype independent of QDMI runtime adoption. Typed metadata and a cached target-environment analysis connect target selection to compilation without requiring unreleased QDMI APIs.

Compiler workstream: main → #2219 → #2162. QDMI adaptation remains the separate integration PR #2227. This compiler-only work targets Core 4.0, subject to Simon's compiler contract review and current CI. It does not require QDMI 1.4 or approval of the later QDMI metadata contract. #2131 tracks compiler requirements; #2365 coordinates the separate Core 4.1/QDMI 1.4 adaptation.

Retain the compiler behavior already released onto main through #2218/#2323/#2215: unknown topology or gate sets fail during inference, variadic controlled DDSIM gates and zero-arity global phase remain supported, and placement/decomposition retain their validated target. No driver replacement, batching or metadata cleanup is included.

Local validation

• Independent release build and CTest: 3,879 passed, one existing optional-device skip.
• Targeted Python compiler/QDMI tests: 558 passed.
• Stub generation, repository lint and full changed-file C++ lint passed.
• Hosted CI must be checked separately on this final head.

AI-assisted restructuring; human design review remains required.

Compiler contract review

Model the capabilities of the selected program/target combination rather than assuming a format's full language is executable. Keep the initial feature vocabulary bounded and informed by OpenQASM and QIR. Validate representative benchmark targets without requiring a QDMI 1.4 device. The later QDMI adapter may expose only a subset until its independent contract is ready.

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 93.11295% with 25 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
mlir/tools/mqt-cc/mqt-cc.cpp	76.7%	13 Missing ⚠️
mlir/lib/Compiler/TargetEnvironment.cpp	93.4%	12 Missing ⚠️

📢 Thoughts on this report? Let us know!

[burgholzer]

This one will likely still need a bit of work to iron out the details.

[coderabbitai]

---

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]

This looks much cleaner now. And should also be ready.

[burgholzer]

@simon1hofmann @denialhaag any feedback on this one from your side?
I looked through this yesterday night already and it looked pretty clean to me.

[simon1hofmann]

@simon1hofmann @denialhaag any feedback on this one from your side? I looked through this yesterday night already and it looked pretty clean to me.

Going through this now and will provide feedback in around 15min.

[simon1hofmann]

Also went through the changes here and they look really clean 👍

[simon1hofmann]

🤖 AI text below 🤖

Rebased onto main at ba3637cd1 and restacked #2162 on top. The review fixes remain in individual commits:

• 8ce67b89f: register the math dialect for runtime target-native synthesis, with a fresh-context regression test.
• 5412f9fba: accept exact version shorthand, with C++, typed-MLIR, and Python regressions. Family/range selection remains separate, as explained in the version thread.
• 9e2339c26: use DDSIM for the executable QIR examples, show 2.1, and document both the attached-environment and inliner prerequisites.
• c78063ca4: align the plan with the compiler-only Core 4.0 scope; the separate QDMI 1.4 adaptation does not gate it.

Local validation on the restacked tree: 253 C++ tests passed (compiler, native synthesis, MQT IR), 55 Python compiler tests and six target-specific Qiskit translation tests passed, and the CLI shorthand output assembled successfully with QIR major/minor flags 2/1. Repository lint passed. Full changed-file C++ lint ran, but the local CLion clang-tidy 23 development build reports three false positives on necessary dereference parentheses. Its suggested edit fails to compile in a minimal reproducer, so those expressions were retained; the genuine trailing-comma finding was fixed. This is not a clean local C++ lint result. The build uses main's exact jeff-mlir dependency pin. Hosted CI is a separate final-head check; these are local results.

The rebase preserves main's reusable-function inlining before #2162's control-flow legalization. The existing loop/switch capability snapshot and safety limits remain intact.

[denialhaag]

Thanks for the continued improvements, @simon1hofmann! 🙂 Overall, this looks pretty good to me. I only have a few remarks:

[denialhaag]

Thanks for addressing all of my comments, @simon1hofmann! I'll leave the final comment open for now, but I'll not die on that hill; you can resolve it whenever we have come to any conclusion. I'm approving for now. Feel free to request another review if there are new changes I can have a look at! 🙂

[simon1hofmann]

Also looks good to me, will leave the final check to @burgholzer before merging.

[burgholzer]

I'll tackle this one next

[burgholzer]

I ran this through another iteration with the goal of simplifying the implementation, which was pretty successful I believe.
I'd vote for getting this in now and looking at the fallout in subsequent audits until the release.