✨Map scf.for operations by restoration using the 4-approximation token swap algorithm

[MatthiasReumann]

Changes

• ✨Add functionality to handle operation with nested operations.
• ✨ Implement the 4-Approximation Algorithm described in arXiv:1602.05150v3.
• ✨Add two unit tests for quantum programs using scf.for operations and one unrolling unit test.
• 📝 Use LLVM codebase style function description (consistent with the IRVerifier and some other parts of the cc).
• 🚛 Move Layout class to separate file.

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:

• I have disclosed the use of AI tools in the PR description as per our AI Usage Guidelines.
• AI-assisted commits include an Assisted-by: [Model Name] via [Tool Name] footer.
• I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.

[MatthiasReumann]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@mlir/lib/Dialect/QCO/Transforms/Mapping/Mapping.cpp`:
- Around line 743-750: The unhappy-swap path in Mapping.cpp continues iterating
over the stale F-graph after curr is mutated, so later choices in the same pass
use outdated distances. Update the logic around the loop over f.getNodes() and
f.getNeighbours(u) to perform only the first eligible unhappy SWAP, then stop
the pass and rebuild f from the updated curr before any further swap selection.
Use the existing swap selection block and swaps bookkeeping to ensure the new
F-graph is always derived from the latest state.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: b6632d43-9dc0-4580-8fd2-bddc0b62283a

📥 Commits

Reviewing files that changed from the base of the PR and between cad617b and df5c584.

📒 Files selected for processing (15)

• CHANGELOG.md
• mlir/include/mlir/Dialect/QCO/Transforms/Mapping/Mapping.h
• mlir/include/mlir/Dialect/QCO/Utils/Algorithms.h
• mlir/include/mlir/Dialect/QCO/Utils/Drivers.h
• mlir/include/mlir/Dialect/QCO/Utils/Graph.h
• mlir/include/mlir/Dialect/QCO/Utils/Layout.h
• mlir/include/mlir/Dialect/QCO/Utils/Qubits.h
• mlir/lib/Dialect/QCO/Transforms/Mapping/Mapping.cpp
• mlir/lib/Dialect/QCO/Utils/Algorithms.cpp
• mlir/lib/Dialect/QCO/Utils/Graph.cpp
• mlir/lib/Dialect/QCO/Utils/Layout.cpp
• mlir/lib/Dialect/QCO/Utils/Qubits.cpp
• mlir/lib/Dialect/QTensor/Utils/TensorIterator.cpp
• mlir/unittests/Dialect/QCO/Transforms/Mapping/test_mapping.cpp
• mlir/unittests/Dialect/QCO/Utils/test_drivers.cpp

💤 Files with no reviewable changes (6)

• mlir/include/mlir/Dialect/QCO/Utils/Algorithms.h
• mlir/lib/Dialect/QCO/Utils/Qubits.cpp
• mlir/lib/Dialect/QCO/Utils/Algorithms.cpp
• mlir/include/mlir/Dialect/QCO/Utils/Qubits.h
• mlir/include/mlir/Dialect/QCO/Utils/Drivers.h
• mlir/unittests/Dialect/QCO/Utils/test_drivers.cpp

[burgholzer]

@MatthiasReumann Just to double check given how there have been fairly recent pushes with changes here and the CI is failing: Is this PR ready for review?

[MatthiasReumann]

@MatthiasReumann Just to double check given how there have been fairly recent pushes with changes here and the CI is failing: Is this PR ready for review?

Sorry! Didn't check the pipeline yesterday anymore. Workflows seem to fail unexpectedly quite frequently recently. Anyway, this pull request is reviewable; yes 🙌

[burgholzer]

This generally looks really clean to me! I'm only have a couple of nitpicks and questions.

[burgholzer]

Once the open conversations are resolved, feel free to merge this 🚀