Noise models

The qtest.noise subpackage provides an SDK-agnostic NoiseModel plus ready-made constructors for the common error channels. Pass any of them to the noise_model argument of qtest.assert_distribution_close() / qtest.assert_state_close(), or set a preset globally with --qtest-noise / [tool.qtest] default_noise.

Public API

NoiseModel	An SDK-agnostic description of a noise channel to apply during simulation.
depolarizing	Depolarizing error of strength p on every gate.
bit_flip	Bit-flip (Pauli-X) error: apply X with probability p after 1-qubit gates.
phase_flip	Phase-flip (Pauli-Z) error: apply Z with probability p after 1-qubit gates.
thermal_relaxation	Thermal-relaxation (T1/T2) error applied to single-qubit gates.
readout_error	Measurement (readout) error.
from_preset	Return the NoiseModel for a built-in preset name.
available_presets	Return the sorted names of the built-in noise presets.

Reference

Noise models for qtest.

Real quantum hardware is noisy, and a test that only ever runs on an ideal simulator says nothing about how a circuit behaves under decoherence and gate error. This module provides a small, SDK-agnostic NoiseModel wrapper plus a handful of ready-made constructors so tests can opt into noisy simulation with a single argument:

from qtest import assert_distribution_close
from qtest.noise import depolarizing

assert_distribution_close(qc, expected, noise_model=depolarizing(0.01))

Design

A NoiseModel is a lightweight, immutable description of the noise to apply — it stores a list of error specs and nothing else. The heavy Qiskit Aer objects are built lazily in NoiseModel.to_qiskit(), so constructing a NoiseModel (and importing this module) never requires qiskit-aer. The import is only triggered when a noisy assertion actually runs.

Models compose with + so several error channels can be layered:

combined = depolarizing(0.01) + readout_error(0.02)

class qtest.noise.models.NoiseModel(specs=None, label='custom')

Bases: object

An SDK-agnostic description of a noise channel to apply during simulation.

Instances are immutable value objects: the recommended way to build one is via the module-level constructors (depolarizing(), bit_flip(), phase_flip(), thermal_relaxation(), readout_error()) and to layer channels with +.

Parameters:

• specs (list[dict[str, Any]] | None) – Internal list of error-spec dicts. Prefer the public constructors.

• label (str) – Human-readable identifier used in assertion failure messages.

property is_empty: bool

Whether this model carries no error channels (a no-op).

to_qiskit()

Build and return a qiskit_aer.noise.NoiseModel.

Raises:

ImportError – If qiskit-aer is not installed.

Return type:

Any

qtest.noise.models.depolarizing(p)

Depolarizing error of strength p on every gate.

With probability p the qubit(s) acted on by a gate are replaced by the maximally mixed state. Applied as a 1-qubit channel to single-qubit gates and a 2-qubit channel to two-qubit gates.

Parameters:

p (float) – Depolarizing probability in [0, 1].

Return type:

NoiseModel

qtest.noise.models.bit_flip(p)

Bit-flip (Pauli-X) error: apply X with probability p after 1-qubit gates.

Parameters:

p (float)

Return type:

NoiseModel

qtest.noise.models.phase_flip(p)

Phase-flip (Pauli-Z) error: apply Z with probability p after 1-qubit gates.

Parameters:

p (float)

Return type:

NoiseModel

qtest.noise.models.thermal_relaxation(t1, t2, time)

Thermal-relaxation (T1/T2) error applied to single-qubit gates.

Parameters:

• t1 (float) – Relaxation time constant (same time unit as time).

• t2 (float) – Dephasing time constant. Must satisfy t2 <= 2 * t1.

• time (float) – Gate duration over which relaxation accumulates.

Return type:

NoiseModel

qtest.noise.models.readout_error(p01, p10=None)

Measurement (readout) error.

Parameters:

• p01 (float) – Probability of reading 1 when the true state is 0.

• p10 (float | None) – Probability of reading 0 when the true state is 1. Defaults to p01 (a symmetric readout error).

Return type:

NoiseModel

qtest.noise.models.available_presets()

Return the sorted names of the built-in noise presets.

Return type:

list[str]

qtest.noise.models.from_preset(name)

Return the NoiseModel for a built-in preset name.

Raises:

ValueError – If name is not a known preset.

Parameters:

name (str)

Return type:

NoiseModel