models.planar: planar stabilizer codes¶

`qecsim.models.planar`¶

This module contains implementations relevant to planar stabilizer codes.

`qecsim.models.planar.PlanarCode`¶

class qecsim.models.planar.PlanarCode(rows, columns)¶

Bases: qecsim.model.StabilizerCode

Implements a planar mixed boundary code defined by its lattice size.

In addition to the members defined in qecsim.model.StabilizerCode, it provides several lattice methods as described below.

Lattice methods:

Get size: size().
Find shortest translation between plaquettes: translation().
Resolve a syndrome to plaquettes: syndrome_to_plaquette_indices().
Construct a Pauli operator on the lattice: new_pauli().

Indices:

Indices are in the format (row, column).
Qubit site (i.e. edge) indices satisfy (row + column) mod 2 = 0. On the primal lattice, horizontal edge indices satisfy row mod 2 = 0 and col mod 2 = 0, while vertical edge indices satisfy row mod 2 = 1 and col mod 2 = 1.

For example, site indices on a 3 x 3 planar lattice (primal lattice edges shown):

(0,0)-----|-----(0,2)-----|-----(0,4)
          |               |
        (1,1)           (1,3)
          |               |
(2,0)-----|-----(2,2)-----|-----(2,4)
          |               |
        (3,1)           (3,3)
          |               |
(4,0)-----|-----(4,2)-----|-----(4,4)

Stabilizer plaquette indices satisfy (row + column) mod 2 = 1. On the primal lattice, plaquette indices satisfy row mod 2 = 1 and col mod 2 = 0, while, on the dual lattice, plaquette indices satisfy row mod 2 = 0 and col mod 2 = 1.

For example, plaquette indices on the primal 3 x 3 lattice (primal lattice edges shown):

   -------|---------------|-------
          |               |
(1,0)     |     (1,2)     |     (1,4)
          |               |
   -------|---------------|-------
          |               |
(3,0)     |     (3,2)     |     (3,4)
          |               |
   -------|---------------|-------

For example, plaquette indices on the dual 3 x 3 lattice (dual lattice edges shown):

:     (0,1)     :     (0,3)     :
:               :               :
: - - - - - - - : - - - - - - - :
:               :               :
:     (2,1)     :     (2,3)     :
:               :               :
: - - - - - - - : - - - - - - - :
:               :               :
:     (4,1)     :     (4,3)     :

__init__(rows, columns)¶

Initialise new planar code.

Parameters

rows (int) – Number of rows in lattice.
columns (int) – Number of columns in lattice.

Raises

ValueError – if (rows, columns) smaller than (2, 2) in either dimension.
TypeError – if any parameter is of an invalid type.

ascii_art(syndrome=None, pauli=None)¶

Return ASCII art style lattice showing primal lattice lines with syndrome bits and Pauli operators as given.

Parameters

syndrome (numpy.array (1d)) – Syndrome (optional) as binary vector.
pauli (PlanarPauli) – Planar Pauli (optional)

Returns

ASCII art style lattice.

Return type

str

property bounds¶

Maximum row and column value that an index coordinate can take.

Return type: 2-tuple of int

classmethod is_dual(index)¶

Return True if the index specifies a dual plaquette (i.e. row mod 2 = 0) or site (i.e. row mod 2 = 1), irrespective of lattice bounds.

Parameters: index (2-tuple of int) – Index in the format (row, column).
Returns: If the index specifies a dual plaquette or site.
Return type: bool

is_in_bounds(index)¶

Return True if the index is within lattice bounds inclusive, irrespective of object type.

Parameters: index (2-tuple of int) – Index in the format (row, column).
Returns: If the index is within lattice bounds inclusive.
Return type: bool

classmethod is_plaquette(index)¶

Return True if the index specifies a plaquette, irrespective of lattice bounds, i.e. (row + column) mod 2 = 1.

Parameters: index (2-tuple of int) – Index in the format (row, column).
Returns: If the index specifies a plaquette
Return type: bool

classmethod is_primal(index)¶

Return True if the index specifies a primal plaquette (i.e. row mod 2 = 1) or site (i.e. row mod 2 = 0), irrespective of lattice bounds.

Parameters: index (2-tuple of int) – Index in the format (row, column).
Returns: If the index specifies a primal plaquette or site.
Return type: bool

classmethod is_site(index)¶

Return True if the index specifies a site (i.e. (row + column) mod 2 = 0), irrespective of lattice bounds.

Parameters: index (2-tuple of int) – Index in the format (row, column).
Returns: If the index specifies a site.
Return type: bool

property label¶: See qecsim.model.StabilizerCode.label()

property logical_xs¶: See qecsim.model.StabilizerCode.logical_xs()

