### Install qecsim within a virtual environment

Source: https://qecsim.github.io/installation.html

Steps to create and activate a Python virtual environment, install qecsim, and verify the installation.

```bash
$ python3 --version             # qecsim requires Python 3.5+
Python 3.7.8
$ python3 -m venv venv          # create new virtual environment
$ source venv/bin/activate      # activate venv (Windows: venv\Scripts\activate)
(venv) $ pip install qecsim     # install qecsim
...
Successfully installed ... qecsim-1.0b9 ...
(venv) $ qecsim --version       # verify qecsim cli
qecsim, version 1.0b9
(venv) $ deactivate             # deactivate venv
$

```

--------------------------------

### Install qecsim using pip

Source: https://qecsim.github.io/installation.html

Install or upgrade qecsim to the latest version from the Python Package Index.

```bash
$ pip install -U qecsim

```

--------------------------------

### Registering a Code with qecsim CLI

Source: https://qecsim.github.io/api/cli.html

Example of how to register a code, such as the 5-qubit code, in the `setup.cfg` file for use with the qecsim CLI. This allows the code to be recognized and utilized by the command-line interface.

```ini
[options.entry_points]
qecsim.cli.run.codes =
    five_qubit = qecsim.models.basic:FiveQubitCode

```

--------------------------------

### Import and Check QECSIM Version

Source: https://qecsim.github.io/usage.html

Import the qecsim library and check its installed version. This is a basic step to ensure the library is accessible.

```python
>>> import qecsim
>>> qecsim.__version__
'1.0b9'
```

--------------------------------

### PlanarYDecoder Decoding Example

Source: https://qecsim.github.io/api/models/planar.html

Illustrates the step-by-step process of decoding a syndrome using the PlanarYDecoder. This visual example shows the transformation from error to syndrome, partial recoveries, and the final sample recovery operator.

```text
Error:     Syndrome:
Y--------  ---------
  Y   |      |   |
----Y----  ------V--
  |   |
---------
  |   |
---------

Partial    Partial       Partial    Partial       Combined   Combined
recovery:  syndrome:     recovery:  syndrome:     partial    partial
                                                  recovery:  syndrome:
---------
  |   |
---------
  |   |
----Y----
  Y   Y
Y---Y---Y

Combined   Combined      Residual   Residual      Sample     Sample
partial    partial       recovery:  syndrome:     recovery:  syndrome:
recovery:  syndrome:
---------
  |   |
---------
  |   Y
--------Y
  |   |
--------Y


```

```text
---------  ---------
  |   |
---------
  |   |
------V--
  | P |
---------
  |   |
---------

---------  ---------
  |   |
---------
------V--
  | P |
---------
  |   |
---------

    |   |
---------
------V--
    | P |
---------
    |   |
---------

    |   |
---------
------V--
    | P |
---------
    |   |
---------

```

```text
---------  ---------
  |   |
---------
------V--
  | P |
---------
  |   |
---------

    |   |
---------
------V--
    | P |
---------
    |   |
---------

    |   |
---------
------V--
    | P |
---------
    |   |
---------

```

```text
---------  ---------
  |   |
---------
------V--
  | P |
---------
  |   |
---------

    |   |
---------
------V--
    | P |
---------
    |   |
---------

    |   |
---------
------V--
    | P |
---------
    |   |
---------

```

```text
Y--------  ---------
  Y   |
----Y----
  |   |
---------
  |   |
---------

```

```text
Y--------  ---------
  Y   |
----Y----
  |   |
---------
  |   |
---------

```

--------------------------------

### qecsim merge Command Help

Source: https://qecsim.github.io/usage.html

Get help for the merge command, which merges simulation data files. Shows arguments and options.

```bash
$ qecsim merge --help
Usage: qecsim merge [OPTIONS] DATA_FILE...

  Merge simulation data files.

  Arguments:

   DATA_FILE...          One or more data files

  Examples:

   qecsim merge "data1.json" "data2.json" "data3.json"

   qecsim merge -o"merged.json" data*.json

Options:
  -o, --output FILENAME  Output file. (Writes to log if file exists).
  --help                 Show this message and exit.

```

--------------------------------

### FileErrorModel: Example Error File Format

Source: https://qecsim.github.io/api/models/generic.html

This example demonstrates the expected format for error files used by FileErrorModel. It includes comments, header lines with JSON objects for metadata, and body lines with JSON lists representing errors.

```text
// 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]

```

--------------------------------

### Check Blossom V availability in qecsim

Source: https://qecsim.github.io/installation.html

Verify if the Blossom V matching library is correctly installed and accessible by qecsim.

```python
>>> from qecsim.graphtools import blossom5
>>> blossom5.available()
True

```

--------------------------------

### Planar Lattice Site Indices Example

Source: https://qecsim.github.io/api/models/planar.html

