qcompile 0.1.23

AI-guided hardware-aware quantum circuit layout optimization for Qiskit

AI-Driven Hardware-Aware Qubit Placement for Qiskit

qcompile is a layout optimizer for Qiskit that uses a graph neural network (GNN) and hardware calibration data to find a high-quality initial qubit mapping. By optimizing the logical-to-physical qubit placement before Qiskit's main transpilation stage, it aims to reduce routing overhead and improve circuit fidelity on IBM Quantum processors.

This project does not replace Qiskit's transpiler but enhances it. It provides a better starting point, allowing the downstream passes to generate a more efficient and reliable physical circuit.

---

Core Optimization Goals

A poor initial layout forces the transpiler to insert excessive SWAP gates, which increases circuit depth and gate errors. qcompile mitigates this by optimizing for three key metrics:

• Reduced Gate Count: Minimizes the number of physical two-qubit gates and SWAP operations.
• Shorter Circuit Depth: Produces shallower circuits to counteract decoherence.
• Improved Fidelity: Maximizes the Estimated Success Probability (ESP) by placing the circuit on high-quality qubits and links.
• Seamless Integration: Functions as a standard analysis pass within the Qiskit PassManager.

---

How It Works

qcompile uses a four-step process:

1. Smart Chip Selection: Finds the best-performing region of qubits on your quantum processor
2. AI Layout Design: Uses machine learning to predict optimal qubit placement
3. Smart Compilation: Runs the standard Qiskit compiler while staying within the selected qubit region
4. Fine-Tuning: Adjusts the final layout to reduce operations and improve accuracy

---

Performance Results

Here's how qcompile compares to standard Qiskit on real quantum circuits. Tests were run on 30-qubit regions of IBM's ibm_fez processor.

Circuit Type	Logical Qubits	2-Qubit Gates	Circuit Depth	Success Rate
QFT	15	510 → 276 ⬇️	433 → 93 ⬇️	0.24 → 0.43 ⬆️
QCNN (Binary Tree)	16	42 → 42	21 → 22	0.62 → 0.76 ⬆️
QML VQC (Ring)	16	108 → 84 ⬇️	69 → 64 ⬇️	0.50 → 0.62 ⬆️
ML Kernel	10	189 → 183 ⬇️	86 → 106	0.51 → 0.53 ⬆️
QAOA Max-Cut	20	135 → 123 ⬇️	34 → 32 ⬇️	0.44 → 0.46 ⬆️
Random Circuit	15	1191 → 1152 ⬇️	298 → 252 ⬇️	0.01 → 0.02 ⬆️
Linear Chain	20	46 → 25 ⬇️	32 → 25 ⬇️	0.63 → 0.63

Legend: Left value = Standard Qiskit | Right value = qcompile

---

Installation

Requirements

Make sure you have Python 3.8+ and these packages:

pip install qiskit qiskit-ibm-runtime torch torch-geometric networkx joblib rich

---

Quick Start

Here's a simple example to get started:

from qiskit import QuantumCircuit
from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
from qcompile import get_ai_layout

# Step 1: Create your quantum circuit
qc = QuantumCircuit(16)
# Add your quantum gates here

# Step 2: Get the optimized layout
ai_layout, cmap_sliced, active_nodes = get_ai_layout(
    qc,
    backend_name="ibm_fez",
    max_physical_qubits=30,
    train_samples=2500,
)

# Step 3: Compile using the optimized layout
pm = generate_preset_pass_manager(
    optimization_level=3,
    coupling_map=cmap_sliced,      # Uses the selected qubits
    initial_layout=ai_layout,      # Uses the optimized placement
    seed_transpiler=42,
)

# Get your compiled circuit
transpiled_qc = pm.run(qc)

---

About This Project

qcompile combines modern AI techniques with quantum hardware knowledge to improve circuit execution. It works alongside Qiskit's compiler to find smarter qubit placements, reduce errors, and get better results from quantum hardware.