Compilation and Routing Tutorial

This tutorial demonstrates how to use the microquantum transpiler to compile circuits for hardware with limited qubit connectivity.

Coupling Maps

A CouplingMap defines which qubit pairs can interact directly:

from microquantum import CouplingMap

# Linear chain: 0-1-2-3
linear = CouplingMap.linear(4)

# 2x3 grid
grid = CouplingMap.grid(2, 3)

# All-to-all connectivity
full = CouplingMap.all_to_all(5)

# Check connectivity
print(linear.are_connected(0, 1))  # True
print(linear.are_connected(0, 3))  # False

Routing

When a circuit has two-qubit gates between non-adjacent qubits, the routing pass automatically inserts SWAP gates:

from microquantum import QuantumCircuit, PassManager
from microquantum.core.coupling import CouplingMap
from microquantum.core.transpiler import RoutingPass

# Create a circuit that needs routing
qc = QuantumCircuit(4)
qc.h(0)
qc.cx(0, 3)  # qubits 0 and 3 are not adjacent in linear topology

# Route for linear connectivity
cmap = CouplingMap.linear(4)
pm = PassManager()
pm.append_pass(RoutingPass(cmap))
routed = pm.run(qc)
print(f"Original: {qc.num_gates} gates")
print(f"Routed: {routed.num_gates} gates (includes SWAPs)")

Noise-Aware Placement

When noise rates vary across device edges, the noise-aware pass schedules low-noise gates first:

from microquantum.core.transpiler import NoiseAwarePlacementPass

noise = {
    (0, 1): 0.01,  # low noise
    (1, 2): 0.05,  # medium noise
    (2, 3): 0.10,  # high noise
}
pm = PassManager()
pm.append_pass(NoiseAwarePlacementPass(cmap, noise))
optimized = pm.run(qc)

Optimization Levels

The PassManager.from_optimization_level() method provides preset compilation pipelines:

# Level 0: no optimization
pm0 = PassManager.from_optimization_level(0)

# Level 2: full optimization + routing
pm2 = PassManager.from_optimization_level(2, coupling_map=cmap)

# Level 3: aggressive + noise-aware
pm3 = PassManager.from_optimization_level(
    3, coupling_map=cmap, noise_rates=noise
)