Illustrates the indexing of sites (edges) on a primal lattice for a 3x3 planar code. Site indices satisfy (row + column) mod 2 = 0.

```text
(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)

```

--------------------------------

### Planar Lattice Plaquette Indices Example (Dual)

Source: https://qecsim.github.io/api/models/planar.html

Illustrates the indexing of plaquettes on a dual lattice for a 3x3 planar code. Plaquette indices satisfy (row + column) mod 2 = 1, and on the dual lattice, row mod 2 = 0 and col mod 2 = 1.

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

```

--------------------------------

### qecsim Help Command

Source: https://qecsim.github.io/usage.html

Display general help for qecsim, listing available commands and global options.

```bash
$ qecsim --help
Usage: qecsim [OPTIONS] COMMAND [ARGS]...

  qecsim - quantum error correction simulator using stabilizer codes.

  See qecsim COMMAND --help for command-specific help.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  merge    Merge simulation data files.
  run      Simulate quantum error correction.
  run-ftp  Simulate fault-tolerant (time-periodic) quantum error correction.

```

--------------------------------

### qecsim run-ftp Command Help

Source: https://qecsim.github.io/usage.html

Display help for the run-ftp command, used for simulating fault-tolerant quantum error correction. Lists arguments like code, time steps, error model, decoder, and probabilities.

```bash
$ qecsim run-ftp --help
Usage: qecsim run-ftp [OPTIONS] CODE TIME_STEPS ERROR_MODEL DECODER
                      ERROR_PROBABILITY...

  Simulate fault-tolerant (time-periodic) quantum error correction.

  Arguments:

   CODE                  Stabilizer code in format name(<args>)
    rotated_planar  Rotated planar (rows INT >= 3, cols INT >= 3)
    rotated_toric   Rotated toric (rows INT even >= 2, cols INT even >= 2)

   TIME_STEPS            Number of time steps as INT >= 1

   ERROR_MODEL           Error model in format name(<args>)
    generic.biased_depolarizing  Biased (bias FLOAT > 0, [axis] CHAR)
    generic.biased_y_x           Biased Y v. X (bias FLOAT >= 0)
    generic.bit_flip             Pr I,X,Y,Z is 1-p,p,0,0

```

--------------------------------

### Initialize Run Parameters for QECSIM

Source: https://qecsim.github.io/demos/demo_basic_plot.html

Sets up the parameters for running QECSIM simulations, including codes, error models, decoders, and error probabilities. Ensure all necessary libraries are imported.

```python
%matplotlib inline
import collections
import itertools
import numpy as np
import matplotlib.pyplot as plt
from qecsim import app
from qecsim.models.generic import DepolarizingErrorModel, NaiveDecoder
from qecsim.models.basic import FiveQubitCode, SteaneCode

# set models
codes = [FiveQubitCode(), SteaneCode()]
error_model = DepolarizingErrorModel()
decoder = NaiveDecoder()
# set physical error probabilities
error_probability_min, error_probability_max = 0, 0.5
error_probabilities = np.linspace(error_probability_min, error_probability_max, 20)
# set max_runs for each probability
max_runs = 10000

# print run parameters
print('Codes:', [code.label for code in codes])
print('Error model:', error_model.label)
print('Decoder:', decoder.label)
print('Error probabilities:', error_probabilities)
print('Maximum runs:', max_runs)

```

--------------------------------

### RotatedToricCode.bounds

Source: https://qecsim.github.io/api/models/rotatedtoric.html

Gets the maximum x and y coordinates for indices within the lattice.

```APIDOC
## `bounds`

### Description
Maximum x and y value that an index coordinate can take.

### Return type
2-tuple of int
```

--------------------------------

### Color666Code.bound Property

Source: https://qecsim.github.io/api/models/color.html

Gets the maximum value that an index coordinate can take on the lattice.

```APIDOC
## `Color666Code.bound`

### Description
Maximum value that an index coordinate can take.

