Naive Qubit Mapping and Routing Algorithm in Runtime #1928

ritu-thombre99 · 2025-07-22T04:45:22Z

Context:

Description of the Change:

When running a quantum circuit on a hardware with certain connectivity constraints, two-qubit gates like CNOTs can only be executed using physical qubits that are connected by an edge on the hardware.

Hence, necessary SWAPs need to be inserted in order to route the logical qubits so that they are mapped to an edge on the device, while respecting other compiling constraint i.e. order the gate dependencies from the input quantum circuit, and ensuring compiled quantum circuit is equivalent to the input quantum circuit.

Following image shows a simple example:

Benefits:

This will support qubit mapping and routing in the runtime
Analogue to qml.transpile transform
Circuits with control structure will also be supported since they will already be optimized by Catalyst passes and unrolled in the runtime.

Possible Drawbacks:

Modification of RuntimeCAPI
Currently, not checking if device supports SWAP
There are multi-qubit gates like Toffoli, MultiRZ, QubitUnitary in RuntimeCAPI.cpp. Routing is not applied to these qubits yet.

Related GitHub Issues:

Example usage:

Currently, seeing what SWAP gates are added can be viewed by using null.qubit done by printing NamedOperation in runtime/lib/backend/null_qubit/NullQubit.hpp

import pennylane as qml
import numpy as np
dev = qml.device("null.qubit", wires = [(0,1),(1,2),(2,3)])
@qml.qjit(autograph=True)
@qml.qnode(dev)
def circuit(c: bool, x: int, y: int):
    if c:
        qml.Hadamard(x)
    qml.Hadamard(y)
    qml.CRZ(0.4,[x,y])
    qml.CNOT([x,2])
    qml.CRX(0.6,[2,y])
    qml.CRY(0.2,[x,y])
    qml.IsingXX(0.24,[0,y])
    qml.CNOT([2,4])
    qml.CNOT([0,5])
    return qml.state()
print(circuit(True,0,3))

Output:

Name: Hadamard
Wires : 0,
Name: Hadamard
Wires : 3,
Name: SWAP
Wires : 0,1,
Name: SWAP
Wires : 1,2,
Name: CRZ
Wires : 2,3,
Name: CNOT
Wires : 2,1,
Name: SWAP
Wires : 1,2,
Name: CRX
Wires : 2,3,
Name: SWAP
Wires : 1,2,
Name: CRY
Wires : 2,3,
Name: IsingXX
Wires : 2,3,
Name: SWAP
Wires : 1,2,
Name: SWAP
Wires : 2,3,
Name: CNOT
Wires : 3,4,
Name: SWAP
Wires : 1,2,
Name: SWAP
Wires : 2,3,
Name: SWAP
Wires : 3,4,
Name: CNOT
Wires : 4,5,
Name: SWAP
Wires : 1,3,
Name: SWAP
Wires : 0,1,
Name: SWAP
Wires : 4,0,
[1.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j
 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j
 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j
 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j
 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j
 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j
 0.+0.j 0.+0.j 0.+0.j 0.+0.j]

github-actions · 2025-08-05T14:07:51Z

Hello. You may have forgotten to update the changelog!
Please edit doc/releases/changelog-dev.md on your branch with:

A one-to-two sentence description of the change. You may include a small working example for new features.
A link back to this PR.
Your name (or GitHub username) in the contributors section.

dime10 · 2025-08-08T15:24:41Z

@ritu-thombre99 can you fix the checks?

dime10

Awesome, I'm excited to add this feature to Catalyst! To merge this in we'll have to meet the PennyLane development standards, like adding tests (both unit and integration), code docs, and make sure there is a good way to control this feature :)

dime10 · 2025-08-08T15:26:15Z

runtime/lib/capi/RuntimeCAPI.cpp

    RT_FAIL_IF(control == target,
               "Invalid input for CNOT gate. Control and target qubit operands must be distinct.");
+
+    std::pair<int,int> routedQubits = getRoutedQubits(control, target, modifiers);


We should have a flag here that controls whether routing is performed or not.

Added option to execution context 4ae4a46#diff-4718a857bb4ed45b3ed299bdb7926e5beca237e53aa645d124f295e0cbbd2357R312

Checks happening before every two-qubit gate 4ae4a46#diff-1a3e5dcf898ac446b6355c7f97c3c62d9039d75db6bb79268d07e3e6d7072bd1R655

dime10 · 2025-08-08T15:28:35Z

runtime/lib/capi/RuntimeCAPI.cpp

        getQuantumDevicePtr()->StartTapeRecording();
    }
+
+    // Extract coupling map from the kwargs passed 


This should be split out into its own function.

In fact, we want to take all these functions and put them in a new file (Routing.cpp/hpp) that you can then call into.

Modularized in Routing.hpp 4ae4a46

dime10 · 2025-08-08T15:29:52Z

