models.generic: generic error models and decoders

qecsim.models.generic

This module contains generic implementations of error models and decoders that will work with any stabilizer codes.

qecsim.models.generic.SimpleErrorModel

class qecsim.models.generic.SimpleErrorModel

Bases: qecsim.model.ErrorModel

Implements a simple IID error model that generates an error based on the number of qubits and the probability distribution.

This class cannot be instantiated directly, see qecsim.models.generic.DepolarizingErrorModel for an example implementation.

generate(code, probability, rng=None)

See qecsim.model.ErrorModel.generate()

Notes:

  • This method delegates to probability_distribution() to find the probability of I, X, Y, Z operators on each qubit, assuming an IID error model.

abstract property label

See qecsim.model.ErrorModel.label()

abstract probability_distribution(probability)

See qecsim.model.ErrorModel.probability_distribution()

Note: Implementing this method is required. It is invoked by generate().

qecsim.models.generic.BiasedDepolarizingErrorModel

class qecsim.models.generic.BiasedDepolarizingErrorModel(bias, axis='Y')

Bases: qecsim.models.generic._simpleerrormodel.SimpleErrorModel

Implements a biased-depolarizing error model.

In addition to the members defined in qecsim.model.ErrorModel, it provides the following method:

The probability distribution for a given error probability p given axis = ‘Y’ is:

  • 1 - p: I (i.e. no error)

  • 1 / (2 * (bias + 1)) * p: X

  • bias / (bias + 1) * p: Y

  • 1 / (2 * (bias + 1)) * p: Z

Notes:

  • Probability distributions are defined analogously for axis = ‘X’ and axis = ‘Z’.

  • bias = 0.5 corresponds to the standard depolarizing error model.

__init__(bias, axis='Y')

Initialise new biased-depolarizing error model.

Parameters

  • bias (float) – Bias in favour of axis errors relative to off-axis errors.

  • axis (str) – Axis towards which the noise is biased (default=’Y’, values=’X’, ‘Y’, ‘Z’)

Raises

  • ValueError – if bias is not > 0.

  • ValueError – if axis is not in (‘X’, ‘Y’, ‘Z’) (lowercase accepted).

  • TypeError – if any parameter is of an invalid type.

property axis

Axis.

Return type

str

property bias

Bias.

Return type

float

generate(code, probability, rng=None)

See qecsim.model.ErrorModel.generate()

Notes:

  • This method delegates to probability_distribution() to find the probability of I, X, Y, Z operators on each qubit, assuming an IID error model.

property label

See qecsim.model.ErrorModel.label()

probability_distribution(probability)

See qecsim.model.ErrorModel.probability_distribution()

qecsim.models.generic.BiasedYXErrorModel

class qecsim.models.generic.BiasedYXErrorModel(bias)

Bases: qecsim.models.generic._simpleerrormodel.SimpleErrorModel

Implements a biased-Y-X error model.

In addition to the members defined in qecsim.model.ErrorModel, it provides the following method:

The probability distribution for a given error probability p is:

  • 1 - p: I (i.e. no error)

  • rx * (1 - ry): X

  • ry * (1 - rx): Y

  • rx * ry: Z

where rx, ry, rz are rates found by solving:

  • p = px + py + pz

  • bias = py / px

Note: bias = 0 corresponds to the standard bit-flip error model (i.e. pure X-noise).

__init__(bias)

Initialise new biased-Y-X error model.

Parameters

bias (float) – Bias in favour of Y errors relative to X errors.

Raises

  • ValueError – if bias is not >=0.

  • TypeError – if any parameter is of an invalid type.

property bias

Bias.

Return type

float

generate(code, probability, rng=None)

See qecsim.model.ErrorModel.generate()

Notes:

  • This method delegates to probability_distribution() to find the probability of I, X, Y, Z operators on each qubit, assuming an IID error model.

property label

See qecsim.model.ErrorModel.label()

probability_distribution(probability)

See qecsim.model.ErrorModel.probability_distribution()

qecsim.models.generic.BitFlipErrorModel

class qecsim.models.generic.BitFlipErrorModel

Bases: qecsim.models.generic._simpleerrormodel.SimpleErrorModel

Implements a bit-flip error model.

The probability distribution for a given error probability p is:

  • (1 - p): I (i.e. no error)

  • p: X

  • 0: Y

  • 0: Z

generate(code, probability, rng=None)

See qecsim.model.ErrorModel.generate()

Notes:

  • This method delegates to probability_distribution() to find the probability of I, X, Y, Z operators on each qubit, assuming an IID error model.

property label

See qecsim.model.ErrorModel.label()

