qb-compiler

OPEN SOURCEApache 2.0

Calibration-aware quantum compiler. Know before you run — viability checks, fidelity estimation, cost estimation, multi-vendor ranking.

Installation

bash

pip install qb-compiler                    # Core (IBM backends via Qiskit)
pip install "qb-compiler[ml]"              # + ML acceleration
pip install "qb-compiler[gnn]"             # + GNN layout predictor
pip install "qb-compiler[dev]"             # Development (tests, linting)

Requirements: Python 3.10+, Qiskit 1.0+

bash

qbc doctor    # Verify installation

Quick Start

python

from qb_compiler import QBCompiler, check_viability
from qiskit.circuit import QuantumCircuit

# Build a circuit
qc = QuantumCircuit(8)
qc.h(0)
for i in range(7):
    qc.cx(i, i + 1)
qc.measure_all()

# 1. Check viability before spending QPU time
result = check_viability(qc, backend="ibm_fez")
print(result)
# → Status: VIABLE | Est. fidelity: 0.8519 | Cost: $0.6554

# 2. Compile with calibration-aware optimizations
compiler = QBCompiler.from_backend("ibm_fez")
compiled = compiler.compile(qc, receipt=True)
print(f"Depth reduction: {compiled.depth_reduction:.1f}%")

Python API

check_viability(circuit, backend)→ViabilityResult

Top-level convenience function. Quick viability check — should you run this circuit on this backend? Returns a verdict (VIABLE / MARGINAL / DO_NOT_RUN) with fidelity estimate, cost, and actionable suggestions. No full compilation needed.

PARAMETERS

Name	Type	Req	Default	Description
circuit	QuantumCircuit	✓	—	Qiskit circuit to evaluate.
backend	str	✓	—	Backend name (e.g. "ibm_fez", "rigetti_ankaa_3").

RETURNS

Field	Type	Description
status	Enum	VIABLE, MARGINAL, or DO_NOT_RUN.
fidelity_estimate	float	Predicted fidelity (0.0–1.0).
depth	int	Circuit depth after transpilation.
two_qubit_gates	int	2-qubit gate count.
cost_4096_shots	float	Estimated cost in USD for 4096 shots.
signal_to_noise_ratio	float	SNR vs viability threshold.
suggestions	List[str]	Actionable recommendations.
confidence	float	Confidence in verdict (0.0–1.0).

EXAMPLES

python

from qb_compiler import check_viability
from qiskit.circuit import QuantumCircuit

qc = QuantumCircuit(8)
qc.h(0)
for i in range(7):
    qc.cx(i, i + 1)
qc.measure_all()

result = check_viability(qc, backend="ibm_fez")
print(result.status)            # VIABLE
print(result.fidelity_estimate) # 0.8519
print(result.cost_4096_shots)   # 0.6554

class QBCompiler(backend, optimization_level=3)

Main compiler class. Create from a backend name using the factory method or constructor.

python

# Factory method (recommended)
compiler = QBCompiler.from_backend("ibm_fez")

# Direct constructor
compiler = QBCompiler(backend="ibm_fez", optimization_level=3)

PARAMETERS

Name	Type	Req	Default	Description
backend	str	✓	—	Backend name (e.g. "ibm_fez", "rigetti_ankaa_3").
optimization_level	int	○	3	Qiskit transpiler optimization level (0–3).

compiler.compile(circuit, apply_dd=True, receipt=False, seed=None)→CompilationResult

Full calibration-aware compilation. Maps qubits to the highest-fidelity region of the backend, applies selective dynamical decoupling, and returns the compiled circuit with fidelity/cost estimates and an optional audit receipt.

PARAMETERS

Name	Type	Req	Default	Description
circuit	QuantumCircuit	✓	—	Input circuit.
apply_dd	bool	○	True	Enable selective dynamical decoupling (XY-4 sequences during idle periods).
receipt	bool	○	False	Generate a CompilationReceipt (JSON-serializable audit trail).
seed	int	○	None	Qiskit transpiler seed for reproducible layouts.

RETURNS

Field	Type	Description
circuit	QuantumCircuit	Compiled circuit ready for execution.
fidelity_estimate	FidelityEstimate	Predicted fidelity with confidence interval.
cost_estimate	float	Estimated cost in USD (4096 shots).
depth_reduction	float	Percentage depth reduction vs input circuit.
compilation_time_ms	float	Wall-clock compilation time in milliseconds.
receipt	CompilationReceipt	Audit trail (only if receipt=True).

EXAMPLES

python

from qb_compiler import QBCompiler

compiler = QBCompiler.from_backend("ibm_fez")
result = compiler.compile(circuit)

print(f"Depth reduction: {result.depth_reduction:.1f}%")
print(f"Est. fidelity: {result.fidelity_estimate.fidelity:.4f}")
print(f"Est. cost: ${result.cost_estimate:.4f}")