runtime/lib/backend/null_qubit/NullQubit.hpp

                        const std::vector<QubitIdType> &controlled_wires = {},
                        const std::vector<bool> &controlled_values = {})
    {
+        // Print to see what naive router does on Null qubits


We should add some runtime tests for the routing functionality

dime10 · 2025-08-08T15:31:39Z

runtime/lib/capi/RuntimeCAPI.cpp

+                                          {/* control = */ routedQubits.first,
+                                           /* target = */ routedQubits.second},


I think we should keep the type that is passed to the function as a QubitIdType (even if you don't use it in your algorithm internally).

Changed types in 4227d89

dime10 · 2025-08-08T15:35:07Z

runtime/lib/capi/RuntimeCAPI.cpp

+                if (distanceMatrix[std::make_pair(*j_itr,*i_itr)] + distanceMatrix[std::make_pair(*i_itr,*k_itr)] < distanceMatrix[std::make_pair(*j_itr,*k_itr)] )
+                {
+                    distanceMatrix[std::make_pair(*j_itr,*k_itr)] = distanceMatrix[std::make_pair(*j_itr,*i_itr)] + distanceMatrix[std::make_pair(*i_itr,*k_itr)];
+                    predecessorMatrix[std::make_pair(*j_itr,*k_itr)] = predecessorMatrix[std::make_pair(*i_itr,*k_itr)];


The next question is where we want to store this kind of information. If we don't want to touch device backends, but still want it to specific to each device (unlike the global you have right now), I think the natural place for it would be in the RTDevice class.

Defined them as class variables in Routing.hpp 4ae4a46 which are initialized only if wires passed to PennyLane device are in a format of list of tuples representing coupling map of the hardware

dime10 · 2025-08-08T15:40:01Z

runtime/lib/capi/RuntimeCAPI.cpp

+    // Extract coupling map from the kwargs passed 
+    // If coupling map is provided then it takes in the form {...,'couplingMap' ((a,b),(b,c))}
+    // else {...,'couplingMap' (a,b,c)}
+    size_t start = args[2].find("coupling_map': ") + 15; // Find key and opening parenthesis


Finally we'll want to device how to pass down the coupling map from the frontend to the runtime.

I think the shortcut via the device_kwargs is okay for now, although normally those are meant to go the Device class constructor. We may want to associate them closer to the runtime then than the device, like we do with shots or qubit management.

mlxd

Just a few fly-by comments from me.
Feel free to ignore them as needed

mlxd · 2025-08-13T16:02:12Z

runtime/lib/capi/Routing.hpp

@@ -0,0 +1,180 @@
+// Copyright 2025 Xanadu Quantum Technologies Inc.


Is this file meant to be the header, or the implementation?
If the header, can we add an #pragma once at the top? If the implementation, we should probably split the header interface and implementation details separately.

mlxd · 2025-08-13T16:04:16Z

runtime/lib/capi/Routing.hpp

+
+#include "RuntimeCAPI.h"
+
+const int MAXIMUM = 1e9;


Rather than having scope visibility across this header, can this be isolated? Otherwise, this will be exported and visible in the generated translation unit.

Either programmatically passing this as an argument to a function/method where needed with a given default value, or (if it is required we set this magic variable), it can be isolated in an anonymous namespace, which should ensure it isn't visible in the compiled code outside of where it is needed.

mlxd · 2025-08-13T16:06:30Z

runtime/lib/capi/RuntimeCAPI.cpp

+/**
+ * @brief Global routing pass pointer.
+ */
+static std::unique_ptr<RoutingPass> RUNTIME_ROUTER = nullptr;


Do we need this to be global? Is there a way we can isolate this so it isn't exposed? Any concerns with thread locality?

I agree, the router should be able to be scoped to each device instance (RTDevice)

ritu-thombre99 added 2 commits July 22, 2025 00:38

floyd warshall

a57e6c5

numm qubit for printing

3d8695f

This was referenced Jul 25, 2025

Z3 import and usage in C++ #1939

Draft

SABRE qubit mapping and routing implementation in Catalyst #1940

Draft

ritu-thombre99 requested a review from dime10 August 5, 2025 14:07

ritu-thombre99 added 2 commits August 5, 2025 10:15

track with main

3d2ed3b

formatting

ab18f54

dime10 requested changes Aug 8, 2025

View reviewed changes

ritu-thombre99 added 8 commits August 8, 2025 11:42

clang format

72036f4

fix ci errors

83d5b33

fix ci errors

70a11b4

fix linting errors

7cffa7b

device capabilities as an optional arg

3eb866f

fix formatting again

1ca60b2

modularize and options

4ae4a46

change qubit types from int to QubitIdType

4227d89

mlxd reviewed Aug 13, 2025

View reviewed changes

ritu-thombre99 force-pushed the ritu/runtime_router branch from d978ed6 to 4227d89 Compare August 21, 2025 18:51

ritu-thombre99 added 10 commits August 21, 2025 16:40

TODO: fix rtdptr dependancy

f4c7dc9

refractoring

c1d738f

fix the end permutation

db26be6

permute end mapping

5142ce1

remove prints

28016b3

add checks for multiqubit gates in runtime

fa429f2

track with main

5864e30

clang formatting

17d42c8

clang format

a5ac864

remove redefinitions

4c4dc80

ritu-thombre99 mentioned this pull request Oct 13, 2025

Runtime router #2117

Open

		{/* control = */ routedQubits.first,
		/* target = */ routedQubits.second},

		@@ -0,0 +1,180 @@
		// Copyright 2025 Xanadu Quantum Technologies Inc.

Naive Qubit Mapping and Routing Algorithm in Runtime #1928

Are you sure you want to change the base?

Naive Qubit Mapping and Routing Algorithm in Runtime #1928

Uh oh!

Conversation

ritu-thombre99 commented Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Aug 5, 2025

Uh oh!

dime10 commented Aug 8, 2025

Uh oh!

dime10 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mlxd left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ritu-thombre99 commented Jul 22, 2025 •

edited

Loading