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.

pip install qb-compiler

Quick Start

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

Fidelity estimate accuracy, measured on hardware

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

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:

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.

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.

Feature Comparison

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.

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.

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

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

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 for the SDK itself.

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

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.

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 and Notebook 17.

Supported Backends

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

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.

# 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

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

pip install "qb-compiler[dev]"
pytest

License

Apache License 2.0. See 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.

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.