Noise — NoiseModel, QuantumError, NoiseOpType

API reference for noise modeling in pyqpanda3. The noise framework allows simulation of realistic quantum hardware by applying error channels to quantum operations.

NoiseModel

Manages a collection of quantum errors and readout errors applied during simulation.

Signature

python

class NoiseModel:
    def __init__() -> None

Methods

NoiseModel.is_enabled

python

is_enabled() -> bool

Check if the noise model contains any errors.

NoiseModel.copy / copy / deepcopy

python

copy() -> NoiseModel

New in 0.5.0: copy() returns an independent shallow copy, and the model implements both the copy and deepcopy protocols, so copy.copy(model) and copy.deepcopy(model) work as expected.

python

import copy
from pyqpanda3.core import NoiseModel

model = NoiseModel()
model.add_read_out_error([[0.9, 0.1], [0.2, 0.8]], 0)

duplicate = copy.deepcopy(model)
snapshot = model.copy()
print(duplicate is not model, snapshot is not model)

Output:

text

True True

Convention (0.5.0): Kraus operator matrices are row-major, readout matrices are indexed M[true][measured], a quantum error applies after the instruction it is attached to, and per-qubit (local) errors override default errors rather than composing with them.

NoiseModel.add_read_out_error

python

add_read_out_error(probs: list[list[float]], qubit: int) -> None

Parameter	Type	Description
probs	`list[list[float]]`	Confusion matrix `M` indexed `M[true][measured]` (since 0.5.0): entry `[i][j]` is the probability of recording outcome `j` when the true state is `i`, e.g. `[[p(0\|0), p(1\|0)], [p(0\|1), p(1\|1)]]` with row = true state.
qubit	`int`	Qubit index to apply readout error

NoiseModel.add_all_qubit_read_out_error

python

add_all_qubit_read_out_error(probs: list[list[float]]) -> None

Parameter	Type	Description
probs	`list[list[float]]`	Confusion matrix in the format `[[p(0\|0), p(1\|0)], [p(0\|1), p(1\|1)]]`, where `p(i\|j)` is the probability of measuring outcome `i` when the true state is `j`.

NoiseModel.add_quantum_error (specific qubits)

python

add_quantum_error(error: QuantumError, gate_type: GateType, qubits: list[int]) -> None
add_quantum_error(error: QuantumError, gate_types: list[GateType], qubits: list[int]) -> None

Parameter	Type	Description
error	`QuantumError`	The quantum error to add
gate_type(s)	`GateType` or `list[GateType]`	Gate type(s) where error applies
qubits	`list[int]`	Qubit indices where error applies

NoiseModel.add_all_qubit_quantum_error

python

add_all_qubit_quantum_error(error: QuantumError, gate_type: GateType) -> None
add_all_qubit_quantum_error(error: QuantumError, gate_types: list[GateType]) -> None

Parameter	Type	Description
error	`QuantumError`	The quantum error to add
gate_type(s)	`GateType` or `list[GateType]`	Gate type(s) where error applies

Examples

python

from pyqpanda3.core import (
    NoiseModel, GateType,
    pauli_x_error, depolarizing_error,
    CPUQVM, QProg, H, CNOT, measure
)

# Create a noise model
model = NoiseModel()

# Add single-qubit depolarizing noise to all H gates
model.add_all_qubit_quantum_error(depolarizing_error(0.01), GateType.H)

# Add two-qubit Pauli-X noise to all CNOT gates
model.add_all_qubit_quantum_error(pauli_x_error(0.02), GateType.CNOT)

# Run with noise
qvm = CPUQVM()
prog = QProg()
prog << H(0) << CNOT(0, 1) << measure(0, 0) << measure(1, 1)
qvm.run(prog, 1000, model)
print(qvm.result().get_counts())

Result (example output, varies per run):

{'01': 18, '00': 481, '10': 18, '11': 483}

QuantumError

Represents a quantum error channel, specified either by Kraus matrices or Pauli error probabilities.

Signature

python

class QuantumError:
    def __init__() -> None
    def __init__(karus_matrices: list[list[complex]]) -> None
    def __init__(probabilities: dict[str, float]) -> None

Parameter	Type	Description
karus_matrices	`list[list[complex]]`	Kraus matrices. Each inner list is a flattened (row-major) matrix, e.g., a 2x2 Kraus operator becomes `[a, b, c, d]`
probabilities	`dict[str, float]`	Pauli error labels and probabilities (e.g., `{"X": 0.01}`)