compiler.estimate_fidelity(circuit)→FidelityEstimate

Pre-execution fidelity prediction without full compilation. Breaks down error sources (gate error, readout error, decoherence) and identifies the dominant contributor.

PARAMETERS

Name	Type	Req	Default	Description
circuit	QuantumCircuit	✓	—	Input circuit.

RETURNS

Field	Type	Description
fidelity	float	Estimated fidelity (0.0–1.0).
confidence_interval	tuple	95% CI bounds (low, high).
dominant_error	str	"gate_error", "readout_error", or "decoherence".
breakdown	dict	Per-source error contribution (sums to 1.0).

EXAMPLES

python

estimate = compiler.estimate_fidelity(circuit)
print(f"Fidelity: {estimate.fidelity:.4f}")
print(f"95% CI: {estimate.confidence_interval}")
print(f"Dominant error: {estimate.dominant_error}")
print(f"Breakdown: {estimate.breakdown}")
# {"gate_error": 0.72, "readout": 0.18, "decoherence": 0.10}

compiler.estimate_cost(circuit, shots=4096)→float

Estimate execution cost in USD for a given shot count.

PARAMETERS

Name	Type	Req	Default	Description
circuit	QuantumCircuit	✓	—	Input circuit.
shots	int	○	4096	Number of shots.

EXAMPLES

python

cost = compiler.estimate_cost(circuit, shots=8192)
print(f"${cost:.4f}")  # $1.3108

# Compare across shot counts
for shots in [1024, 4096, 8192, 32768]:
    c = compiler.estimate_cost(circuit, shots=shots)
    print(f"{shots:>6} shots → ${c:.4f}")

compiler.recommend_backend(circuit, candidates=None)→BackendRecommendation

Rank available backends by predicted fidelity and cost for a specific circuit. Evaluates each candidate and returns a sorted recommendation with reasoning.

PARAMETERS

Name	Type	Req	Default	Description
circuit	QuantumCircuit	✓	—	Input circuit.
candidates	List[str]	○	None	Backend names to evaluate. None = all available backends.

RETURNS

Field	Type	Description
best	str	Recommended backend name.
ranked_backends	List[dict]	Sorted list: {backend, fidelity_estimate, cost_estimate, rank, reason}.

EXAMPLES

python

rec = compiler.recommend_backend(
    circuit,
    candidates=["ibm_fez", "ibm_torino", "rigetti_ankaa_3"]
)
print(f"Best: {rec.best}")
for r in rec.ranked_backends:
    print(f"  #{r['rank']} {r['backend']}: fidelity={r['fidelity_estimate']:.4f}, "
          f"cost=${r['cost_estimate']:.4f} — {r['reason']}")

Types

ViabilityResult

Returned by check_viability().

FIELDS

Field	Type	Description
status	Enum	VIABLE, MARGINAL, or DO_NOT_RUN.
fidelity_estimate	float	Predicted fidelity (0.0–1.0).
depth	int	Circuit depth after transpilation.
two_qubit_gates	int	2-qubit gate count.
cost_4096_shots	float	Estimated cost in USD for 4096 shots.
signal_to_noise_ratio	float	SNR vs viability threshold.
suggestions	List[str]	Actionable recommendations.
confidence	float	Confidence in verdict (0.0–1.0).

CompilationResult

Returned by compiler.compile().

FIELDS

Field	Type	Description
circuit	QuantumCircuit	Compiled circuit ready for execution.
fidelity_estimate	FidelityEstimate	Predicted fidelity with confidence interval.
cost_estimate	float	Estimated cost in USD (4096 shots).
depth_reduction	float	Percentage depth reduction vs input circuit.
compilation_time_ms	float	Wall-clock compilation time in milliseconds.
receipt	CompilationReceipt	Audit trail (only if receipt=True).

FidelityEstimate

Returned by compiler.estimate_fidelity().

FIELDS

Field	Type	Description
fidelity	float	Estimated fidelity (0.0–1.0).
confidence_interval	tuple	95% CI bounds (low, high).
dominant_error	str	"gate_error", "readout_error", or "decoherence".
breakdown	dict	Per-source error contribution (sums to 1.0).

BackendRecommendation

Returned by compiler.recommend_backend().

FIELDS

Field	Type	Description
best	str	Recommended backend name.
ranked_backends	List[dict]	Sorted list: {backend, fidelity_estimate, cost_estimate, rank, reason}.

CompilationReceipt

JSON-serializable audit trail. Returned by compiler.compile(receipt=True).

python

receipt = result.receipt
receipt.save("my_circuit.receipt.json")

CLI Reference

$qbc preflightcircuit.qasm -b ibm_fez

