Metadata-Version: 2.5
Name: qb-compiler
Version: 0.14.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: record
Requires-Dist: pymatching>=2.3; extra == 'record'
Requires-Dist: scikit-learn>=1.4; extra == 'record'
Requires-Dist: stim>=1.14; extra == 'record'
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 floor](https://img.shields.io/badge/coverage%20floor-60%25-yellow)](https://github.com/mwpwalshe/qb-compiler/blob/master/pyproject.toml)
[![Docs](https://img.shields.io/badge/docs-site-blue)](https://mwpwalshe.github.io/qb-compiler/)

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

---

## 0.14: tendrils

Every vendor, format and toolkit qb-compiler can reach is now a tendril, and each one declares the
same things: what it supports, where its prices come from, where its calibration comes from, and
how far its numbers have been checked on real hardware.

```bash
qbc tendrils             # every tendril, its label, and whether a validation record covers today
qbc tendril check ibm    # the conformance check, with a receipt
```

The labels are the ones `qbc when` prints. `validated` needs a named record of a real job: date,
backend, job id and the sha256 of the result. A record covers 90 days and the listing says when it
lapsed, so IBM today reads `validated`, record `expired` since 2026-06-12.

Anyone can add a tendril without changing qb-compiler. Register an entry point in the
`qb_compiler.tendrils` group, run `qbc tendril check <name> --sign`, and the receipt is signed with
your key, not ours. See [docs/tendrils.md](docs/tendrils.md).

## 0.13: check the record before you decode it

A wrong number should never reach your results without something telling you. 0.13 closes two
places it could get through.

**Wrong QEC data.** If a QEC dataset is put together wrong, with the rounds in the wrong order for
example, the decoder still runs and still gives you a logical error rate. It is just the wrong one.
`qbc record validate` runs eight checks on how the record was built and prints what it found,
before you decode anything. In Samuel Stein's public IBM Fez repetition code release
([Zenodo 20768087](https://doi.org/10.5281/zenodo.20768087)) each register is listed highest bit
first, the order Qiskit prints it in, so the rounds come last round first. Read them as they come
and the logical error rate is 9.69 percent where the correctly built record gives 1.43 (d11, r11),
and nothing errors. Both traps, each measured on a public hardware record, with the numbers each
one leaves behind, are in [docs/record.md](docs/record.md).

**Wrong prices.** qb-compiler ranks backends by what a run will cost you. The price table was
re-checked against the vendor pages, the cost tables show the date each price was checked, and
`qbc pricing verify` checks a signed price file offline against a public key that ships in the
package.

```bash
pip install -U "qb-compiler[record]"
qbc record validate --help
```

**Running it on real data?** Tell us what it caught, or what it missed. Open a thread in
[Discussions](https://github.com/mwpwalshe/qb-compiler/discussions) or write to mike@qubitboost.io.
The first ten labs that do get a free evaluation of the QubitBoost assurance tools on their own
data.
`qbc hello` prints this note. qb-compiler reports nothing back to us, so this is the only way we
find out.

---

## 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 | a 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.

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.13.3
✔  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 on 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% | Region 120-143 |
| GHZ-10 | 78.8% | 79.8% | +1.0% | Region 120-147 |

The score is the GHZ population, P(000...0) + P(111...1) over 4096 shots. It is an upper bound on GHZ state fidelity, not the fidelity itself. Each row is one A/B pair of jobs in one calibration window, so each delta is a single measurement: the same comparison on another day can move by more than the delta. Run it on your own circuits with `qbc verify`.

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**

| | |
|---|---|
| Python | 3.10 to 3.12 |
| Qiskit | 1.0 to 1.4, and 2.3 (both legs run in CI) |
| Hardware the fidelity model is validated against | IBM Fez, Torino, Marrakesh |
| Hardware with an adapter but no validation | Rigetti Ankaa-3, IonQ, IQM, Quantinuum |

**Known pairing problem.** On qiskit 1.x with qiskit-ibm-runtime 0.40 or newer, an IBM backend can
advertise a translation plugin that the installed qiskit does not ship, and a plain `transpile`
raises `TranspilerError: Invalid plugin name` on a circuit that has nothing wrong with it. Pass
`translation_method="translator"`, or move to qiskit 2.x. `qbc doctor` detects the pairing and
prints the same workaround.

```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 |
| `qbc chem-audit <file>` | Five integrity checks on a qubit Hamiltonian: ACCEPT / INCOMPLETE / REFUSE |
| `qbc measure-plan <file>` | Terms, QWC settings and shots for that operator, before you submit |
| `qbc verify-receipt <file>` | Check a receipt signature offline against a public key |
| `qbc corpus list \| show \| verify` | Public QEC datasets, and whether your copy matches the published bytes |
| `qbc record validate \| residual \| load-fez` | How a QEC record was built, and what a feature block adds over a decoder |
| `qbc hello` | How to tell us you are running it on real data. Prints a note, sends nothing |
| `qbc tendrils` | Every vendor, format and toolkit qb-compiler reaches, its label, and whether a validation record covers today |
| `qbc tendril check <name>` | The conformance check on one tendril, or on a declaration with `--file`; `--sign` signs the receipt with your key |
| `qbc pricing show \| verify` | Vendor prices with their billing model, and a signed feed checked offline |
| `qbc when <circuit>` | Rank backends by predicted fidelity per dollar |
| `qbc dem-audit <file>` | QEC decoder-input correctness audit |

---

## 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` chooses a layout from calibration data by scoring candidates on gate error,
coherence, readout error, T1 asymmetry and temporal correlation, then picking the best via VF2
subgraph search. `selection_receipt()` turns that choice into a record somebody else can check: the
layout, its score, the per signal breakdown, the calibration fingerprint, and how old that
calibration was.

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

mapper = CalibrationMapper(backend)
result = mapper.run(circuit, {})

receipt = selection_receipt(result, calibration=backend)          # the recommendation ran

receipt = selection_receipt(                                       # something else ran
    result,
    calibration=backend,
    executed_layout={0: 6, 1: 5, 2: 4},
    scorer=functools.partial(mapper.score_layout, circuit=circuit),
)
```

Pass `executed_layout=` whenever you run a layout other than the pass's pick. The receipt then
describes what ran, keeps the recommendation in `recommended_layout`, and records what the override
cost in `score_penalty_vs_recommended`. Before 0.12.0 the receipt always named the recommendation,
so a receipt could describe a run that never happened.

`sign=True` signs with an Ed25519 key created once at `~/.qb-compiler/signing_key`, or wherever
`QBC_SIGNING_KEY` points, and the receipt carries that key's fingerprint rather than the key.
Anyone can check it offline with `qbc verify-receipt receipt.json --key their-public-key.txt`, which
needs no account, no network and no compiled crypto library.

**Receipts signed by 0.9.0 to 0.11.0 should not be treated as evidence of origin.** Those releases
generated a fresh keypair per call and embedded its public half in the receipt, so the signature
verified against a key that travelled with it. The verifier reports that shape as
`LEGACY_SELF_SIGNED` and refuses it.

Full detail: [docs/receipts.md](docs/receipts.md).