Methods

QuantumError.tensor

python

tensor(quantum_error: QuantumError) -> QuantumError

Parameter	Type	Description
quantum_error	`QuantumError`	The quantum error to tensor with

Apply tensor product operation with another quantum error.

QuantumError.expand

python

expand(quantum_error: QuantumError) -> QuantumError

Parameter	Type	Description
quantum_error	`QuantumError`	The quantum error to expand with

Expand the error to a larger qubit system.

QuantumError.compose

python

compose(quantum_error: QuantumError) -> QuantumError

Parameter	Type	Description
quantum_error	`QuantumError`	The quantum error to compose with

Compose the error with another quantum error.

QuantumError.qubit_num

python

qubit_num() -> int

Number of qubits affected by the error.

QuantumError.error_type

python

error_type() -> NoiseOpType

The type of error representation (Kraus matrices or noise circuit).

QuantumError.error_circuit

python

error_circuit(qubits: list[int]) -> QCircuit

Parameter	Type	Description
qubits	`list[int]`	Qubit indices to apply the error circuit on

Circuit representation of the error.

QuantumError.error_karus

python

error_karus(qubits: list[int]) -> Karus

Parameter	Type	Description
qubits	`list[int]`	Qubit indices to get the Kraus matrices for

Kraus matrix representation of the error. The returned Karus object is a C++ type with limited Python-side interoperability. Note: this method works correctly for errors of type KARUS_MATRIICES (created via Kraus matrices), but will hang for errors of type NOISE (created via Pauli probabilities or factory functions like depolarizing_error).

Karus

Karus encapsulates a set of Kraus operators and the qubits they act on, representing a noise channel. Users typically obtain it via QuantumError.error_karus(qubits), but it can also be constructed directly.

Signature

python

class Karus:
    def __init__(qubits: list[int], matrices: list[list[complex]])
    def remap(remap_qubits: list[int]) -> Karus
    def remap(remap_qubits: dict[int, int]) -> Karus
    def qubits() -> list[int]
    def karus_matrices() -> list[list[complex]]

Karus.init

python

Karus(qubits: list[int], matrices: list[list[complex]])

Construct a Kraus channel from explicit qubit indices and a list of flattened Kraus matrices.

Parameters

Parameter	Type	Description
qubits	`list[int]`	Physical qubit indices the channel acts on.
matrices	`list[list[complex]]`	A list of flattened Kraus operators. Each inner list is a row-major flattened matrix; for an n-qubit channel, length is 4^n.

Karus.remap (by list)

python

Karus.remap(remap_qubits: list[int]) -> Karus

Remap the qubits of this Kraus channel using an index table. Current qubit index i is replaced by remap_qubits[i].

Parameters

Parameter	Type	Description
remap_qubits	`list[int]`	Table mapping old qubit indices to new qubit indices.

Returns

A reference to itself after remapping.

Karus.remap (by dict)

python

Karus.remap(remap_qubits: dict[int, int]) -> Karus

Remap the qubits of this Kraus channel using a dictionary. Qubits not present in the mapping are left unchanged.

Parameters

Parameter	Type	Description
remap_qubits	`dict[int, int]`	Mapping from old qubit indices to new qubit indices.

Returns

A reference to itself after remapping.

Karus.qubits

python

Karus.qubits() -> list[int]

Return the qubits this Kraus channel acts on.

Returns

List of qubit indices associated with the Kraus matrices.

Karus.karus_matrices

python

Karus.karus_matrices() -> list[list[complex]]

Return the flattened Kraus matrices.

Returns

List of flattened Kraus matrices stored by this channel.

Examples

python

from pyqpanda3.core import Karus, QuantumError, depolarizing_error

# Direct construction
k = Karus([0], [[1+0j, 0j, 0j, 1+0j]])
print(k.qubits())            # [0]
print(len(k.karus_matrices()))  # 1

# Via QuantumError
err = depolarizing_error(0.01)
k2 = err.error_karus([2])
print(k2.qubits())           # [2]

# Remap qubits
k2.remap({2: 5})
print(k2.qubits())           # [5]

NoiseOpType

Enum for noise operation representation types.

Value	Description
`KARUS_MATRIICES`	Error represented by Kraus matrices
`NOISE`	Error represented by a noise circuit

Error Factory Functions

pauli_x_error

python

pauli_x_error(prob: float) -> QuantumError

Parameter	Type	Description
prob	`float`	Probability of Pauli-X error

