qcompile — AI-Driven Hardware-Aware Qubit Placement for Qiskit

qcompile is an AI-driven hardware-aware layout optimizer for Qiskit that combines Graph Attention Networks (GATv2), live IBM Quantum calibration data, and heuristic search to generate high-quality initial qubit mappings.

Instead of replacing Qiskit's transpiler, qcompile improves the initial logical-to-physical qubit placement before routing begins, allowing the standard Qiskit compilation pipeline to produce circuits with fewer routing operations, lower depth, and higher execution fidelity on superconducting quantum processors.

Project Links

• GitHub: https://github.com/shaguntembhurne/qcompile
• PyPI: https://pypi.org/project/qcompile/

Why qcompile?

Modern quantum compilers often spend a significant portion of compilation repairing poor initial layouts by inserting SWAP operations. Every additional two-qubit gate introduces noise, increases execution time, and reduces the probability of successful circuit execution.

qcompile improves this first stage by learning hardware-aware placement strategies from thousands of optimized Qiskit compilations, enabling smarter initial layouts before routing even begins.

Unlike traditional layout heuristics, qcompile combines machine learning with live hardware information to produce layouts tailored to the current state of the target quantum processor.

How qcompile Fits Into Qiskit

          Quantum Circuit
                 │
                 ▼
             qcompile
                 │
     Optimized Initial Layout
                 │
                 ▼
      Qiskit Transpiler (O3)
                 │
                 ▼
     Optimized Physical Circuit

qcompile integrates seamlessly with the existing Qiskit transpiler and requires no modifications to the downstream compilation pipeline.

Features

• ✅ Live IBM Quantum calibration-aware optimization
• ✅ Automatic high-fidelity hardware slice selection
• ✅ Graph Attention Network (GATv2) based layout prediction
• ✅ Expert imitation learning from optimized Qiskit layouts
• ✅ Frequency-aware Neural Beam Search
• ✅ Reliability-aware shortest-path heuristic search
• ✅ Local search refinement using simulated annealing
• ✅ Physics-based multi-objective optimization
• ✅ Automatic zero-SWAP fast-path optimization
• ✅ Detailed research-grade telemetry and compiler statistics
• ✅ Fully compatible with the standard Qiskit PassManager

Core Optimization Goals

A poor initial layout forces the transpiler to insert excessive SWAP gates, increasing hardware errors and circuit execution time.

qcompile optimizes the initial mapping according to three primary objectives:

• Reduced Two-Qubit Gates – minimizes physical two-qubit operations and SWAP overhead.
• Lower Circuit Depth – produces shallower circuits that better tolerate decoherence.
• Higher Estimated Success Probability (ESP) – maximizes execution fidelity by selecting reliable qubits and couplers.
• Seamless Integration – works directly with the standard Qiskit compilation workflow.

Compiler Architecture

                 Quantum Circuit
                        │
                        ▼
      Hardware Analysis & Calibration Extraction
                        │
                        ▼
      High-Fidelity Hardware Slice Selection
                        │
                        ▼
      Expert Layout Harvesting (Qiskit O3)
                        │
                        ▼
        Elite Layout Selection & Ranking
                        │
                        ▼
      Graph Attention Network (GATv2)
                        │
                        ▼
     Frequency-Aware Neural Beam Search
                        │
                        ▼
     Local Search Layout Refinement
                        │
                        ▼
       Optimized Initial Layout
                        │
                        ▼
      Standard Qiskit Transpiler
                        │
                        ▼
       Optimized Physical Circuit

How It Works

1. Hardware Analysis

The compiler connects to a live IBM Quantum backend and extracts:

• Coupling map
• Readout errors
• Two-qubit gate errors
• Current calibration data

It then automatically selects a high-quality hardware region for optimization.

2. Expert Layout Harvesting

Thousands of randomized Qiskit compilations are generated using different transpiler configurations.

The resulting layouts are

• Deduplicated
• Evaluated
• Ranked using a physics-based hierarchy

