Metadata-Version: 2.4
Name: qb-compiler
Version: 0.10.0
Summary: Quantum execution intelligence. Circuit viability, backend recommendation, cost estimation, and automatic optimizations for quantum computing.
Project-URL: Homepage, https://qubitboost.io/compiler
Project-URL: Documentation, https://mwpwalshe.github.io/qb-compiler/
Project-URL: Repository, https://github.com/mwpwalshe/qb-compiler
Project-URL: Issues, https://github.com/mwpwalshe/qb-compiler/issues
Project-URL: Changelog, https://github.com/mwpwalshe/qb-compiler/blob/master/CHANGELOG.md
Author-email: QubitBoost <mike@qubitboost.io>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: calibration,compiler,error-correction,noise-aware,qec,qiskit,quantum,quantum-computing,qubitboost,transpiler
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Compilers
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.25
Requires-Dist: numpy<3.0,>=1.24
Requires-Dist: pydantic>=2.0
Requires-Dist: qiskit<3.0,>=1.0
Requires-Dist: rich>=13.0
Requires-Dist: rustworkx>=0.14
Provides-Extra: all
Requires-Dist: amazon-braket-sdk>=1.60; extra == 'all'
Requires-Dist: azure-quantum>=2.0; extra == 'all'
Requires-Dist: cirq>=1.3; extra == 'all'
Requires-Dist: iqm-client>=17.0; extra == 'all'
Requires-Dist: pennylane>=0.35; extra == 'all'
Requires-Dist: pymatching>=2.3; extra == 'all'
Requires-Dist: pyquil>=4.0; extra == 'all'
Requires-Dist: pytket-quantinuum>=0.30; extra == 'all'
Requires-Dist: qiskit-ibm-runtime>=0.20; extra == 'all'
Requires-Dist: qiskit-qasm3-import>=0.5; extra == 'all'
Requires-Dist: qubitboost-sdk>=2.4; extra == 'all'
Requires-Dist: scikit-learn>=1.4; extra == 'all'
Requires-Dist: stim>=1.14; extra == 'all'
Requires-Dist: torch>=2.0; extra == 'all'
Requires-Dist: xgboost>=2.0; extra == 'all'
Provides-Extra: azure
Requires-Dist: azure-quantum>=2.0; extra == 'azure'
Provides-Extra: cirq
Requires-Dist: cirq>=1.3; extra == 'cirq'
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: myst-parser>=3.0; extra == 'dev'
Requires-Dist: nbsphinx>=0.9; extra == 'dev'
Requires-Dist: pre-commit>=3.6; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest-mock>=3.12; extra == 'dev'
Requires-Dist: pytest-timeout>=2.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: qiskit-aer>=0.15; extra == 'dev'
Requires-Dist: qiskit-sphinx-theme>=2.0; extra == 'dev'
Requires-Dist: ruff<0.16,>=0.15.0; extra == 'dev'
Requires-Dist: scikit-learn>=1.4; extra == 'dev'
Requires-Dist: sphinx>=7.0; extra == 'dev'
Requires-Dist: torch>=2.0; extra == 'dev'
Requires-Dist: xgboost>=2.0; extra == 'dev'
Provides-Extra: gnn
Requires-Dist: torch>=2.0; extra == 'gnn'
Provides-Extra: ibm
Requires-Dist: qiskit-ibm-runtime>=0.20; extra == 'ibm'
Provides-Extra: ionq
Requires-Dist: amazon-braket-sdk>=1.60; extra == 'ionq'
Provides-Extra: iqm
Requires-Dist: iqm-client>=17.0; extra == 'iqm'
Provides-Extra: ising
Requires-Dist: pymatching>=2.3; extra == 'ising'
Requires-Dist: stim>=1.14; extra == 'ising'
Provides-Extra: ising-nvidia
Requires-Dist: pymatching>=2.3; extra == 'ising-nvidia'
Requires-Dist: safetensors>=0.4; extra == 'ising-nvidia'
Requires-Dist: stim>=1.14; extra == 'ising-nvidia'
Requires-Dist: torch>=2.0; extra == 'ising-nvidia'
Provides-Extra: ml
Requires-Dist: scikit-learn>=1.4; extra == 'ml'
Requires-Dist: xgboost>=2.0; extra == 'ml'
Provides-Extra: pennylane
Requires-Dist: pennylane>=0.35; extra == 'pennylane'
Provides-Extra: qasm3
Requires-Dist: qiskit-qasm3-import>=0.5; extra == 'qasm3'
Provides-Extra: quantinuum
Requires-Dist: pytket-quantinuum>=0.30; extra == 'quantinuum'
Provides-Extra: qubitboost
Requires-Dist: qubitboost-sdk>=2.4; extra == 'qubitboost'
Provides-Extra: rigetti
Requires-Dist: pyquil>=4.0; extra == 'rigetti'
Description-Content-Type: text/markdown