Creates a single-qubit Pauli-X (bit-flip) error channel. With probability $p$ , an $X$ gate is applied.

E (ρ) = (1 - p) ρ + p X ρ X

pauli_y_error

python

pauli_y_error(prob: float) -> QuantumError

Creates a Pauli-Y (bit-phase-flip) error channel.

E (ρ) = (1 - p) ρ + p Y ρ Y

pauli_z_error

python

pauli_z_error(prob: float) -> QuantumError

Creates a Pauli-Z (phase-flip) error channel.

E (ρ) = (1 - p) ρ + p Z ρ Z

depolarizing_error

python

depolarizing_error(prob: float) -> QuantumError

Creates a depolarizing error channel. With probability $p$ , the state is replaced by the maximally mixed state $I / 2$ .

E (ρ) = (1 - p) ρ + p \frac{I}{2}

amplitude_damping_error

python

amplitude_damping_error(prob: float) -> QuantumError

Creates an amplitude damping (T1 relaxation) error channel modeling energy dissipation.

E (ρ) = E_{0} ρ E_{0}^{†} + E_{1} ρ E_{1}^{†}

where $E_{0} = [\begin{matrix} 1 & 0 \\ 0 & \sqrt{1 - γ} \end{matrix}]$ and $E_{1} = [\begin{matrix} 0 & \sqrt{γ} \\ 0 & 0 \end{matrix}]$ .

phase_damping_error

python

phase_damping_error(prob: float) -> QuantumError

Creates a phase damping (T2 dephasing) error channel modeling loss of phase coherence.

E (ρ) = [\begin{matrix} ρ_{00} & (1 - λ) ρ_{01} \\ (1 - λ) ρ_{10} & ρ_{11} \end{matrix}]

decoherence_error

python

decoherence_error(T1: float, T2: float, time_param: float) -> QuantumError

Parameter	Type	Description
T1	`float`	T1 (amplitude damping) relaxation time
T2	`float`	T2 (phase damping) dephasing time
time_param	`float`	Gate operation time

Creates a combined decoherence error modeling both T1 (amplitude damping) and T2 (phase damping) processes.

Noise — NoiseModel, QuantumError, NoiseOpType ​

NoiseModel ​

Signature ​

Methods ​

NoiseModel.is_enabled ​

NoiseModel.copy / copy / deepcopy ​

NoiseModel.add_read_out_error ​

NoiseModel.add_all_qubit_read_out_error ​

NoiseModel.add_quantum_error (specific qubits) ​

NoiseModel.add_all_qubit_quantum_error ​

Examples ​

QuantumError ​

Signature ​

Methods ​

QuantumError.tensor ​

QuantumError.expand ​

QuantumError.compose ​

QuantumError.qubit_num ​

QuantumError.error_type ​

QuantumError.error_circuit ​

QuantumError.error_karus ​

Karus ​

Signature ​

Karus.init ​

Parameters ​

Karus.remap (by list) ​

Parameters ​

Returns ​

Karus.remap (by dict) ​

Parameters ​

Returns ​

Karus.qubits ​

Returns ​

Karus.karus_matrices ​

Returns ​

Examples ​

NoiseOpType ​

Error Factory Functions ​

pauli_x_error ​

pauli_y_error ​

pauli_z_error ​

depolarizing_error ​

amplitude_damping_error ​

phase_damping_error ​

decoherence_error ​

See Also ​

Noise — NoiseModel, QuantumError, NoiseOpType

NoiseModel

Signature

Methods

NoiseModel.is_enabled

NoiseModel.copy / copy / deepcopy

NoiseModel.add_read_out_error

NoiseModel.add_all_qubit_read_out_error

NoiseModel.add_quantum_error (specific qubits)

NoiseModel.add_all_qubit_quantum_error

Examples

QuantumError

Signature

Methods

QuantumError.tensor

QuantumError.expand

QuantumError.compose

QuantumError.qubit_num

QuantumError.error_type

QuantumError.error_circuit

QuantumError.error_karus

Karus

Signature

Karus.init

Parameters

Karus.remap (by list)

Parameters

Returns

Karus.remap (by dict)

Parameters

Returns

Karus.qubits

Returns

Karus.karus_matrices

Returns

Examples

NoiseOpType

Error Factory Functions

pauli_x_error

pauli_y_error

pauli_z_error

depolarizing_error

amplitude_damping_error

phase_damping_error

decoherence_error

See Also