Backends, Calibration & Noise

This page covers backend target descriptions, vendor-specific adapters, calibration data providers, and noise modelling.

Backend Target

BackendTarget encapsulates the physical constraints of a quantum device – qubit count, native gate set, and coupling topology.

Backend target description for the compiler.

class qb_compiler.backends.base.BackendTarget(n_qubits: int, basis_gates: tuple[str, ...], coupling_map: list[tuple[int, int]] = <factory>, name: str = 'unknown')

Bases: object

Hardware target that the compiler compiles to.

Encapsulates the physical constraints — qubit count, native gate set, and coupling topology — that compilation passes must respect.

Parameters:

  • n_qubits (int) – Number of physical qubits.

  • basis_gates (tuple[str, ...]) – Tuple of native gate names the backend can execute.

  • coupling_map (list[tuple[int, int]]) – Directed adjacency list [(ctrl, tgt), ...]. An empty list means all-to-all connectivity.

  • name (str) – Optional human-readable name.

are_connected(q1: int, q2: int) → bool

Check whether qubits q1 and q2 share a direct coupling.

basis_gates: tuple[str, ...]
coupling_map: list[tuple[int, int]]
classmethod from_backend_properties(props: BackendProperties) → BackendTarget

Build from a BackendProperties calibration snapshot.

property is_fully_connected: bool

True if coupling_map is empty (all-to-all assumed).

n_qubits: int
name: str = 'unknown'
neighbours(qubit: int) → frozenset[int]

Return the set of qubits directly coupled to qubit.

qubit_distance(q1: int, q2: int) → int

Shortest-path distance between q1 and q2 on the coupling graph.

Returns 0 if q1 == q2, 1 if directly coupled, etc. For all-to-all connectivity, always returns min(1, |q1 - q2|). Raises ValueError if no path exists.

supports_gate(gate: str) → bool

Check whether gate is in the native gate set.

Vendor Adapters

Each vendor module provides basis-gate constants, gate-time tables, and calibration parsers that normalise hardware-specific data into the qb-compiler common format.

IBM

IBM backend support.

qb_compiler.backends.ibm.load_ibm_calibration(path: str | Path) → BackendProperties

Convenience: load JSON file and parse in one call.

qb_compiler.backends.ibm.parse_ibm_calibration(data: dict) → BackendProperties

