Skip to main content
Classiq-hosted simulators support user-defined noise through ClassiqSimulatorNoiseSpecification. Combine any subset of gate and readout channels; an empty specification runs an ideal (noise-free) simulation. Custom noise is available on Classiq Aer simulators (simulator, simulator_density_matrix, simulator_matrix_product_state, and related backends) and on Nvidia / Braket Nvidia simulators. See Execution on Classiq simulators for backend names.
Preset vs custom noise: ClassiqBackendPreferences accepts either noise_model (a named preset from CLASSIQ_NOISE_MODELS, such as ibm_pittsburgh) or simulator_noise_spec (custom). Set at most one of them.

​
Quick start

Attach a noise specification through backend preferences when you execute a program. 
from classiq import *
@qfunc
def main(res: Output[QBit]) -> None:
    allocate(res)
    X(res)

qprog = synthesize(main)

noise_spec = ClassiqSimulatorNoiseSpecification(
    readout_bit_flip_probability=0.02,
)

df = sample(
    qprog,
    backend="simulator",
    config={"simulator_noise_spec": noise_spec},
    num_shots=1000,
)

​
Noise channels

The sections below describe each building block. Every section includes a minimal code example you can copy into ClassiqSimulatorNoiseSpecification(...).

​
Depolarizing noise on gates

Depolarizing noise mixes the state with the maximally mixed state on the support of the gate: with probability (4n−1)/4n⋅λ(4^n-1)/4^n \cdot \lambda a uniform Pauli error is applied (excluding identity), and otherwise the channel leaves the state unchanged, where nn is the number of qubits the gate acts on and λ\lambda is the probability parameter. Use DepolarizingNoiseOnGate to apply the same depolarizing channel on every occurrence of a named gate. 
from classiq import ClassiqSimulatorNoiseSpecification, DepolarizingNoiseOnGate

ClassiqSimulatorNoiseSpecification(
    gate_depolarizing_errors=[
        DepolarizingNoiseOnGate(gate="x", probability=0.001, num_qubits=1),
        DepolarizingNoiseOnGate(gate="cx", probability=0.01, num_qubits=2),
    ],
)

​
Local depolarizing noise on gates

LocalDepolarizingNoiseOnGate applies depolarizing noise only when the named gate acts on a specific ordered tuple of qubit indices. Other placements of the same gate name are unaffected. 
from classiq import ClassiqSimulatorNoiseSpecification, LocalDepolarizingNoiseOnGate

ClassiqSimulatorNoiseSpecification(
    local_depolarizing_errors=[
        LocalDepolarizingNoiseOnGate(
            gate="cx",
            num_qubits=2,
            probability=0.02,
            qubits=[0, 1],
        ),
    ],
)

​
Pauli noise on gates

Pauli noise is a probabilistic mixture: each term is a Pauli product (written as a string of I, X, Y, Z per qubit, e.g. X on one qubit, IX or XY on two) with an associated probability. All term probabilities must sum to 1. Use PauliNoiseTerm and PauliNoiseOnGate to attach a mixed Pauli channel to every occurrence of a gate. Include an identity (I) term when you want a fraction of executions to stay error-free. 
from classiq import (
    ClassiqSimulatorNoiseSpecification,
    PauliNoiseOnGate,
    PauliNoiseTerm,
)

ClassiqSimulatorNoiseSpecification(
    gate_pauli_errors=[
        PauliNoiseOnGate(
            gate="x",
            num_qubits=1,
            pauli_terms=[
                PauliNoiseTerm(pauli="I", probability=0.99),
                PauliNoiseTerm(pauli="X", probability=0.01),
            ],
        ),
    ],
)

​
Thermal relaxation on single-qubit gates

Thermal relaxation models energy decay and dephasing over a gate duration. Use coherent time constants t1 (amplitude damping) and t2 (dephasing) in any consistent unit, the same unit for time as the gate duration, and optional excited_state_population for the equilibrium ∣1⟩|1\rangle population. For physical consistency, require T2≤2T1T_2 \leq 2 T_1. ThermalRelaxationNoiseOnGate is defined for a single computational qubit; attach it only to single-qubit gate names. 
from classiq import ClassiqSimulatorNoiseSpecification, ThermalRelaxationNoiseOnGate

ClassiqSimulatorNoiseSpecification(
    gate_thermal_relaxation_errors=[
        ThermalRelaxationNoiseOnGate(
            gate="sx",
            t1=60_000.0,
            t2=20_000.0,
            time=100.0,
        ),
    ],
)

​
Global readout bit-flip probability