Quick viability check. Returns VIABLE/CAUTION/DO NOT RUN verdict, estimated fidelity, cost for 4096 shots, and actionable suggestions. Run this before every hardware job.

$qbc compilecircuit.qasm -b ibm_fez --receipt

Full calibration-aware compilation. Output: compiled circuit, depth reduction %, fidelity estimate, cost. Use --receipt for JSON audit trail.

$qbc analyzecircuit.qasm -b ibm_fez

Detailed calibration overlay analysis. Shows qubit quality heatmap, bottleneck report, SNR vs threshold, mitigation suggestions.

$qbc diffcircuit.qasm -b ibm_fez --vs ibm_torino

Side-by-side backend comparison. Shows fidelity delta, cost delta, and recommendation.

$qbc calibration showibm_fez

Display current calibration data: gate errors, T1/T2 times, readout errors, qubit count, topology.

$qbc doctor

Environment diagnostics: qb-compiler version, Qiskit version, backend credentials, calibration data freshness.

Notebooks

Interactive deep dives. Download and run locally with pip install qb-compiler[ml]

Preflight & Viability Checks

Check if your circuit should run before spending QPU time. VIABLE/MARGINAL/DO_NOT_RUN verdicts, SNR analysis, actionable suggestions.

01_preflight_viability.ipynb

Compilation & Audit Receipts

Calibration-aware compilation walkthrough. Depth reduction vs Qiskit opt_level=3, JSON receipts for reproducibility.

02_compilation_receipts.ipynb

Multi-Vendor Backend Ranking

Rank IBM, Rigetti, IonQ, IQM backends. Cost vs fidelity Pareto, vendor-specific gate set comparison.

03_multi_vendor_ranking.ipynb

Selective Dynamical Decoupling

When DD helps and when it hurts. XY-4 sequence insertion, auto-skip for dense circuits.

04_dynamical_decoupling.ipynb

Fidelity Estimation Deep Dive

Error source breakdown (gate, readout, decoherence), confidence intervals, dominant error identification.

05_fidelity_estimation.ipynb

Cost Estimation & Budgeting

Per-vendor cost models, shot count optimization, budget planning for multi-circuit experiments.

06_cost_estimation.ipynb

Calibration Data & Snapshots

Load calibration snapshots, inspect gate errors, T1/T2 times, readout errors across backends.

07_calibration_data.ipynb

Qiskit Integration

Drop-in replacement for Qiskit transpile(). PassManager integration, circuit conversion.

08_qiskit_integration.ipynb

ML Layout Prediction

ML-accelerated qubit layout selection. Feature extraction, model comparison, GNN predictor.

09_ml_layout_prediction.ipynb

Circuit IR & Analysis

Internal representation, gate decomposition, circuit statistics, IR-level optimizations.

10_circuit_ir.ipynb

Compilation Strategies

Fidelity-optimal, depth-optimal, budget-optimal strategies. Custom strategy configuration.

11_compilation_strategies.ipynb

Error Handling & Diagnostics

Graceful degradation, detailed error messages, retry patterns, diagnostic utilities.

12_error_handling.ipynb

QubitBoost SDK Integration

Use qb-compiler as the compilation backend for the full QubitBoost SDK pipeline.

13_qubitboost_integration.ipynb

Backend Deep Dive

Topology inspection, native gate sets, qubit quality heatmaps, connectivity graphs.

14_backend_deep_dive.ipynb

CLI Workflows & Automation

qbc CLI commands, batch processing, CI/CD integration, pre-commit hooks.

15_cli_workflows.ipynb

Real-World Pipelines

End-to-end compilation pipelines for QEC, VQE, QAOA, and tomography workloads.

16_real_world_pipelines.ipynb

Supported Backends

Vendor	Backends	Qubits	Native Gates	Connectivity
IBM (Heron)	Fez, Torino, Marrakesh	133–156	ECR, RZ, SX	Heavy hex
Rigetti	Ankaa-3	84	CZ, RZ, RX	Square octagon
IonQ	Aria, Forte	25–36	MS, GPI, GPI2	Full (trapped-ion)
IQM	Garnet, Emerald	5–20	CZ, PRX	Tunable
Quantinuum	H2	32	RZ, U1Q, ZZ	Linear chain

Qiskit Transpiler Plugins

qb-compiler registers 4 custom passes with Qiskit's transpiler plugin system.

Pass	Purpose	Mutating
CalibrationMapperPass	Layout + routing with calibration data	Yes
SelectiveDDPass	Post-routing dynamical decoupling insertion	Yes
FidelityEstimatorPass	Fidelity scoring (analysis only)	No (analysis)
CostEstimatorPass	Cost calculation (analysis only)	No (analysis)

Documentation

PyPI: pip install qb-compilerMarketing page →