Parse a QubitBoost calibration_hub/heron/*.json dict into BackendProperties.

The IBM-specific format stores: - qubit_properties[].T1 / T2 in microseconds - qubit_properties[].readout_error_0to1 / readout_error_1to0 - qubit_properties[].frequency in GHz (often null for Heron) - gate_properties[].parameters.gate_error - gate_properties[].parameters.gate_length in nanoseconds - coupling_map as list of [q1, q2] pairs - basis_gates as list of gate name strings

Parameters:

data – Parsed JSON from a QubitBoost IBM calibration file.

Returns:

Fully populated properties object.

Return type:

BackendProperties

IBM backend adapter wrapping BackendTarget with IBM-specific defaults.

qb_compiler.backends.ibm.adapter.ibm_backend_target(name: str, n_qubits: int, coupling_map: list[tuple[int, int]] | None = None, *, processor_family: str | None = None) → BackendTarget

Create a BackendTarget with IBM-specific defaults.

Parameters:

  • name – Backend identifier (e.g. "ibm_fez").

  • n_qubits – Number of physical qubits.

  • coupling_map – Directed coupling pairs. If None, an empty list is used (all-to-all, which is incorrect for IBM but allows basic usage).

  • processor_family – "heron" or "eagle". If None, inferred from name.

Returns:

Configured for IBM hardware.

Return type:

BackendTarget

Parse IBM calibration data from the QubitBoost calibration_hub format.

qb_compiler.backends.ibm.calibration.load_ibm_calibration(path: str | Path) → BackendProperties

Convenience: load JSON file and parse in one call.

qb_compiler.backends.ibm.calibration.parse_ibm_calibration(data: dict) → BackendProperties

Parse a QubitBoost calibration_hub/heron/*.json dict into BackendProperties.

The IBM-specific format stores: - qubit_properties[].T1 / T2 in microseconds - qubit_properties[].readout_error_0to1 / readout_error_1to0 - qubit_properties[].frequency in GHz (often null for Heron) - gate_properties[].parameters.gate_error - gate_properties[].parameters.gate_length in nanoseconds - coupling_map as list of [q1, q2] pairs - basis_gates as list of gate name strings

Parameters:

data – Parsed JSON from a QubitBoost IBM calibration file.

Returns:

Fully populated properties object.

Return type:

BackendProperties

Rigetti

Rigetti backend support.

qb_compiler.backends.rigetti.load_rigetti_calibration(path: str | Path) → BackendProperties

Convenience: load JSON file and parse in one call.

qb_compiler.backends.rigetti.parse_rigetti_calibration(data: dict) → BackendProperties

Parse a QubitBoost calibration_hub/braket/rigetti_ankaa*.json dict into BackendProperties.

The Rigetti calibration data uses the same QubitBoost JSON schema as IBM, with vendor-specific differences in typical gate names (CZ-based) and error magnitudes.

Parameters:

data – Parsed JSON from a QubitBoost Rigetti calibration file.

Returns:

Fully populated properties object.

Return type:

BackendProperties

Parse Rigetti calibration data from the QubitBoost calibration_hub format.

qb_compiler.backends.rigetti.calibration.load_rigetti_calibration(path: str | Path) → BackendProperties

Convenience: load JSON file and parse in one call.

qb_compiler.backends.rigetti.calibration.parse_rigetti_calibration(data: dict) → BackendProperties

Parse a QubitBoost calibration_hub/braket/rigetti_ankaa*.json dict into BackendProperties.

The Rigetti calibration data uses the same QubitBoost JSON schema as IBM, with vendor-specific differences in typical gate names (CZ-based) and error magnitudes.

Parameters:

data – Parsed JSON from a QubitBoost Rigetti calibration file.

Returns:

Fully populated properties object.

Return type:

BackendProperties

IonQ

IonQ backend support.

qb_compiler.backends.ionq.load_ionq_calibration(path: str | Path) → BackendProperties

Convenience: load JSON file and parse in one call.

qb_compiler.backends.ionq.parse_ionq_calibration(data: dict) → BackendProperties

Parse a QubitBoost calibration_hub/braket/ionq_aria*.json dict into BackendProperties.

IonQ trapped-ion backends differ from superconducting backends: - All-to-all connectivity (coupling_map is empty or contains all pairs) - Much longer gate times (microseconds vs nanoseconds) - Much lower error rates - T1/T2 values are effectively infinite (seconds to minutes)

Parameters:

data – Parsed JSON from a QubitBoost IonQ calibration file.

Returns:

Fully populated properties object.

Return type:

BackendProperties

Parse IonQ calibration data from the QubitBoost calibration_hub format.

qb_compiler.backends.ionq.calibration.load_ionq_calibration(path: str | Path) → BackendProperties

Convenience: load JSON file and parse in one call.

qb_compiler.backends.ionq.calibration.parse_ionq_calibration(data: dict) → BackendProperties

Parse a QubitBoost calibration_hub/braket/ionq_aria*.json dict into BackendProperties.

IonQ trapped-ion backends differ from superconducting backends: - All-to-all connectivity (coupling_map is empty or contains all pairs) - Much longer gate times (microseconds vs nanoseconds) - Much lower error rates - T1/T2 values are effectively infinite (seconds to minutes)

Parameters:

data – Parsed JSON from a QubitBoost IonQ calibration file.

Returns:

Fully populated properties object.

Return type:

BackendProperties

IQM

IQM backend support.

qb_compiler.backends.iqm.load_iqm_calibration(path: str | Path) → BackendProperties

Convenience: load JSON file and parse in one call.

qb_compiler.backends.iqm.parse_iqm_calibration(data: dict) → BackendProperties

Parse a QubitBoost calibration_hub/braket/iqm_garnet*.json dict into BackendProperties.

IQM backends use CZ as the native two-qubit gate and PRX for single-qubit rotations.

Parameters:

data – Parsed JSON from a QubitBoost IQM calibration file.

Returns:

Fully populated properties object.

Return type:

BackendProperties

Parse IQM calibration data from the QubitBoost calibration_hub format.

qb_compiler.backends.iqm.calibration.load_iqm_calibration(path: str | Path) → BackendProperties

Convenience: load JSON file and parse in one call.

qb_compiler.backends.iqm.calibration.parse_iqm_calibration(data: dict) → BackendProperties

Parse a QubitBoost calibration_hub/braket/iqm_garnet*.json dict into BackendProperties.

IQM backends use CZ as the native two-qubit gate and PRX for single-qubit rotations.

Parameters:

data – Parsed JSON from a QubitBoost IQM calibration file.

Returns:

Fully populated properties object.

Return type:

BackendProperties

Calibration Providers

Calibration providers supply per-qubit and per-gate error data to the compiler. The abstract base class defines the interface; concrete implementations fetch data from files, caches, or live APIs.

Abstract base class for calibration data providers.

class qb_compiler.calibration.provider.CalibrationProvider

Bases: ABC

Interface for objects that supply device calibration data.

Concrete implementations may pull from static files, live APIs, or cached wrappers around other providers.

property age_hours: float

Hours elapsed since the calibration was taken.

abstract property backend_name: str

Human-readable backend identifier (e.g. 'ibm_fez').

abstractmethod get_all_gate_properties() → list[GateProperties]

Return calibration data for every characterised gate.

abstractmethod get_all_qubit_properties() → list[QubitProperties]

Return calibration data for every qubit on the device.

abstractmethod get_gate_properties(gate: str, qubits: tuple[int, ...]) → GateProperties | None

Return calibration data for gate on qubits, or None.

abstractmethod get_qubit_properties(qubit: int) → QubitProperties | None

Return calibration data for qubit, or None if unknown.

abstract property timestamp: datetime

UTC datetime when the calibration data was taken.

qb_compiler.calibration.provider.validate_calibration_url(url: str) → None

Validate that url points to an approved calibration host over HTTPS.

Parameters:

url – The URL to validate.

Raises:

CalibrationError – If the host is not in the allowlist or the scheme is not HTTPS.

Calibration provider backed by a static BackendProperties snapshot.

class qb_compiler.calibration.static_provider.StaticCalibrationProvider(props: BackendProperties)

Bases: CalibrationProvider

Serves calibration data from an in-memory BackendProperties.

This is the simplest provider — no network calls, no caching logic. Useful for offline analysis, unit tests, and replaying historical calibration snapshots from the QubitBoost calibration_hub.

Parameters:

props – Pre-loaded backend calibration snapshot.

property backend_name: str

Human-readable backend identifier (e.g. 'ibm_fez').

classmethod from_dict(data: dict) → StaticCalibrationProvider

Build from an already-parsed calibration dict.

classmethod from_json(path: str | Path) → StaticCalibrationProvider

Load from a QubitBoost calibration_hub JSON file.

Parameters:

path – Filesystem path to a JSON file matching the QubitBoost calibration format (backend_name, qubit_properties, gate_properties, coupling_map, etc.).

get_all_gate_properties() → list[GateProperties]

Return calibration data for every characterised gate.

get_all_qubit_properties() → list[QubitProperties]

Return calibration data for every qubit on the device.

get_gate_properties(gate: str, qubits: tuple[int, ...]) → GateProperties | None

Return calibration data for gate on qubits, or None.

get_qubit_properties(qubit: int) → QubitProperties | None

Return calibration data for qubit, or None if unknown.

property properties: BackendProperties

The underlying BackendProperties snapshot.

property timestamp: datetime

UTC datetime when the calibration data was taken.

Thread-safe caching wrapper around any CalibrationProvider.

class qb_compiler.calibration.cached_provider.CachedCalibrationProvider(provider_factory: Callable[[], CalibrationProvider], *, max_age_seconds: float = 3600.0, hard_limit_hours: float = 24.0)

Bases: CalibrationProvider

Wraps another CalibrationProvider, caching its results.

The wrapper checks the cached data’s age before every access and refreshes transparently when the cache is stale.

Parameters:

  • provider_factory – Callable that returns a fresh CalibrationProvider. Called on first access and whenever the cache expires.

  • max_age_seconds – Maximum cache lifetime in seconds. Defaults to 3600 (1 hour).

  • hard_limit_hours – If the provider factory raises and cached data is older than this many hours, a CalibrationStaleError is raised instead of serving potentially very old data. Defaults to 24.

property backend_name: str

Human-readable backend identifier (e.g. 'ibm_fez').

get_all_gate_properties() → list[GateProperties]

Return calibration data for every characterised gate.

get_all_qubit_properties() → list[QubitProperties]

Return calibration data for every qubit on the device.

get_gate_properties(gate: str, qubits: tuple[int, ...]) → GateProperties | None

Return calibration data for gate on qubits, or None.

get_qubit_properties(qubit: int) → QubitProperties | None

Return calibration data for qubit, or None if unknown.

invalidate() → None

Force the next access to refresh from the factory.

prefetch() → None

Eagerly populate the cache (useful at application startup).

property timestamp: datetime

UTC datetime when the calibration data was taken.

Calibration Models

Vendor-neutral data classes that represent calibration snapshots.

Calibration data models.

class qb_compiler.calibration.models.BackendProperties(backend: str, provider: str, n_qubits: int, basis_gates: tuple[str, ...], coupling_map: list[tuple[int, int]], qubit_properties: list[QubitProperties], gate_properties: list[GateProperties], timestamp: str)

Bases: object

Complete calibration snapshot for a quantum backend.

Parameters:
backend: str
basis_gates: tuple[str, ...]
coupling_map: list[tuple[int, int]]
classmethod from_qubitboost_dict(data: dict) → BackendProperties

Build from an already-parsed QubitBoost calibration dict.

classmethod from_qubitboost_json(path: str | Path) → BackendProperties

Load from a QubitBoost calibration_hub JSON file.

The expected top-level keys are backend_name, n_qubits, timestamp, qubit_properties, gate_properties, coupling_map, basis_gates.

gate(gate_type: str, qubits: tuple[int, ...]) → GateProperties | None

Return GateProperties matching gate_type and qubits.

gate_properties: list[GateProperties]
n_qubits: int
provider: str
qubit(qubit_id: int) → QubitProperties | None

Return QubitProperties for qubit_id, or None.

qubit_properties: list[QubitProperties]
timestamp: str
class qb_compiler.calibration.models.GateProperties(gate_type: str, qubits: tuple[int, ...], error_rate: float | None = None, gate_time_ns: float | None = None)

Bases: object

Calibration snapshot for a single gate on specific qubit(s).

Parameters:

  • gate_type (str) – Gate name (lower-cased, e.g. "cx", "cz", "sx").

  • qubits (tuple[int, ...]) – Ordered tuple of physical qubit indices the gate acts on.

  • error_rate (float | None) – Gate error rate from randomised benchmarking / IRB, or None.

  • gate_time_ns (float | None) – Gate duration in nanoseconds, or None.

error_rate: float | None
classmethod from_qubitboost_dict(d: dict) → GateProperties

Parse a single entry from the QubitBoost gate_properties list.

Expected keys: gate, qubits (list[int]), parameters.gate_error, parameters.gate_length.

gate_time_ns: float | None
gate_type: str
qubits: tuple[int, ...]
class qb_compiler.calibration.models.QubitProperties(qubit_id: int, t1_us: float | None = None, t2_us: float | None = None, readout_error: float | None = None, frequency_ghz: float | None = None, readout_error_0to1: float | None = None, readout_error_1to0: float | None = None)

Bases: object

Calibration snapshot for a single physical qubit.

Parameters:

  • qubit_id (int) – Physical qubit index on the device.

  • t1_us (float | None) – Energy relaxation time (T1) in microseconds, or None if unavailable.

  • t2_us (float | None) – Dephasing time (T2) in microseconds, or None if unavailable.

  • readout_error (float | None) – Combined (symmetrised) readout error probability, or None.

  • frequency_ghz (float | None) – Qubit drive frequency in GHz, or None.

  • readout_error_0to1 (float | None) – P(1|0) — probability of reading 1 when state is 0, or None.

  • readout_error_1to0 (float | None) – P(0|1) — probability of reading 0 when state is 1, or None.

frequency_ghz: float | None
classmethod from_qubitboost_dict(d: dict) → QubitProperties

Parse a single entry from the QubitBoost qubit_properties list.

Expected keys: qubit, T1, T2, frequency, readout_error_0to1, readout_error_1to0.

qubit_id: int
readout_error: float | None
readout_error_0to1: float | None
readout_error_1to0: float | None
static symmetrise_readout(err_0to1: float | None, err_1to0: float | None) → float | None

Average the two asymmetric readout errors into one number.

property t1_asymmetry_penalty: float

Readout-scaled penalty for T1 asymmetry.

Returns readout_error * ln(ratio) so the penalty is proportional to both the magnitude of the readout error and the asymmetry. This keeps the penalty in the same units as readout error, ensuring it doesn’t overwhelm other scoring terms.

  • ratio=1 → penalty=0 (symmetric, no penalty)

  • ratio=10, ro=0.01 → penalty≈0.023

  • ratio=24, ro=0.01 → penalty≈0.032

Clamped so ratios below 1 produce zero penalty (those qubits are actually better at holding |1⟩ states).

property t1_asymmetry_ratio: float

Ratio of |1⟩→|0⟩ decay error to |0⟩→|1⟩ excitation error.

On superconducting qubits, thermal excitation P(1|0) is typically much smaller than relaxation P(0|1). A high ratio means the qubit loses |1⟩ states disproportionately — circuits that hold qubits in |1⟩ (after X gates, CNOT targets, etc.) suffer more on these qubits.

Returns 1.0 when asymmetry data is unavailable, meaning no penalty.

t1_us: float | None
t2_us: float | None

Aggregate backend calibration snapshot.

class qb_compiler.calibration.models.backend_properties.BackendProperties(backend: str, provider: str, n_qubits: int, basis_gates: tuple[str, ...], coupling_map: list[tuple[int, int]], qubit_properties: list[QubitProperties], gate_properties: list[GateProperties], timestamp: str)

Bases: object

Complete calibration snapshot for a quantum backend.

Parameters:
backend: str
basis_gates: tuple[str, ...]
coupling_map: list[tuple[int, int]]
classmethod from_qubitboost_dict(data: dict) → BackendProperties

Build from an already-parsed QubitBoost calibration dict.

classmethod from_qubitboost_json(path: str | Path) → BackendProperties

Load from a QubitBoost calibration_hub JSON file.

The expected top-level keys are backend_name, n_qubits, timestamp, qubit_properties, gate_properties, coupling_map, basis_gates.

gate(gate_type: str, qubits: tuple[int, ...]) → GateProperties | None

Return GateProperties matching gate_type and qubits.

gate_properties: list[GateProperties]
n_qubits: int
provider: str
qubit(qubit_id: int) → QubitProperties | None

Return QubitProperties for qubit_id, or None.

qubit_properties: list[QubitProperties]
timestamp: str

Noise Modelling

Noise models provide per-gate depolarizing rates and fidelity estimates used by noise-aware compilation passes.

Noise modelling and fidelity estimation.

class qb_compiler.noise.EmpiricalNoiseModel(qubit_props: dict[int, QubitProperties], gate_props: dict[tuple[str, tuple[int, ...]], GateProperties])

Bases: NoiseModel

Noise model derived from a CalibrationProvider.

Translates per-qubit T1/T2 and per-gate error rates into the unified NoiseModel interface. Where calibration data is missing, conservative defaults are used.

Parameters:

  • qubit_props – Mapping from qubit index to its calibration properties.

  • gate_props – Mapping from (gate_type, qubits) to gate calibration.

decoherence_factor(qubit: int, gate_time_ns: float) → float

Decoherence error from T1 relaxation.

Uses the formula: p_decay = 1 - exp(-t / T1)

where t is the gate time. T2-based dephasing is also incorporated: p_dephase = 1 - exp(-t / T2). The combined decoherence error is:

p_err = 1 - (1 - p_decay) * (1 - p_dephase)

classmethod from_calibration(provider: CalibrationProvider) → EmpiricalNoiseModel

Build an EmpiricalNoiseModel from a calibration provider.

gate_error(gate: str, qubits: tuple[int, ...]) → float

Error rate for gate applied to qubits.

Returns a value in [0, 1]. For gates not found in calibration, implementations should return a conservative default.

gate_time_ns(gate: str, qubits: tuple[int, ...]) → float

Gate duration in nanoseconds, or default if unknown.

property n_qubits: int

Number of qubits with calibration data.

qubit_error(qubit: int) → float

Combined error: average of best single-qubit gate error, readout error, and a T2-based idling decoherence term over one gate time.

readout_error(qubit: int) → float

Measurement error probability for qubit.

Returns a value in [0, 1].

class qb_compiler.noise.FidelityEstimator(*, default_gate_time_ns: float = 40.0)

Bases: object

Estimates expected output fidelity of a circuit under a noise model.

The estimation works in two stages:

  1. Gate fidelity product — multiply (1 - error) for every gate in the circuit.

  2. Decoherence penalty — for each qubit, compute the total time it is active (sum of gate durations on its critical path) and apply the T1/T2 decoherence factor.

  3. Readout penalty — multiply by (1 - readout_error) for every measured qubit.

estimate(circuit: QBCircuit, noise_model: NoiseModel) → float

Return estimated output fidelity in [0, 1].

Parameters:

  • circuit – Circuit to analyse.

  • noise_model – Noise model providing per-gate and per-qubit error rates.

Returns:

Estimated probability that the circuit produces the correct output bitstring on a single shot. Values close to 1.0 are good; values below ~0.5 suggest the circuit is too deep for the hardware.

Return type:

float

estimate_depth_limited_fidelity(n_two_qubit_gates: int, avg_two_qubit_error: float, n_one_qubit_gates: int = 0, avg_one_qubit_error: float = 0.001) → float

Quick estimate without a full circuit — useful for planning.

Parameters:

  • n_two_qubit_gates – Number of 2-qubit gates.

  • avg_two_qubit_error – Average 2-qubit gate error rate.

  • n_one_qubit_gates – Number of 1-qubit gates.

  • avg_one_qubit_error – Average 1-qubit gate error rate.

Returns:

Estimated fidelity (gate errors only, no decoherence/readout).

Return type:

float

class qb_compiler.noise.NoiseModel

Bases: ABC

Interface for objects that estimate noise characteristics.

Implementations translate raw calibration numbers into error estimates that the compiler can use for routing, scheduling, and fidelity prediction.

abstractmethod decoherence_factor(qubit: int, gate_time_ns: float) → float

Decoherence-induced error for qubit over gate_time_ns.

Based on T1/T2 relaxation. Returns a value in [0, 1] where 0 = no decoherence and 1 = fully decohered.

abstractmethod gate_error(gate: str, qubits: tuple[int, ...]) → float

Error rate for gate applied to qubits.

Returns a value in [0, 1]. For gates not found in calibration, implementations should return a conservative default.

abstractmethod qubit_error(qubit: int) → float

Combined single-qubit error estimate (gate + readout + decoherence).

Returns a value in [0, 1] where 0 = perfect, 1 = maximally noisy.

abstractmethod readout_error(qubit: int) → float

Measurement error probability for qubit.

Returns a value in [0, 1].

class qb_compiler.noise.QBCircuit(gates: list[tuple[str, tuple[int, ...]]], n_qubits: int, measurements: frozenset[int] = frozenset({}))

Bases: object

Minimal circuit descriptor for fidelity estimation.

Parameters:

  • gates (list[tuple[str, tuple[int, ...]]]) – Ordered sequence of gate operations. Each element is a (gate_name, qubit_tuple) pair.

  • n_qubits (int) – Total number of qubits in the circuit.

  • measurements (frozenset[int]) – Set of qubit indices that are measured at the end.

gates: list[tuple[str, tuple[int, ...]]]
measurements: frozenset[int]
n_qubits: int

Noise model built from real calibration data.

class qb_compiler.noise.empirical_model.EmpiricalNoiseModel(qubit_props: dict[int, QubitProperties], gate_props: dict[tuple[str, tuple[int, ...]], GateProperties])

Bases: NoiseModel

Noise model derived from a CalibrationProvider.

Translates per-qubit T1/T2 and per-gate error rates into the unified NoiseModel interface. Where calibration data is missing, conservative defaults are used.

Parameters:

  • qubit_props – Mapping from qubit index to its calibration properties.

  • gate_props – Mapping from (gate_type, qubits) to gate calibration.

decoherence_factor(qubit: int, gate_time_ns: float) → float

Decoherence error from T1 relaxation.

Uses the formula: p_decay = 1 - exp(-t / T1)

where t is the gate time. T2-based dephasing is also incorporated: p_dephase = 1 - exp(-t / T2). The combined decoherence error is:

p_err = 1 - (1 - p_decay) * (1 - p_dephase)

classmethod from_calibration(provider: CalibrationProvider) → EmpiricalNoiseModel

Build an EmpiricalNoiseModel from a calibration provider.

gate_error(gate: str, qubits: tuple[int, ...]) → float

Error rate for gate applied to qubits.

Returns a value in [0, 1]. For gates not found in calibration, implementations should return a conservative default.

gate_time_ns(gate: str, qubits: tuple[int, ...]) → float

Gate duration in nanoseconds, or default if unknown.

property n_qubits: int

Number of qubits with calibration data.

qubit_error(qubit: int) → float

Combined error: average of best single-qubit gate error, readout error, and a T2-based idling decoherence term over one gate time.

readout_error(qubit: int) → float

Measurement error probability for qubit.

Returns a value in [0, 1].

Circuit fidelity estimation from noise models.

class qb_compiler.noise.fidelity_estimator.FidelityEstimator(*, default_gate_time_ns: float = 40.0)

Bases: object

Estimates expected output fidelity of a circuit under a noise model.

The estimation works in two stages:

  1. Gate fidelity product — multiply (1 - error) for every gate in the circuit.

  2. Decoherence penalty — for each qubit, compute the total time it is active (sum of gate durations on its critical path) and apply the T1/T2 decoherence factor.

  3. Readout penalty — multiply by (1 - readout_error) for every measured qubit.

estimate(circuit: QBCircuit, noise_model: NoiseModel) → float

Return estimated output fidelity in [0, 1].

Parameters:

  • circuit – Circuit to analyse.

  • noise_model – Noise model providing per-gate and per-qubit error rates.

Returns:

Estimated probability that the circuit produces the correct output bitstring on a single shot. Values close to 1.0 are good; values below ~0.5 suggest the circuit is too deep for the hardware.

Return type:

float

estimate_depth_limited_fidelity(n_two_qubit_gates: int, avg_two_qubit_error: float, n_one_qubit_gates: int = 0, avg_one_qubit_error: float = 0.001) → float

Quick estimate without a full circuit — useful for planning.

Parameters:

  • n_two_qubit_gates – Number of 2-qubit gates.

  • avg_two_qubit_error – Average 2-qubit gate error rate.

  • n_one_qubit_gates – Number of 1-qubit gates.

  • avg_one_qubit_error – Average 1-qubit gate error rate.

Returns:

Estimated fidelity (gate errors only, no decoherence/readout).

Return type:

float

class qb_compiler.noise.fidelity_estimator.QBCircuit(gates: list[tuple[str, tuple[int, ...]]], n_qubits: int, measurements: frozenset[int] = frozenset({}))

Bases: object

Minimal circuit descriptor for fidelity estimation.

Parameters:

  • gates (list[tuple[str, tuple[int, ...]]]) – Ordered sequence of gate operations. Each element is a (gate_name, qubit_tuple) pair.

  • n_qubits (int) – Total number of qubits in the circuit.

  • measurements (frozenset[int]) – Set of qubit indices that are measured at the end.

gates: list[tuple[str, tuple[int, ...]]]
measurements: frozenset[int]
n_qubits: int