tensorcircuit.zx.noise_model

Pauli noise channels and error sampling infrastructure.

class tensorcircuit.zx.noise_model.Channel(probs: Any, unique_col_ids: tuple[int, ...])

Bases: object

A probability distribution over error outcomes.

probs

Shape (2^k,) probability array, sums to 1, dtype float64

Type:

Any

unique_col_ids

Tuple of column IDs, where each ID corresponds to a bit of the channel.

Type:

tuple[int, …]

__init__(probs: Any, unique_col_ids: tuple[int, ...]) → None

property num_bits: int

Number of bits in the channel (k where probs has shape 2^k).

probs: Any

unique_col_ids: tuple[int, ...]

class tensorcircuit.zx.noise_model.ChannelSampler(channel_probs: list[Any], error_transform: Any, seed: int | None = None)

Bases: object

Samples from multiple error channels and transforms to a reduced basis.

This class combines multiple error channels (each producing error bits e0, e1, …) and applies a linear transformation over GF(2) to convert samples from the original “e” basis to a reduced “f” basis using geometric-skip sampling optimized for low-noise regimes.

f_i = error_transform_ij * e_j mod 2

Channels are automatically simplified by: 1. Removing bits e_i that do not affect any f-variable (i.e. all-zero columns in error_transform) 2. Merging channels with identical column signatures, i.e. channels whose corresponding

columns in error_transform are identical.

3. Absorbing channels whose signatures are subsets of others, i.e. channels whose corresponding

   columns in error_transform are a strict subset of another channel’s columns.

Example

>>> probs = [error_probs(0.1), error_probs(0.2)]  # two 1-bit channels
>>> transform = np.array([[1, 1]])  # f0 = e0 XOR e1
>>> sampler = ChannelSampler(probs, transform)
>>> samples = sampler.sample(1000)  # shape (1000, 1)

__init__(channel_probs: list[Any], error_transform: Any, seed: int | None = None)

Initialize the sampler with channel probabilities and a basis transformation.

Parameters:

• channel_probs – List of probability arrays. Channel i has shape (2^k_i,) and produces k_i error bits starting at index sum(k_0:k_{i-1}). For example, if channels have shapes [(4,), (2,), (4,)], they produce variables [e0,e1], [e2], [e3,e4].

• error_transform – Binary matrix of shape (num_f, num_e) where entry [i, j] = 1 means f_i depends on e_j. For example, if row 0 is [0, 1, 0, 1], then f0 = e1 XOR e3.

• seed – Random seed for sampling. If None, a random seed is generated.

property num_f_params: int

Number of reduced basis parameters (f-basis).

Returns:

Number of parameters.

Return type:

int

sample(num_samples: int = 1) → Any

Sample from all error channels and transform to the f-basis.

Uses geometric-skip sampling optimized for low-noise regimes.

Parameters:

num_samples (int, optional) – Number of samples to draw, defaults to 1.

Returns:

Binary array of shape (num_samples, num_f) containing sampled outcomes.

Return type:

np.ndarray

sample_jax(num_samples: int, key: Any) → tuple[Any, Any]

Sample from all error channels on-device using JAX categorical sampling.

Parameters:

• num_samples (int) – Number of samples to draw.

• key (Any) – JAX PRNG key.

Returns:

Tuple of (samples, next_key) where samples is a JAX array of shape (num_samples, num_f) with dtype uint8.

Return type:

tuple[jax.Array, Any]

tensorcircuit.zx.noise_model.absorb_subset_channels(channels: list[Channel], max_bits: int = 4) → list[Channel]

Absorb channels whose signatures are subsets of others.

If channel A’s signatures are a strict subset of channel B’s signatures, and |B| <= max_bits, then A is absorbed into B.

Parameters:

• channels – List of channels

• max_bits – Maximum number of bits allowed per channel

Returns:

List with no channel being a strict subset of another

tensorcircuit.zx.noise_model.correlated_error_probs(probabilities: list[float]) → Any

Build probability distribution for correlated error chain.

Given conditional probabilities [p1, p2, …, pk] from a chain of CORRELATED_ERROR(p1) ELSE_CORRELATED_ERROR(p2) … ELSE_CORRELATED_ERROR(pk), computes the joint probability distribution over 2^k outcomes.

