qb-compiler
Quantum Execution Intelligence
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. v0.8.0 adds ObservableGate, a QEC decoder-input correctness audit for stim Detector Error Models.
KNOW BEFORE YOU RUN
qb-compiler helps quantum developers make better execution decisions.
Viability Check
Is your circuit worth running? Get a VIABLE / CAUTION / DO NOT RUN verdict with fidelity estimate and cost before you submit.
Multi-Vendor
IBM, AWS Braket, Rigetti, IonQ, IQM, Quantinuum from one API. Compare backends side-by-side. Budget-aware compilation with cost estimation.
Smart Optimizations
Selective dynamical decoupling that knows when to skip. Calibration-aware layout. Compilation receipts for full audit trails.
OBSERVABLEGATE
NEW · v0.8.0A QEC decoder-input correctness audit. A stim Detector Error Model error mechanism carries both detector targets and logical-observable masks. If a DEM-to-matrix step merges mechanisms by detector signature alone, it can collapse detector-identical, logical-distinct mechanisms and erase the logical frame, inflating the reported logical error rate. ObservableGate flags it and offers an observable-preserving canonicalization. CI-safe: PASS / WARN / FAIL.
$ qbc dem-audit model.dem
ObservableGate: PASS
groups: 482 mixed (detector-identical, observable-distinct): 0
verdict: no observable-mask collapse risk
# observable-preserving canonicalization
$ qbc dem-canonicalize model.dem -o safe.dem
merged exact (detector, observable) duplicates
kept distinct logical masks separate -> safe.demWhat it catches
Two mechanisms can be detector-identical but logical-distinct. A merge keyed on the detector signature alone drops or arbitrarily picks the logical mask, which is not a semantics-preserving operation. ObservableGate keeps the distinct (detector, observable) columns.
Honest scope
Standard surface, repetition and Bivariate-Bicycle / Gross codes audit PASS, the qLDPC codes teams actually run are observable-mask safe. ObservableGate is a preflight invariant that catches the edge case at the DEM boundary. It is not a claim that any decoder or library is broken.
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)CLI
Five commands for quantum execution intelligence from your terminal
qbc preflight
· Should I run this?$ qbc preflight circuit.qasm -b ibm_fez
Circuit: GHZ-8 Backend: ibm_fez (156q)
Status: VIABLE
Est. fidelity: 0.8519
Depth: 12 (viable limit: 188)
2Q gates: 7
Cost (4096 shots): $0.6554qbc analyze
· Detailed analysis$ qbc analyze circuit.qasm -b ibm_fez
Circuit: QAOA-MaxCut
Qubits: 6 Gates: 84 Depth: 47
Status: MARGINAL
Est. fidelity: 0.1823
Signal/noise: 11.7x
Cost (4096 shots): $0.6554
Suggestions:
- Consider ZNE or PEC error mitigation
- Good candidate for 2-5x improvementqbc diff
· Compare backends$ qbc diff circuit.qasm -b ibm_fez --vs ibm_torino
Circuit: GHZ-5
ibm_fez ibm_torino
Status VIABLE VIABLE
Fidelity 0.9430 0.9285
Cost/4096 $0.6554 $0.5734
Recommendation: ibm_fez (+0.0145)qbc doctor
· Health check$ qbc doctor
✔ qb-compiler 0.8.0
✔ Python 3.11.14
✔ Qiskit 1.4.5
✔ IBM credentials (2 accounts)
✔ 9 backends configured
✔ 5 calibration snapshots
Environment looks good!qbc compile
· With receipt$ qbc compile circuit.qasm -b ibm_fez --receipt
Compiled: depth 12 -> 8 (33.3%)
Est. fidelity: 0.8519
Time: 142.3 ms
Receipt: circuit.receipt.jsonFEATURE COMPARISON
qb-compiler vs standard Qiskit transpiler
| Feature | Qiskit | qb-compiler |
|---|---|---|
| Transpilation | Yes | Uses Qiskit internally |
| Circuit viability check | - | qbc preflight |
| Pre-execution fidelity estimate | - | Yes |
| Backend recommendation | - | Yes |
| Selective dynamical decoupling | - | Yes |
| Cost estimation | - | Yes |
| Budget enforcement | - | Yes |
| Compilation receipts | - | --receipt |
| QEC decoder-input audit (DEM) | - | qbc dem-audit |
| Multi-vendor backends | IBM only | IBM, AWS Braket, Rigetti, IonQ, IQM, Quantinuum |
| Environment health check | - | qbc doctor |
| Circuit analysis + suggestions | - | qbc analyze |
| Backend comparison | - | qbc diff |
HARDWARE VALIDATION
IBM Fez (156 qubits, March 2026). All results are measured fidelity from real hardware runs with 4096 shots.
Layout Selection: GHZ Circuits
CalibrationMapper (post-routing scoring, multi-region search) vs Qiskit opt_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. Improvement is largest when qb-compiler discovers a better region than Qiskit's default search. When both converge on the same optimal region, results are statistically equivalent.
Dynamical Decoupling
Selective DD applied after Qiskit routing. Automatically skipped for dense circuits where it adds noise.
| 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, DD skipped in v0.2.1 |
QFT-6 and QAOA-6 base fidelities are in the noise floor (depth exceeds viable limit).qbc preflight would flag these as DO NOT RUN, saving QPU time.
Journey to These Results
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
Reproduce: python scripts/hardware_validation_v2.py --dry-run
HOW IT WORKS
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 that matches or exceeds Qiskit's default on hardware-validated benchmarks.
SUPPORTED BACKENDS
| Vendor | Backends | Qubits | Native Basis |
|---|---|---|---|
| IBM | Fez, Torino, Marrakesh (Heron) | 133-156 | ECR, RZ, SX |
| AWS Braket | Rigetti, IonQ, IQM, OQC (adding live device data) | varies | per-device |
| 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 loaded from local JSON files or fetched from vendor APIs.
OPEN SOURCE vs QUBITBOOST PRO
| Feature | Open Source | QubitBoost Pro |
|---|---|---|
| Single-backend preflight | Yes | Yes |
| ObservableGate DEM audit | Yes | Yes |
| Local JSON receipts + CI exit codes | Yes | Yes |
| Multi-backend ranking | - | Yes |
| Cached calibration | Yes | Live calibration |
| Cost estimation | Single vendor | Cross-vendor |
| Signed + stored receipts | - | Yes |
| Batch reports + shared dashboards | - | Yes |
| CI policy bundles | - | Yes |
| Drift alerts + circuit watchlist | - | Yes |
qb-compiler is free and fully functional standalone. QubitBoost Pro adds live multi-vendor calibration, cloud execution history, and advanced optimizations.
INSTALLATION
pip install qb-compilerCore (IBM backends via Qiskit)pip install "qb-compiler[ml]"+ ML acceleration (optional)pip install "qb-compiler[gnn]"+ GNN layout predictor (optional)pip install "qb-compiler[dev]"DevelopmentCLI 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 dem-audit <model.dem> | ObservableGate: audit a stim DEM for observable-mask collapse (PASS / WARN / FAIL) |
| qbc dem-canonicalize <model.dem> -o <out.dem> | Observable-preserving canonicalization |
| qbc info | Show version and available backends |
| qbc calibration show <backend> | Show calibration summary |
OPEN SOURCE
Apache 2.0. Contributions welcome.
See CONTRIBUTING.md for guidelines.
FULL EXECUTION LIFECYCLE
PRE-EXECUTION
qb-compiler
Free and open source. Apache 2.0.
EXECUTION & POST-EXECUTION
QubitBoost SDK
Available at qubitboost.io
Together they cover the complete quantum execution lifecycle.