model: abstract base classes

qecsim.model

This module contains base classes relevant to simulating stabilizer codes and a CLI description class decorator.

qecsim.model.StabilizerCode

class qecsim.model.StabilizerCode

Defines stabilizer code properties and methods.

This class cannot be instantiated directly, see qecsim.models.basic.FiveQubitCode for an example implementation.

abstract property label

Label suitable for use in plots.

Return type

str

abstract property logical_xs

Logical X operators as binary symplectic vector or matrix.

Notes:

  • Each row is a logical X operator.

  • The order of logical X operators matches that of logical Z operators given by logical_zs(), with one for each logical qubit.

Return type

numpy.array (1d or 2d)

abstract property logical_zs

Logical Z operators as binary symplectic vector or matrix.

Notes:

  • Each row is a logical Z operator.

  • The order of logical Z operators matches that of logical X operators given by logical_xs(), with one for each logical qubit.

Return type

numpy.array (1d or 2d)

property logicals

Logical operators as binary symplectic matrix.

Notes:

  • Each row is a logical operator.

  • All logical X operators are stacked above all logical Z operators, in the order given by logical_xs() and logical_zs().

Return type

numpy.array (2d)

abstract property n_k_d

Descriptor of the code in the format (n, k, d).

Notes:

  • n == number of physical qubits.

  • k == number of logical qubits.

  • d == distance of the code. (Optional. None if not known).

Return type

3-tuple of int

abstract property stabilizers

Stabilizer generators as binary symplectic vector or matrix.

Notes:

  • Each row is a stabilizer generator.

  • The set must include at least a full set of generators but it may include additional stabilizers to simplify the decoding of syndromes. (E.g. all plaquette / vertex stabilizers on a surface code).

Return type

numpy.array (1d or 2d)

validate()

Perform various sanity checks.

Sanity checks:

  • \(stabilizers \odot stabilisers^T = 0\)

  • \(stabilizers \odot logicals^T = 0\)

  • \(logicals \odot logicals^T = \Lambda\)

See qecsim.paulitools.bsp() for definition of \(\odot\) and \(\Lambda\).

Raises

QecsimError – if the stabilizers or logicals fail the sanity checks.

qecsim.model.ErrorModel

class qecsim.model.ErrorModel

Defines error model properties and methods.

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

abstract generate(code, probability, rng=None)

Generate new error.

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 resolves to numpy.random.default_rng())

Returns

New error as binary symplectic vector.

Return type

numpy.array (1d)

abstract property label

Label suitable for use in plots.

Return type

str

probability_distribution(probability)

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

Notes:

  • Implementing this method is optional. It is not invoked by any core modules. By default, it raises NotImplementedError.

  • Since this method is often useful for decoders, it is provided as a template and subclasses are encouraged to implement it when appropriate, particularly for IID error models.

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

NotImplementedError – Unless implemented in a subclass.

qecsim.model.Decoder

class qecsim.model.Decoder

Defines decoder properties and methods.

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

abstract decode(code, syndrome, **kwargs)

Resolve recovery operation for given syndrome.

Assumptions:

  • The syndrome has length equal to the number of stabilizers.

  • A syndrome element value of 0 or 1 indicates that the corresponding stabilizer commutes or does not commute with the error, respectively.

Notes:

  • The keyword parameters kwargs may be provided by the client with context values such as error_model, error_probability and error, see qecsim.app.run_once(). Most implementations will ignore such parameters; however, if they are used, implementations should declare them explicitly and treat them as optional.

  • This method typically returns a recovery operation but it may, alternatively, return DecodeResult to indicate success/failure more explicitly.

Parameters

  • code (StabilizerCode) – Stabilizer code.

  • syndrome (numpy.array (1d)) – Syndrome as binary vector.

  • kwargs (dict) – Optional context parameters passed by a client.

Returns

Recovery operation as binary symplectic vector, or decode result indicating recovery success.

Return type

numpy.array (1d) or DecodeResult

abstract property label

Label suitable for use in plots.

Return type

str

qecsim.model.DecoderFTP

class qecsim.model.DecoderFTP

Defines (fault-tolerant time-periodic) decoder properties and methods.

This class cannot be instantiated directly, see qecsim.models.rotatedtoric.RotatedToricSMWPMDecoder for an example implementation.

abstract decode_ftp(code, time_steps, syndrome, **kwargs)

Resolve recovery operation for given (fault-tolerant time-periodic) syndrome.

Assumptions:

  • The syndrome has shape (number of time steps, number of stabilizers).

  • In the absence of a measurement error, a syndrome element value of 0 or 1 indicates that the corresponding stabilizer commutes or does not commute with the error, respectively.

  • The presence of a measurement error inverts the value of the corresponding syndrome element.

Notes:

  • The keyword parameters kwargs may be provided by the client with context values such as error_model, error_probability, error, step_errors, measurement_error_probability and step_measurement_errors, see qecsim.app.run_once_ftp(). Most implementations will ignore such parameters; however, if they are used, implementations should declare them explicitly and treat them as optional.

  • This method typically returns a recovery operation but it may, alternatively, return DecodeResult to indicate success/failure more explicitly.

Parameters

  • code (StabilizerCode) – Stabilizer code.

  • time_steps (int) – Number of time steps.

  • syndrome (numpy.array (2d)) – Syndrome as binary array.

  • kwargs (dict) – Optional context parameters passed by a client.

Returns

Recovery operation as binary symplectic vector, or decode result indicating recovery success.

Return type

numpy.array (1d) or DecodeResult

abstract property label

Label suitable for use in plots.

Return type

str

qecsim.model.DecodeResult

class qecsim.model.DecodeResult(success=None, logical_commutations=None, recovery=None, custom_values=None)

Represents the result of decoding.

Typically decoders return a recovery operation and delegate the evaluation of success and logical commutations to qecsim.app. Optionally, decoders may return an instance of this class to partially or completely override the evaluation of success and logical commutations. Additionally, decoders can provide custom values to be summed across runs.

Notes:

  • success and/or logical_commutations, if not None, are used by qecsim.app to override the usual evaluation of success and logical commutations.

  • recovery, if not None, is used by qecsim.app to evaluate any values unspecified by success and/or logical_commutations.

  • success and recovery must not both be None; this ensures that qecsim.app can resolve a success value.

  • Logical commutations, as resolved by qecsim.app, and custom values must be consistent across identically parameterized simulation runs, i.e. always None or always equal length arrays; this ensures that qecsim.app can sum results across multiple runs.

See also Decoder and DecoderFTP.

__init__(success=None, logical_commutations=None, recovery=None, custom_values=None)

Initialise new decode result.

Parameters

  • success (bool) – If the decoding was successful (default=None).

  • logical_commutations (numpy.array (1d)) – Logical commutations as binary vector or None (default=None).

  • recovery (numpy.array (1d)) – Recovery operation as binary symplectic vector (default=None).

  • custom_values (numpy.array (1d)) – Custom values as numeric vector or None (default=None).

Raises

QecsimError – If both success and recovery are unspecified (i.e. None).

qecsim.model.cli_description

@qecsim.model.cli_description

CLI description class decorator.

Notes:

Parameters

description (str) – CLI description.

Returns

CLI description class decorator.

Return type

function