property logical_zs¶: See qecsim.model.StabilizerCode.logical_zs()

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)

property n_k_d¶: See qecsim.model.StabilizerCode.n_k_d()

new_pauli(bsf=None)¶

Convenience constructor of planar Pauli for this code.

Notes:

For performance reasons, the new Pauli is a view of the given bsf. Modifying one will modify the other.

Parameters: bsf (numpy.array (1d)) – Binary symplectic representation of Pauli. (Optional. Defaults to identity.)
Returns: Planar Pauli
Return type: PlanarPauli

property size¶

Size of the lattice in format (rows, columns), e.g. (5, 5).

Return type: 2-tuple of int

property stabilizers¶: See qecsim.model.StabilizerCode.stabilizers()

syndrome_to_plaquette_indices(syndrome)¶

Returns the indices of the plaquettes associated with the non-commuting stabilizers identified by the syndrome.

Parameters: syndrome (numpy.array (1d)) – Binary vector identifying commuting and non-commuting stabilizers by 0 and 1 respectively.
Returns: Set of plaquette indices.
Return type: set of 2-tuple of int

translation(a_index, b_index)¶

Evaluate the shortest taxi-cab translation from plaquette A to plaquette B in format (row_steps, col_steps), where translation is the number of plaquette steps not the the difference in indices.

Notes:

Indices are in the format (row, column).
Both indices must index the same lattice, see is_primal() / is_dual().
Plaquettes not indexed within the lattice are said to be virtual, see bounds().
If both plaquettes are virtual then the translation is defined to be (0, 0).
Negative row_steps / col_steps indicate steps in the direction of decreasing index.

Parameters

a_index (2-tuple of int) – Index identifying a plaquette in the format (row, column).
b_index (2-tuple of int) – Index identifying a plaquette in the format (row, column).

Returns

Taxi-cab translation between plaquettes.

Return type

2-tuple of int

Raises

IndexError – If indices are not plaquette indices on the same lattice.

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.

virtual_plaquette_index(index)¶

For the given index of a plaquette on the primal (dual) lattice, returns the index of the virtual plaquette just outside the nearest primal (dual) boundary.

Notes:

Index is in the format (row, column).
Given a primal (dual) plaquette, the nearest virtual plaquette will reside on the North or South (West or East) boundary, so the returned index will be the same as the given index with the row (column) adjusted to sit just outside the nearest boundary. If both boundaries are equally close then the North (West) boundary is preferred.
The above rule applies even if the given index is outside the boundary.

Parameters: index (2-tuple of int) – Index identifying a plaquette in the format (row, column).
Returns: Index of nearest virtual plaquette.
Return type: 2-tuple of int
Raises: IndexError – If index is not a plaquette index.

`qecsim.models.planar.PlanarPauli`¶

class qecsim.models.planar.PlanarPauli(code, bsf=None)¶

Defines a Pauli operator on a planar lattice.

Notes:

This is a utility class used by planar implementations of the core models.
It is typically instantiated using qecsim.models.planar.PlanarCode.new_pauli()

Use cases:

Construct a planar Pauli operator by applying site, plaquette, path and logical operators: site(), plaquette(), path(), logical_x(), logical_z().
Get the single Pauli operator applied to a given site: operator()
Convert to binary symplectic form: to_bsf().
Copy a planar Pauli operator: copy().

__init__(code, bsf=None)¶

Initialise new planar Pauli.

Notes:

For performance reasons, the new Pauli is a view of the given bsf. Modifying one will modify the other.

Parameters

code (PlanarCode) – The planar code.
bsf (numpy.array (1d)) – Binary symplectic representation of Pauli. (Optional. Defaults to identity.)

property code¶

The planar code.

Return type: PlanarCode

copy()¶

Returns a copy of this Pauli that references the same code but is backed by a copy of the bsf.

Returns: A copy of this Pauli.
Return type: PlanarPauli

logical_x()¶

Apply a logical X operator, i.e. column of X on horizontal-edge sites of primal lattice.

Notes:

The column of X is applied to the rightmost column to allow optimisation of the MPS decoder.

Returns: self (to allow chaining)
Return type: PlanarPauli

logical_z()¶

Apply a logical Z operator, i.e. row of Z on horizontal-edge sites of primal lattice.

Notes:

The row of Z is applied to the bottom row to allow optimisation of the MPS decoder.

Returns: self (to allow chaining)
Return type: PlanarPauli

operator(index)¶

Returns the operator on the site identified by the index.

Parameters: index (2-tuple of int) – Index identifying a site in the format (row, column).
Returns: Pauli operator. One of ‘I’, ‘X’, ‘Y’, ‘Z’.
Return type: str
Raises: IndexError – If index is not an in-bounds site index.

