Backends API¶
Core¶
base
¶
Abstract base class for quantum backends.
Backend
¶
Bases: ABC
Abstract backend for circuit execution.
All quantum backends (Qiskit Aer, IBM Runtime, PennyLane, Cirq, Braket) implement this interface so algorithms are backend-agnostic.
backend_id
abstractmethod
property
¶
Unique identifier for this backend.
run(circuit, shots=1024)
abstractmethod
¶
Execute a circuit and return measurement results.
statevector(circuit)
abstractmethod
¶
Return the statevector for a circuit (simulator only).
is_simulator()
¶
Whether this backend is a simulator (default True).
Mock Backend¶
MockBackend
¶
Qiskit Aer Backend¶
QiskitAerBackend
¶
Noise Models¶
noise_models
¶
Configurable noise models for quantum circuit simulation.
Provides realistic noise channels that can be composed and applied to the Qiskit Aer simulator. Supports per-gate error rates, thermal relaxation (T1/T2), readout errors, and device-calibrated profiles.
References¶
Nielsen & Chuang, Ch. 8 — Quantum noise and quantum operations. Georgopoulos et al., "Modeling and simulating the noisy behavior of near-term quantum computers" (2021).
IDEAL = NoiseProfile(single_gate_error=0.0, two_gate_error=0.0, readout_error=0.0, t1_us=1000000000.0, t2_us=1000000000.0, name='ideal')
module-attribute
¶
IBM_EAGLE_R3 = NoiseProfile(single_gate_error=0.00024, two_gate_error=0.0075, readout_error=0.011, t1_us=290.0, t2_us=150.0, single_gate_time_us=0.06, two_gate_time_us=0.66, name='ibm_eagle_r3')
module-attribute
¶
IBM_HERON_R2 = NoiseProfile(single_gate_error=0.00015, two_gate_error=0.0035, readout_error=0.006, t1_us=350.0, t2_us=200.0, single_gate_time_us=0.035, two_gate_time_us=0.08, name='ibm_heron_r2')
module-attribute
¶
NOISY_NEAR_TERM = NoiseProfile(single_gate_error=0.001, two_gate_error=0.01, readout_error=0.03, t1_us=50.0, t2_us=30.0, single_gate_time_us=0.05, two_gate_time_us=0.5, name='noisy_near_term')
module-attribute
¶
NoiseProfile
dataclass
¶
Configurable noise profile for quantum simulation.
Parameters¶
single_gate_error : float Depolarizing error rate for single-qubit gates (e.g., 1e-4 to 1e-2). two_gate_error : float Depolarizing error rate for two-qubit gates (typically ~10x single). readout_error : float Probability of bit-flip on measurement (symmetric for 0->1 and 1->0). t1_us : float T1 (amplitude damping) time in microseconds. t2_us : float T2 (dephasing) time in microseconds. Must satisfy T2 <= 2*T1. single_gate_time_us : float Duration of a single-qubit gate in microseconds. two_gate_time_us : float Duration of a two-qubit gate in microseconds. name : str Human-readable name for this profile.
NoisyAerBackend
¶
build_noise_model(profile)
¶
Build a Qiskit Aer NoiseModel from a NoiseProfile.
Constructs depolarizing errors on all gates, thermal relaxation, and readout bit-flip errors.
Returns¶
qiskit_aer.noise.NoiseModel
sweep_noise(circuit, error_rates, shots=4096, seed=42)
¶
Run a circuit at multiple noise levels and collect statistics.
Useful for Zero-Noise Extrapolation (ZNE) or for understanding noise sensitivity of an algorithm.
Parameters¶
circuit : QuantumCircuit Circuit to execute. error_rates : list[float] Two-qubit gate error rates to sweep (e.g., [0, 0.001, 0.005, 0.01]). shots : int Shots per execution. seed : int | None Random seed.
Returns¶
List of dicts with keys: error_rate, counts, most_frequent, entropy.
Error Mitigation¶
error_mitigation
¶
Error mitigation strategies for noisy quantum backends.
Implements Zero-Noise Extrapolation (ZNE), Twirled Readout Error eXtinction (TREX), measurement error mitigation via matrix inversion, Probabilistic Error Cancellation (PEC), and Clifford Data Regression (CDR).
These strategies improve the accuracy of expectation values and probability distributions from noisy quantum hardware without requiring additional qubits.
References¶
Temme, Bravyi, Gambetta, "Error Mitigation for Short-Depth Quantum Circuits", PRL 119:180509 (2017) — ZNE & PEC. van den Berg et al., "Probabilistic Error Cancellation with Sparse Pauli-Lindblad Models on Noisy Quantum Processors" (2023) — TREX. Bravyi, Gambetta, et al., "Mitigating measurement errors in multiqubit experiments", PRA 103:042605 (2021) — M3/matrix mitigation. Czarnik, Arrasmith, Coles, Cincio, "Error mitigation with Clifford quantum-circuit data", Quantum 5, 592 (2021) — CDR.
MitigationResult
dataclass
¶
Result after applying error mitigation.
Parameters¶
raw_counts : dict[str, int] Original noisy measurement counts. mitigated_counts : dict[str, int] Counts after mitigation (may contain non-integer values rounded). mitigated_probs : dict[str, float] Mitigated probability distribution. method : str Mitigation method used. metadata : dict Additional info (e.g., calibration data, extrapolation coefficients).
PECConfig
dataclass
¶
Configuration for Probabilistic Error Cancellation.
Parameters¶
n_samples : int Number of Monte Carlo PEC samples. noise_model_type : str Type of noise model: "depolarizing", "pauli_twirl", or "custom". max_overhead : float Maximum allowed sampling overhead (gamma). If the estimated overhead exceeds this, a warning is issued. seed : int | None Random seed for reproducibility.
CDRConfig
dataclass
¶
Configuration for Clifford Data Regression.
Parameters¶
n_training_circuits : int Number of near-Clifford training circuits to generate. regression_type : str Regression model: "linear" or "ridge". ridge_alpha : float Regularization strength for ridge regression. seed : int | None Random seed for reproducibility.
zne_extrapolate(circuit, backend, scale_factors=None, shots=4096, observable_fn=None)
¶
Zero-Noise Extrapolation via unitary folding.
Amplifies noise by repeating (folding) the circuit at multiple scale factors, measures the observable at each, and extrapolates to the zero-noise limit using Richardson extrapolation.
Parameters¶
circuit : QuantumCircuit The circuit to mitigate. Must NOT include measurements (added here). backend : Backend Noisy backend to execute on. scale_factors : list[float] Noise amplification factors (e.g., [1, 3, 5]). Each must be an odd integer. Default: [1, 3, 5]. shots : int Shots per execution. observable_fn : callable Function(counts_dict, shots) -> float that computes the observable from measurement counts. Default: probability of the all-zeros state.
Returns¶
Dict with keys: mitigated_value, raw_values, scale_factors, coefficients.
calibrate_readout(n_qubits, backend, shots=8192)
¶
Calibrate the readout error matrix for n_qubits.
Prepares each computational basis state and measures to build the 2^n x 2^n calibration matrix M where M[i,j] = P(measure i | prepared j).
Parameters¶
n_qubits : int Number of qubits (max ~6 for full matrix; beyond that use tensored). backend : Backend Backend to calibrate on. shots : int Shots per calibration circuit.
Returns¶
Calibration matrix M of shape (2^n, 2^n).
mitigate_readout(counts, cal_matrix, shots, method='pseudo_inverse')
¶
Apply readout error mitigation using the calibration matrix.
Parameters¶
counts : dict[str, int] Raw measurement counts. cal_matrix : NDArray Calibration matrix from calibrate_readout(). shots : int Total number of shots. method : str "pseudo_inverse" (default) or "least_squares".
Returns¶
MitigationResult with corrected counts.
trex_mitigate(circuit, backend, n_twirls=10, shots_per_twirl=1024)
¶
Twirled Readout Error eXtinction (TREX).
Randomizes measurement errors by applying random X gates before measurement and flipping the corresponding classical bits in post-processing. Averages over multiple twirls to suppress correlated readout errors.
Parameters¶
circuit : QuantumCircuit Circuit WITHOUT final measurements. backend : Backend Backend to execute on. n_twirls : int Number of random twirl patterns to average over. shots_per_twirl : int Shots per twirl execution.
Returns¶
MitigationResult with TREX-corrected counts.
pec_mitigate(circuit, backend, config=None, observable_fn=None, noise_params=None)
¶
Probabilistic Error Cancellation via Monte Carlo sampling.
Implements the PEC protocol from Temme et al. (2017): 1. Characterize the noise channel for each gate 2. Compute quasi-probability decomposition (QPD) 3. Sample noisy circuit instances according to quasi-probabilities 4. Compute weighted average for unbiased expectation value
Parameters¶
circuit : QuantumCircuit Circuit WITHOUT final measurements. backend : Backend Noisy backend to execute on. config : PECConfig | None PEC configuration. Uses defaults if None. observable_fn : callable | None Function(counts, shots) -> float. Default: P(all-zeros). noise_params : dict | None Noise parameters for overhead estimation. Keys: "gate_error" (float). Default: {"gate_error": 0.01}.
Returns¶
Dict with keys: mitigated_value, raw_value, gamma, n_samples, sample_values, overhead_estimate.
cdr_mitigate(circuit, backend, config=None, observable_fn=None, ideal_backend=None, shots=4096)
¶
Clifford Data Regression error mitigation.
Implements the CDR protocol from Czarnik et al. (2021): 1. Generate near-Clifford training circuits 2. Run training circuits on noisy backend and ideal simulator 3. Fit linear regression: ideal_value = f(noisy_value) 4. Apply learned correction to the target circuit result
Parameters¶
circuit : QuantumCircuit Target circuit WITHOUT final measurements. backend : Backend Noisy backend. config : CDRConfig | None CDR configuration. Uses defaults if None. observable_fn : callable | None Function(counts, shots) -> float. Default: P(all-zeros). ideal_backend : Backend | None Ideal (noiseless) backend for training. If None, uses the same backend (useful for MockBackend in testing). shots : int Shots per circuit execution.
Returns¶
Dict with keys: mitigated_value, raw_value, slope, intercept, training_noisy, training_ideal, n_training.
PennyLane Backend¶
pennylane_backend
¶
PennyLane Lightning backend adapter.
Provides a qufin Backend interface wrapping PennyLane's default.qubit or lightning.qubit simulators, with parameter-shift gradient support and cross-framework verification utilities.
Requires: pip install qufin[pennylane]
PennyLaneBackend
¶
Bases: Backend
PennyLane backend adapter.
Converts Qiskit circuits to PennyLane via qml.from_qiskit()
conversion, or runs native PennyLane circuits. Supports
parameter-shift gradient computation for variational algorithms.
Parameters¶
device_name : str
PennyLane device name ("default.qubit" or "lightning.qubit").
n_qubits : int
Number of qubits (required for device initialisation).
diff_method : str
Differentiation method for QNodes (default "parameter-shift").
run(circuit, shots=1024)
¶
Execute a circuit and return measurement results.
Accepts either a PennyLane QNode or a Qiskit QuantumCircuit.
For Qiskit circuits, converts via qml.from_qiskit().
statevector(circuit)
¶
Return the statevector for a circuit.
gradient(cost_fn, params)
¶
Compute gradients of cost_fn using the parameter-shift rule.
Parameters¶
cost_fn : callable A PennyLane-compatible cost function (QNode) that accepts a 1-D parameter array and returns a scalar expectation value. params : NDArray Current parameter values.
Returns¶
NDArray[np.float64] Gradient vector with the same shape as params.
run_with_gradient(cost_fn, params)
¶
make_cost_qnode(ansatz_fn, hamiltonian, n_qubits=None)
¶
Create a differentiable QNode from an ansatz and Hamiltonian.
Parameters¶
ansatz_fn : callable
A function ansatz_fn(params, wires) that applies gates.
hamiltonian : pennylane.Hamiltonian
Observable to measure.
n_qubits : int, optional
Qubit count (defaults to self._n_qubits).
Returns¶
QNode
A differentiable cost function cost(params) -> float.
verify_against_qiskit(circuit, shots=4096, atol=0.05)
staticmethod
¶
Run the same Qiskit circuit on both backends and compare.
Parameters¶
circuit : qiskit.QuantumCircuit Circuit to verify (must include measurements for the Qiskit leg; PennyLane side uses probability-based sampling). shots : int Number of shots per backend. atol : float Absolute tolerance on probability differences per bitstring.
Returns¶
dict
{"match": bool, "qiskit_probs": dict, "pennylane_probs": dict,
"max_diff": float}
Amazon Braket Backend¶
braket_backend
¶
AWS Braket backend adapter (IonQ, Rigetti, IQM, QuEra).
Provides a qufin Backend interface wrapping Amazon Braket devices and simulators, with target-specific metadata, hybrid job support, and cost estimation.
Requires: pip install qufin[braket]
BraketBackend
¶
Bases: Backend
Amazon Braket backend.
Supports local simulator, managed QPU devices, hybrid jobs, and cost estimation.
Parameters¶
device_arn : str or None AWS device ARN. None uses local simulator. s3_bucket : str or None S3 bucket for results (required for QPU). s3_prefix : str S3 key prefix for results.
run(circuit, shots=1024)
¶
Execute a circuit and return measurement results.
statevector(circuit)
¶
Return the statevector (local simulator only).
submit_hybrid_job(algorithm_script, *, entry_point='algorithm_script:main', hyperparameters=None, instance_type='ml.m5.large', wait_until_complete=False)
¶
Submit a Braket hybrid job for long-running optimizations.
Parameters¶
algorithm_script : str
Path to the Python script containing the algorithm.
entry_point : str
Module and function entry point (default: algorithm_script:main).
hyperparameters : dict or None
Hyperparameters passed to the algorithm script.
instance_type : str
EC2 instance type for the classical co-processor.
wait_until_complete : bool
If True, block until the job completes.
Returns¶
HybridJobHandle Handle with job ARN and initial status.
Raises¶
RuntimeError If using local simulator (hybrid jobs require QPU/on-demand). ImportError If braket SDK hybrid job module is unavailable.
poll_job_status(job_arn)
¶
get_job_result(job_arn)
¶
IonQTarget
dataclass
¶
IonQ trapped-ion device target.
Attributes¶
name : str Human-readable device name. arn : str AWS device ARN. topology : Topology Qubit connectivity (all-to-all for trapped ion). max_qubits : int Maximum number of qubits supported. swap_overhead : float SWAP overhead factor for QAOA-style circuits (1.0 = no overhead).
RigettiTarget
dataclass
¶
Rigetti superconducting device target.
Attributes¶
name : str Human-readable device name. arn : str AWS device ARN. topology : Topology Qubit connectivity (grid for superconducting). max_qubits : int Maximum number of qubits supported. swap_overhead : float Estimated SWAP overhead factor for QAOA circuits on grid topology.
CostEstimate
dataclass
¶
Estimated cost for running a circuit.
Attributes¶
device_name : str Human-readable device name. device_arn : str AWS device ARN. shots : int Number of shots requested. per_task_usd : float Fixed cost per task submission. per_shot_usd : float Cost per shot. total_usd : float Total estimated cost.
estimate_cost(target, shots=1024, n_tasks=1)
¶
Estimate the cost of running on a Braket QPU.
Parameters¶
target : IonQTarget | RigettiTarget | IQMTarget Device target with ARN. shots : int Number of shots per task. n_tasks : int Number of task submissions.
Returns¶
CostEstimate Breakdown of estimated costs.
Raises¶
ValueError If the target ARN is not in the price table.
analyze_swap_overhead(target, n_qubits, n_two_qubit_gates)
¶
Estimate SWAP overhead for a circuit on a given target.
For all-to-all connectivity (trapped ion), no SWAPs are needed. For grid/heavy-hex topologies, overhead scales with connectivity distance.
Parameters¶
target : IonQTarget | RigettiTarget | IQMTarget Device target. n_qubits : int Number of logical qubits. n_two_qubit_gates : int Number of two-qubit gates in the logical circuit.
Returns¶
dict Analysis with keys: estimated_swaps, total_two_qubit_gates, overhead_factor, topology.
Cirq Backend¶
cirq_backend
¶
Cirq backend adapter.
Provides a qufin Backend interface wrapping Google's Cirq simulator, with optional access paths to Google Sycamore/Willow hardware via Google Cloud Quantum Engine.
Requires: pip install qufin[cirq]
v0.3.0 enhancements¶
- Google hardware configuration (Sycamore/Willow processor IDs)
- XEB noise characterization integration
- Enhanced Qiskit-to-Cirq circuit translation
- Native Cirq circuit builder helpers for finance circuits
- Sycamore-native gate decomposition (sqrt-iSWAP)
- Cirq noise model integration (ConstantQubitNoiseModel, DEPOLARIZE)
CirqBackend
¶
Bases: Backend
Cirq simulator backend with Google hardware access path.
Converts Qiskit circuits to Cirq via OpenQASM export, or runs native Cirq circuits. Optionally connects to Google Quantum Engine for hardware execution.
Parameters¶
noise_model : Any or None
Cirq noise model for noisy simulation.
hardware_config : GoogleHardwareConfig or None
Configuration for Google hardware access. When set,
is_simulator() returns False and circuits are
dispatched to the Quantum Engine.
noise_characterization
property
¶
Most recent noise characterization results, if available.
with_device_noise(processor_id='sycamore', depolarize_rate=0.005, two_qubit_depolarize_rate=0.02)
classmethod
¶
Create a CirqBackend with device-like depolarizing noise.
Uses cirq.ConstantQubitNoiseModel with cirq.depolarize
channels to approximate noise from a given processor.
Parameters¶
processor_id : str Processor name (used for backend_id labeling). depolarize_rate : float Single-qubit depolarizing error rate. two_qubit_depolarize_rate : float Two-qubit depolarizing error rate.
Returns¶
CirqBackend Backend configured with depolarizing noise.
get_hardware_info()
¶
xeb_fidelity(qubits=None, num_circuits=20, cycle_depths=None)
¶
Estimate cross-entropy benchmarking fidelity.
Generates random circuits and compares measured bitstring distributions against ideal simulation to estimate fidelity.
Parameters¶
qubits : list or None
Cirq qubits to benchmark. Defaults to a pair of
LineQubits.
num_circuits : int
Number of random circuits to sample.
cycle_depths : list[int] or None
Depths at which to measure fidelity.
Returns¶
float Estimated XEB fidelity in [0, 1].
characterize_noise(n_qubits=2, num_circuits=20, cycle_depths=None)
¶
Characterize backend noise via random circuit sampling.
Runs XEB and derives approximate single- and two-qubit error rates from the fidelity decay curve.
Parameters¶
n_qubits : int Number of qubits to characterize. num_circuits : int Random circuits per depth. cycle_depths : list[int] or None Depths for the sweep.
Returns¶
NoiseCharacterization Full characterization results.
translate_qiskit_circuit(circuit)
¶
build_zz_interaction(qubit_pairs, angles)
¶
Build a Cirq circuit with ZZ interactions for finance models.
ZZ interactions are common in portfolio optimization and risk QUBO Hamiltonians.
Parameters¶
qubit_pairs : list[tuple[int, int]] Pairs of qubit indices for ZZ couplings. angles : list[float] Rotation angles (radians) for each ZZ term.
Returns¶
cirq.Circuit Circuit implementing the ZZ interactions.
decompose_for_sycamore(circuit)
¶
Decompose circuit into Sycamore-native gates (sqrt-iSWAP).
The Sycamore processor uses sqrt-iSWAP as its native two-qubit gate. This method decomposes arbitrary two-qubit gates into sqrt-iSWAP + single-qubit rotations.
Parameters¶
circuit : cirq.Circuit Input circuit with arbitrary gates.
Returns¶
cirq.Circuit Circuit using only sqrt-iSWAP and single-qubit gates.
run(circuit, shots=1024)
¶
Execute a circuit and return measurement results.
statevector(circuit)
¶
Return the statevector for a circuit.
is_simulator()
¶
Return False if hardware config is set.
GoogleHardwareConfig
dataclass
¶
Configuration for Google Quantum Engine hardware access.
Parameters¶
processor_id : str
Processor identifier, e.g. "rainbow", "weber",
"sycamore", "willow".
project_id : str
Google Cloud project ID for Quantum Engine access.
region : str
Google Cloud region (default "us-central1").
gate_set : str
Native gate set name. "sqrt_iswap" for Sycamore-era,
"google_v2" for Willow.
max_qubits : int
Maximum qubit count for the processor.
topology : str
Qubit connectivity topology description.
NoiseCharacterization
dataclass
¶
Results from XEB or random-circuit noise characterization.
Attributes¶
xeb_fidelity : float Cross-entropy benchmarking fidelity estimate (0..1). single_qubit_error : float Average single-qubit gate error rate. two_qubit_error : float Average two-qubit gate error rate. num_circuits : int Number of random circuits used for characterization. cycle_depths : list[int] Circuit depths used in the characterization sweep. raw_fidelities : dict[int, float] Per-depth fidelity estimates {depth: fidelity}.
CUDA-Q Backend¶
cudaq_backend
¶
NVIDIA CUDA-Q backend adapter.
Provides GPU-accelerated quantum circuit simulation via the CUDA-Q SDK. Supports single-GPU state vector simulation and multi-GPU for >30 qubits.
Requires: pip install cuda-quantum
CudaQBackend
¶
Bases: Backend
GPU-accelerated backend using NVIDIA CUDA-Q.
Parameters¶
target : str
CUDA-Q target: "nvidia" (single GPU) or
"nvidia-mgpu" (multi-GPU).
seed : int | None
Random seed for reproducibility.
multi_gpu_threshold : int
Qubit count above which multi-GPU target is used
automatically when target="auto".
run(circuit, shots=1024)
¶
statevector(circuit)
¶
benchmark_simulation(n_qubits, depth=10)
¶
get_gpu_info()
staticmethod
¶
Query available GPU device information.
Returns¶
dict
Keys: available (bool), num_gpus (int),
targets (list[str]).
is_simulator()
¶
CUDA-Q targets are simulators (not real hardware).
Backend Auto-Selection¶
auto_select
¶
Automatic backend selection based on circuit properties.
Analyzes circuit characteristics (qubit count, depth, gate types) and selects the most suitable available backend, with a configurable fallback chain.
CircuitAnalysis
dataclass
¶
Static analysis of a quantum circuit.
Attributes¶
qubit_count : int Number of qubits. depth : int Circuit depth (longest path). connectivity_graph : dict[int, set[int]] Adjacency mapping for two-qubit gates. gate_counts : dict[str, int] Counts per gate name.
BackendRegistry
¶
Registry for discovering and managing available backends.
Examples¶
registry = BackendRegistry() registry.register("mock", MockBackend) registry.get("mock")
analyze_circuit(circuit)
¶
auto_select_backend(circuit, available_backends=None, preference=None)
¶
Automatically select the best backend for a circuit.
Selection priorities (unless overridden by preference):
- If the user specifies a preference and it is available, use it.
- For large circuits (>30 qubits): prefer CUDA-Q GPU.
- For medium circuits (16-30 qubits): prefer Qiskit Aer, fallback to CUDA-Q.
- For small circuits (<=15 qubits): Qiskit Aer or MockBackend.
Fallback chain: cudaq -> qiskit_aer -> mock.
Parameters¶
circuit : qiskit.QuantumCircuit
Circuit to select a backend for.
available_backends : dict[str, bool] | None
Override availability map; if None, probed automatically.
preference : str | None
Preferred backend name (e.g. "cudaq", "qiskit_aer").
Returns¶
Backend An instantiated backend.
Finance Transpiler¶
transpiler
¶
Finance-optimized circuit transpiler for QAOA and QAE circuits.
Exploits problem structure (QUBO interaction graphs, commuting gate groups) to reduce circuit depth and CNOT count, improving fidelity on noisy hardware.
Uses Qiskit's transpiler API for the heavy lifting, wrapping it with finance-specific heuristics for initial layout, gate cancellation, and connectivity-aware routing.
FinanceTranspiler
¶
Finance-optimized transpiler for QAOA and QAE circuits.
Applies problem-structure-aware optimizations that go beyond Qiskit's generic transpiler passes.
optimize_qaoa_circuit(circuit, qubo_matrix)
¶
Optimize a QAOA circuit using QUBO structure.
Exploits the QUBO interaction graph to: 1. Identify and cancel redundant ZZ interactions 2. Reorder gates for better parallelism 3. Apply Qiskit transpilation at the configured level
Parameters¶
circuit : QuantumCircuit QAOA circuit to optimize. qubo_matrix : NDArray QUBO problem matrix.
Returns¶
Tuple of (optimized_circuit, TranspilationResult).
parallelize_commuting_zz(circuit)
¶
Group commuting ZZ gates for parallel execution.
Identifies ZZ-type interactions (RZZ, CX-RZ-CX patterns) that act on disjoint qubits and reorders them into parallel layers.
Parameters¶
circuit : QuantumCircuit Circuit with ZZ interactions.
Returns¶
Tuple of (reordered_circuit, TranspilationResult).
reduce_cnot_count(circuit)
¶
Reduce CNOT count via aggressive transpilation.
Targets 30-50% CNOT reduction for portfolio QAOA circuits using Qiskit's optimization passes (gate cancellation, commutation, template matching).
Parameters¶
circuit : QuantumCircuit Circuit to optimize.
Returns¶
Tuple of (optimized_circuit, TranspilationResult).
connectivity_aware_routing(circuit, coupling_map, qubo_matrix)
¶
Route circuit using QUBO-aware initial layout.
Maps high-weight QUBO edges to adjacent physical qubits to minimize SWAP insertions during routing.
Parameters¶
circuit : QuantumCircuit Circuit to route. coupling_map : list[tuple[int, int]] Physical qubit connectivity. qubo_matrix : NDArray QUBO problem matrix.
Returns¶
Tuple of (routed_circuit, TranspilationResult).
benchmark_transpilation(circuit, methods=None)
¶
TranspilationResult
dataclass
¶
Result of a transpilation optimization pass.
Parameters¶
original_depth : int Circuit depth before optimization. optimized_depth : int Circuit depth after optimization. original_cx_count : int Number of CX (CNOT) gates before optimization. optimized_cx_count : int Number of CX (CNOT) gates after optimization. estimated_error_rate : float Estimated error rate based on gate counts and noise profile. method_used : str Name of the transpilation method applied. metadata : dict Additional info (e.g., layout mapping, routing stats).
qubo_interaction_graph(Q)
¶
find_commuting_groups(circuit)
¶
Identify groups of commuting gates in a circuit.
Gates that act on disjoint qubits trivially commute and can be executed in parallel. This function groups gate indices by qubit overlap: gates within each group have no qubit conflicts.
Parameters¶
circuit : QuantumCircuit Qiskit quantum circuit.
Returns¶
List of groups, each group is a list of gate indices that commute.
initial_layout_from_qubo(Q, coupling_map)
¶
Compute a SABRE-style initial layout from QUBO structure.
Maps the highest-weight QUBO interactions to adjacent physical qubits in the coupling map, reducing SWAP overhead.
Parameters¶
Q : NDArray QUBO matrix of shape (n, n). coupling_map : list[tuple[int, int]] Physical qubit connectivity as edge list.
Returns¶
Dict mapping logical qubit -> physical qubit.
Dynamical Decoupling¶
dynamical_decoupling
¶
Dynamical Decoupling (DD) sequence insertion for decoherence suppression.
Implements DD pulse sequences that suppress low-frequency noise during idle periods in quantum circuits. Supported sequences:
- XY4: Four-pulse sequence (X-Y-X-Y) that suppresses both dephasing and amplitude-damping noise.
- CPMG: Carr-Purcell-Meiboom-Gill sequence of evenly spaced pi-pulses.
- Uhrig: Uhrig Dynamical Decoupling with optimally timed pulses for pure dephasing noise.
Can be combined with ZNE for compound mitigation.
References¶
Viola, Knill, Lloyd, "Dynamical Decoupling of Open Quantum Systems", PRL 82:2417 (1999). Uhrig, "Keeping a Quantum Bit Alive by Optimized Pi-Pulse Sequences", PRL 98:100504 (2007).
DDSequence
¶
Bases: Enum
Supported dynamical decoupling sequences.
DDConfig
dataclass
¶
Configuration for dynamical decoupling insertion.
Parameters¶
sequence_type : DDSequence Which DD sequence to use. pulse_spacing : float Minimum idle time (in gate units) before inserting DD pulses. Default 1.0 means any idle period of 1 or more gate slots gets DD. n_pulses : int Number of pi-pulses for CPMG/Uhrig sequences. Ignored for XY4. combine_with_zne : bool Whether to combine DD with ZNE for compound mitigation. custom_gates : list[str] | None Gate names for CUSTOM sequence type (e.g., ["x", "y", "x", "y"]).
insert_dd_sequences(circuit, config=None)
¶
Insert dynamical decoupling sequences into idle periods.
Analyzes the circuit for idle qubit periods and inserts the configured DD pulse sequence to suppress decoherence.
Parameters¶
circuit : QuantumCircuit Transpiled quantum circuit (without measurements). config : DDConfig | None DD configuration. Uses XY4 defaults if None.
Returns¶
New QuantumCircuit with DD sequences inserted.
xy4_sequence(qubit)
¶
cpmg_sequence(qubit, n_pulses=4)
¶
Return CPMG dynamical decoupling gate sequence.
Carr-Purcell-Meiboom-Gill sequence: evenly spaced pi-X pulses. Effective at suppressing dephasing noise.
Parameters¶
qubit : int Qubit index. n_pulses : int Number of pi-pulses (must be even for proper refocusing).
Returns¶
List of (gate_name, qubit) tuples.
uhrig_sequence(qubit, n_pulses=4)
¶
Return Uhrig DD sequence with optimal timing.
Uhrig DD uses non-uniform pulse spacing optimized for suppressing pure dephasing noise. The j-th pulse (1-indexed) is placed at fractional time t_j = sin^2(j * pi / (2*(n+1))).
Parameters¶
qubit : int Qubit index. n_pulses : int Number of pi-pulses.
Returns¶
List of (gate_name, qubit, fractional_time) tuples, where fractional_time is in [0, 1] indicating when in the idle period the pulse should be applied.
estimate_t2_extension(original_t2, dd_sequence, n_pulses=4)
¶
Estimate T2 coherence time improvement from DD sequences.
Uses analytical models for the expected T2 extension factor based on the DD sequence type and number of pulses.
Parameters¶
original_t2 : float Original T2 coherence time (in microseconds). dd_sequence : DDSequence DD sequence type. n_pulses : int Number of pulses (for CPMG/Uhrig).
Returns¶
Dict with keys: original_t2, extended_t2, extension_factor, sequence.
dd_with_zne(circuit, backend, dd_config=None, zne_scale_factors=None, shots=4096, observable_fn=None)
¶
Compound mitigation: Dynamical Decoupling + Zero-Noise Extrapolation.
First inserts DD sequences to suppress idle-time decoherence, then applies ZNE on the DD-protected circuit.
Parameters¶
circuit : QuantumCircuit Circuit WITHOUT measurements. backend : Backend Backend to execute on. dd_config : DDConfig | None DD configuration. Uses XY4 defaults if None. zne_scale_factors : list[float] | None Scale factors for ZNE. Default [1, 3, 5]. shots : int Shots per execution. observable_fn : callable | None Observable function for ZNE. Default: P(all-zeros).
Returns¶
Dict with keys: mitigated_value, raw_values, scale_factors, dd_sequence, dd_depth_overhead.
M3 Measurement Mitigation¶
m3_mitigation
¶
Matrix-free Measurement Mitigation (M3) for scalable readout correction.
Implements a tensored (per-qubit) calibration approach that scales
linearly in the number of qubits, unlike the full calibration matrix
approach in error_mitigation.py which scales as 2^n.
The key insight: if readout errors are approximately independent across qubits, the full 2^n x 2^n calibration matrix can be approximated as a tensor product of n 2x2 matrices, requiring only 2n calibration circuits instead of 2^n.
Includes iterative Bayesian correction for improved accuracy.
References¶
Nation, Kang, Sundaresan, Gambetta, "Scalable Mitigation of Measurement Errors on Quantum Computers", PRX Quantum 2:040326 (2021).
M3Config
dataclass
¶
Configuration for M3 measurement mitigation.
Parameters¶
n_calibration_shots : int Shots per calibration circuit. Higher = more accurate calibration. method : str Correction method: "direct" (matrix inversion) or "iterative" (Bayesian iterative correction). max_iterations : int Maximum iterations for iterative method. convergence_tol : float Convergence tolerance for iterative method.
M3Mitigator
¶
Matrix-free measurement mitigator using tensored calibration.
Calibrates per-qubit readout errors and applies scalable correction to measurement counts. Much more efficient than full matrix calibration for large qubit counts.
Parameters¶
config : M3Config Configuration for calibration and correction.
is_calibrated
property
¶
Whether calibration has been performed.
calibration_data
property
¶
Return the current calibration data.
calibrate(backend, qubit_list=None, n_qubits=None)
¶
Calibrate per-qubit readout errors.
Runs 2 circuits per qubit (prepare |0> and |1>), measuring the readout fidelity for each qubit independently.
Parameters¶
backend : Backend Backend to calibrate on. qubit_list : list[int] | None Specific qubits to calibrate. If None, calibrates qubits 0..n_qubits-1. n_qubits : int | None Number of qubits (used if qubit_list is None). Default 2.
Returns¶
CalibrationData with per-qubit 2x2 matrices.
apply(counts, shots)
¶
tensored_calibration(n_qubits, backend, shots=8192)
¶
Calibrate individual qubit readout errors using tensored approach.
Runs 2 circuits per qubit (prepare |0> and prepare |1>), building a 2x2 calibration matrix for each qubit independently. This requires only 2*n_qubits circuits instead of 2^n_qubits for full calibration.
Parameters¶
n_qubits : int Number of qubits to calibrate. backend : Backend Backend to run calibration circuits on. shots : int Shots per calibration circuit.
Returns¶
CalibrationData with per-qubit 2x2 matrices.
iterative_correction(counts, cal_data, max_iter=25, tol=1e-06)
¶
Iterative Bayesian correction using tensored calibration.
Uses an iterative algorithm that converges to the maximum-likelihood corrected distribution without requiring matrix inversion. Each iteration applies Bayes' rule using the tensored calibration matrix.
Parameters¶
counts : dict[str, int] Raw measurement counts. cal_data : CalibrationData Calibration data from tensored_calibration. max_iter : int Maximum number of iterations. tol : float Convergence tolerance (L1 norm of change).
Returns¶
Corrected probability distribution.
Noise-Aware Optimizer¶
noise_aware_optimizer
¶
Noise-aware variational parameter optimization for QAOA/VQE.
Implements optimization strategies that account for hardware noise when tuning variational circuit parameters. Supports noise-agnostic, noise-penalized, and robust (worst-case) optimization modes.
References¶
Fontana et al., "Non-trivial symmetries in quantum landscapes and their resilience to noise" (2021). Sharma et al., "Noise resilience of variational quantum compiling" PRA 102:062415 (2020). Wang et al., "Noise-induced barren plateaus in variational quantum algorithms", Nat Commun 12:6961 (2021).
NoiseAwareConfig
dataclass
¶
Configuration for noise-aware optimization.
Parameters¶
noise_model : dict[str, float]
Depolarizing error rates keyed by gate type,
e.g. {"cx": 0.01, "rx": 0.001}.
optimization_method : str
One of "noise_aware", "robust", "noise_agnostic".
noise_budget : float
Maximum acceptable cumulative noise level (0-1).
calibration_drift_range : tuple[float, float]
Multiplicative worst-case range for noise parameter drift,
e.g. (0.8, 1.2) means +/- 20 %.
penalty_weight : float
Relative weight of the noise penalty term.
maxiter : int
Maximum optimizer iterations.
optimizer : str
SciPy optimizer method name.
NoiseAwareOptimizer
¶
Variational optimizer that incorporates a noise penalty.
Wraps a cost function with a differentiable noise penalty so the optimizer favours parameter regions with lower noise impact.
Parameters¶
backend : Backend Quantum backend for circuit execution. config : NoiseAwareConfig Optimization configuration.
history
property
¶
Objective value history across optimizer iterations.
optimize(circuit, initial_params, cost_fn, shots=4096)
¶
Optimize variational parameters with optional noise penalty.
Parameters¶
circuit : object
Parameterized quantum circuit. Must support
assign_parameters or be callable with params.
initial_params : NDArray
Starting parameter values.
cost_fn : callable(counts, shots) -> float
Maps measurement counts to a scalar cost.
shots : int
Shots per circuit execution.
Returns¶
Dict with keys: optimal_params, optimal_cost, history, noise_penalty, estimated_fidelity, method.
noise_penalty(circuit, params, noise_model=None)
¶
Compute a differentiable noise penalty for the current circuit.
The penalty is weight * (1 - expected_fidelity).
Parameters¶
circuit : object Quantum circuit (bound or unbound). params : NDArray Current parameter values (used for heuristic scaling). noise_model : dict | None Override noise rates; if None uses config.
Returns¶
float >= 0.
expected_noise_cost(circuit, noise_rates)
¶
Compute expected noise contribution for given rates.
Returns the infidelity 1 - F under the supplied noise model.
robust_optimize(circuit, params, cost_fn, noise_range, shots=4096)
¶
Optimize robust to calibration drift (worst-case over noise range).
Evaluates the cost at the nominal noise level plus a worst-case penalty sampled from the calibration drift range.
Parameters¶
circuit : object Parameterized circuit. params : NDArray Initial parameters. cost_fn : callable(counts, shots) -> float Cost function. noise_range : tuple[float, float] Multiplicative drift range, e.g. (0.8, 1.2). shots : int Shots per execution.
Returns¶
Dict with optimisation results.
NoiseChannel
dataclass
¶
A single noise channel on a gate.
Parameters¶
gate_type : str Gate name (e.g. "cx", "rx", "rz"). error_rate : float Depolarizing error probability for this gate. qubit_indices : tuple[int, ...] Qubits this channel acts on.
DepolarizingModel
¶
Analytical depolarizing noise model for circuit fidelity estimation.
Provides fast, differentiable estimates of noise impact without running the circuit on a simulator.
channels
property
¶
Return the list of noise channels.
from_backend(backend)
classmethod
¶
Extract noise parameters from a backend.
For NoisyAerBackend uses the stored NoiseProfile.
For other backends, returns a default low-noise model.
gate_error(gate_type)
¶
Return the error rate for a gate type, or 0 if unknown.
expected_fidelity(circuit)
¶
Estimate overall circuit fidelity under depolarizing noise.
Uses the product formula F = prod(1 - e_g) over all gates g in the circuit, where e_g is the depolarizing error rate.
Parameters¶
circuit : object
Must expose an iterable data attribute whose elements
have an operation.name attribute (Qiskit QuantumCircuit).
If data is not available, falls back to depth()
with average error.
Returns¶
float Estimated fidelity in [0, 1].
noise_gradient(circuit, params)
¶
Estimate gradient of noise cost w.r.t. variational parameters.
Uses finite differences on the expected fidelity. The circuit
must be rebuildable from parameters via a bind_parameters
method or equivalent.
For circuits without bind_parameters, returns a heuristic
gradient proportional to the parameter magnitudes (larger
rotation angles produce deeper effective circuits).
Parameters¶
circuit : object Parameterized circuit template. params : NDArray Current parameter values.
Returns¶
NDArray of shape (len(params),).
circuit_noise_budget(circuit, noise_model)
¶
compare_noise_aware_vs_agnostic(circuit, backend, problem, initial_params=None, shots=4096, maxiter=50)
¶
Run a side-by-side comparison of noise-aware vs agnostic optimization.
Parameters¶
circuit : object Parameterized circuit template. backend : Backend Noisy backend. problem : callable(counts, shots) -> float Cost function. initial_params : NDArray | None Starting parameters. If None, uses zeros. shots : int Shots per evaluation. maxiter : int Max iterations for each optimizer.
Returns¶
Dict with aware and agnostic result sub-dicts plus a summary.