Since errors are mutually exclusive, only outcomes with at most one bit set have non-zero probability: - P(0) = (1-p1)(1-p2)…(1-pk) (no error) - P(2^i) = (1-p1)…(1-p_i) * p_{i+1} (error i+1 occurred)

Parameters:

probabilities – List of conditional probabilities [p1, p2, …, pk]

Returns:

Array of shape (2^k,) with probabilities for each outcome.

tensorcircuit.zx.noise_model.error_probs(p: float) → Any

Single-bit error channel probability distribution.

Parameters:

p (float) – Error probability.

Returns:

Array [1-p, p] of shape (2,).

Return type:

np.ndarray

tensorcircuit.zx.noise_model.expand_channel(channel: Channel, target_col_ids: tuple[int, ...]) → Channel

Expand a channel’s distribution to a larger signature set.

The channel’s existing col_ids must be a strict subset of target_col_ids. Both must be sorted. New bit positions are treated as “don’t care” (always 0).

Parameters:

• channel – Channel to expand (must have sorted unique_col_ids)

• target_col_ids – Target signature set (must be sorted superset)

Returns:

New channel with expanded distribution

tensorcircuit.zx.noise_model.merge_identical_channels(channels: list[Channel]) → list[Channel]

Merge all channels with identical signature sets.

Groups channels by their unique_col_ids and convolves all channels in each group into a single channel.

Parameters:

channels – List of channels

Returns:

List with at most one channel per unique signature set

tensorcircuit.zx.noise_model.normalize_channels(channels: list[Channel]) → list[Channel]

Normalize channels by sorting unique_col_ids, permuting probs accordingly.

This ensures channels affecting the same set of columns have identical unique_col_ids tuples, enabling merge_identical_channels to group them.

Parameters:

channels – List of channels

Returns:

List of channels with sorted unique_col_ids

tensorcircuit.zx.noise_model.pauli_channel_1_probs(px: float, py: float, pz: float) → Any

Single-qubit Pauli channel probability distribution.

Parameters:

• px (float) – X error probability.

• py (float) – Y error probability.

• pz (float) – Z error probability.

Returns:

Array [I, Z, X, Y] of shape (4,).

Return type:

np.ndarray

tensorcircuit.zx.noise_model.pauli_channel_2_probs(pix: float, piy: float, piz: float, pxi: float, pxx: float, pxy: float, pxz: float, pyi: float, pyx: float, pyy: float, pyz: float, pzi: float, pzx: float, pzy: float, pzz: float) → Any

Two-qubit Pauli channel probability distribution.

Parameters:

pix – Probability of error I on qubit 1 and X on qubit 2.

… :return: Array of shape (16,). :rtype: np.ndarray

tensorcircuit.zx.noise_model.reduce_null_bits(channels: list[Channel], null_col_id: int | None = None) → list[Channel]

Remove bits corresponding to the null column (all-zero column).

If a channel has bits mapped to null_col_id (representing an all-zero column in the transform matrix), those bits don’t affect any f-variable and can be marginalized out by summing over them.

Parameters:

• channels – List of channels

• null_col_id – Column ID representing the all-zero column, or None if there is no all-zero column.

Returns:

List of channels with null bits marginalized out. Channels with all null entries are removed entirely (they have no effect on outputs).

tensorcircuit.zx.noise_model.simplify_channels(channels: list[Channel], max_bits: int = 4, null_col_id: int | None = None) → list[Channel]

Simplify a list of channels by reducing null bits, merging identical signatures, and absorbing subsets.

Parameters:

• channels (list[Channel]) – List of input channels.

• max_bits (int, optional) – Maximum number of bits allowed per simplified channel, defaults to 4.

• null_col_id (int, optional) – ID of the all-zero column in the error transform, defaults to None.

Returns:

Simplified list of channels.

Return type:

list[Channel]

tensorcircuit.zx.noise_model.xor_convolve(probs_a: Any, probs_b: Any) → Any

XOR convolution of two probability distributions.

Parameters:

• probs_a (np.ndarray) – Probability distribution of channel A.

• probs_b (np.ndarray) – Probability distribution of channel B.

Returns:

Combined probability distribution.

Return type:

np.ndarray