### Return type
int
```

--------------------------------

### qecsim run Command Help

Source: https://qecsim.github.io/usage.html

Display help for the run command, used for simulating quantum error correction. Lists arguments like code, error model, decoder, and probabilities, along with options.

```bash
$ qecsim run --help
Usage: qecsim run [OPTIONS] CODE ERROR_MODEL DECODER ERROR_PROBABILITY...

  Simulate quantum error correction.

  Arguments:

   CODE                  Stabilizer code in format name(<args>)
    color666        Color 6.6.6 (size INT odd >=3)
    five_qubit      5-qubit
    planar          Planar (rows INT >= 2, cols INT >= 2)
    rotated_planar  Rotated planar (rows INT >= 3, cols INT >= 3)
    rotated_toric   Rotated toric (rows INT even >= 2, cols INT even >= 2)
    steane          Steane
    toric           Toric (rows INT >= 2, cols INT >= 2)

   ERROR_MODEL           Error model in format name(<args>)
    generic.biased_depolarizing  Biased (bias FLOAT > 0, [axis] CHAR)
    generic.biased_y_x           Biased Y v. X (bias FLOAT >= 0)
    generic.bit_flip             Pr I,X,Y,Z is 1-p,p,0,0
    generic.bit_phase_flip       Pr I,X,Y,Z is 1-p,0,p,0
    generic.center_slice         Slice (lim 3-tuple of FLOAT, pos FLOAT)
    generic.depolarizing         Pr I,X,Y,Z is 1-p,p/3,p/3,p/3
    generic.file                 File (filename STR, [start] INT >= 0)
    generic.phase_flip           Pr I,X,Y,Z is 1-p,0,0,p

   DECODER               Decoder in format name(<args>)
    color666.mps          MPS ([chi] INT, ...)
    generic.naive         Naive ([max_qubits] INT)
    planar.cmwpm          Converging MWPM ([factor] FLOAT >=0, ...)
    planar.mps            MPS ([chi] INT >=0, [mode] CHAR, ...)
    planar.mwpm           MWPM
    planar.rmps           Rotated MPS ([chi] INT >=0, [mode] CHAR, ...)
    planar.y              Y-noise
    rotated_planar.mps    MPS ([chi] INT >=0, [mode] CHAR, ...)
    rotated_planar.rmps   Rotated MPS ([chi] INT >=0, [mode] CHAR, ...)
    rotated_planar.smwpm  Symmetry MWPM ([eta] FLOAT >=0)
    rotated_toric.smwpm   Symmetry MWPM ([itp] BOOL, [eta] FLOAT >=0)
    toric.mwpm            MWPM

   ERROR_PROBABILITY...  One or more probabilities as FLOAT in [0.0, 1.0]

  Examples:

   qecsim run -r10 "five_qubit" "generic.depolarizing" "generic.naive" 0.1

   qecsim run -f5 -r50 -s13 "steane" "generic.phase_flip" "generic.naive"
   0.1

   qecsim run -r20 "planar(7,7)" "generic.bit_flip" "planar.mps(6)" 0.101
   0.102 0.103

   qecsim run -r10 "color666(7)" "generic.bit_flip" "color666.mps(16)" 0.09
   0.10

   qecsim run -o"data.json" -f9 "toric(3,3)" "generic.bit_flip" "toric.mwpm"
   0.1

Options:
  -f, --max-failures INT  Maximum number of failures for each probability.
  -r, --max-runs INT      Maximum number of runs for each probability.
                          [default: 1 if max-failures unspecified]

  -o, --output FILENAME   Output file. (Writes to log if file exists).
  -s, --random-seed INT   Random seed for qubit error generation. (Re-applied
                          for each probability).

  --help                  Show this message and exit.

```

--------------------------------

### Color666Code.size Property

Source: https://qecsim.github.io/api/models/color.html

Gets the size of any side of the triangular lattice in terms of the number of qubits.

```APIDOC
## `Color666Code.size`

### Description
Size of any side of the triangular lattice in terms of number of qubits.

### Return type
int
```

--------------------------------

### qecsim.util.init_logging

Source: https://qecsim.github.io/api/util.html

Initializes the logging configuration for qecsim. It attempts to load configuration from environment variables or default file locations.

```APIDOC
## `qecsim.util.init_logging`

### Description
Initialise logging.

### Notes
- Configuration loaded from `$QECSIM_CFG/logging_qecsim.ini` (if `QECSIM_CFG` env variable is set).
- Configuration loaded from `./logging_qecsim.ini` or `~/.qecsim/logging_qecsim.ini` (otherwise).
- If configuration not found then a basic configuration is used.
```

--------------------------------

### Get Lattice Bounds

Source: https://qecsim.github.io/api/models/rotatedtoric.html

Retrieves the maximum x and y coordinates for indices within the lattice.

```python
code.bounds
```

--------------------------------

### Get PlanarCode Label

Source: https://qecsim.github.io/api/models/planar.html

Retrieves the label for the planar code, as defined in the base class `qecsim.model.StabilizerCode`.

```python
code.label
```

--------------------------------

### Initialize Models for Basic Simulation

Source: https://qecsim.github.io/demos/demo_basic.html

Initializes the FiveQubitCode, DepolarizingErrorModel, and NaiveDecoder. These are fundamental components for setting up an error correction simulation.

```python
%run qsu.ipynb  # color-printing functions
import numpy as np
from qecsim import paulitools as pt
from qecsim.models.generic import DepolarizingErrorModel, NaiveDecoder
from qecsim.models.basic import FiveQubitCode

# initialise models
my_code = FiveQubitCode()
my_error_model = DepolarizingErrorModel()
my_decoder = NaiveDecoder()
# print models
print(my_code)
print(my_error_model)
print(my_decoder)