path(a_index, b_index)¶

Apply the shortest taxi-cab path of operators between the plaquettes indexed by A and B.

Notes:

Indices are in the format (row, column).
Both indices must index the same lattice, see qecsim.models.planar.PlanarCode.is_primal() / qecsim.models.planar.PlanarCode.is_dual().
Plaquettes not indexed within the lattice are said to be virtual, see qecsim.models.planar.PlanarCode.bounds().
Paths proceed in the following directions in order: North/South, West/East. Therefore if one plaquette lies beyond both boundaries the path will meet the boundary as dictated by the directions defined here.
If both plaquettes are virtual then they are considered connected by a zero length path.
Parts of paths that lie outside the lattice have no effect on the lattice.

Parameters

a_index (2-tuple of int) – Index identifying a plaquette in the format (row, column).
b_index (2-tuple of int) – Index identifying a plaquette in the format (row, column).

Returns

self (to allow chaining)

Return type

PlanarPauli

Raises

IndexError – If indices are not plaquette indices on the same lattice.

plaquette(index)¶

Apply a plaquette operator at the given index.

Notes:

Index is in the format (row, column).
If the primal lattice is indexed (i.e. row % 2 = 1), then Z operators are applied around the plaquette. (This is equivalent to a vertex operator on the dual lattice.)
If the dual lattice is indexed (i.e. row % 2 = 0), then X operators are applied around the plaquette. (This is equivalent to a vertex operator on the primal lattice.)
Parts of plaquettes that lie outside the lattice have no effect on the lattice.

Parameters: index (2-tuple of int) – Index identifying the plaquette in the format (row, column).
Returns: self (to allow chaining)
Return type: PlanarPauli
Raises: IndexError – If index is not a plaquette index.

site(operator, *indices)¶

Apply the operator to site identified by the index.

Notes:

Index is in the format (row, column).
Operations on sites that lie outside the lattice have no effect on the lattice.

Parameters

operator (str) – Pauli operator. One of ‘I’, ‘X’, ‘Y’, ‘Z’.
indices (Any number of 2-tuple of int) – Any number of indices identifying a site in the format (row, column).

Returns

self (to allow chaining)

Return type

PlanarPauli

Raises

IndexError – If index is not a site index.

to_bsf()¶

Binary symplectic representation of Pauli.

Notes:

For performance reasons, the returned bsf is a view of this Pauli. Modifying one will modify the other.

Returns: Binary symplectic representation of Pauli.
Return type: numpy.array (1d)

`qecsim.models.planar.PlanarCMWPMDecoder`¶

class qecsim.models.planar.PlanarCMWPMDecoder(factor=3, max_iterations=4, box_shape='t', distance_algorithm=4)¶

Bases: qecsim.model.Decoder

Implements a planar Converging Minimum Weight Perfect Matching (CMWPM) decoder.

Decoding algorithm:

Resolve syndrome plaquettes using: qecsim.models.planar.PlanarCode.syndrome_to_plaquette_indices().
Separate syndrome plaquettes into primal and dual plaquettes.
For max_iterations:
- Resolve matched_primal_pairs using MWPM with edge weights between primal plaquettes given by the taxi-cab distance through a background grid determined by the previous_matched_dual_pairs.
- Resolve matched_dual_pairs using MWPM with edge weights between dual plaquettes given by the taxi-cab distance through a background grid determined by the previous_matched_primal_pairs.
- Stop if matched_primal_pairs = previous_matched_primal_pairs and matched_dual_pairs = previous_matched_dual_pairs.
Return recovery operator by applying the shortest path between matching pairs using: qecsim.models.planar.PlanarPauli.path().

Notes on background grid:

The grid is initialised with a grid factor (e.g. 3), box-shape (e.g. tight) and distance-algorithm (e.g. 1), and each edge is given an initial weight (e.g. 1).
The grid background is set such that, for each pair of syndrome indices (e.g. matched Z syndromes), all edges outside the chosen box-shape (see below), bounding the pair of indices, is multiplied by the grid factor.
The distance between any two syndrome indices (e.g. unmatched X syndromes) is weighted by the taxi-cab path through the background according to the chosen distance algorithm (see below).
A minimum-weight perfect matching in a graph of syndrome indices (e.g. unmatched X syndromes) with edges weighted by distance through the background gives matched pairs (e.g. matched X syndromes) taking into account correlations with the background (e.g. matched Z syndromes).
Box shape defines area outside of which the background is multiplied by the grid factor:

Tight:

X+ + +
+ + + +
 + + +
+ + + +
 + + +X

Rounded:

   + +
 X+ + +
 + + + +