probability_distribution(probability)

See qecsim.model.ErrorModel.probability_distribution()

qecsim.models.generic.BitPhaseFlipErrorModel

class qecsim.models.generic.BitPhaseFlipErrorModel

Bases: qecsim.models.generic._simpleerrormodel.SimpleErrorModel

Implements a bit-phase-flip error model.

The probability distribution for a given error probability p is:

  • (1 - p): I (i.e. no error)

  • 0: X

  • p: Y

  • 0: Z

generate(code, probability, rng=None)

See qecsim.model.ErrorModel.generate()

Notes:

  • This method delegates to probability_distribution() to find the probability of I, X, Y, Z operators on each qubit, assuming an IID error model.

property label

See qecsim.model.ErrorModel.label()

probability_distribution(probability)

See qecsim.model.ErrorModel.probability_distribution()

qecsim.models.generic.CenterSliceErrorModel

class qecsim.models.generic.CenterSliceErrorModel(lim, pos)

Bases: qecsim.models.generic._simpleerrormodel.SimpleErrorModel

Implements a center-slice error model.

In addition to the members defined in qecsim.model.ErrorModel, it provides the following properties:

The (normalized) limit defines a point on the boundary of the triangle with vertices (1, 0, 0), (0, 1, 0), and (0, 0, 1) in Euclidean x, y, z coordinates. The center point is defined to be at (1/3, 1/3, 1/3). The negative limit defines the point at the other intersection of the boundary of the triangle and the line through the limit and the center. Positive position defines a point on a linear scale along this line from the center, at position 0, to the limit, at position 1. Similarly, negative position defines a point on the line from the center to the negative limit, at position -1. The ratio, r_x:r_y:r_z, corresponds to the coordinates (r_x, r_y, r_z) of the point defined by position. With such a definition, ratio is always normalized to sum to 1.

The probability distribution for a given error probability p is:

  • 1 - p: I (i.e. no error)

  • r_x * p: X

  • r_y * p: Y

  • r_z * p: Z

Notes:

  • pos = 0 corresponds to the standard depolarizing error model.

  • lim = (1, 0, 0) and pos = 1 corresponds to pure bit-flip noise.

  • lim = (0, 1, 0) and pos = 1 corresponds to pure bit-phase-flip noise.

  • lim = (0, 0, 1) and pos = 1 corresponds to pure phase-flip noise.

__init__(lim, pos)

Initialise new center-slice error model.

Parameters

  • lim (3-tuple of float) – Limit (possibly unnormalized).

  • pos (float) – Position.

Raises

  • ValueError – if lim is not of length 3 with 1 or 2 zeros.

  • ValueError – if stp is not -1.0 <= pos <= 1.0.

  • TypeError – if any parameter is of an invalid type.

generate(code, probability, rng=None)

See qecsim.model.ErrorModel.generate()

Notes:

  • This method delegates to probability_distribution() to find the probability of I, X, Y, Z operators on each qubit, assuming an IID error model.

property label

See qecsim.model.ErrorModel.label()

property lim

Limit (normalized).

Return type

3-tuple of float

property neg_lim

Negative limit.

Return type

3-tuple of float

property pos

Position.

Return type

float

probability_distribution(probability)

See qecsim.model.ErrorModel.probability_distribution()

property ratio

Ratio.

Return type

3-tuple of float

qecsim.models.generic.DepolarizingErrorModel

class qecsim.models.generic.DepolarizingErrorModel

Bases: qecsim.models.generic._simpleerrormodel.SimpleErrorModel

Implements a depolarizing error model.

The probability distribution for a given error probability p is:

  • (1 - p): I (i.e. no error)

  • p/3: X

  • p/3: Y

  • p/3: Z

generate(code, probability, rng=None)

See qecsim.model.ErrorModel.generate()

Notes:

  • This method delegates to probability_distribution() to find the probability of I, X, Y, Z operators on each qubit, assuming an IID error model.

property label

See qecsim.model.ErrorModel.label()

probability_distribution(probability)

See qecsim.model.ErrorModel.probability_distribution()

qecsim.models.generic.FileErrorModel

class qecsim.models.generic.FileErrorModel(filename, start=0)

Bases: qecsim.model.ErrorModel

Implements a file error model.

In addition to the members defined in qecsim.model.ErrorModel, it provides properties given by additional headers in the file.

The expected file format is new-line delimited JSON + JS comments:

