FAQ & Troubleshooting

General Questions

What does qb-compiler do that Qiskit’s transpiler doesn’t?

Qiskit’s transpiler maps circuits using topology only — it knows which qubits are connected but not how noisy each qubit/gate is. qb-compiler uses today’s calibration data (T1, T2, gate error, readout error) to select the best physical qubits. This typically improves estimated fidelity by 2–5%.

Do I need a QubitBoost account?

No. The open-source core works with calibration snapshots (JSON files). You can use the shipped test fixtures or capture your own from vendor APIs. A QubitBoost account is only needed for the LiveCalibrationProvider which fetches real-time calibration data.

Which backends are supported?

IBM (Fez, Torino, Marrakesh), Rigetti (Ankaa-3), IonQ (Aria, Forte), and IQM (Garnet, Emerald). See qbc info for the full list.

What Python versions are supported?

Python 3.10, 3.11, and 3.12.

Is qb-compiler a replacement for Qiskit?

No. qb-compiler sits on top of Qiskit. It adds calibration-aware passes to the compilation pipeline. You still use Qiskit for circuit construction and job submission.

Calibration Questions

How do I get calibration data?

Three options:

  1. Test fixtures — qb-compiler ships with calibration snapshots in tests/fixtures/calibration_snapshots/. These are real data captured from IBM and Rigetti devices.

  2. Capture your own — Use your vendor’s API to download calibration data and save as JSON. Set QBC_CALIBRATION_DIR to point at your snapshot directory.

  3. Live feed — Install qubitboost-sdk and use LiveCalibrationProvider for real-time data.

How old can calibration data be?

Calibration data is valid for 4–24 hours on superconducting devices (IBM, Rigetti, IQM). Trapped-ion devices (IonQ) have more stable calibration. The CachedCalibrationProvider can enforce staleness limits.

What if I don’t have calibration data?

The compiler falls back to built-in device specifications with median error rates. You’ll still get topology-aware mapping but without the calibration advantage.

Compilation Questions

Why is my compiled circuit deeper than the input?

SWAP gates are inserted when the circuit requires 2-qubit gates between non-adjacent physical qubits. Each SWAP decomposes to 3 CX/CZ gates. This is inherent to the hardware topology and happens with any transpiler.

To reduce depth:

  • Use strategy="depth_optimal"

  • Design circuits with linear connectivity if the backend is linear

  • Use fewer qubits to give the mapper more layout options

How accurate is the fidelity estimate?

The estimate uses a depolarising model: F ≈ Π(1 - e_gate). This is a reasonable approximation for short circuits (< 100 2Q gates) but overestimates fidelity for deep circuits where correlated errors and decoherence accumulate non-linearly. Use it for relative comparisons (this layout vs that layout) rather than absolute predictions.

What’s the maximum circuit size?

Practically limited by compilation time. The VF2 subgraph isomorphism search is the bottleneck:

  • Up to 20 qubits: < 1 second

  • 20–50 qubits: 1–10 seconds

  • 50+ qubits: may need max_candidates tuning

Can I compile for a backend I don’t have access to?

Yes. The compiler only needs calibration data, not hardware access. Compile for any backend with a calibration snapshot.

Cost & Budget Questions

How accurate are cost estimates?

Cost estimates use published per-shot pricing. They’re accurate for pay-per-shot platforms (IBM, IonQ). For pay-per-second platforms, the estimate includes a depth-based multiplier but actual cost depends on queue time and runtime overhead.

What happens if I set a budget and the circuit is too expensive?

BudgetExceededError is raised before returning the compilation result. The error includes the estimated cost and budget limit so you can adjust.

How do I find the cheapest backend?

from qb_compiler.cost.budget_optimizer import BudgetOptimizer

optimizer = BudgetOptimizer()
result = optimizer.find_cheapest_backend(
    budget_usd=10.0,
    min_qubits=10,
    target_shots=4096,
)
print(f"Use {result.backend}: ${result.estimated_cost_usd:.2f}")

Troubleshooting

ImportError: No module named ‘rustworkx’

Install rustworkx:

pip install rustworkx>=0.14

This is a core dependency and should be installed automatically. If not, check your Python environment.

CalibrationMapper finds no valid layout

This can happen when:

  • The circuit needs more qubits than the backend has

  • The circuit’s interaction graph can’t be embedded in the coupling map

  • max_candidates is too low

Fix: increase max_candidates or vf2_call_limit in CalibrationMapperConfig.

Slow compilation for large circuits

Increase max_candidates for better quality at the cost of speed, or decrease for faster compilation:

from qb_compiler.passes.mapping.calibration_mapper import CalibrationMapperConfig

# Faster but potentially lower quality
config = CalibrationMapperConfig(max_candidates=100, vf2_call_limit=10000)

# Slower but explores more options
config = CalibrationMapperConfig(max_candidates=50000, vf2_call_limit=500000)

Tests fail with “fixture not found”

Make sure you’re running tests from the project root:

cd /path/to/qb-compiler
pytest

Getting Help