✨ Expand Qiskit RL actions by flowerthrower · Pull Request #794 · munich-quantum-toolkit/predictor

flowerthrower · 2026-08-27T14:14:03Z

🤖 AI text below 🤖

Description

Expands the RL action space with focused Qiskit layout, routing, and optimization passes: TrivialLayout, SabreSwap, BasicSwap, LookaheadSwap, RemoveIdentityEquivalent, and Optimize1qGatesSimpleCommutation.

It also registers AIRouting for routing an existing layout and AIRouting_opt for combined layout and routing. Both use IBM's local AI routing pass at optimization level 3. The IBM pass is loaded lazily, and both actions are masked when qiskit-ibm-transpiler cannot be imported.

The IBM package is not added as a dependency because its current release pins NetworkX 2.8.5 while MQT Bench requires NetworkX 2.8.8 or newer, excludes Python 3.14, and imports Qiskit internals removed in Qiskit 2.5. This keeps the action schema ready for a future compatible release without reintroducing the prototype's global dependency override.

Existing RL models must be retrained because the action schema changes.

This is position 3 of the stack. It depends on #758 and is followed by #795. No new package dependencies are introduced.

Part of #675

Part of #664

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.

Signed-off-by: flowerthrower <flowerthrower@users.noreply.github.com> Assisted-by: GPT 5.6 via Codex

Assisted-by: GPT-5.6 via Codex Signed-off-by: flowerthrower <flowerthrower@users.noreply.github.com>

Signed-off-by: flowerthrower <flowerthrower@users.noreply.github.com> Assisted-by: GPT 5.6 via Codex

flowerthrower · 2026-08-27T14:57:25Z

@coderabbitai full review

coderabbitai · 2026-08-27T14:58:35Z

✅ Action performed

Full review finished.

coderabbitai · 2026-08-27T15:04:20Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 87c186fe-eec3-47b2-9c53-3251812e20ca

📥 Commits

Reviewing files that changed from the base of the PR and between 16d7c15 and 8a50c24.

📒 Files selected for processing (4)

CHANGELOG.md
UPGRADING.md
src/mqt/predictor/rl/actions/qiskit_actions.py
src/mqt/predictor/rl/actions/registry.py

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

Summary by CodeRabbit

New Features
- Added Qiskit layout, routing, and optimization actions, including swap, permutation-elision, identity-removal, and single-qubit optimization.
- Added automatic decomposition of remaining Clifford gates during Qiskit action execution.
- Registered the new actions for use in reinforcement-learning workflows.
Documentation
- Updated the changelog and upgrade guide with the new actions, processing changes, and model retraining considerations.

Walkthrough

The Qiskit RL action set now includes layout, routing, and optimization passes. Clifford collection and decomposition behavior changed. The registry includes routing actions. The changelog and upgrade guide document the new actions and required model updates.

Changes

Qiskit RL action expansion

Layer / File(s)	Summary
Qiskit optimization and Clifford processing `src/mqt/predictor/rl/actions/qiskit_actions.py`	`OptimizeCliffords` now collects Clifford gates first. New identity-removal and single-qubit optimization actions were added. Remaining `clifford` gates are decomposed during execution.
Layout and routing action definitions `src/mqt/predictor/rl/actions/qiskit_actions.py`, `src/mqt/predictor/rl/actions/registry.py`	`TrivialLayout`, `ElidePermutations`, `SabreSwap`, `BasicSwap`, and `LookaheadSwap` actions were added. Routing actions are registered globally.
Action-set upgrade documentation `CHANGELOG.md`, `UPGRADING.md`	The documentation describes the expanded Qiskit actions, Clifford changes, and required model retraining and numeric-index updates.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 8a50c

The PR expands the Qiskit RL action schema and documents the required model retraining; no actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant Registry
  participant QiskitActions
  participant DeferredDeviceAction
  participant QiskitPasses
  Registry->>QiskitActions: request routing actions
  QiskitActions->>DeferredDeviceAction: create device-deferred actions
  DeferredDeviceAction->>QiskitPasses: construct SabreSwap, BasicSwap, or LookaheadSwap
  Registry->>DeferredDeviceAction: register routing actions