```

```text
FiveQubitCode()
DepolarizingErrorModel()
NaiveDecoder(10)

```

--------------------------------

### Get Toric Code Size

Source: https://qecsim.github.io/api/models/toric.html

Retrieves the size of the toric code lattice in the format (rows, columns).

```python
size = code.size
# size is (5, 5)
```

--------------------------------

### qecsim.util.load_clib

Source: https://qecsim.github.io/api/util.html

Loads a C shared library, searching in specific directories based on environment variables or default locations.

```APIDOC
## `qecsim.util.load_clib`

### Description
Load clib shared library.

### Notes
- Library loaded from `$QECSIM_CFG/clib/<filename>` (if `QECSIM_CFG` env variable is set).
- Library loaded from `./clib/<filename>` or `~/.qecsim/clib/<filename>` (otherwise).

### Parameters
#### Path Parameters
- **filename** (str) - Library file name, e.g. ‘libpypm.so’.

### Returns
Library loaded as a `ctypes.CDLL` object.

### Raises
- **FileNotFoundError**: if filename does not resolve to an existing file.
- **OSError**: if filename cannot be loaded as a shared library.
```

--------------------------------

### Get PlanarCode Logicals

Source: https://qecsim.github.io/api/models/planar.html

Retrieves the logical operators (both X and Z) for the planar code, as defined in the base class `qecsim.model.StabilizerCode`.

```python
code.logicals
```

--------------------------------

### Get PlanarCode Logical Zs

Source: https://qecsim.github.io/api/models/planar.html

Retrieves the logical Z operators for the planar code, as defined in the base class `qecsim.model.StabilizerCode`.

```python
code.logical_zs
```

--------------------------------

### Run qecsim Console Script

Source: https://qecsim.github.io/usage.html

Execute the qecsim console script or use it as a Python module. The default command shows version and general help.

```bash
$ qecsim                    # console script
$ python3 -O -m qecsim      # module script with Python options e.g -O for optimize
```

--------------------------------

### Build Blossom V C++ library

Source: https://qecsim.github.io/installation.html

Commands to download, extract, and build the Blossom V C++ matching library and its Python wrapper.

```bash
$ tar -xzf blossom5-v2.05.src.tar.gz
$ tar -xzf blossom5-v2.05.pyw.tar.gz
$ cp blossom5-v2.05.pyw/* blossom5-v2.05.src/
$ cd blossom5-v2.05.src/
$ make -f Makefile-pyw
...
c++ -shared ... -o libpypm.so

```

--------------------------------

### Get PlanarCode Logical Xs

Source: https://qecsim.github.io/api/models/planar.html

Retrieves the logical X operators for the planar code, as defined in the base class `qecsim.model.StabilizerCode`.

```python
code.logical_xs
```

--------------------------------

### Initialize Rotated Planar Code Simulation Parameters

Source: https://qecsim.github.io/demos/demo_rotatedplanar_plot.html

Sets up the codes, error model, decoder, and physical error probabilities for the simulation. Use this to configure the simulation environment.

```python
%matplotlib inline
import collections
import itertools
import numpy as np
import matplotlib.pyplot as plt
from qecsim import app
from qecsim.models.generic import BitPhaseFlipErrorModel
from qecsim.models.rotatedplanar import RotatedPlanarCode, RotatedPlanarMPSDecoder

# set models
codes = [RotatedPlanarCode(*size) for size in [(3, 3), (5, 5), (7, 7), (9, 9)]]
error_model = BitPhaseFlipErrorModel()
decoder = RotatedPlanarMPSDecoder(chi=8)
# set physical error probabilities
error_probability_min, error_probability_max = 0, 0.5
error_probabilities = np.linspace(error_probability_min, error_probability_max, 20)
# set max_runs for each probability
max_runs = 10000

# print run parameters
print('Codes:', [code.label for code in codes])
print('Error model:', error_model.label)
print('Decoder:', decoder.label)
print('Error probabilities:', error_probabilities)
print('Maximum runs:', max_runs)

```

--------------------------------

### Run QECSim Simulation in a Single Call

Source: https://qecsim.github.io/demos/demo_planar.html

This snippet shows how to run a QECSim simulation using the `run_once` function, passing all necessary parameters in a single call. It's useful for quick simulations or integrating into larger workflows.

```python
# repeat demo in single call
from qecsim import app
print(app.run_once(my_code, my_error_model, my_decoder, error_probability))
```

```json
{'error_weight': 3, 'success': True}
```

--------------------------------

### Get ASCII Art Representation

Source: https://qecsim.github.io/api/models/color.html

Returns an ASCII art representation of the lattice, optionally showing syndrome bits and Pauli operators.

```python
code.ascii_art(syndrome=None, pauli=None)
```

--------------------------------

### Initialize Color 6.6.6 Code, Error Model, and Decoder

Source: https://qecsim.github.io/demos/demo_color666.html

Initializes the necessary components for simulating error correction: the Color666Code, a DepolarizingErrorModel, and a Color666MPSDecoder. Ensure 'qsu.ipynb' is run for color printing functions.

```python
%run qsu.ipynb  # color-printing functions
import numpy as np
from qecsim import paulitools as pt
from qecsim.models.generic import DepolarizingErrorModel
from qecsim.models.color import Color666Code, Color666MPSDecoder

# initialise models
my_code = Color666Code(5)
my_error_model = DepolarizingErrorModel()
my_decoder = Color666MPSDecoder()
# print models
print(my_code)
print(my_error_model)
print(my_decoder)
```

```text
Color666Code(5)
DepolarizingErrorModel()
Color666MPSDecoder(None, None)
```

--------------------------------

### Get Virtual Plaquette Index

Source: https://qecsim.github.io/api/models/color.html

Returns the index of the virtual plaquette just outside the boundary, matching the color of the given plaquette index.

```python
code.virtual_plaquette_index(index)
```

--------------------------------

### Initialize Rotated Planar Code Models

Source: https://qecsim.github.io/demos/demo_rotatedplanar.html

Initializes the RotatedPlanarCode, DepolarizingErrorModel, and RotatedPlanarMPSDecoder. Ensure qsu.ipynb is run for color-printing functions.

```python
%run qsu.ipynb  # color-printing functions
import numpy as np
from qecsim import paulitools as pt
from qecsim.models.generic import DepolarizingErrorModel
from qecsim.models.rotatedplanar import RotatedPlanarCode, RotatedPlanarMPSDecoder

# initialise models
my_code = RotatedPlanarCode(7, 7)
my_error_model = DepolarizingErrorModel()
my_decoder = RotatedPlanarMPSDecoder(chi=8)
# print models
print(my_code)
print(my_error_model)
print(my_decoder)
```

```text
RotatedPlanarCode(7, 7)
DepolarizingErrorModel()
RotatedPlanarMPSDecoder(8, 'c', None)
```

--------------------------------

### Initialize Toric Code Simulation Parameters

Source: https://qecsim.github.io/demos/demo_toric_plot.html

Sets up the necessary parameters for simulating toric stabilizer codes, including code sizes, error models, decoders, and error probabilities. This code is essential for preparing simulation runs.

```python
%matplotlib inline
import collections
import itertools
import numpy as np
import matplotlib.pyplot as plt
from qecsim import app
from qecsim.models.generic import BitFlipErrorModel
from qecsim.models.toric import ToricCode, ToricMWPMDecoder

# set models
codes = [ToricCode(*size) for size in [(3, 3), (5, 5), (7, 7), (9, 9)]]
error_model = BitFlipErrorModel()
decoder = ToricMWPMDecoder()
# set physical error probabilities
error_probability_min, error_probability_max = 0, 0.4
error_probabilities = np.linspace(error_probability_min, error_probability_max, 20)
# set max_runs for each probability
max_runs = 10000

# print run parameters
print('Codes:', [code.label for code in codes])
print('Error model:', error_model.label)
print('Decoder:', decoder.label)
print('Error probabilities:', error_probabilities)
print('Maximum runs:', max_runs)

```

--------------------------------

### Get Toric Code Shape

Source: https://qecsim.github.io/api/models/toric.html

Retrieves the shape of the toric code lattice, including primal and dual lattices, in the format (lattices, rows, columns).

```python
shape = code.shape
# shape is (2, 5, 5)
```

--------------------------------

### Color 666 Triangular Lattice Example

Source: https://qecsim.github.io/api/models/color.html

Visual representation of a size 5 color 6.6.6 triangular lattice. This serves as the basis for mapping to a tensor network for decoding.

```text
o
|
o   @
  \
@   o - o
    |     \
o - o   @   o
|     \     |
o   @   o - o   @
  \     |     \
@   o - o   @   o - o
    |     \     |
o - o   @   o - o   @

```

--------------------------------

### Initialize Run Parameters for Planar Codes

Source: https://qecsim.github.io/demos/demo_planar_plot.html

Sets up the parameters for running simulations, including code sizes, error models, decoders, and the range of physical error probabilities. This code is used to configure the simulation environment.

```python
%matplotlib inline
import collections
import itertools
import numpy as np
import matplotlib.pyplot as plt
from qecsim import app
from qecsim.models.generic import PhaseFlipErrorModel
from qecsim.models.planar import PlanarCode, PlanarMWPMDecoder

# set models
codes = [PlanarCode(*size) for size in [(3, 3), (5, 5), (7, 7), (9, 9)]]
error_model = PhaseFlipErrorModel()
decoder = PlanarMWPMDecoder()
# set physical error probabilities
error_probability_min, error_probability_max = 0, 0.4
error_probabilities = np.linspace(error_probability_min, error_probability_max, 20)
# set max_runs for each probability
max_runs = 10000

# print run parameters
print('Codes:', [code.label for code in codes])
print('Error model:', error_model.label)
print('Decoder:', decoder.label)
print('Error probabilities:', error_probabilities)
print('Maximum runs:', max_runs)

```

--------------------------------

### Create Correlated Error

Source: https://qecsim.github.io/demos/demo_planar_correlated.html

Generates a specific correlated error on the planar code by applying Y errors at two distinct sites. This setup is used to test the decoders' performance.

```python
# error: correlated error
error = my_code.new_pauli().site('Y', (2, 0), (2, 4)).to_bsf()
qsu.print_pauli('error:\n{}'.format(my_code.new_pauli(error)))
```

--------------------------------

### Output of Initial Run Parameters

Source: https://qecsim.github.io/demos/demo_color666_plot.html

Displays the configured parameters for the error correction simulations, including code labels, error model, decoder, error probabilities, and maximum runs.

```text
Codes: ['Color 6.6.6 3', 'Color 6.6.6 5', 'Color 6.6.6 7', 'Color 6.6.6 9']
Error model: Depolarizing
Decoder: Color 6.6.6 MPS (chi=8)
Error probabilities: [0.         0.02105263 0.04210526 0.06315789 0.08421053 0.10526316
 0.12631579 0.14736842 0.16842105 0.18947368 0.21052632 0.23157895
 0.25263158 0.27368421 0.29473684 0.31578947 0.33684211 0.35789474
 0.37894737 0.4       ]
Maximum runs: 10000

```

--------------------------------

### Initialize Toric Code, Error Model, and Decoder

Source: https://qecsim.github.io/demos/demo_toric.html

Initializes the ToricCode, DepolarizingErrorModel, and ToricMWPMDecoder. These models are fundamental for setting up a simulation.

```python
%run qsu.ipynb  # color-printing functions
import numpy as np
from qecsim import paulitools as pt
from qecsim.models.generic import DepolarizingErrorModel
from qecsim.models.toric import ToricCode, ToricMWPMDecoder

# initialise models
my_code = ToricCode(5, 5)
my_error_model = DepolarizingErrorModel()
my_decoder = ToricMWPMDecoder()
# print models
print(my_code)
print(my_error_model)
print(my_decoder)
```

```text
ToricCode(5, 5)
DepolarizingErrorModel()
ToricMWPMDecoder()
```

--------------------------------

### qecsim.app.run_ftp

Source: https://qecsim.github.io/api/app.html

Executes a fault-tolerant, time-periodic stabilizer code simulation multiple times and returns aggregated data. Similar to `run`, it continues until maximum runs or failures are met, or runs once if unspecified.

```APIDOC
## `qecsim.app.run_ftp`

### Description
Execute stabilizer code error-decode-recovery (fault-tolerant time-periodic) simulation many times and return aggregated runs data.

### Parameters
* **code** (_StabilizerCode_) – Stabilizer code.
* **time_steps** (_int_) – Number of time steps.
* **error_model** (_ErrorModel_) – Error model.
* **decoder** (_Decoder_) – Decoder.
* **error_probability** (_float_) – Error probability.
* **measurement_error_probability** (_float_) – Measurement error probability. (default=None)
* **max_runs** (_int_) – Maximum number of runs. (default=None or 1 if max_failures unspecified, unrestricted=None)
* **max_failures** (_int_) – Maximum number of failures. (default=None, unrestricted=None)
* **random_seed** (_int_) – Error generation random seed. (default=None, unseeded=None)

### Returns
Aggregated runs data.

### Return type
dict
```

--------------------------------

### Biased YX Error Model

Source: https://qecsim.github.io/api/models/generic.html

Implements a biased Y-X error model. The probability distribution for a given error probability p is defined, along with methods to get the bias and generate errors.

```APIDOC
## `qecsim.models.generic.BiasedYXErrorModel`

### Description
Implements a biased-Y-X error model. 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).

### Method
`__init__(self, 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

### Method
`generate(self, 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()`

### Method
`probability_distribution(self, probability)`

See `qecsim.model.ErrorModel.probability_distribution()`
```

--------------------------------

### Run QECSIM Simulations

Source: https://qecsim.github.io/demos/demo_basic_plot.html

Executes the QECSIM simulations for the defined parameters. The `app.run` function is used to generate simulation data. This snippet also prints a sample of the output data.

```python
# run simulations and print data from middle run to view format
data = [app.run(code, error_model, decoder, error_probability, max_runs=max_runs)
        for code in codes for error_probability in error_probabilities]
print(data[len(data)//2])

```

--------------------------------

### Initialize Run Parameters for Color 6.6.6 Codes

Source: https://qecsim.github.io/demos/demo_color666_plot.html

Sets up the simulation parameters including code sizes, error model, decoder, and the range of physical error probabilities. Ensure `matplotlib` is configured for inline plotting.

```python
%matplotlib inline
import collections
import itertools
import numpy as np
import matplotlib.pyplot as plt
from qecsim import app
from qecsim.models.generic import DepolarizingErrorModel
from qecsim.models.color import Color666Code, Color666MPSDecoder

# set models
codes = [Color666Code(size) for size in [3, 5, 7, 9]]
error_model = DepolarizingErrorModel()
decoder = Color666MPSDecoder(chi=8)
# set physical error probabilities
error_probability_min, error_probability_max = 0, 0.4
error_probabilities = np.linspace(error_probability_min, error_probability_max, 20)
# set max_runs for each probability
max_runs = 10000

# print run parameters
print('Codes:', [code.label for code in codes])
print('Error model:', error_model.label)
print('Decoder:', decoder.label)
print('Error probabilities:', error_probabilities)
print('Maximum runs:', max_runs)

```

--------------------------------

### Planar Lattice Plaquette Indices Example (Primal)

Source: https://qecsim.github.io/api/models/planar.html

Illustrates the indexing of plaquettes on a primal lattice for a 3x3 planar code. Plaquette indices satisfy (row + column) mod 2 = 1, and on the primal lattice, row mod 2 = 1 and col mod 2 = 0.

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

```

--------------------------------

### Run FTP Simulation with Output to JSON

Source: https://qecsim.github.io/usage.html

Executes an FTP simulation using the rotated planar code and directs the output to a JSON file. This command specifies the code, qubit count, error model, and decoder.

```bash
qecsim run-ftp -r5 -o"data.json" "rotated_planar(7,7)" 7
"generic.depolarizing" "rotated_planar.smwpm" 0.1
```

--------------------------------

### Run QECSIM Simulation in a Single Call

Source: https://qecsim.github.io/demos/demo_toric.html

This snippet shows how to run a QECSIM simulation using a single function call, equivalent to the previous demo. Ensure 'my_code', 'my_error_model', 'my_decoder', and 'error_probability' are defined beforehand.

```python
# repeat demo in single call
from qecsim import app
print(app.run_once(my_code, my_error_model, my_decoder, error_probability))
```

```json
{
  "error_weight": 4,
  "success": True
}
```

--------------------------------

### run_once_ftp

Source: https://qecsim.github.io/api/app.html

Runs a fault-tolerant time-periodic simulation for a stabilizer code. This function simulates errors, syndromes, and decoding over multiple time steps.

```APIDOC
## `qecsim.app.run_once_ftp`

### Description
Run a stabilizer code error-decode-recovery (fault-tolerant time-periodic) simulation and return run data.
Assumptions:
  * Time steps is integer >= 1.
  * Probabilities, where defined, are float in [0, 1].

Notes:
  * The simulation is as follows:
>     * for each time step t:
>>       * generate Pauli `step_errors[t]` by passing `code` and `error_probability` to `qecsim.model.ErrorModel.generate()`.
>>       * evaluate `step_syndromes[t]` as `step_errors[t]` ⊙ `code.stabilizers`T.
>>       * generate `step_measurement_errors[t]` as syndrome bit-flips.

### Parameters
    
  * **code** (_StabilizerCode_) – Stabilizer code.
  * **time_steps** (_int_) – Number of time steps.
  * **error_model** (_ErrorModel_) – Error model.
  * **decoder** (_DecoderFTP_) – Fault-tolerant time-periodic decoder.
  * **error_probability** (_float_) – Error probability.
  * **measurement_error_probability** (_float_) – Measurement error probability. (default=None, None=error_probability or 0.0 if single time step)
  * **max_runs** (_int_) – Maximum number of runs. (default=None or 1 if max_failures unspecified, unrestricted=None)
  * **max_failures** (_int_) – Maximum number of failures. (default=None, unrestricted=None)
  * **random_seed** (_int_) – Error generation random seed. (default=None, unseeded=None)

### Returns
    
Aggregated runs data. 

### Return type
    
dict 

### Raises
    
  * **ValueError** – if time_steps is not >= 1.
  * **ValueError** – if error_probability is not in [0, 1].
  * **ValueError** – if measurement_error_probability is not None or in [0, 1].
```

--------------------------------

### ToricCode Constructor

Source: https://qecsim.github.io/api/models/toric.html

Initializes a new toric code with specified rows and columns.

```APIDOC
## `__init__` (rows, columns)

### Description
Initialise new toric 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.
```

--------------------------------

### Initialize Color666MPSDecoder

Source: https://qecsim.github.io/api/models/color.html

Initializes a new planar MPS decoder. Specify `chi` for truncated bond dimension or `tol` for singular value tolerance. Unrestricted values are falsy.

```python
decoder = Color666MPSDecoder(chi=None, tol=None)
```

--------------------------------

### Color666Pauli Initialization

Source: https://qecsim.github.io/api/models/color.html

Initializes a new color 6.6.6 Pauli operator. The new Pauli is a view of the given bsf for performance reasons.

```APIDOC
## `__init__`

### Description
Initialise new color 6.6.6 Pauli.

### Parameters
* **code** (_Color666Code_) – The color 6.6.6 code.
* **bsf** (_numpy.array (1d)_) – Binary symplectic representation of Pauli. (Optional. Defaults to identity.)
```

--------------------------------

### Initialize Planar Code, Error Model, and Decoder

Source: https://qecsim.github.io/demos/demo_planar.html

Initializes the PlanarCode, DepolarizingErrorModel, and PlanarMWPMDecoder. These are fundamental components for simulating error correction.

```python
%run qsu.ipynb  # color-printing functions
import numpy as np
from qecsim import paulitools as pt
from qecsim.models.generic import DepolarizingErrorModel
from qecsim.models.planar import PlanarCode, PlanarMWPMDecoder

# initialise models
my_code = PlanarCode(5, 5)
my_error_model = DepolarizingErrorModel()
my_decoder = PlanarMWPMDecoder()
# print models
print(my_code)
print(my_error_model)
print(my_decoder)
```

```text
PlanarCode(5, 5)
DepolarizingErrorModel()
PlanarMWPMDecoder()
```

--------------------------------

### PlanarCMWPMDecoder Initialization

Source: https://qecsim.github.io/api/models/planar.html

Initializes a new planar CMWPM decoder with specified parameters.

```APIDOC
## `__init__`

### Description
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.
```

--------------------------------

### available()

Source: https://qecsim.github.io/api/graphtools.html

Checks the availability of the Blossom V library.

```APIDOC
## available()

### Description
Checks the availability of the Blossom V library.

### Returns
- **bool**: True if the library is available, False otherwise.

### Raises
**OSError**: if Blossom V library cannot be loaded.
```

--------------------------------

### qecsim.models.basic.SteaneCode

Source: https://qecsim.github.io/api/models/basic.html

Implements the Steane [7, 1, 3] code.

```APIDOC
## `qecsim.models.basic.SteaneCode`

### Description
Implements the Steane [7, 1, 3] code.

### Class Signature
`__init__()`

### Properties
* **label** - See `qecsim.model.StabilizerCode.label()`
* **logical_xs** - See `qecsim.model.StabilizerCode.logical_xs()`
* **logical_zs** - See `qecsim.model.StabilizerCode.logical_zs()`
* **logicals** - Logical operators as binary symplectic matrix.
* **n_k_d** - See `qecsim.model.StabilizerCode.n_k_d()`
* **stabilizers** - See `qecsim.model.StabilizerCode.stabilizers()`

### Methods
* **validate()** - Perform various sanity checks.
```

--------------------------------

### Sample Simulation Data Output

Source: https://qecsim.github.io/demos/demo_color666_plot.html

Presents a dictionary containing the results of a single simulation run, including code details, error parameters, run statistics, and performance metrics like logical failure rate and physical error rate.

```json
{
    "code": "Color 6.6.6 7",
    "n_k_d": (37, 1, 7),
    "time_steps": 1,
    "error_model": "Depolarizing",
    "decoder": "Color 6.6.6 MPS (chi=8)",
    "error_probability": 0.0,
    "measurement_error_probability": 0.0,
    "n_run": 10000,
    "n_success": 10000,
    "n_fail": 0,
    "error_weight_total": 0,
    "error_weight_pvar": 0,
    "logical_failure_rate": 0.0,
    "physical_error_rate": 0.0,
    "wall_time": 188.2068080680001
}

```

--------------------------------

### Run Full Simulation Cycle

Source: https://qecsim.github.io/demos/demo_rotatedplanar.html

Executes a complete simulation cycle for the code, including error generation, decoding, and recovery. This is a convenient way to run the entire demo in a single call.

```python
# repeat demo in single call
from qecsim import app
print(app.run_once(my_code, my_error_model, my_decoder, error_probability))
```

--------------------------------

### Initialize PlanarMPSDecoder

Source: https://qecsim.github.io/api/models/planar.html

Initializes a new planar MPS decoder. Parameters like chi, mode, stp, and tol can be configured to control the decoding process and approximation accuracy.

```python
decoder = PlanarMPSDecoder(chi=16, mode='a', stp=0.5, tol=1e-8)
```

--------------------------------

### Run FTP Simulation with Rotated Planar Code

Source: https://qecsim.github.io/usage.html

Executes a full-tomography (FTP) simulation using the rotated planar code, specifying the code parameters, number of qubits, error model, and decoder with its probability.

```bash
qecsim run-ftp -r5 "rotated_planar(13,13)" 13 "generic.bit_phase_flip"
"rotated_planar.smwpm" 0.1 0.2
```