What is the proper way to do initial mapping for a circuit?

[geexie]

@alecandido, I have circuit with 3 logical registers q0, q1, q2 and I have some connectivity graph with let's say 5 physical qubits (not necessary continuous). How can I do initial mapping without setting wire_names explicitly?

I tried

    placer = Random(connectivity=cg)
    initial_layout = placer(c)

but it asserts

[Qibo 0.2.18|ERROR|2025-07-14 11:48:27]: Number of qubits in the circuit (3) does not match either the number of qubits in the layout (3) or the connectivity graph (5).
Traceback (most recent call last):
  File "/mnt/home/geexie/qumib/qft.py", line 184, in <module>
    transpiled_circuit, final_qubit_map = get_sabre_transpiler(p, reduced = True)
                                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/mnt/home/geexie/qumib/qft.py", line 84, in get_sabre_transpiler
    initial_layout = placer(c)
                     ^^^^^^^^^
  File "/mnt/scratch/envs/qibo/lib/python3.12/site-packages/qibo/transpiler/placer.py", line 193, in __call__
    assert_placement(circuit, self.connectivity)
  File "/mnt/scratch/envs/qibo/lib/python3.12/site-packages/qibo/transpiler/asserts.py", line 137, in assert_placement
    raise_error(
  File "/mnt/scratch/envs/qibo/lib/python3.12/site-packages/qibo/config.py", line 46, in raise_error
    raise exception(message)
qibo.transpiler._exceptions.PlacementError: Number of qubits in the circuit (3) does not match either the number of qubits in the layout (3) or the connectivity graph (5).

which I believe is too strict since I should be able to close smaller circuit into bigger QPU

[alecandido]

There is a Preprocessing step, which can be used for that.

qibo/src/qibo/transpiler/optimizer.py

Lines 11 to 12 in 14b62c4

	class Preprocessing(Optimizer):
	"""Pad the circuit with unused qubits to match the number of physical qubits.

[geexie]

I tried to use this

    natives = NativeGates(0).from_gatelist(glist)
    passes = [Preprocessing(connectivity=cg), Sabre(), Unroller(native_gates=natives)]
    return Passes(connectivity=cg, passes=passes)(c)

algoritm qubits q0, q1, q2
connectivity 0,1,3,4,5

it produces the error

 geexie@geekbox qumib % python3 qft.py
[Qibo 0.2.19|ERROR|2025-07-14 16:56:28]: Some wire_names in the circuit are not in the connectivity graph.
Traceback (most recent call last):
  File "/Users/geexie/code/phd/qumib/qft.py", line 224, in <module>
    transpiled_circuit, _ = run_sabre_transpiler(p, reduced=True)
                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/geexie/code/phd/qumib/qft.py", line 127, in run_sabre_transpiler
    return Passes(connectivity=cg, passes=passes)(c)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/geexie/code/phd/qibo/src/qibo/transpiler/pipeline.py", line 87, in __call__
    circuit = transpiler_pass(circuit)
              ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/geexie/code/phd/qibo/src/qibo/transpiler/optimizer.py", line 23, in __call__
    raise_error(
  File "/Users/geexie/code/phd/qibo/src/qibo/config.py", line 46, in raise_error
    raise exception(message)
ValueError: Some wire_names in the circuit are not in the connectivity graph.

The full code

import matplotlib.pyplot as plt
from qibo import Circuit, gates
from qibo.ui import plot_circuit
from qibo.transpiler import (
    NativeGates,
    Passes,
    Unroller,
    Preprocessing,
    Sabre
)

from qibo.transpiler.placer import (
    # Custom,
    Random,
    # StarConnectivityPlacer,
    # Subgraph,
    # Trivial,
    # assert_placement,
)

import networkx as nx
import math
import numpy as np

def run_sabre_transpiler(c, glist = [gates.GPI2, gates.RZ, gates.Z, gates.CZ], reduced = False):
    connectivity = [
    ]

    reduced_connectivity = [
        (0, 1),
        (0, 3),
        (1, 4),
        (3, 4),
        (4, 5)
    ]

    cg = nx.Graph(connectivity if not reduced else reduced_connectivity)

    # placer = Random(connectivity=cg)
    # initial_layout = placer(c)

    natives = NativeGates(0).from_gatelist(glist)
    passes = [Preprocessing(connectivity=cg), Sabre(), Unroller(native_gates=natives)]
    return Passes(connectivity=cg, passes=passes)(c)


# build QFT for chosen size
def get_qft(a, n):
    qft = Circuit(a+n)

    for j in range(a, a+n):
        qft.add(gates.H(j))
        n_ent = max(a, a + n - j)
        for k in range(j + 1, j + n_ent):
            theta = np.pi / (2 ** (k - j))
            qft.add(gates.CU1(k, j, theta))

    for i in range(n // 2):
        qft.add(gates.SWAP(a+i, a+n - i - 1))

    return qft

# build GFT for chosen size
def get_iqft(a, n):
    qft = Circuit(a+n)

    for i in range(n // 2):
        qft.add(gates.SWAP(a+i, a+n - i - 1))

    for j in reversed(range(a, a+n)):
        n_ent = max(a, a + n - j)
        for k in reversed(range(j + 1, j + n_ent)):
            theta = np.pi / (2 ** (k - j))
            qft.add(gates.CU1(k, j, -theta))
        qft.add(gates.H(j))
    return qft

filename = "qft"

p = Circuit(3)

# 5
p.add(gates.X(0))
p.add(gates.X(2))

qft = get_qft(0,3)
plot_circuit(qft)
plt.title("QFT")
plt.savefig(filename+".png")

iqft = get_iqft(0,3)
plot_circuit(iqft)
plt.title("iQFT")
plt.savefig("i"+filename+".png")

p = p + qft + iqft
p.add(gates.M(0, 1, 2))
plot_circuit(p)
plt.title("QFT^{-1}QFT")
plt.savefig("full_"+filename+".png")

# SABRE transpilation
# p.wire_names =list([0,1,3])
transpiled_circuit, _ = run_sabre_transpiler(p, reduced=True)
plot_circuit(transpiled_circuit)
plt.title("Transpiled Circuit")
plt.savefig(filename+"_sabre.png")
result = transpiled_circuit(nshots=4096)
r = result.frequencies(binary=True)

keys = list(r.keys())
values = list(r.values())
plt.figure(8)
plt.bar(keys, values)
plt.xlabel('Encoded value')
plt.ylabel('Probability')
plt.title('QFT^{-1}QFT')
plt.savefig(filename+"_h_sabre.png")

[alecandido]

In this case, the error is not that bad. And it is coming from here:

qibo/src/qibo/transpiler/optimizer.py

Line 22 in 14b62c4

if not all(qubit in self.connectivity.nodes for qubit in circuit.wire_names):

So, the reason is that some of the "qubits" (their names) in the circuit are not in the connectivity.
At a certain point in Qibo's transpiler evolution, this could have also happened because you have a qubit named 0 on the one side (e.g. in the connectivity) and "q0" on the other (e.g. the circuit). Which is kind of silly, but they are certainly two different values.
By now, we should have mostly dropped this convention of using "q"-prepended strings by default to label qubits, and if you do not specify the names manually, you should be working with plain integers.

Unless the former is still the case (I'm rarely working on the main qibo package myself, not sure of all the developments), this should not happen.
And instead, it seems that you're trying to place a circuit

algoritm qubits q0, q1, q2
connectivity 0,1,3,4,5

on a gapped connectivity, which is missing qubit 2.

You may argue that you just want to place your 3-qubit circuit, no matter what. And the first three qubits in the circuit topology are good enough, whatever they are.
Well, that's not what Preprocessing is doing, since it may be desired in some situations, but certainly unexpected in others. E.g. in case of a wicked platform, with qubits named 1, 1.5, 2, 2.5, ..., or a normal one, lexigraphically sorted as 1, 10, 11, 12, ..., 2, 20, ..., 3, if you specify that your circuit is allocated on qubits 1, 2, 3, it could be unwanted to find it on 1, 1.5, 2 or 1, 10, 11.

Here the problem is that there is currently no way in Qibo circuits to not assign Circuit.wire_names. If they are not assigned, this is automatically supplied as 1, 2, 3, ..., nqubits. While the information vacuity (keeping it None) could be meaningful.
So, we are missing a slot to convey the choice of choosing no .wire_names, and then automatically place on the first available qubits, whatever they are.

In any case, if you want to actually use the first elements, then you can do this "manually", by assigning .wire_names explicitly to cg.nodes[:c.nqubits]. In this way, it will be 0, 1, 3, instead of the current 0, 1, 2.
It is a more manual process. To make it automated, contributions would be welcomed :)

[geexie]

@alecandido, thanks for a detailed replay! I appreciate your timely and detailed help!

1. I already discovered this naming thing while loading benchmark from openQasm. I had to manually drop qs. Which I feel is a bit hacky. I would rather do some random mapping in this case with explicit Pass or implicitly sine names in the circuit may reflect math but may be platform agnostic. What is your opinion about this?
2. Yes, I want to place circuit with algorithmic qubits named somehow to discontinued connectivity map which is quite valid case if device is partially working (uncalibrated or some qubits are lower quality and rather be excluded from mapping/routing). I don't have favour for the first 3 qubits in a connectivity graph and I feel like any would work as original placement. Even in your weird example of lexical etc. naming I would rather prefer to have some qubits rather than error. I did the wire hack what you suggested and it works but I would like to have this pass to be available. How do you think it could be implemented? Is it like pass to randomly assign physical qubits to algorithmic qubits?

[alecandido]

1. I already discovered this naming thing while loading benchmark from openQasm. I had to manually drop qs. Which I feel is a bit hacky. I would rather do some random mapping in this case with explicit Pass or implicitly sine names in the circuit may reflect math but may be platform agnostic. What is your opinion about this?

I agree about the hacky feeling.
Unfortunately, as we are focusing on other parts of the Qibo ecosystem, we are lacking some efforts to preserve a consistent and intuitive user interface. Which eventually results in possible but annoying bridges required for certain workflows.

The transpiler is particularly in need, both from the external (user) perspective and the internal (developer) one. Since on the one side it is missing features, documentation, and quality-of-life improvements (as the one you describe), and the other it is not much suitable for extensions.
Some time should be taken to redesign it consistently (which does not mean rewriting all of it - but possibly changing its structure).

2. Yes, I want to place circuit with algorithmic qubits named somehow to discontinued connectivity map which is quite valid case if device is partially working (uncalibrated or some qubits are lower quality and rather be excluded from mapping/routing). I don't have favour for the first 3 qubits in a connectivity graph and I feel like any would work as original placement. Even in your weird example of lexical etc. naming I would rather prefer to have some qubits rather than error. I did the wire hack what you suggested and it works but I would like to have this pass to be available. How do you think it could be implemented? Is it like pass to randomly assign physical qubits to algorithmic qubits?

That's certainly meaningful.
As said, the problem is mostly in the current .wire_names property. Right now, every time you retrieve it, it has a value. And if the value is not provided by the user, it is assigned in a rather arbitrary way.
I would say that we should stop doing that, and just allow for an empty value.
Then, as a built-in or plug-in part of a transpiler, we can add a step that conditionally apply a random/meaningful placement only if the .wire_names attribute is not manually set.
The idea is that .wire_names should work as an initial placement of the qubits, such that all other placements will work as additional permutation, and you can reconstruct the mapping to the initial qubits composing all the permutations and inverting them (this is needed to eventually reassign the results to the correct qubit names). But, indeed, the user should not be forced to manually specify a tentative placement. It is only useful as an option (opt-in).