Metadata-Version: 2.4
Name: qcompile
Version: 0.1.24
Summary: AI-guided hardware-aware quantum circuit layout optimization for Qiskit
Author-email: Shagun Tembhurne <shaxtembhurne@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/shaxtembhurne/qcompile
Project-URL: Repository, https://github.com/shaxtembhurne/qcompile
Project-URL: Issues, https://github.com/shaxtembhurne/qcompile/issues
Keywords: quantum-computing,qiskit,compiler,transpiler,layout,optimization,graph-neural-network,machine-learning
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: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: networkx
Requires-Dist: joblib
Requires-Dist: qiskit
Requires-Dist: qiskit-ibm-runtime
Requires-Dist: torch
Requires-Dist: torch-geometric

# 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:

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

---

## Quick Start

Here's a simple example to get started:

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