✨ Preserve classical control through target mapping

[simon1hofmann]

🤖 AI text below 🤖

Description

• Add explicit target capabilities for runtime classical control.
• Scalarize supported rank-one QTensors carried through qco.if and reject unsupported forms before mapping.
• Preserve structured control as a routing boundary and restore SSA dominance without reordering CBit or memref accesses.
• Place complete all-to-all target topologies once with the identity layout; retain zero-SWAP previews for sparse targets.

This PR now starts an independent stack on main. It no longer depends on the payload-compilation stack.

Stack

1. ✨ Preserve classical control through target mapping #2179 — classical-control-aware target mapping (this PR)
2. ⚡ Avoid redundant target-compilation liveness analysis #2180 — target-compilation liveness scaling
3. ⚡ Keep wide OpenQASM register conditions linear #2181 — wide OpenQASM register conditions

Overlap

Open pull request #1956 also changes Mapping.cpp and the Layout API. Its routing work is independent, but this PR must be rebased and the complete mapping suite rerun if #1956 lands first.

Testing

• mqt-core-mlir-unittest-mapping: 91 passed.
• mqt-core-mlir-unittests-compiler: 145 passed.
• mqt-core-mlir-unittest-qco-ir: 493 passed.
• mqt-core-mlir-unittest-qco-utils: 115 passed.
• Python MLIR tests: 49 passed.
• Type stubs, uvx nox -s lint, and git diff --check: passed.

AI assistance: Codex assisted with implementation, review, testing, stack construction, 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.
• 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.

[github-actions]

Cpp-Linter Report ⚠️

Some files did not pass the configured checks!

clang-tidy (v22.1.8) reports: 2 concern(s)

• mlir/lib/Dialect/QCO/Transforms/Mapping/Mapping.cpp:80:6: warning: [llvm-prefer-static-over-anonymous-namespace]

  function 'containsClassicalMemoryAccess' is declared in an anonymous namespace; prefer using 'static' for restricting visibility

     80 | bool containsClassicalMemoryAccess(Operation* operation) {
        |      ^

• mlir/unittests/Compiler/test_compiler_target.cpp:182:23: warning: [clang-analyzer-optin.core.EnumCastOutOfRange]

  The value '255' provided to the cast expression is not in the valid range of values for 'ClassicalControl'

    182 |                      {static_cast<ClassicalControl>(255)}),
        |                       ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  /home/runner/work/core/core/mlir/include/mlir/Compiler/Target.h:199:14: note: enum declared here
    199 |   enum class ClassicalControl : uint8_t {
        |   ~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~
    200 |     /// Runtime forward branching such as `qco.if` or `scf.if`.
        |     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    201 |     Conditional,
        |     ~~~~~~~~~~~~
    202 |     /// Structured counted iteration such as `scf.for`.
        |     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    203 |     Iteration,
        |     ~~~~~~~~~~
    204 |     /// Runtime condition-terminated looping such as `scf.while`.
        |     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    205 |     ConditionalLoop,
        |     ~~~~~~~~~~~~~~~~
    206 |     /// Runtime multiway branching such as `qco.index_switch` or
        |     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    207 |     /// `scf.index_switch`.
        |     ~~~~~~~~~~~~~~~~~~~~~~~
    208 |     MultiwayBranch,
        |     ~~~~~~~~~~~~~~~
    209 |   };
        |   ~
  /home/runner/work/core/core/mlir/unittests/Compiler/test_compiler_target.cpp:182:23: note: The value '255' provided to the cast expression is not in the valid range of values for 'ClassicalControl'
    182 |                      {static_cast<ClassicalControl>(255)}),
        |                       ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Have any feedback or feature suggestions? Share it here.

[codecov]

Codecov Report

❌ Patch coverage is 95.22863% with 24 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
mlir/lib/Dialect/QCO/IR/SCF/IfOp.cpp	94.6%	9 Missing ⚠️
...lir/lib/Dialect/QCO/Transforms/Mapping/Mapping.cpp	93.9%	9 Missing ⚠️
mlir/lib/Compiler/TargetCompilation.cpp	95.6%	6 Missing ⚠️

📢 Thoughts on this report? Let us know!

[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]

🤖 AI text below 🤖

pre-commit.ci run

[simon1hofmann]

This PR now somehow includes an old state of #2162.

[burgholzer]

Hm. I wanted to disentangle the series from here on out from the lower chain. Might be that something went wrong with that. I'll try to fix that up once the main PR series gets closer to mergable.