// Comment lines start with //; comment lines are ignored.
// Blank lines are also ignored.
// Non-comment lines are JSON-encoded per line.
//
// Header lines are JSON objects containing one or more keys.
// A dictionary is built from header lines; an exception is raised if keys are repeated across header lines.
// The following header key is required; it gives the marginal error probability per qubit.
{"probability": 0.4}
// The following header key is required; it identifies the algorithm/parameters used to generate the errors.
{"label": "Biased (bias=10)"}
// The following header key is desirable; it gives the (I, X, Y, Z) marginal probability distribution per qubit.
{"probability_distribution": [0.6, 0.018181818181818184, 0.36363636363636365, 0.018181818181818184]}
// Additional header keys are optional; they are added as properties to the error model.
{"bias": 10}
// All header lines must appear before body lines.
//
// Body lines are JSON lists containing a single error per line.
// Each error unpacked using qecsim.paulitools.unpack into a NumPy array in binary symplectic form.
// (The following errors are suitable for the qecsim.models.linear.FiveQubitCode)
["f380", 10]
["2940", 10]
["ce00", 10]
["7bc0", 10]
["8400", 10]
["5280", 10]
["1080", 10]
["d680", 10]
["4a40", 10]
["4a40", 10]

Notes:

  • Header key “probability” is used to validate the error probability assumed in simulations matches that of the generated errors.

  • Header key “label” is used to identify simulations that can be merged for statistical purposes.

  • Header key “probability_distribution” is used to make that information available to decoders that make use of it.

  • Extra header keys are made available as object attributes to decoders that make use of them. The key format must be a valid Python attribute name, not start with an underscore, and not shadow an existing attribute.

__init__(filename, start=0)

Initialise new file error model.

Parameters

  • filename (str or path-like) – Name of file containing generated errors.

  • start (int) – Index of first error to serve. (default=0)

Raises

  • ValueError – if start is not >=0.

  • OSError – if filename cannot be opened for reading.

  • ValueError – if file parsing fails.

  • EOFError – if start error unavailable.

  • TypeError – if any parameter is of an invalid type.

generate(code, probability, rng=None)

Return next error from file.

Parameters

  • code (StabilizerCode) – Stabilizer code.

  • probability (float) – Overall probability of an error on a single qubit.

  • rng (numpy.random.Generator) – Random number generator. (default=None, ignored)

Returns

Next error as binary symplectic vector.

Return type

numpy.array (1d)

Raises

  • ValueError – if probability does not equal probability given in file header.

  • EOFError – if next error unavailable.

  • ValueError – if file parsing fails.

  • ValueError – if length of error is inconsistent with number of qubits in code.

property label

See qecsim.model.ErrorModel.label()

probability_distribution(probability)

Return the single-qubit probability distribution amongst Pauli I, X, Y and Z.

Parameters

probability (float) – Overall probability of an error on a single qubit.

Returns

Tuple of probability distribution in the format (Pr(I), Pr(X), Pr(Y), Pr(Z)).

Return type

4-tuple of float

Raises

  • ValueError – if probability does not equal probability given in file header.

  • ValueError – if probability_distribution not given in file header.

qecsim.models.generic.PhaseFlipErrorModel

class qecsim.models.generic.PhaseFlipErrorModel

Bases: qecsim.models.generic._simpleerrormodel.SimpleErrorModel

Implements a phase-flip error model.

The probability distribution for a given error probability p is:

  • (1 - p): I (i.e. no error)

  • 0: X

  • 0: Y

  • p: Z

generate(code, probability, rng=None)

See qecsim.model.ErrorModel.generate()

Notes:

  • This method delegates to probability_distribution() to find the probability of I, X, Y, Z operators on each qubit, assuming an IID error model.

property label

See qecsim.model.ErrorModel.label()

probability_distribution(probability)

See qecsim.model.ErrorModel.probability_distribution()

qecsim.models.generic.NaiveDecoder

class qecsim.models.generic.NaiveDecoder(max_qubits=10)

Bases: qecsim.model.Decoder

Implements a naive decoder.

Decoding algorithm:

  • Naively iterate through all possible errors, in ascending weight, and resolve to the first error that matches the syndrome.

Notes:

  • Slow for large numbers of qubits and high weights.

__init__(max_qubits=10)

Initialise new naive decoder.

Notes:

  • As this decoder is slow for large number of qubits, it is restricted by default. Set max_qubits to override.

Parameters

max_qubits (int or None) – Maximum supported number of physical qubits. (default=10, unrestricted=falsy)

Raises

  • ValueError – if max_qubits is not falsy or > 0.

  • TypeError – if any parameter is of an invalid type.

decode(code, syndrome, **kwargs)

See qecsim.model.Decoder.decode()

Raises

ValueError – if qubits in code exceeds max_qubits.

property label

See qecsim.model.Decoder.label()