# qb-compiler

[![Qiskit Ecosystem](https://img.shields.io/badge/Qiskit%20Ecosystem-Member-6929C4?logo=Qiskit)](https://www.ibm.com/quantum/ecosystem)
[![PyPI](https://img.shields.io/pypi/v/qb-compiler.svg)](https://pypi.org/project/qb-compiler/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)
[![Tests](https://github.com/mwpwalshe/qb-compiler/actions/workflows/ci.yml/badge.svg)](https://github.com/mwpwalshe/qb-compiler/actions)
[![Coverage](https://img.shields.io/badge/coverage-60%25-yellow)]()
[![Docs](https://img.shields.io/badge/docs-README-blue)](https://github.com/mwpwalshe/qb-compiler#readme)

**Quantum Execution Intelligence. Know before you run.**

---

## What is qb-compiler?

qb-compiler helps quantum developers make better execution decisions. Know which backend to use, whether your circuit is viable, what fidelity to expect, and what it will cost, before you spend QPU time.

Built on top of Qiskit's transpiler.

```bash
pip install qb-compiler
```

---

## Quick Start

```python
from qb_compiler import QBCompiler, check_viability

# Is my circuit worth running?
result = check_viability(circuit, backend="ibm_fez")
print(result)
# → Status: VIABLE
# → Est. fidelity: 0.847
# → Cost (4096 shots): $0.6554
# → Suggestions:
# →   - Circuit looks good, proceed with execution.

# Compile with automatic optimizations
compiler = QBCompiler.from_backend("ibm_fez")
compiled = compiler.compile(circuit)
```

---

## v0.7: trust the number

Every estimate now tells you how much to trust it, the tool keeps receipts, and you can check it
against hardware yourself.

**What's new**

| capability | what you get |
|---|---|
| Error budget | preflight shows WHERE fidelity goes: two-qubit gates vs readout, pct of loss |
| Honest band | every fidelity estimate carries a typical-error band with stated provenance |
| Calibration age | preflight warns when its snapshot is stale, shows the age |
| Verify mode | `qbc verify`: mirror-circuit check of the prediction, builds a local accuracy log |
| Receipts | a passport per compile: versions, calibration age, prediction + band, error budget |
| Regression watch | flags when YOUR circuit compiles worse than your own history, beyond noise |
| Best-of-N | `qb_transpile(n_seeds=5)`: seed sweep scored by calibrated fidelity, evidence attached |
| Fidelity per dollar | `qbc when`: rank backends by predicted fidelity per dollar, with trend |
| Shot budgets | how many shots to resolve your observable or error rate, before you pay |
| QEC preflight | projected LER band + shot bill for a memory experiment, from calibration |
| Backend discovery | rank whatever backends your own credentials expose |
| NVIDIA Ising onramp | the only Qiskit-side bridge to the Ising decoder family, with telemetry |

**Fidelity estimate accuracy, measured on hardware**

Predicted vs measured on IBM Fez (GHZ family, 4096 shots, March 2026):

| circuit | predicted | measured | delta |
|---|---|---|---|
| GHZ-5 (qb layout) | 0.948 | 0.931 | +0.017 |
| GHZ-5 (qiskit layout) | 0.947 | 0.920 | +0.027 |
| GHZ-8 (qb layout) | 0.905 | 0.856 | +0.049 |
| GHZ-8 (qiskit layout) | 0.905 | 0.863 | +0.042 |
| GHZ-10 (qb layout) | 0.874 | 0.793 | +0.081 |
| GHZ-10 (qiskit layout) | 0.874 | 0.808 | +0.067 |

Median absolute error 0.045; the model runs optimistic by about +0.05 (it prices gate and readout
error, not crosstalk or idle decoherence). That is why every estimate prints with a +-0.05 band and
why `qbc verify` exists: check it on your own circuits, the log stays on your machine.

**Example: a real run vs the projection**

50,000-shot distance-3 surface code memory run on ibm_fez, April 2026:

| | LER |
|---|---|
| projected (uniform gate-error proxy at the day's calibration) | 0.005 to 0.059 |
| measured, full run | 0.245 |
| measured, first 25k shots | 0.129 |
| measured, second 25k shots | 0.361 |

The device drifted 2.8x inside the job, and the proxy doesn't model crosstalk, leakage or drift, so
the projection undershoots by 5-50x. This is the case the calibration age warning, the regression
watch and verify mode exist for.

Notebooks 19 and 20 walk through everything with live outputs. Everything here is signals only,
nothing gates or blocks your jobs.

## CLI

### `qbc preflight`. Should I run this?

```
$ qbc preflight circuit.qasm --backend ibm_fez

  Circuit: GHZ-8
  Backend: ibm_fez (156q)

  Status: VIABLE
  Estimated fidelity: 0.8519
  Depth: 12  (viable limit: 188)
  2Q gates: 7
  Cost (4096 shots): $0.6554
```

### `qbc analyze`. Detailed analysis with suggestions

```
$ qbc analyze circuit.qasm --backend ibm_fez

  Circuit Analysis: QAOA-MaxCut
  Qubits: 6  Gates: 84  Depth: 47
  Gate breakdown: cx:24, rz:18, rx:12, h:6, measure:6

  Backend: ibm_fez (156q)
  Status: MARGINAL
  Estimated fidelity: 0.1823
  Signal/noise ratio: 11.7x
  Depth: 47  (viable limit: 188)
  2Q gates after transpilation: 24
  Cost (4096 shots): $0.6554

  Suggestions:
    - Consider ZNE or PEC error mitigation (2-5x improvement possible).
    - Good candidate for error mitigation to further improve results.
```

### `qbc diff`. Compare two backends

```
$ qbc diff circuit.qasm --backend ibm_fez --vs ibm_torino

  Circuit: GHZ-5

                              ibm_fez        ibm_torino
                           ----------------   ----------------
  Status                          VIABLE           VIABLE
  Est. fidelity                  0.9430           0.9285 <
  2Q gates                            4                4
  Depth                               5                5
  Cost/4096 shots              $0.6554          $0.5734 <

  Recommendation: ibm_fez (+0.0145 fidelity)
```

### `qbc doctor`. Environment health check

```
$ qbc doctor

qbc doctor

✔  qb-compiler 0.9.0
✔  Python 3.11.14
✔  Qiskit 1.4.5
✔  IBM credentials configured (2 account(s))
✔  9 backends configured
✔  5 calibration snapshot(s) available
✔  numpy 2.3.5
✔  rustworkx 0.17.1

Environment looks good!
```

### `qbc compile`. Compile with receipt

```
$ qbc compile circuit.qasm --backend ibm_fez --receipt

Compiled: depth 12 -> 8 (33.3% reduction)
Estimated fidelity: 0.8519
Compilation time: 142.3 ms
Receipt saved to circuit.receipt.json
```

### `qbc dem-audit`. QEC decoder-input correctness preflight (ObservableGate)

A stim Detector Error Model (DEM) error mechanism carries detectors, logical-observable masks, and a
probability. If a DEM-to-matrix step merges mechanisms by detector signature alone, two mechanisms that
are detector-identical but logical-distinct collapse and the logical mask is lost, which can inflate the
logical error rate. `dem-audit` detects this before decoding (CI-safe exit codes), and `dem-canonicalize`
writes an observable-preserving canonical form.

```
$ qbc dem-audit model.dem
ObservableGate DEM audit
  raw mechanisms             : 2
  unique detector signatures : 1
  unique detector+obs masks  : 2
  mixed detector groups      : 1
  status: FAIL
  recommendation: detector-identical mechanisms carry conflicting masks; canonicalize by
  (detectors, observables) or preserve P(L|H), never merge by detector alone.
# exit code: 0 = PASS, 1 = WARN (--strict), 2 = FAIL

$ qbc dem-canonicalize model.dem -o safe.dem
```

Scope (honest): standard production paths are safe: surface/repetition and the full bivariate-bicycle /
Gross family ([[72,12,6]] … [[144,12,12]] … [[288,12,18]], X and Z basis) audit PASS; decomposed DEMs are
XOR-benign. The hazard is real and measured on graphlike DEMs with genuine detector-identical /
logical-distinct mechanisms. See [docs/observablegate.md](docs/observablegate.md).

ObservableGate and its `--json` receipts are free and open source. Signed receipts, batch reports, shared
dashboards, and CI policy bundles are part of QubitBoost Pro, see [docs/open-core.md](docs/open-core.md).

---

## Feature Comparison

| Feature | Qiskit | qb-compiler |
|---------|--------|-------------|
| Transpilation | Excellent | Uses Qiskit internally |
| Circuit viability check | No | `qbc preflight` |
| Pre-execution fidelity estimate | No | Yes |
| Backend recommendation | No | Yes |
| Selective dynamical decoupling | No | Yes |
| Cost estimation | No | Yes |
| Budget enforcement | No | Yes |
| Compilation receipts | No | `--receipt` |
| Multi-vendor backend specs | IBM only | IBM, Rigetti, IonQ, IQM, Quantinuum |
| Environment health check | No | `qbc doctor` |
| Circuit analysis with suggestions | No | `qbc analyze` |
| Backend comparison | No | `qbc diff` |

---

## Hardware Validation

Validated on IBM Fez (156 qubits, March 2026). All results are measured fidelity from real hardware, 4096 shots per circuit.

### Layout Selection. GHZ Circuits

qb-compiler's CalibrationMapper (post-routing scoring, multi-region search) vs Qiskit `transpile` `optimization_level=3`. Both use Qiskit's SabreSwap for routing, the only difference is initial qubit placement.

| Circuit | Qiskit | qb-compiler | Delta | Notes |
|---------|--------|-------------|-------|-------|
| GHZ-3 | 96.5% | 96.7% | +0.2% | Both find optimal region |
| GHZ-5 | 92.5% | 93.2% | +0.7% | Different regions selected |
| GHZ-8 | 82.1% | 87.5% | **+5.3%** | Best result, region 120-143 |
| GHZ-10 | 78.8% | 79.8% | +1.0% | Region 120-147 |

Fidelity = P(000...0) + P(111...1) over 4096 shots.

Results vary by calibration window. In runs where both mappers converge on the same optimal region (identical qubit selection), results are statistically equivalent. Improvement is largest when qb-compiler discovers a better region than Qiskit's default search.

### Dynamical Decoupling

Selective DD applied after Qiskit routing. DD is automatically skipped for dense circuits where it adds noise without benefit.

| Circuit | Without DD | With DD | Delta | Notes |
|---------|-----------|---------|-------|-------|
| GHZ-8 | 83.5% | 83.6% | +0.1% | Minimal idle time |
| QFT-6 | 2.1% | 2.6% | +27% rel. | Long idle periods. DD helps |
| QAOA-6 | 5.9% | 5.5% | -6.6% rel. | Dense circuit. DD skipped in v0.2.1 |

QFT-6 and QAOA-6 base fidelities are in the noise floor (circuit depth exceeds viable limit). `qbc preflight` would flag these as DO NOT RUN, saving QPU time.

### Journey to These Results

These results followed an iterative hardware validation process:

1. Initial mapper lost to Qiskit by up to 10.6% (pre-routing scoring flaw)
2. Post-routing scoring fix closed the gap
3. Multi-region search + routed fidelity tiebreaker achieved positive results
4. Qiskit seed injection ensures qb-compiler never selects a worse layout than Qiskit's own best

All raw validation data is in the `results/` directory. Reproduce: `python scripts/hardware_validation.py --dry-run`

Full walkthrough: [docs/tutorials/hardware_validation_walkthrough.ipynb](docs/tutorials/hardware_validation_walkthrough.ipynb)

---

## How It Works

```
Your Circuit
  │
  ├─→ Viability Check         Is it worth running?
  │
  ├─→ Backend Selection        Where should it run?
  │
  ├─→ Qiskit Transpilation     Best of N seeds, opt_level=3
  │
  ├─→ Selective DD             Protect idle qubits (skip dense circuits)
  │
  ├─→ Fidelity Estimation      What to expect
  │
  ├─→ Cost Estimation          What it will cost
  │
  └─→ Compilation Receipt      Full audit trail (JSON)
```

All transpilation uses Qiskit's routing engine internally. qb-compiler's value is in execution intelligence (preflight, viability, cost estimation) and calibration-aware layout selection. Performance vs Qiskit `optimization_level=3` is workload-dependent: qb-compiler v0.5.1 wins on QAOA-style and VQE chemistry workloads (UCCSD-H4 4e4o: +12% estimated fidelity vs Qiskit, p<0.05 paired Wilcoxon, n=30 seeds, IBM Fez calibration), ties or marginally underperforms on simple GHZ circuits where Qiskit's own VF2 layout is already strong. Full benchmark + raw data in CHANGELOG v0.5.1.

---

## Additional integrations

Beyond the core calibration-aware compiler, qb-compiler ships two opt-in
integrations. Neither loads unless you install the matching extra; the
core `pip install qb-compiler` doesn't pull these dependencies.

### Live calibration via QubitBoost SDK (v0.5+)

```bash
pip install qb-compiler[qubitboost]
```

Replaces the static-fixture calibration path with a live fetch from IBM
Quantum (or other vendor APIs as they're added). Auto-refreshes every 30
min, falls back to stale cache with a `UserWarning` on vendor outages.
See `LiveCalibrationProvider` in `qb_compiler.calibration.live_provider`.

Optional companion gates from the QubitBoost SDK (adaptive shot reduction
for QAOA, evaluation reduction for VQE, runtime execution checks) are
surfaced as recommendations in `qbc preflight` / `qbc analyze` when the
circuit type is detected. qb-compiler reports which gates are eligible for a
given circuit and attaches no performance figure to them. See
[qubitboost.io](https://qubitboost.io) for the SDK itself.

### NVIDIA Ising Decoder onramp (v0.4.0b1, beta)

```bash
pip install --pre qb-compiler[ising]          # stim + pymatching baseline
pip install --pre qb-compiler[ising-nvidia]   # adds torch + safetensors
```

First Qiskit-side onramp to NVIDIA's `Ising-Decoder-SurfaceCode-1`
(released 2026-04-14). Takes a rotated surface-code memory experiment,
emits the 4-channel `(B, 4, T, D, D)` tensor the pretrained decoder
consumes. A PyMatching MWPM baseline ships in the package; bring your
own NVIDIA gated weights (Apache 2.0 integration code; NVIDIA Open Model
License weights distributed separately by NVIDIA). Stim-validated only,
no hw shots through it yet.

```python
from qb_compiler.ising import (
    SurfaceCodePatchSpec, PyMatchingDecoder, evaluate_logical_error_rate,
)
spec = SurfaceCodePatchSpec(distance=7, rounds=7, basis="X", p_error=0.003)
result = evaluate_logical_error_rate(
    spec, PyMatchingDecoder(spec), shots=50_000, seed=42,
)
```

Full API + walkthrough: [`src/qb_compiler/ising/README.md`](src/qb_compiler/ising/README.md)
and [Notebook 17](notebooks/17_nvidia_ising_integration.ipynb).

---

## Supported Backends

| Vendor     | Backends                       | Qubits  | Native Basis  |
|------------|--------------------------------|---------|---------------|
| IBM        | Fez, Torino, Marrakesh (Heron) | 133-156 | ECR, RZ, SX   |
| Rigetti    | Ankaa-3                        | 84      | CZ, RZ, RX    |
| IonQ       | Aria, Forte                    | 25-36   | MS, GPI, GPI2 |
| IQM        | Garnet, Emerald                | 5-20    | CZ, PRX       |
| Quantinuum | H2                             | 32      | RZ, U1Q, ZZ   |

Calibration data can be loaded from local JSON files OR fetched live from vendor APIs via `LiveCalibrationProvider`. The live path requires `pip install qb-compiler[qubitboost]` and a saved IBM-credentials profile; see Quick Start for the live-fetch workflow.

---

## Installation

**Compatibility:** Qiskit 1.0-1.4 | Python 3.10-3.12 | Tested on IBM Fez, Torino, Marrakesh, Rigetti Ankaa-3

```bash
# Core (IBM backends via Qiskit)
pip install qb-compiler

# With ML acceleration (optional)
pip install "qb-compiler[ml]"

# With GNN layout predictor (optional)
pip install "qb-compiler[gnn]"

# Development
pip install "qb-compiler[dev]"
```

---

## CLI Reference

| Command | Description |
|---------|-------------|
| `qbc preflight <circuit> -b <backend>` | Quick viability check: VIABLE / CAUTION / DO NOT RUN |
| `qbc analyze <circuit> -b <backend>` | Detailed analysis with suggestions |
| `qbc diff <circuit> -b <backend> --vs <backend>` | Side-by-side backend comparison |
| `qbc doctor` | Environment health check |
| `qbc compile <circuit> -b <backend> --receipt` | Compile with audit trail |
| `qbc info` | Show version and available backends |
| `qbc calibration show <backend>` | Show calibration summary |

---

## Contributing

Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

```bash
pip install "qb-compiler[dev]"
pytest
```

---

## License

Apache License 2.0. See [LICENSE](LICENSE) for the full text.

Copyright 2026 QubitBoost.

## Selection receipts

`CalibrationMapper` already chooses a layout from live calibration by scoring candidates on gate
error, coherence (T1/T2), readout error, T1 asymmetry, and temporal correlation, then picking the
best via VF2 subgraph search. `selection_receipt()` turns that choice into an auditable record: the
chosen layout, its score, the per-signal breakdown, and a stable calibration fingerprint. The check
is free; the signed, stored receipt is the product.

```python
from qb_compiler.passes.mapping import CalibrationMapper, selection_receipt

mapper = CalibrationMapper(backend)          # backend: BackendProperties (live calibration)
result = mapper.run(circuit, {})
receipt = selection_receipt(result, calibration=backend)   # unsigned dict
```

`sign=True` produces an Ed25519-signed receipt when the QubitBoost SDK is installed, and otherwise
degrades to an unsigned receipt with a pointer, never raising. Signing lives in the paid layer; the
receipt itself is Apache-2.0 with zero paid-SDK dependency.
