✨ Preserve classical control through target mapping

[simon1hofmann]

🤖 AI text below 🤖

Description

This PR makes target mapping preserve structured classical control without
defining target capability policy:

• Scalarize supported static rank-one qubit tensors carried through qco.if.
• Keep unary structured operations as routing boundaries and select the qubit
  values that actually cross those boundaries.
• Restore SSA dominance with deterministic dependency ordering that preserves
  observable CBit and memref access order.
• Fail mapping without a partial reorder if the combined SSA and
  classical-memory dependencies contain a cycle.

This is the focused MQT Core 4.0 scope. It intentionally does not add
CompilerTarget::ClassicalControl, target-capability legality validation,
complete-topology identity placement, zero-SWAP preview optimizations, or
payload/QDMI 1.4 work. Target acceptance policy can therefore evolve separately
from the mapper's semantic-correctness guarantees.

Preserved history

Before rewriting the PR branch, the full prior stack was preserved exactly:

• Original base: 25b7eb8ef50db57abe0de94044821a160f384b89
• Original head: 9f7a0eb08bb410f67312c802f212b544e0f2a547
• Archive ref: archive/pr-2179-full-classical-control-2026-09-01, verified at the original head above

The range-diff drops the target-capability, complete-topology, and target-check
alignment commits and rewrites only the structured-control preservation commit
onto current main. The archive retains those deferred changes for future
extraction without keeping them in the Core 4.0 critical path.

Testing

• QCO IR: 494 tests passed.
• QCO utilities: 138 tests passed.
• Mapping: 89 tests passed.
• Compiler: 138 tests passed.
• Changed-source C++ lint: 0 clang-format and 0 clang-tidy findings.
• uvx nox -s lint: passed.
• git diff --check: passed.

AI assistance: Codex assisted with the rescope, implementation review, testing,
and this description. The original human contribution and commit authorship
remain attributed to Simon Hofmann.

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

Files with missing lines	Patch %	Lines
mlir/lib/Dialect/QCO/IR/SCF/IfOp.cpp	97.7%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Team

Run ID: 1c7ad68e-554c-4a76-b32f-751e4a631652

📥 Commits

Reviewing files that changed from the base of the PR and between 9dee2f4 and 79c7688.

📒 Files selected for processing (5)

• CHANGELOG.md
• mlir/lib/Dialect/QCO/IR/SCF/IfOp.cpp
• mlir/lib/Dialect/QCO/Transforms/Mapping/Mapping.cpp
• mlir/unittests/Dialect/QCO/IR/test_qco_ir.cpp
• mlir/unittests/Dialect/QCO/Transforms/Mapping/test_mapping.cpp

Included review availability: Your plan provides up to 2 included reviews per hour; 1 remains after this review.

---

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

📝 Summary

Summary by CodeRabbit

• Improvements

  • Improved compiler optimization for conditional operations involving statically indexed quantum tensors.
  • Preserved tensor elements and result ordering more accurately during optimization.
  • Improved mapping of non-adjacent two-qubit operations within conditional regions.
  • Enhanced routing decisions around composite operations to produce more reliable mappings.

• Bug Fixes

  • Prevented unsafe transformations when tensor indices or shapes are dynamic.
  • Improved handling of qubit boundaries during placement and routing.

• Documentation

  • Updated the changelog with the latest compiler-target-aware routing pass release information.

Walkthrough

The change adds QTensor scalarization for eligible qco.if operations, updates mapping around composite wire boundaries, adds coverage for both behaviors, adjusts loop index types, and updates the changelog reference.

Changes

QCO compiler updates

Layer / File(s)	Summary
Scalarize constant-index QTensor branches mlir/lib/Dialect/QCO/IR/SCF/IfOp.cpp, mlir/unittests/Dialect/QCO/IR/test_qco_ir.cpp	IfOp canonicalization now converts complete constant-index QTensor extract/compute/reinsert lifetimes into scalar qubit arguments and results. Tests cover accessed elements, forwarded tensors, result ordering, dynamic indices, and dynamic shapes.
Preserve composite mapping frontiers mlir/lib/Dialect/QCO/Transforms/Mapping/Mapping.cpp, mlir/unittests/Dialect/QCO/Transforms/Mapping/test_mapping.cpp	Mapping now resolves wire values before composite boundaries and defers composites when another active wire has an earlier operation. Tests cover non-adjacent two-qubit routing and use size_t for measurement loops.
Record the compiler-target-aware pass update CHANGELOG.md	The changelog entry includes the pull request reference and an additional contributor reference definition.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: 🔵 Low · up to 79c76

The PR improves preservation of structured classical control during compile-time mapping and is mergeable with owner awareness. A late mapping failure may leave partially transformed compiler state if the failed pipeline result is reused, so failure-state handling should be explicitly verified or documented.

Sequence Diagram(s)

sequenceDiagram
  participant CleanupPipeline
  participant ScalarizeQTensorInputs
  participant QCOIfOp
  participant QTensorOps
  CleanupPipeline->>ScalarizeQTensorInputs: apply canonicalization
  ScalarizeQTensorInputs->>QCOIfOp: analyze constant-index branches
  ScalarizeQTensorInputs->>QCOIfOp: create scalar qubit operands and results
  QCOIfOp->>QTensorOps: extract and reinsert QTensor elements

Loading

Suggested reviewers: denialhaag, burgholzer, matthiasreumann

Poem

A rabbit traced the qubit line
Through tensor paths both neat and fine
Branches yielded scalars bright
Wires crossed boundaries right
Tests watched each index glow
And changelog links now show

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 27.59% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 29 functions across 4 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the primary change: preserving classical control through target mapping.
Description check	✅ Passed	The description provides a clear summary, motivation, scope, preserved history, testing results, AI disclosure, and a completed checklist. It does not include an explicit issue reference or dependency…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Description check

Explanation

The description provides a clear summary, motivation, scope, preserved history, testing results, AI disclosure, and a completed checklist. It does not include an explicit issue reference or dependency statement, but these omissions are non-critical because no issue or dependency is identified.

Full details: Docstring Coverage

Explanation

Docstring coverage is 27.59% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 29 functions across 4 files. (1 skipped: 1 unsupported.)

---

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.

[denialhaag]

I admittedly didn't go through all of the logic, but this generally LGTM. I just have a few comments, none of which should be a major blocker.

[burgholzer]

Might have been a bit premature to declare this as ready for review. This still has quite a few dependencies on other open PRs it seems.
Might be worth getting those in first before handing this one back to Codex with all the feedback.

[simon1hofmann]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[denialhaag]

Thanks a lot for addressing all of my comments, @simon1hofmann! I only cross-checked that they are all resolved now, but I didn't check the full PR again. I'm approving now so this doesn't get help up. If you want me to have another look, I'm happy to do so tomorrow morning! 🙂

[burgholzer]

Simplified this a bit further. But otherwise this also looks good to me now and ready to go in. We may want to eliminate that one check that is true by design.

[burgholzer]

Looks reasonable to me for now!
Let's get this in!