+ + + + +
 + + + +
  + + +X
   + +

Fitted:

   + + +
 X+ + + +
 + + + +
+ + + + +
 + + + +
+ + + +X
 + + +

Loose:

 + + + +
+X+ + + +
 + + + +
+ + + + +
 + + + +
+ + + +X+
 + + + +

Distance algorithm defines how the path sum over the background of weighted edges is calculated:

Alg. 1:

X+ + +
| + + +
 + + +
| + + +
 - - -X

Alg. 2:

     X+ + +      X- - -
     | + + +     + + + |
min(  + + +   ,   + + +  )
     | + + +     + + + |
      - - -X      + + +X

Alg. 4:

     X+ + +      X- - -      X+ + +      X- | +
     | + + +     + + + |     | + + +     + + + +
min(  + + +   ,   + + +   ,   - - -   ,   + | +  )
     | + + +     + + + |     + + + |     + + + +
      - - -X      + + +X      + + +X      + - -X

class StepGrid(code)¶

Bases: object

Grid providing a weighted background for MWPM.

Methods:

Set background weights based on matched index pairs: set_background().
Resolve taxi-cab distance, weighted by the background, between a pair of indices: distance().
Minimum weight perfect matching in a graph of indices where sites are weighted based on distance through the background: mwpm().

__init__(code)¶

Initialise new step grid.

Parameters: code (PlanarCode) – Planar code.

distance(src_i, tgt_i, algorithm=4)¶

Distance between syndrome indices weighted by the grid background.

Note:

The distance algorithm defines the path(s) used to calculate distance between syndrome indices.

Parameters