The symmetric one-parameter readout model swaps classical outcomes 0 and 1 with probability p on each qubit, for both ∣0⟩|0\rangle and ∣1⟩|1\rangle pre-measurement states. Set readout_bit_flip_probability on ClassiqSimulatorNoiseSpecification. This field is mutually exclusive with readout_assignment_probabilities. 
from classiq import ClassiqSimulatorNoiseSpecification

ClassiqSimulatorNoiseSpecification(
    readout_bit_flip_probability=0.02,
)

​
Global readout assignment matrix

Readout noise can also be specified with a 2-by-2 assignment matrix: row index is the true pre-measurement computational state (0 or 1), column index is the classical outcome (0 or 1); entry (i,j)(i,j) is the probability of recording outcome jj when the qubit was in state ∣i⟩|i\rangle. Each row must be non-negative and sum to 1. Set readout_assignment_probabilities to apply one matrix to every qubit’s measurement. Mutually exclusive with readout_bit_flip_probability. 
from classiq import ClassiqSimulatorNoiseSpecification

ClassiqSimulatorNoiseSpecification(
    readout_assignment_probabilities=[[0.98, 0.02], [0.03, 0.97]],
)

​
Local readout noise

LocalReadoutNoise assigns a full 2-by-2 assignment matrix to a single simulator qubit index. Use local_readout_errors when different qubits need different readout confusion. 
from classiq import ClassiqSimulatorNoiseSpecification, LocalReadoutNoise

ClassiqSimulatorNoiseSpecification(
    local_readout_errors=[
        LocalReadoutNoise(
            qubit=0,
            assignment_probabilities=[[0.9, 0.1], [0.15, 0.85]],
        ),
    ],
)

​
Basis gates

basis_gates lists optional primitive gate names used when the simulator decomposes circuits before attaching noise. If omitted, the backend uses its default primitive set (commonly single-qubit rotations and one entangling gate type). 
from classiq import ClassiqSimulatorNoiseSpecification

ClassiqSimulatorNoiseSpecification(
    basis_gates=["id", "rz", "sx", "cx", "x"],
)

​
Combining channels

You can mix gate and readout channels in one specification. Global readout settings (readout_bit_flip_probability or readout_assignment_probabilities) cannot both be set; per-qubit readout in local_readout_errors uses the same matrix convention. 
from classiq import (
    ClassiqSimulatorNoiseSpecification,
    DepolarizingNoiseOnGate,
    LocalDepolarizingNoiseOnGate,
    LocalReadoutNoise,
    PauliNoiseOnGate,
    PauliNoiseTerm,
    ThermalRelaxationNoiseOnGate,
)

ClassiqSimulatorNoiseSpecification(
    basis_gates=["id", "rz", "sx", "cx", "x"],
    gate_depolarizing_errors=[
        DepolarizingNoiseOnGate(gate="x", probability=0.001, num_qubits=1),
    ],
    local_depolarizing_errors=[
        LocalDepolarizingNoiseOnGate(
            gate="cx", num_qubits=2, probability=0.02, qubits=[0, 1]
        ),
    ],
    gate_pauli_errors=[
        PauliNoiseOnGate(
            gate="h",
            num_qubits=1,
            pauli_terms=[
                PauliNoiseTerm(pauli="I", probability=0.99),
                PauliNoiseTerm(pauli="Z", probability=0.01),
            ],
        ),
    ],
    gate_thermal_relaxation_errors=[
        ThermalRelaxationNoiseOnGate(gate="sx", t1=60_000.0, t2=20_000.0, time=100.0),
    ],
    readout_assignment_probabilities=[[0.98, 0.02], [0.03, 0.97]],
    local_readout_errors=[
        LocalReadoutNoise(
            qubit=0,
            assignment_probabilities=[[0.9, 0.1], [0.15, 0.85]],
        ),
    ],
)

​
Validation rules

The SDK validates noise specifications before execution. Common constraints:
RuleApplies to
noise_model and simulator_noise_spec are mutually exclusiveClassiqBackendPreferences
readout_bit_flip_probability and readout_assignment_probabilities are mutually exclusiveClassiqSimulatorNoiseSpecification
Pauli term probabilities must sum to 1PauliNoiseOnGate
len(qubits) must equal num_qubitsLocalDepolarizingNoiseOnGate
T2≤2T1T_2 \leq 2 T_1ThermalRelaxationNoiseOnGate
Assignment matrices must be 2-by-2, non-negative, row-stochasticLocalReadoutNoise, global readout fields
For full field-level reference, see Simulator noise (SDK reference).