Metadata-Version: 2.4
Name: qcompile
Version: 0.1.25
Summary: AI-driven hardware-aware qubit placement optimizer for Qiskit using Graph Neural Networks and live IBM Quantum calibration data
Author-email: Shagun Tembhurne <shaxtembhurne@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/shaguntembhurne/qcompile
Project-URL: Repository, https://github.com/shaguntembhurne/qcompile
Project-URL: Documentation, https://github.com/shaguntembhurne/qcompile#readme
Project-URL: Issues, https://github.com/shaguntembhurne/qcompile/issues
Keywords: quantum-computing,qiskit,compiler,transpiler,layout,optimization,graph-neural-network,machine-learning,graph-attention-network,quantum-ai,hardware-aware
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: networkx>=3.0
Requires-Dist: joblib>=1.3
Requires-Dist: qiskit>=2.0
Requires-Dist: qiskit-ibm-runtime>=0.40
Requires-Dist: torch>=2.0
Requires-Dist: torch-geometric>=2.5
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"

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

![Python](https://img.shields.io/badge/Python-3.10+-blue)
![License](https://img.shields.io/badge/License-MIT-green)
![Qiskit](https://img.shields.io/badge/Qiskit-Compatible-purple)
![PyPI](https://img.shields.io/pypi/v/qcompile)
![PyPI Downloads](https://img.shields.io/pypi/dm/qcompile)

`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)

| Circuit Type | Logical Qubits | 2-Qubit Gates | Circuit Depth | Estimated Success Probability (ESP) |
| :--- | :---: | :---: | :---: | :---: |
| **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 |

**Left value = Standard Qiskit | Right value = qcompile**

---

# Installation

## Install from PyPI

```bash
pip install qcompile
```

## Requirements

- Python **3.10+**

Or install the latest development version directly from GitHub:

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

cd qcompile

pip install -e .
```

# Quick Start

```python
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.