src_i (2-tuple of int) – Source syndrome index.
tgt_i (2-tuple of int) – Target syndrome index.
algorithm (int) – Distance algorithm. (default=4, 1=v+h, 2=min(v+h,h+v), 4=min(v+h,h+v,v+h+v,h+v+h)

Returns

Distance.

Return type

float

mwpm(matched_indices, syndrome_indices, factor=3, initial=1, box_shape='t', distance_algorithm=4)¶

Minimum-weight perfect matching of syndrome indices over a background of matched dual syndrome indices.

Notes:

The background is set according to set_background().
A graph of the unmatched foreground indices is created, with appropriate virtual indices, and with edge weights given by distance().
A standard minimum-weight perfect matching is found in the graph.

Parameters

matched_indices (frozenset of 2-tuples of 2-tuple of int) – Matched pairs of background syndrome indices (dual to foreground).
syndrome_indices (frozenset of 2-tuple of int) – Unmatched foreground syndrome indices.
factor (int or float) – Multiplication factor. (default=3)
initial (int or float) – Initial edge weight. (default=1)
box_shape (str) – Shape of background boxes. (default=’t’, ‘t’=tight, ‘r’=rounded, ‘f’=fitted, ‘l’=loose)
distance_algorithm (int) – Distance algorithm. (default=4, 1=v+h, 2=min(v+h,h+v), 4=min(v+h,h+v,v+h+v,h+v+h)

Returns

Minimum-weight perfect matching of foreground syndrome indices.

Return type

frozenset of 2-tuples of 2-tuple of int

set_background(matched_indices=None, factor=3, initial=1, box_shape='t')¶

Set grid background from matched syndrome indices.

Note:

The grid is initialised with initial value at all sites and zero elsewhere.
For each matched pair of syndrome indices, all sites outside the box-shape, bounding the pair of indices, are multiplied by factor.

Parameters

matched_indices (set of 2-tuples of 2-tuple of int) – Matched pairs of syndrome indices.
factor (int or float) – Multiplication factor. (default=3)
initial (int or float) – Initial edge weight. (default=1)
box_shape (str) – Shape of background boxes. (default=’t’, ‘t’=tight, ‘r’=rounded, ‘f’=fitted, ‘l’=loose)

__init__(factor=3, max_iterations=4, box_shape='t', distance_algorithm=4)¶

Initialise new planar CMWPM decoder.

Parameters

factor (int or float) – Multiplication factor.
max_iterations (int) – Maximum number of iterations. (default=4, 0=null, 1=MWPM, 2+=CMWPM)
box_shape (str) – Shape of background boxes. (default=’t’, ‘t’=tight, ‘r’=rounded, ‘f’=fitted, ‘l’=loose)
distance_algorithm (int) – Distance algorithm. (default=4, 1=h+v, 2=min(h+v,v+h), 4=min(h+v,v+h,h+v+h,v+h+v)

Raises

ValueError – if factor is not >= 0.0.
ValueError – if max_iterations is not >= 0.
ValueError – if box_shape not in (‘t’, ‘r’, ‘f’, ‘l’).
ValueError – if distance_algorithm not in (1, 2, 4).
TypeError – if any parameter is of an invalid type.

decode(code, syndrome, **kwargs)¶: See qecsim.model.Decoder.decode()

property label¶: See qecsim.model.Decoder.label()

`qecsim.models.planar.PlanarMPSDecoder`¶

class qecsim.models.planar.PlanarMPSDecoder(chi=None, mode='c', stp=None, tol=None)¶

Bases: qecsim.model.Decoder

Implements a planar Matrix Product State (MPS) decoder.

A version of this decoder yielded results reported in https://arxiv.org/abs/1708.08474 and https://arxiv.org/abs/1812.08186.

Decoding algorithm:

A sample recovery operation \(f\) is found by resolving the syndrome to plaquettes (qecsim.models.planar.PlanarCode.syndrome_to_plaquette_indices()), finding the nearest boundary of the same type for each plaquette (qecsim.models.planar.PlanarCode.virtual_plaquette_index()), constructing a recovery operation by applying the path between each plaquette and its corresponding boundary (qecsim.models.planar.PlanarPauli.path()).
The probability of the left coset \(fG\) of the stabilizer group \(G\) of the planar code with respect to \(f\) is found by contracting an appropriately defined MPS-based tensor network (see https://arxiv.org/abs/1405.4883).
The complexity of the algorithm can managed by defining a bond dimension \(\chi\) to which the MPS bond dimension is truncated after each row/column of the tensor network is contracted into the MPS.
The probability of cosets \(f\bar{X}G\), \(f\bar{Y}G\) and \(f\bar{Z}G\) are calculated similarly.
The default contraction is column-by-column but can be set using the mode parameter to row-by-row or the average of both contractions.
A sample recovery operation from the most probable coset is returned.

Notes:

Specifying chi=None gives an exact contract (up to rounding errors) but is exponentially slow in the size of the lattice.
Modes:
- mode=’c’: contract by columns
- mode=’r’: contract by rows
- mode=’a’: contract by columns and by rows and, for each coset, take the average of the probabilities.
Contracting by columns (i.e. truncating vertical links) may give different coset probabilities to contracting by rows (i.e. truncating horizontal links). However, the effect is symmetric in that transposing the sample_pauli on the lattice and exchanging X and Z single Paulis reverses the difference between X and Z cosets probabilities.
Specifying stp (skip truncate probability) gives the probability that a tensor is not truncated in the approximate contraction controlled by chi. This can be used to break the symmetry of the contraction approximation.
The code is optimised to evaluate cosets that differ only in the last column/row together. It is important, therefore, that the logical X/Z operators of the PlanarPauli act on the last column/row respectively.

Tensor network example:

3x4 planar code (H=qubit on horizontal edge, V=qubit on vertical edge):

H---H---H---H
  |   |   |
  V   V   V
  |   |   |
H---H---H---H
  |   |   |
  V   V   V
  |   |   |
H---H---H---H

MPS tensor network as per https://arxiv.org/abs/1405.4883 (s=stabilizer):

 0 1 2 3 4 5 6
0H-s-H-s-H-s-H
 | | | | | | |
1s-V-s-V-s-V-s
 | | | | | | |
2H-s-H-s-H-s-H
 | | | | | | |
3s-V-s-V-s-V-s
 | | | | | | |
4H-s-H-s-H-s-H

__init__(chi=None, mode='c', stp=None, tol=None)¶

Initialise new planar MPS decoder.

Parameters

chi (int or None) – Truncated bond dimension. (default=None, unrestricted=falsy)
mode (str) – Contraction mode. (default=’c’, ‘c’=columns, ‘r’=rows, ‘a’=average)
stp (float or None) – Skip truncate probability. (default=None, disabled=falsy)
tol (float or None) – Tolerance for treating normalised singular values as zero. (default=None, unrestricted=falsy)

Raises

ValueError – if chi is not falsy or > 0.
ValueError – if mode not in (‘c’, ‘r’, ‘a’).
ValueError – if stp is not falsy or 1.0 >= stp > 0.0.
ValueError – if tol is not falsy or > 0.0.
TypeError – if any parameter is of an invalid type.

decode(code, syndrome, error_model=DepolarizingErrorModel(), error_probability=0.1, **kwargs)¶

See qecsim.model.Decoder.decode()

Note: The optional keyword parameters error_model and error_probability are used to determine the prior probability distribution for use in the decoding algorithm. Any provided error model must implement probability_distribution().

Parameters

code (PlanarCode) – Planar code.
syndrome (numpy.array (1d)) – Syndrome as binary vector.
error_model (ErrorModel) – Error model. (default=DepolarizingErrorModel())
error_probability (float) – Overall probability of an error on a single qubit. (default=0.1)

Returns

Recovery operation as binary symplectic vector.

Return type

numpy.array (1d)

property label¶: See qecsim.model.Decoder.label()

classmethod sample_recovery(code, syndrome)¶

Return a sample Pauli consistent with the syndrome, created by applying a path between each plaquette identified by the syndrome and the nearest boundary of the same type as the plaquette.

Parameters

code (PlanarCode) – Planar code.
syndrome (numpy.array (1d)) – Syndrome as binary vector.

Returns

Sample recovery operation as planar pauli.

Return type

PlanarPauli

`qecsim.models.planar.PlanarMWPMDecoder`¶

class qecsim.models.planar.PlanarMWPMDecoder¶

Bases: qecsim.model.Decoder

Implements a planar Minimum Weight Perfect Matching (MWPM) decoder.

Decoding algorithm:

The syndrome is resolved to plaquettes defects using: qecsim.models.planar.PlanarCode.syndrome_to_plaquette_indices().
For each defect the nearest off-boundary plaquette defect is added using: qecsim.models.planar.PlanarCode.virtual_plaquette_index().
If the total number of defects is odd an extra virtual off-boundary defect is added.
A graph between plaquettes is built with weights given by: distance().
A MWPM algorithm is used to match plaquettes into pairs.
A recovery operator is constructed by applying the shortest path between matching plaquette pairs using: qecsim.models.planar.PlanarPauli.path() and returned.

decode(code, syndrome, **kwargs)¶: See qecsim.model.Decoder.decode()

classmethod distance(code, a_index, b_index)¶

Distance between plaquettes in terms of plaquette steps.

Note: This implementation returns the taxi-cab distance based on qecsim.models.planar.PlanarCode.translation().

Parameters

code (PlanarCode) – Planar code.
a_index (2-tuple of int) – Index identifying a plaquette in the format (row, column).
b_index (2-tuple of int) – Index identifying a plaquette in the format (row, column).

Returns

Distance between plaquettes.

Return type

int

Raises

IndexError – If indices are not plaquette indices on the same lattice.

property label¶: See qecsim.model.Decoder.label()

`qecsim.models.planar.PlanarRMPSDecoder`¶

class qecsim.models.planar.PlanarRMPSDecoder(chi=None, mode='c', stp=None, tol=None)¶

Bases: qecsim.model.Decoder

Implements a planar Rotated Matrix Product State (RMPS) decoder.

Decoding algorithm:

A sample recovery operation \(f\) is found by resolving the syndrome to plaquettes (qecsim.models.planar.PlanarCode.syndrome_to_plaquette_indices()), finding the nearest boundary of the same type for each plaquette (qecsim.models.planar.PlanarCode.virtual_plaquette_index()), constructing a recovery operation by applying the path between each plaquette and its corresponding boundary (qecsim.models.planar.PlanarPauli.path()).
The probability of the left coset \(fG\) of the stabilizer group \(G\) of the planar code with respect to \(f\) is found by contracting an appropriately defined MPS-based tensor network (see https://arxiv.org/abs/1405.4883).
Since this is a rotated MPS decoder, the links of the network are rotated 45 degrees by splitting each stabilizer node into 4 delta nodes that are absorbed into the neighbouring qubit nodes.
The complexity of the algorithm can managed by defining a bond dimension \(\chi\) to which the MPS bond dimension is truncated after each row/column of the tensor network is contracted into the MPS.
The probability of cosets \(f\bar{X}G\), \(f\bar{Y}G\) and \(f\bar{Z}G\) are calculated similarly.
The default contraction is column-by-column but can be set using the mode parameter to row-by-row or the average of both contractions.
A sample recovery operation from the most probable coset is returned.

Notes:

Specifying chi=None gives an exact contract (up to rounding errors) but is exponentially slow in the size of the lattice.
Modes:
- mode=’c’: contract by columns
- mode=’r’: contract by rows
- mode=’a’: contract by columns and by rows and, for each coset, take the average of the probabilities.
Contracting by columns (i.e. truncating vertical links) may give different coset probabilities to contracting by rows (i.e. truncating horizontal links). However, the effect is symmetric in that transposing the sample_pauli on the lattice and exchanging X and Z single Paulis reverses the difference between X and Z cosets probabilities.
Specifying stp (skip truncate probability) gives the probability that a tensor is not truncated in the approximate contraction controlled by chi. This can be used to break the symmetry of the contraction approximation.

Tensor network example:

3x4 planar code (H=qubit on horizontal edge, V=qubit on vertical edge):

H---H---H---H
  |   |   |
  V   V   V
  |   |   |
H---H---H---H
  |   |   |
  V   V   V
  |   |   |
H---H---H---H

MPS tensor network as per https://arxiv.org/abs/1405.4883 (s=stabilizer):

 0 1 2 3 4 5 6
0H-s-H-s-H-s-H
 | | | | | | |
1s-V-s-V-s-V-s
 | | | | | | |
2H-s-H-s-H-s-H
 | | | | | | |
3s-V-s-V-s-V-s
 | | | | | | |
4H-s-H-s-H-s-H

Links are rotated by splitting stabilizers and summing them into neighbouring qubits:

  H            H            H
  |            |           / \
V-s-V  =>      s      =>  V   V
  |           / \          \ /
  H        V-s   s-V        H
              \ /
               s
               |
               H

Resultant MPS tensor network (rotated 45 degree clockwise for contraction by column/row):

 0 1 2 3 4 5
0    H
     |
1  H-V-H
   | | |
2H-V-H-V-H
   | | | |
3  H-V-H-V-H
     | | |
4    H-V-H
       |
5      H

__init__(chi=None, mode='c', stp=None, tol=None)¶

Initialise new planar RMPS decoder.

Parameters

chi (int or None) – Truncated bond dimension. (default=None, unrestricted=falsy)
mode (str) – Contraction mode. (default=’c’, ‘c’=columns, ‘r’=rows, ‘a’=average)
stp (float or None) – Skip truncate probability. (default=None, disabled=falsy)
tol (float or None) – Tolerance for treating normalised singular values as zero. (default=None, unrestricted=falsy)

Raises

ValueError – if chi is not falsy or > 0.
ValueError – if mode not in (‘c’, ‘r’, ‘a’).
ValueError – if stp is not falsy or 1.0 >= stp > 0.0.
ValueError – if tol is not falsy or > 0.0.
TypeError – if any parameter is of an invalid type.

decode(code, syndrome, error_model=DepolarizingErrorModel(), error_probability=0.1, **kwargs)¶

See qecsim.model.Decoder.decode()

Note: The optional keyword parameters error_model and error_probability are used to determine the prior probability distribution for use in the decoding algorithm. Any provided error model must implement probability_distribution().

Parameters

code (PlanarCode) – Planar code.
syndrome (numpy.array (1d)) – Syndrome as binary vector.
error_model (ErrorModel) – Error model. (default=DepolarizingErrorModel())
error_probability (float) – Overall probability of an error on a single qubit. (default=0.1)

Returns

Recovery operation as binary symplectic vector.

Return type

numpy.array (1d)

property label¶: See qecsim.model.Decoder.label()

classmethod sample_recovery(code, syndrome)¶

Return a sample Pauli consistent with the syndrome, created by applying a path between each plaquette identified by the syndrome and the nearest boundary of the same type as the plaquette.

Parameters

code (PlanarCode) – Planar code.
syndrome (numpy.array (1d)) – Syndrome as binary vector.

Returns

Sample recovery operation as planar pauli.

Return type

PlanarPauli

`qecsim.models.planar.PlanarYDecoder`¶

class qecsim.models.planar.PlanarYDecoder¶

Bases: qecsim.model.Decoder

Implements a planar Y-noise decoder.

A version of this decoder yielded results reported in https://arxiv.org/abs/1812.08186.

NOTE: This decoder will not be optimal for noise models that are not pure Y-noise.

Decoding algorithm given syndrome:

Find a sample all-Y recovery operator matching syndrome.
Construct an alternative all-Y recovery operator by adding an all-Y non-trivial logical operator.
Find group of all-Y stabilizer operators.
Calculate probability of coset of stabilizer group with each recovery operator.
Return a recovery operator from highest probability coset.

Notes:

MP math is used to calculate coset probabilities with exact exponent and precision of 50 decimal places.

Algorithm to find a sample all-Y recovery operator given syndrome (general case):

For each syndrome bit, construct a partial recovery operator that triggers the given syndrome bit and some bits on the right/lower boundary (whichever is shorter).
Combine partial recoveries to give combined partial recovery.
Subtract error syndrome from combined partial recovery syndrome to give residual syndrome on lower boundary.
Find residual recovery operator that triggers residual syndrome on right/lower boundary.
Return combined partial and residual recovery as all-Y recovery operator.

Notes:

Constructing a partial recovery operator: An operator that triggers a given syndrome bit and some bits on the right/lower boundary can be constructed directly by by applying a zig-zag pattern of Y starting right/below the given syndrome bit. For a p x q code, there are n - 1 = pq + (p-1)(q-1) - 1 distinct syndrome bits.
For co-prime codes, it is always possible to trigger a single syndrome bit on a boundary by apply Y next to the syndrome bit and bouncing diagonally around the lattice until a corner is encountered. That is destabilizers exist for co-prime codes. This is implemented in this decoder.
For codes where one side is an integer multiple of the other, the residual syndrome will always be trivial because patterns of Y that trigger no syndrome bits on 3 boundaries also trigger no syndrome bits on the 4th boundary. This is implemented in this decoder.
For constant gcd > 1 codes where one side is not a multiple of the other, it is possible to combine the above approaches for rectangular regions of the lattice where one side is a multiple of the other and one co-prime region to find a sample recovery operator. This is not yet implemented in this decoder; instead a look-up table of residual recovery operators is constructed by combining operators consisting of applying a zig-zag pattern of Y starting at each of the edges on the left/upper boundary.

Example:

Error:     Syndrome:
Y--------  ---------
  Y   |      |   |
----Y----  ------V--
  |   |      | P |
---------  ---------
  |   |      |   |
---------  ---------

Partial    Partial       Partial    Partial       Combined   Combined
recovery:  syndrome:     recovery:  syndrome:     partial    partial
                                                  recovery:  syndrome:
---------  ---------     ---------  ---------     ---------  ---------
  |   |      |   |         |   |      |   |         |   |      |   |
---------  ---------     ---------  ------V--     ---------  ------V--
  |   |      | P |    +    |   Y      |   |    =    |   Y      | P |
----Y----  ---------     ----Y---Y  ---------     --------Y  ---------
  Y   Y      |   |         Y   Y      |   |         |   |      |   |
Y---Y---Y  --V---V--     Y---Y----  --V------     --------Y  ------V--

Combined   Combined      Residual   Residual      Sample     Sample
partial    partial       recovery:  syndrome:     recovery:  syndrome:
recovery:  syndrome:
---------  ---------     Y--------  ---------     Y--------  ---------
  |   |      |   |         Y   |      |   |         Y   |      |   |
---------  ------V--     ----Y----  ---------     ----Y----  ------V--
  |   Y      | P |    +    |   Y      |   |    =    |   |      | P |
--------Y  ---------     --------Y  ---------     ---------  ---------
  |   |      |   |         |   |      |   |         |   |      |   |
--------Y  ------V--     --------Y  ------V--     ---------  ---------

Algorithm to find group of all-Y stabilizers and logicals algorithm (general case):

Create generators: For row=0 and column=each of 0 to gcd(p,q) - 1, apply Y at row,column and in a SE direction, bouncing just beyond the boundaries until a loop is completed or a corner is encountered.
Create full group: Combine generators in a possible combinations without repetition.
Split into stabilizers/logicals: Check commutation relations with logical X and Z of code.

Notes:

There are 2^gcd(p,q) all-Y (trivial and non-trivial) logical operator for a p x q code.
For coprime codes, the all-Y non-trivial logical operator consists of Y on all horizontal edges.
For square codes, an all-Y non-trivial logical operator consists of Y on the major diagonal edges.

decode(code, syndrome, error_model=BitPhaseFlipErrorModel(), error_probability=0.1, **kwargs)¶

See qecsim.model.Decoder.decode()

Note: The optional keyword parameters error_model and error_probability are used to determine the prior probability distribution for use in the decoding algorithm. Any provided error model must implement probability_distribution().

Parameters

code (PlanarCode) – Planar code.
syndrome (numpy.array (1d)) – Syndrome as binary vector.
error_model (ErrorModel) – Error model. (default=BitPhaseFlipErrorModel())
error_probability (float) – Overall probability of an error on a single qubit. (default=0.1)

Returns

Recovery operation as binary symplectic vector.

Return type

numpy.array (1d)

property label¶: See qecsim.model.Decoder.label()

models.planar: planar stabilizer codes¶

qecsim.models.planar¶

qecsim.models.planar.PlanarCode¶

qecsim.models.planar.PlanarPauli¶

qecsim.models.planar.PlanarCMWPMDecoder¶

qecsim.models.planar.PlanarMPSDecoder¶

qecsim.models.planar.PlanarMWPMDecoder¶

qecsim.models.planar.PlanarRMPSDecoder¶

qecsim.models.planar.PlanarYDecoder¶

`qecsim.models.planar`¶

`qecsim.models.planar.PlanarCode`¶

`qecsim.models.planar.PlanarPauli`¶

`qecsim.models.planar.PlanarCMWPMDecoder`¶

`qecsim.models.planar.PlanarMPSDecoder`¶

`qecsim.models.planar.PlanarMWPMDecoder`¶

`qecsim.models.planar.PlanarRMPSDecoder`¶

`qecsim.models.planar.PlanarYDecoder`¶