Suggested reviewers: denialhaag

Poem

A rabbit hops through layout gates,
Then routes the swaps through quantum states.
Cliffords gather, identities flee,
Small gates optimize neatly.
New actions bloom in the registry tree.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 2 files. (2 skipped: 2 …
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.
Description check	✅ Passed	The description summarizes the Qiskit RL action changes, explains motivation and dependency constraints, identifies migration impact and stacked-PR context, and completes the required checklist with A…
Title check	✅ Passed	The title is concise, specific, and accurately describes the main change: expanding the Qiskit RL action space.

Full details: Docstring Coverage

Explanation

Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 2 files. (2 skipped: 2 unsupported.)

Full details: Description check

Explanation

The description summarizes the Qiskit RL action changes, explains motivation and dependency constraints, identifies migration impact and stacked-PR context, and completes the required checklist with AI-use disclosures.

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

_{Comment @coderabbitai help to get the list of available commands.}

burgholzer

Some of these additions do not make too much sense to me to be honest. Might be worth double checking.

burgholzer · 2026-08-28T07:47:40Z

+def qiskit_routing_actions() -> list[Action]:
+    """Return the Qiskit routing actions."""
+    return [
+        DeferredDeviceAction(
+            "SabreSwap",
+            CompilationOrigin.QISKIT,
+            PassType.ROUTING,
+            transpile_pass=lambda device: cast(
+                "list[Task]", [SabreSwap(coupling_map=CouplingMap(device.build_coupling_map()), heuristic="decay")]
+            ),
+        ),
+        DeferredDeviceAction(
+            "BasicSwap",
+            CompilationOrigin.QISKIT,
+            PassType.ROUTING,
+            transpile_pass=lambda device: cast(
+                "list[Task]", [BasicSwap(coupling_map=CouplingMap(device.build_coupling_map()))]
+            ),
+        ),
+        DeferredDeviceAction(
+            "LookaheadSwap",
+            CompilationOrigin.QISKIT,
+            PassType.ROUTING,
+            transpile_pass=lambda device: cast(
+                "list[Task]",
+                [
+                    LookaheadSwap(
+                        coupling_map=CouplingMap(device.build_coupling_map()),
+                        search_depth=1,
+                        search_width=1,
+                    )
+                ],
+            ),
+        ),


Everything that is not SABRE here is a bit pointless to add because these outer routing methods aren't really developed or improved anymore and there is hardly ever any reason to choose them.

oh i see. my naive thought was "cool more passes -> more room for experimantation for the agent", but you are right they seem hardly useful compared to SABRE

I'd actually argue that more passes can be quite counter-productive if the passes being added do not really add value but just enlarge the search space.

burgholzer · 2026-08-28T07:48:48Z

+        DeferredDeviceAction(
+            "ElidePermutations",
+            CompilationOrigin.QISKIT,
+            PassType.LAYOUT,
+            transpile_pass=lambda device: cast(
+                "list[Task]",
+                [
+                    ElidePermutations(),
+                    TrivialLayout(coupling_map=CouplingMap(device.build_coupling_map())),
+                    FullAncillaAllocation(coupling_map=CouplingMap(device.build_coupling_map())),
+                    EnlargeWithAncilla(),
+                    ApplyLayout(),
+                ],
+            ),
+        ),
+    ]


This is a bit of a strange addition. The Elision pass is a regular pass, not a Layout per-se. I see no reason why it should be coupled to a trivial layout.

Yeah, the thing I was trying to workaround here is that elidepermuations alone do produce a virtual_permutation_layout, which would be lost after the pass if not directly followed by a layout. The cleaner solution would probably be to track that along in our layout bookkeeping, but i have to investigate first what that would do in a cross-compiler scenario (i.e., when interleaving with TKET for example).

I see. Then I'd rather defer the addition of this to a later PR. I do not believe the current elide+trivial-layout pass provides any meaningful value.

burgholzer · 2026-08-28T07:50:05Z

            CompilationOrigin.QISKIT,
            PassType.OPT,
-            [OptimizeCliffords()],
+            [CollectCliffords(), OptimizeCliffords()],


OptimizeCliffords already works for subsequent Cliffords. So I am fairly sure this is pointless and only adds runtime.

Signed-off-by: flowerthrower <flowerthrower@users.noreply.github.com> Assisted-by: GPT 5.6 via Codex

flowerthrower added 6 commits August 27, 2026 16:07

✨ Add SABRE routing action

890ee09

Signed-off-by: flowerthrower <flowerthrower@users.noreply.github.com> Assisted-by: GPT 5.6 via Codex

📝 Document the SABRE routing action

4cb43a1

Assisted-by: GPT-5.6 via Codex Signed-off-by: flowerthrower <flowerthrower@users.noreply.github.com>

✨ Expand Qiskit RL actions

27ad066

Signed-off-by: flowerthrower <flowerthrower@users.noreply.github.com> Assisted-by: GPT 5.6 via Codex

🧪 Align Qiskit action tests

62ce9c8

Signed-off-by: flowerthrower <flowerthrower@users.noreply.github.com> Assisted-by: GPT 5.6 via Codex

🧪 Cover Qiskit actions through pass invariants

f8aaad9

Signed-off-by: flowerthrower <flowerthrower@users.noreply.github.com> Assisted-by: GPT 5.6 via Codex

♻️ Assume bidirectional device coupling

bcf2df6

Signed-off-by: flowerthrower <flowerthrower@users.noreply.github.com> Assisted-by: GPT 5.6 via Codex

flowerthrower force-pushed the v3/675-qiskit-passes branch from 4247f27 to 36c7835 Compare August 27, 2026 14:15

flowerthrower mentioned this pull request Aug 27, 2026

✨ Add missing BQSKit RL synthesis actions #795

Open

12 tasks

flowerthrower added enhancement New feature or request major Part of a major release refactor PR or issues that refactor code labels Aug 27, 2026

flowerthrower self-assigned this Aug 27, 2026

📝 Attribute Qiskit action changes to PR #794

8a50c24

Signed-off-by: flowerthrower <flowerthrower@users.noreply.github.com> Assisted-by: GPT 5.6 via Codex

flowerthrower force-pushed the v3/675-qiskit-passes branch from 36c7835 to 8a50c24 Compare August 27, 2026 14:46

flowerthrower removed the refactor PR or issues that refactor code label Aug 27, 2026

flowerthrower changed the title ~~✨ Expand Qiskit RL actions with stochastic selection~~ ✨ Expand Qiskit RL actions Aug 27, 2026

flowerthrower marked this pull request as ready for review August 27, 2026 14:57

coderabbitai Bot approved these changes Aug 27, 2026

View reviewed changes

flowerthrower requested a review from burgholzer August 28, 2026 07:22

burgholzer requested changes Aug 28, 2026

View reviewed changes

flowerthrower added 3 commits August 28, 2026 10:21

✨ Add optional AI routing actions

6fd59d5

Signed-off-by: flowerthrower <flowerthrower@users.noreply.github.com> Assisted-by: GPT 5.6 via Codex

🐛 Correct Qiskit action behavior

72d115c

Signed-off-by: flowerthrower <flowerthrower@users.noreply.github.com> Assisted-by: GPT 5.6 via Codex

✨ Add optional AI routing actions

b780667

Signed-off-by: flowerthrower <flowerthrower@users.noreply.github.com> Assisted-by: GPT 5.6 via Codex

flowerthrower mentioned this pull request Aug 28, 2026

✨ Add rotation-through-CX optimization pass munich-quantum-toolkit/core#2274

Open

Uh oh!

Uh oh!

Conversation

flowerthrower commented Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

flowerthrower commented Aug 27, 2026

Uh oh!

coderabbitai Bot commented Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

burgholzer left a comment

Choose a reason for hiding this comment

Uh oh!

burgholzer Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

flowerthrower Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

burgholzer Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

burgholzer Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

flowerthrower Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

burgholzer Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

burgholzer Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

flowerthrower commented Aug 27, 2026 •

edited

Loading

coderabbitai Bot commented Aug 27, 2026 •

edited

Loading

coderabbitai Bot commented Aug 27, 2026 •

edited

Loading