Priority order:

1. Minimum two-qubit gate count
2. Maximum Estimated Success Probability (ESP)
3. Minimum circuit depth

Only the highest-quality layouts are retained.

3. Graph Attention Network Training

The elite layouts are converted into graph datasets and used to train a Graph Attention Network (GATv2).

Instead of learning from random layouts, the network performs expert imitation learning, learning placement strategies directly from optimized Qiskit solutions.

4. Frequency-Aware Neural Beam Search

During inference, the trained GNN predicts promising physical qubit assignments.

A frequency-aware beam search explores multiple candidate layouts simultaneously while using hardware reliability and shortest-path heuristics to guide the search toward high-quality mappings.

5. Local Search Refinement

The highest-ranked layouts undergo simulated annealing based local search.

Each candidate is refined according to the same optimization hierarchy:

• Fewer two-qubit gates
• Higher Estimated Success Probability (ESP)
• Lower circuit depth

6. Final Qiskit Compilation

The optimized layout is passed directly into the standard Qiskit preset pass manager.

Because qcompile only improves the initial layout, all of Qiskit's existing routing and optimization passes remain unchanged.

Fast-Path Optimization

If Qiskit's optimization level 3 already produces a zero-SWAP solution, qcompile automatically bypasses the AI optimization pipeline and immediately returns the native layout.

This avoids unnecessary computation while preserving optimal compiler performance.

Performance Results

Benchmarks were performed on 30-qubit high-fidelity regions extracted from IBM's ibm_fez quantum processor.

Benchmark Configuration

• Backend: ibm_fez
• Optimization Level: 3
• Hardware Slice Size: 30 qubits
• Seed: 42
• All benchmarks were performed using identical transpiler settings, hardware slice size, and random seed for a fair comparison.

Metrics:

• Physical two-qubit gates
• Circuit depth
• Estimated Success Probability (ESP)

Left value = Standard Qiskit | Right value = qcompile

Installation

Install from PyPI

pip install qcompile

Requirements

• Python 3.10+

Or install the latest development version directly from GitHub:

git clone https://github.com/shaguntembhurne/qcompile.git

cd qcompile

pip install -e .

Quick Start

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

# Create your quantum circuit
qc = QuantumCircuit(16)

# Generate an optimized layout
ai_layout, cmap_sliced, active_nodes = get_ai_layout(
    qc,
    backend_name="ibm_fez",
    max_physical_qubits=30,
    train_samples=2500,
)

# Compile using the optimized layout
pm = generate_preset_pass_manager(
    optimization_level=3,
    coupling_map=cmap_sliced,
    initial_layout=ai_layout,
    seed_transpiler=42,
)

transpiled_qc = pm.run(qc)

Research Highlights

Unlike traditional layout optimization techniques, qcompile combines multiple AI and heuristic optimization methods into a unified compiler framework.

Core techniques include:

• Live hardware-aware optimization
• Dynamic hardware slicing
• Expert imitation learning
• Graph Attention Networks (GATv2)
• Frequency-aware Neural Beam Search
• Reliability-aware shortest-path heuristics
• Simulated annealing local refinement
• Multi-objective optimization based on:
  • Two-qubit gate count
  • Estimated Success Probability (ESP)
  • Circuit depth

Experimental

qcompile is an active research project. APIs and implementation details may evolve as new optimization techniques and hardware backends are incorporated.

Getting Help

If you encounter a bug or have a feature request, please open an issue on GitHub.

GitHub Issues: https://github.com/shaguntembhurne/qcompile/issues

Citation

If you use qcompile in academic research, please consider citing the forthcoming publication and starring the GitHub repository.

A formal BibTeX citation will be added after the associated research paper is published.

License

This project is released under the MIT License.

About

qcompile is an AI-assisted compiler extension for Qiskit that combines graph neural networks, live hardware calibration data, and heuristic optimization to improve initial qubit placement on superconducting quantum processors while remaining fully compatible with Qiskit's existing transpilation pipeline.