PanQEC

https://panqec.readthedocs.io/en/latest/
Admin
PanQEC is a Python package for simulating and visualizing quantum error correcting codes, allowing...
Tokens:26,468
Snippets:272
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Start the PanQEC GUI

Source: https://panqec.readthedocs.io/en/latest/installation.html

Run this command to launch the local web interface for testing the installation.

```bash
panqec start-gui
```

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

### Install PanQEC from Source

Source: https://panqec.readthedocs.io/en/latest/installation.html

Clone the repository and perform an editable installation to work with the source code directly.

```bash
git clone https://github.com/panqec/panqec
pip install -e ./panqec
```

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

### Start GUI

Source: https://panqec.readthedocs.io/en/latest/cli.html

Initializes the PanQEC graphical user interface.

```bash
panqec start-gui [OPTIONS]
```

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

### Install PanQEC via PyPI

Source: https://panqec.readthedocs.io/en/latest/installation.html

Use this command to install the latest stable version of PanQEC from the Python Package Index.

```bash
pip install panqec
```

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

### Initialize and run the GUI

Source: https://panqec.readthedocs.io/en/latest/tutorials/Adding%20new%20code.html

Use this snippet to register a code class and start the local GUI server.

```python
gui = GUI()
gui.add_code(MyToric3DCode, 'My Toric 3D')
gui.run(port=5000)
```

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

### Install development dependencies

Source: https://panqec.readthedocs.io/en/latest/development.html

Install required packages and the library in editable mode within a Python 3.8+ environment.

```bash
pip install -r requirements/dev.txt
pip install -e .
```

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

### Perform a mock experiment run

Source: https://panqec.readthedocs.io/en/latest/tutorials/Running%20experiments%20on%20a%20cluster.html

Executes a test run with a limited number of trials to verify the input file and installation.

```bash
panqec run -i my-experiment/inputs/experiment.json -o mock.json.gz -t 10
```

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

### Run project tests

Source: https://panqec.readthedocs.io/en/latest/development.html

Execute standard or comprehensive test suites to verify installation integrity.

```bash
pytest
```

```bash
pytest --runslow
```

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

### Example experiment input file

Source: https://panqec.readthedocs.io/en/latest/tutorials/Running%20experiments%20on%20a%20cluster.html

A JSON configuration file defining a 2D toric code simulation with depolarizing noise and a matching decoder.

```json
{
    "comments": "",
    "ranges": {
        "label": "toric-2d-experiment",
        "method": {
            "name": "direct",
            "parameters": {}
        },
        "code": {
            "name": "Toric2DCode",
            "parameters": [
                {
                    "L_x": 5,
                    "L_y": 5,
                },
                {
                    "L_x": 7,
                    "L_y": 7,
                },
                {
                    "L_x": 9,
                    "L_y": 9,
                }
            ]
        },
        "error_model": {
            "name": "PauliErrorModel",
            "parameters": {
                "r_x": 0.33333333333333337,
                "r_y": 0.33333333333333337,
                "r_z": 0.3333333333333333
            }
        },
        "decoder": {
            "name": "MatchingDecoder",
            "parameters": {}
        },
        "error_rate": [
            0.1,
            0.11,
            0.12,
            0.13,
            0.14,
            0.15,
            0.16,
            0.17,
            0.18,
            0.19,
            0.2,
        ]
    }
}
```

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

### Define XZZX error model parameters

Source: https://panqec.readthedocs.io/en/latest/tutorials/XZZX%20threshold%20vs%20bias.html

Example configuration dictionary for simulating an XZZX code under unbiased depolarizing noise.

```python
{
    ...
    'code': {
        'name': 'Toric2DCode',
        'parameters': [{'L_x': 6}, {'L_x': 12}, {'L_x': 24}]
    },
    'error_model': {
        'name': 'PauliErrorModel',  # Class name of the error model
        'parameters': [
            {'r_x': 1/3, 'r_y': 1/3, 'r_z': 1/3, 'deformation_name': 'XZZX'}
        ],
    },
    ...
}
```

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

### Build and serve documentation

Source: https://panqec.readthedocs.io/en/latest/development.html

Generate the documentation locally and serve it via a local HTTP server.

```bash
make doc
```

```bash
python -m http.server 9000 --directory docs/_build/html
```

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

### panqec start-gui

Source: https://panqec.readthedocs.io/en/latest/cli.html

Launches the PanQEC graphical user interface.

```APIDOC
## panqec start-gui

### Description
Starts the GUI application.

### Options
- **-p, --port** (int) - Optional - The port to run the GUI on.
```

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

### Initialize Batch Simulation

Source: https://panqec.readthedocs.io/en/latest/tutorials/XZZX%20threshold%20vs%20bias.html

Create a batch simulation instance from the input dictionary and specify an output file.

```python
from panqec.simulation import read_input_dict

n_trials = 200  # Target number of Monte Carlo runs

# We create a BatchSimulation by reading the input dictionary
batch_sim = read_input_dict(
    input_data,
    output_file='xzzx-css-2d-results.json'
)
```

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

### Get stabilizer operator

Source: https://panqec.readthedocs.io/en/latest/tutorials/Adding%20new%20code.html

Returns a dictionary mapping qubit locations to Pauli operators for a given stabilizer location.

```python
get_stabilizer((1,1,0)) -> {(1,0,0): 'X', (0,1,0): 'X', (2,1,0): 'X', (1,2,0): 'X'}
```

```python
def get_stabilizer(self, location):
    if self.stabilizer_type(location) == 'vertex':
        pauli = 'Z'
    else:
        pauli = 'X'

    x, y, z = location

    # delta specifies the positions of the qubits involved in the stabilizer
    # relative to the stabilizer position
    if self.stabilizer_type(location) == 'vertex':
        delta = [(-1, 0, 0), (1, 0, 0), (0, -1, 0), (0, 1, 0), (0, 0, -1), (0, 0, 1)]
    else:
        # Face in xy-plane.
        if z % 2 == 0:
            delta = [(-1, 0, 0), (1, 0, 0), (0, -1, 0), (0, 1, 0)]
        # Face in yz-plane.
        elif (x % 2 == 0):
            delta = [(0, -1, 0), (0, 1, 0), (0, 0, -1), (0, 0, 1)]
        # Face in zx-plane.
        elif (y % 2 == 0):
            delta = [(-1, 0, 0), (1, 0, 0), (0, 0, -1), (0, 0, 1)]

    operator = dict()
    for d in delta:
        Lx, Ly, Lz = self.size
        qubit_location = ((x + d[0]) % (2*Lx), (y + d[1]) % (2*Ly), (z + d[2]) % (2*Lz))

        if self.is_qubit(qubit_location):
            operator[qubit_location] = pauli

    return operator
```

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

### Clone the PanQEC repository

Source: https://panqec.readthedocs.io/en/latest/development.html

Initial steps to download the source code and navigate to the project directory.

```bash
git clone https://github.com/ehua7365/panqec.git
cd panqec
```

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

### Initialize Analysis object

Source: https://panqec.readthedocs.io/en/latest/tutorials/Computing%20threshold.html

Load simulation results from a JSON file to prepare for threshold analysis.

```python
analysis = Analysis("toric-2d-results.json")
```

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

### Get Deformation from Error Model Label

Source: https://panqec.readthedocs.io/en/latest/analysis.html

Retrieves the deformation name associated with a specific error model configuration string.

```python
>>> error_model_label = "PauliErrorModel()"
>>> get_deformation(error_model_label)
'undeformed'
```

```python
>>> error_model_label = "PauliErrorModel(r_x=0.00495, r_y=0.00495, "             "r_z=0.990099, deformation_name=None, deformation_kwargs={})"
>>> get_deformation(error_model_label)
'undeformed'
```

```python
>>> error_model_label = "PauliErrorModel(r_x=0.333333, r_y=0.333333, "             "r_z=0.333333, deformation_name='XZZX', deformation_kwargs={})"
>>> get_deformation(error_model_label)
'XZZX'
```

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

### Initialize Analysis and Calculate Thresholds

Source: https://panqec.readthedocs.io/en/latest/tutorials/XZZX%20threshold%20vs%20bias.html

Load simulation results from a JSON file and compute threshold values for the code.

```python
from panqec.analysis import Analysis

analysis = Analysis("xzzx-css-2d-results.json")
analysis.calculate_thresholds()
analysis.calculate_sector_thresholds()
```

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

### Instantiate code, noise model, and decoder

Source: https://panqec.readthedocs.io/en/latest/tutorials/Panqec%20basics.html

Initialize a 4x4 toric code, a Pauli error model with specific probabilities, and a matching decoder.

```python
code = Toric2DCode(4)

error_model = PauliErrorModel(0.2, 0.3, 0.5)
p = 0.1

decoder = MatchingDecoder(code, error_model, p)
```

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

### Initialize batch simulation

Source: https://panqec.readthedocs.io/en/latest/tutorials/Computing%20threshold.html

Creates a BatchSimulation instance from the input dictionary and enables live plotting.

```python
plot_frequency = 20  # Frequency of plot update
save_frequency = 10  # Frequency of saving to file
n_trials = 1000  # Target number of Monte Carlo runs

# We create a BatchSimulation by reading the input dictionary
batch_sim = read_input_dict(
    input_data,
    output_file='toric-2d-results.json',  # Where to store the simulation results
    update_frequency=plot_frequency,
    save_frequency=save_frequency
)

# Live update of the plot during the simulation
# (only works in Jupyter notebooks)
batch_sim.activate_live_update()
```

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

### Check resource usage

Source: https://panqec.readthedocs.io/en/latest/tutorials/Running%20experiments%20on%20a%20cluster.html

Visualize RAM and CPU usage graphically in the command line.

```bash
panqec check-usage my-experiment/
```

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

### Import PanQEC components

Source: https://panqec.readthedocs.io/en/latest/tutorials/Panqec%20basics.html

Import the necessary classes for the toric code, Pauli error model, and matching decoder.

```python
from panqec.codes import Toric2DCode
from panqec.error_models import PauliErrorModel
from panqec.decoders import MatchingDecoder
```

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

### General CLI usage

Source: https://panqec.readthedocs.io/en/latest/cli.html

Base command structure for the panqec CLI.

```bash
panqec [OPTIONS] COMMAND [ARGS]...
```

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

### Run simulation

Source: https://panqec.readthedocs.io/en/latest/cli.html

Execute a single job or multiple jobs from an input file.

```bash
panqec run [OPTIONS]
```

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

### Execute Simulation with Progress Bar

Source: https://panqec.readthedocs.io/en/latest/tutorials/XZZX%20threshold%20vs%20bias.html

Run the batch simulation using a tqdm progress bar to monitor progress.

```python
from tqdm import tqdm
batch_sim.run(n_trials, progress=tqdm)
```

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

### Base Representation Methods

Source: https://panqec.readthedocs.io/en/latest/tutorials/Adding%20new%20code.html

Initial implementation of stabilizer and qubit representation methods using a JSON configuration file.

```python
def stabilizer_representation(self, location, rotated_picture=False):
    representation = super().stabilizer_representation(location, rotated_picture, json_file='toric3d.json')

    return representation

def qubit_representation(self, location, rotated_picture=False):
    representation = super().qubit_representation(location, rotated_picture, json_file='toric3d.json')

    return representation
```

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

### Generate XZZX input configurations

Source: https://panqec.readthedocs.io/en/latest/tutorials/XZZX%20threshold%20vs%20bias.html

List comprehension to generate input dictionaries for XZZX surface code simulations.

```python
xzzx_inputs = [
    {
        'label': 'XZZX surface code eta = ' + str(entry['eta']),
        'code': code_input,
        'error_model': {
            'name': 'PauliErrorModel',
            'parameters': {
                **get_direction_from_bias_ratio('Z', entry['eta']),
                'deformation_name': 'XZZX',
            },
        },
        'decoder': decoder_input,
        'error_rate': np.linspace(entry['min'], entry['max'], 8).tolist(),
    }
    for entry in xzzx_error_rate_ranges
]
```

```python
[{'label': 'CSS surface code eta = 0.5',
  'code': {'name': 'Toric2DCode',
   'parameters': [{'L_x': 6}, {'L_x': 12}, {'L_x': 24}]},
  'error_model': {'name': 'PauliErrorModel',
   'parameters': {'r_x': 0.33333333333333337,
    'r_y': 0.33333333333333337,
    'r_z': 0.3333333333333333}},
  'decoder': {'name': 'MatchingDecoder', 'parameters': [{}]},
  'error_rate': [0.1, 0.125, 0.15000000000000002, 0.17500000000000002, 0.2]},
 {'label': 'CSS surface code eta = 10',
  'code': {'name': 'Toric2DCode',
   'parameters': [{'L_x': 6}, {'L_x': 12}, {'L_x': 24}]},
  'error_model': {'name': 'PauliErrorModel',
   'parameters': {'r_x': 0.04545454545454547,
    'r_y': 0.04545454545454547,
    'r_z': 0.9090909090909091}},
  'decoder': {'name': 'MatchingDecoder', 'parameters': [{}]},
  'error_rate': [0.05, 0.075, 0.1, 0.125, 0.15]},
 {'label': 'CSS surface code eta = 30',
  'code': {'name': 'Toric2DCode',
   'parameters': [{'L_x': 6}, {'L_x': 12}, {'L_x': 24}]},
  'error_model': {'name': 'PauliErrorModel',
   'parameters': {'r_x': 0.016129032258064502,
    'r_y': 0.016129032258064502,
    'r_z': 0.967741935483871}},
  'decoder': {'name': 'MatchingDecoder', 'parameters': [{}]},
  'error_rate': [0.05, 0.075, 0.1, 0.125, 0.15]}]
```

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

### panqec.simulation.run_file

Source: https://panqec.readthedocs.io/en/latest/simulation.html

Executes a simulation based on an input JSON file and saves the results to an output file.

```APIDOC
## panqec.simulation.run_file(input_file, output_file, n_trials, progress, log_file, verbose)

### Description
Runs a quantum error correction simulation defined in an input JSON file.

### Parameters
- **input_file** (str) - Required - Path to the input json file.
- **output_file** (str) - Required - Path to the json file that will contain the results.
- **n_trials** (int) - Required - The number of MCMC trials to do.
- **progress** (Callable) - Optional - Callable function for progress tracking.
- **log_file** (str | None) - Optional - Path to the log file.
- **verbose** (bool) - Optional - Verbosity of the output.
```

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

### panqec.simulation.run_once

Source: https://panqec.readthedocs.io/en/latest/simulation.html

Runs a single simulation instance and returns the results.

```APIDOC
## panqec.simulation.run_once(code, error_model, decoder, error_rate, rng)

### Description
Executes a simulation once and returns the results as a dictionary.

### Parameters
- **code** (StabilizerCode) - Required
- **error_model** (BaseErrorModel) - Required
- **decoder** (BaseDecoder) - Required
- **error_rate** (float) - Required
- **rng** (Any) - Optional

### Response
- **dict** - The simulation results.
```

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

### Importing PanQEC modules

Source: https://panqec.readthedocs.io/en/latest/tutorials/Adding%20new%20code.html

Initial imports required to define custom codes and utilize the GUI.

```python
from panqec.codes import StabilizerCode
from panqec.gui import GUI
```

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

### XCubeCode Constructor

Source: https://panqec.readthedocs.io/en/latest/codes.html

Initializes an X-Cube model on a periodic 3D cubic lattice.

```APIDOC
## XCubeCode(L_x, L_y=None, L_z=None)

### Description
Initializes the X-Cube model of Vijay, Haah and Fu 2016 on a periodic 3D cubic lattice.

### Parameters
- **L_x** (int) - Required - Size of lattice in x direction
- **L_y** (int) - Optional - Size of lattice in y direction
- **L_z** (int) - Optional - Size of lattice in z direction
```

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

### List available models

Source: https://panqec.readthedocs.io/en/latest/cli.html

List available codes, error models, or decoders.

```bash
panqec ls [OPTIONS] [[codes|error_models|decoders]]
```

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

### Visualize thresholds

Source: https://panqec.readthedocs.io/en/latest/tutorials/Running%20experiments%20on%20a%20cluster.html

Initialize the Analysis class and plot thresholds from the merged results file.

```python
from panqec.analysis import Analysis
analysis = Analysis("my-experiment/merged-results.json.gz")
analysis.plot_thresholds()
```

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

### Import required libraries

Source: https://panqec.readthedocs.io/en/latest/tutorials/Computing%20threshold.html

Imports necessary modules for simulation, data handling, and visualization.

```python
from tqdm.notebook import tqdm
import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
%matplotlib inline

from panqec.simulation import read_input_dict
from panqec.analysis import Analysis
```

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

### Execute batch simulation

Source: https://panqec.readthedocs.io/en/latest/tutorials/Computing%20threshold.html

Runs the simulation for the specified number of trials with progress tracking.

```python
batch_sim.run(n_trials, progress=tqdm)
```

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

### Generate experiment input via CLI

Source: https://panqec.readthedocs.io/en/latest/tutorials/Running%20experiments%20on%20a%20cluster.html

Command to automatically generate the required directory structure and JSON input file for an experiment.

```bash
panqec generate-input -d "my-experiment" \
    --code_class Toric2DCode --sizes "5x5,7x7,9x9" \
    --decoder_class MatchingDecoder \
    --bias "Z" --eta "0.5" \
    --prob "0.1:0.2:0.01"
```

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

### Generate experiment inputs

Source: https://panqec.readthedocs.io/en/latest/cli.html

Generate JSON input files for experiments.

```bash
panqec generate-input [OPTIONS]
```

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

### Define CSS surface code parameters

Source: https://panqec.readthedocs.io/en/latest/tutorials/XZZX%20threshold%20vs%20bias.html

Sets up the Toric2DCode configuration with varying lattice sizes.

```python
code_input = {
    'name': 'Toric2DCode',
    'parameters': [
        {'L_x': 6},
        {'L_x': 12},
        {'L_x': 24}
    ]
}
```

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

### Define Simulation Input Dictionary

Source: https://panqec.readthedocs.io/en/latest/tutorials/XZZX%20threshold%20vs%20bias.html

Combine CSS and XZZX input ranges into a single dictionary for simulation processing.

```python
input_data = {
    'ranges': css_inputs + xzzx_inputs
}

input_data
```

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

### DirectSimulation

Source: https://panqec.readthedocs.io/en/latest/simulation.html

Class for performing direct quantum error correction simulations.

```APIDOC
## DirectSimulation

### Description
Quantum Error Correction Simulation using direct sampling.

### Constructor
`DirectSimulation(code: StabilizerCode, error_model: BaseErrorModel, decoder: BaseDecoder, error_rate: float, compress: bool = True, verbose: bool = True, rng = None)`

### Methods
- `get_results()`: Return results as dictionary.
```

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

### Generate formatted class labels

Source: https://panqec.readthedocs.io/en/latest/misc.html

Create a string representation of a class name and its initialization parameters.

```python
>>> get_label('Toric2DCode', {'L_x': 5, 'L_y': 6, 'L_z': 7})
'Toric2DCode(L_x=5, L_y=6, L_z=7)'
```

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

### BaseSimulation

Source: https://panqec.readthedocs.io/en/latest/simulation.html

Base class for quantum error correction simulations.

```APIDOC
## BaseSimulation

### Description
Base class for quantum error correction simulations.

### Constructor
`BaseSimulation(code: StabilizerCode, error_model: BaseErrorModel, compress: bool = True, verbose: bool = True, rng = None)`

### Methods
- `load_results(output_file: str)`: Load previously written results from directory.
- `save_results(output_file: str)`: Save results to directory.
```

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

### Run parallel jobs

Source: https://panqec.readthedocs.io/en/latest/cli.html

Executes PanQEC jobs in parallel using specified data directories and trial counts.

```bash
panqec run-parallel [OPTIONS]
```

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

### Generate cluster script

Source: https://panqec.readthedocs.io/en/latest/cli.html

Create a generic cluster submission script from a header file.

```bash
panqec generate-cluster-script [OPTIONS] HEADER_FILE
```

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

### Monitor resource usage

Source: https://panqec.readthedocs.io/en/latest/cli.html

Continuously monitor CPU usage and log to a file.

```bash
panqec monitor-usage [OPTIONS] LOG_FILE
```

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

### panqec.utils.get_label(name, parameters)

Source: https://panqec.readthedocs.io/en/latest/misc.html

Generates a formatted label string based on a class name and its initialization parameters.

```APIDOC
## panqec.utils.get_label(name, parameters)

### Description
Get label filtering entries from class name and parameters.

### Parameters
- **name** (str) - Required - The name of the class.
- **parameters** (Dict[str, Any]) - Required - The dictionary of parameters used to initialize an instance of that class.

### Returns
- **label** (str) - The formatted label.

### Example
```python
>>> get_label('Toric2DCode', {'L_x': 5, 'L_y': 6, 'L_z': 7})
'Toric2DCode(L_x=5, L_y=6, L_z=7)'
```
```

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

### Check resource usage

Source: https://panqec.readthedocs.io/en/latest/cli.html

Check resource usage across multiple data directories.

```bash
panqec check-usage [OPTIONS] DATA_DIRS...
```

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

### panqec.bsparse.zero_matrix

Source: https://panqec.readthedocs.io/en/latest/misc.html

Creates a zero sparse matrix.

```APIDOC
## panqec.bsparse.zero_matrix(shape)

### Description
Create a zero sparse matrix in the csr format.

### Parameters
- **shape** (tuple) - Required - Shape of the matrix
```

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

### Expand dictionaries with the unpacking operator

Source: https://panqec.readthedocs.io/en/latest/tutorials/XZZX%20threshold%20vs%20bias.html

Demonstration of the Python dictionary unpacking operator.

```python
{'a': 1, 'b': 2, **{'c': 3}}
```

```python
{'a': 1, 'b': 2, 'c': 3}
```

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

### BatchSimulation

Source: https://panqec.readthedocs.io/en/latest/simulation.html

Class for holding and controlling multiple simulations.

```APIDOC
## BatchSimulation

### Description
Holds and controls many simulations.

### Constructor
`BatchSimulation(output_file: str, label='unlabelled', on_update: Callable = identity, update_frequency: int = 5, save_frequency: int = 1, method: str = 'direct', log_file: str | None = None, verbose: bool = True)`

### Methods
- `append(simulation: BaseSimulation)`: Append a simulation to the current BatchSimulation.
- `estimate_remaining_time(n_trials: int)`: Estimate remaining time given target n_trials.
- `load_results()`: Load results from disk.
- `on_update(n_trials: int)`: Function that gets called on every update.
- `run(n_trials, progress: Callable = identity)`: Perform the running.
- `save_file()`: Do a complete save of the file.

### Properties
- `wall_time`: Total time run so far.
```

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

### Generate collapse plots

Source: https://panqec.readthedocs.io/en/latest/tutorials/Computing%20threshold.html

Create collapse plots to evaluate the quality of the fit used for threshold estimation.

```python
analysis.make_collapse_plots()
```

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

### Generate simulation inputs

Source: https://panqec.readthedocs.io/en/latest/tutorials/XZZX%20threshold%20vs%20bias.html

Constructs the list of input dictionaries for the CSS surface code simulations across different bias values.

```python
import numpy as np
css_inputs = [
    {
        'label': 'CSS surface code eta = ' + str(entry['eta']),
        'code': code_input,
        'error_model': {
            'name': 'PauliErrorModel',
            'parameters': get_direction_from_bias_ratio('Z', entry['eta']),
        },
        'decoder': decoder_input,
        'error_rate': np.linspace(entry['min'], entry['max'], 5).tolist(),
    }
    for entry in css_error_rate_ranges
]

css_inputs
```

```python
[{'label': 'CSS surface code eta = 0.5',
  'code': {'name': 'Toric2DCode',
   'parameters': [{'L_x': 6}, {'L_x': 12}, {'L_x': 24}]},
  'error_model': {'name': 'PauliErrorModel',
   'parameters': {'r_x': 0.33333333333333337,
    'r_y': 0.33333333333333337,
    'r_z': 0.3333333333333333}},
  'decoder': {'name': 'MatchingDecoder', 'parameters': [{}]},
  'error_rate': [0.1, 0.125, 0.15000000000000002, 0.17500000000000002, 0.2]},
 {'label': 'CSS surface code eta = 10',
  'code': {'name': 'Toric2DCode',
   'parameters': [{'L_x': 6}, {'L_x': 12}, {'L_x': 24}]},
  'error_model': {'name': 'PauliErrorModel',
   'parameters': {'r_x': 0.04545454545454547,
    'r_y': 0.04545454545454547,
    'r_z': 0.9090909090909091}},
  'decoder': {'name': 'MatchingDecoder', 'parameters': [{}]},
  'error_rate': [0.05, 0.075, 0.1, 0.125, 0.15]},
 {'label': 'CSS surface code eta = 30',
  'code': {'name': 'Toric2DCode',
   'parameters': [{'L_x': 6}, {'L_x': 12}, {'L_x': 24}]},
  'error_model': {'name': 'PauliErrorModel',
   'parameters': {'r_x': 0.016129032258064502,
    'r_y': 0.016129032258064502,
    'r_z': 0.967741935483871}},
  'decoder': {'name': 'MatchingDecoder', 'parameters': [{}]},
  'error_rate': [0.05, 0.075, 0.1, 0.125, 0.15]}]
```

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

### Monitor experiment progress

Source: https://panqec.readthedocs.io/en/latest/tutorials/Running%20experiments%20on%20a%20cluster.html

Check the status of the experiment logs.

```bash
panqec check-progress my-experiment/logs
```

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

### panqec.simulation.read_input_json

Source: https://panqec.readthedocs.io/en/latest/simulation.html

Reads a simulation configuration from a JSON file.

```APIDOC
## panqec.simulation.read_input_json(input_file, output_file, log_file)

### Description
Reads a json input file or .json.gz file and returns a BatchSimulation object.

### Parameters
- **input_file** (str) - Required
- **output_file** (str) - Required
- **log_file** (str | None) - Optional

### Response
- **BatchSimulation** - The simulation batch object.
```

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

### Color3DCode(L_x, L_y=None, L_z=None)

Source: https://panqec.readthedocs.io/en/latest/codes.html

Initializes a 3D Color Code on a periodic truncated octahedral lattice.

```APIDOC
## Color3DCode(L_x, L_y=None, L_z=None)

### Description
Initializes a 3D Color Code on a periodic truncated octahedral lattice.

### Parameters
- **L_x** (int) - Required - Size in the x direction.
- **L_y** (int) - Optional - Size in the y direction.
- **L_z** (int) - Optional - Size in the z direction.
```

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

### Print binary arrays compactly

Source: https://panqec.readthedocs.io/en/latest/misc.html

Display binary arrays in a space-saving format, with optional suppression of zeros.

```python
>>> simple_print(np.eye(3))
100
010
001
```

```python
>>> simple_print(np.eye(3), zeros=False)
1
 1
  1
```

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

### Inspect threshold estimates

Source: https://panqec.readthedocs.io/en/latest/tutorials/Running%20experiments%20on%20a%20cluster.html

Display numerical threshold estimates and confidence intervals.

```python
analysis.thresholds[['code', 'error_model', 'bias', 'p_th_fss', 'p_th_fss_left', 'p_th_fss_right']]
```

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

### Complete Custom Code Class

Source: https://panqec.readthedocs.io/en/latest/tutorials/Adding%20new%20code.html

Full implementation of a custom 3D code class defining qubit and stabilizer coordinates.

```python
class MyToric3DCode(StabilizerCode):
    dimension = 3

    @property
    def label(self):
        return 'My Toric {}x{}x{}'.format(*self.size)

    def get_qubit_coordinates(self):
        coordinates = []
        Lx, Ly, Lz = self.size

        # Qubits along e_x
        for x in range(1, 2*Lx, 2):
            for y in range(0, 2*Ly, 2):
                for z in range(0, 2*Lz, 2):
                    coordinates.append((x, y, z))

        # Qubits along e_y
        for x in range(0, 2*Lx, 2):
            for y in range(1, 2*Ly, 2):
                for z in range(0, 2*Lz, 2):
                    coordinates.append((x, y, z))

        # Qubits along e_z
        for x in range(0, 2*Lx, 2):
            for y in range(0, 2*Ly, 2):
                for z in range(1, 2*Lz, 2):
                    coordinates.append((x, y, z))

        return coordinates

    def get_stabilizer_coordinates(self):
        coordinates = []
        Lx, Ly, Lz = self.size

        # Vertices
        for x in range(0, 2*Lx, 2):
            for y in range(0, 2*Ly, 2):
                for z in range(0, 2*Lz, 2):
                    coordinates.append((x, y, z))

        # Face in xy plane
        for x in range(1, 2*Lx, 2):
            for y in range(1, 2*Ly, 2):
                for z in range(0, 2*Lz, 2):
                    coordinates.append((x, y, z))

        # Face in yz plane
        for x in range(0, 2*Lx, 2):
            for y in range(1, 2*Ly, 2):
                for z in range(1, 2*Lz, 2):
                    coordinates.append((x, y, z))

        # Face in xz plane
        for x in range(1, 2*Lx, 2):
            for y in range(0, 2*Ly, 2):
                for z in range(1, 2*Lz, 2):
                    coordinates.append((x, y, z))

        return coordinates
```

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

### Generate Data Collapse Plots

Source: https://panqec.readthedocs.io/en/latest/tutorials/XZZX%20threshold%20vs%20bias.html

Create plots to visualize data collapse for a specific sector.

```python
analysis.make_collapse_plots(sector='total')
```

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

### Check resource progress

Source: https://panqec.readthedocs.io/en/latest/cli.html

Monitor resource usage for a specific log directory.

```bash
panqec check-progress [OPTIONS] LOG_DIR
```

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

### qubit_representation(location, rotated_picture=False, json_file=None)

Source: https://panqec.readthedocs.io/en/latest/codes.html

Returns visualization parameters for a qubit for use in a web visualizer.

```APIDOC
## qubit_representation(location, rotated_picture=False, json_file=None)

### Description
Returns a dictionary of visualization parameters for the input qubit, including location, object type, and specific parameters.

### Parameters
- **location** (Tuple) - Required - Coordinates of the qubit.
- **rotated_picture** (bool) - Optional - Used to differentiate visualization types.
- **json_file** (str) - Optional - File with the initial configuration for the code.
```

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

### panqec run-parallel

Source: https://panqec.readthedocs.io/en/latest/cli.html

Executes PanQEC jobs in parallel.

```APIDOC
## panqec run-parallel

### Description
Run panqec jobs in parallel.

### Options
- **-d, --data_dir** (path) - Optional - Data directory.
- **-t, --trials** (int) - Optional - Number of trials (Default: 1000).
- **-n, --n_nodes** (int) - Optional - Number of nodes (Default: 1).
- **-j, --job_idx** (int) - Optional - Job index (Default: 1).
- **-c, --n_cores** (int) - Optional - Number of cores.
- **--delete-existing** (flag) - Optional - Delete existing results folder in the data directory (Default: False).
```

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

### Manage Slurm scripts

Source: https://panqec.readthedocs.io/en/latest/cli.html

Base command for generating and running Slurm scripts.

```bash
panqec slurm [OPTIONS] COMMAND [ARGS]...
```

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

### Define 3D visual configuration for qubits and stabilizers

Source: https://panqec.readthedocs.io/en/latest/tutorials/Adding%20new%20code.html

Use this JSON structure to map specific code types to their visual objects, colors, and opacity parameters.

```json
{
    "MyToric3DCode": {
        "qubits": {
            "kitaev": {
                "object": "cylinder",
                "color": {
                    "I": "pink",
                    "X": "red",
                    "Y": "green",
                    "Z": "blue"
                },
                "opacity": {
                    "activated": {
                        "min": 1,
                        "max": 1
                    },
                    "deactivated": {
                        "min": 0.1,
                        "max": 0.6
                    }
                },
                "params": {
                    "length": 2,
                    "radius": 0.1,
                    "angle": 0
                }
            },
            "rotated": {
                "object": "sphere",
                "color": {
                    "I": "white",
                    "X": "red",
                    "Y": "green",
                    "Z": "blue"
                },
                "opacity": {
                    "activated": {
                        "min": 1,
                        "max": 1
                    },
                    "deactivated": {
                        "min": 0.1,
                        "max": 0.4
                    }
                },
                "params": {
                    "radius": 0.2
                }
            }
        },
        "stabilizers": {
            "kitaev": {
                "vertex": {
                    "object": "sphere",
                    "color": {
                        "activated": "gold",
                        "deactivated": "white"
                    },
                    "opacity": {
                        "activated": {
                            "min": 1,
                            "max": 1
                        },
                        "deactivated": {
                            "min": 0.1,
                            "max": 0.6
                        }
                    },
                    "params": {"radius": 0.2}
                },
                "face": {
                    "object": "rectangle",
                    "color": {
                        "activated": "gold",
                        "deactivated": "blue"
                    },
                    "opacity": {
                        "activated": {
                            "min": 0.6,
                            "max": 0.6
                        },
                        "deactivated": {
                            "min": 0,
                            "max": 0
                        }
                    },
                    "params": {
                        "w": 1.5,
                        "h": 1.5,
                        "normal": [1, 0, 0],
                        "angle": 0
                    }
                }
            },
            "rotated": {
                "vertex": {
                    "object": "octahedron",
                    "color": {
                        "activated": "orange",
                        "deactivated": "orange"
                    },
                    "opacity": {
                        "activated": {
                            "min": 0.9,
                            "max": 0.9
                        },
                        "deactivated": {
                            "min": 0.1,
                            "max": 0.3
                        }
                    },
                    "params": {
                        "length": 1,
                        "angle": 0
                    }
                },
                "face": {
                    "object": "rectangle",
                    "color": {
                        "activated": "gold",
                        "deactivated": "gold"
                    },
                    "opacity": {
                        "activated": {
                            "min": 0.9,
                            "max": 0.9
                        },
                        "deactivated": {
                            "min": 0.1,
                            "max": 0.3
                        }
                    },
                    "params": {
                        "w": 1.4142,
                        "h": 1.4142,
                        "normal": [0,0,1],
                        "angle": 0.7854
                    }
                }
            }
        }
    }
}
```

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

### Sync results to local machine

Source: https://panqec.readthedocs.io/en/latest/tutorials/Running%20experiments%20on%20a%20cluster.html

Transfer the merged results file from the cluster to a local directory using rsync.

```bash
rsync -avzhe ssh user@example.com:~/my-experiments/merged-results.json.gz my-experiment/
```

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

### panqec.bsparse.zero_row

Source: https://panqec.readthedocs.io/en/latest/misc.html

Creates a zero sparse row.

```APIDOC
## panqec.bsparse.zero_row(n_cols)

### Description
Create a zero sparse row in the csr format.

### Parameters
- **n_cols** (int) - Required - Number of columns
```

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

### Check code style and type safety

Source: https://panqec.readthedocs.io/en/latest/development.html

Run the linter to check for PEP 8 compliance and perform type checking via mypy.

```bash
make lint
```

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

### panqec.io.serialize_results

Source: https://panqec.readthedocs.io/en/latest/misc.html

Converts simulation trial results into a dictionary format.

```APIDOC
## panqec.io.serialize_results(i_trial, n_trials, L_list, p_list, L_repeats, start_time, time_elapsed, time_remaining, eta, p_est, p_se, n_fail, n_try, effective_errors)

### Description
Aggregates various simulation metrics and metadata into a dictionary structure.

### Returns
- **dict** - A dictionary containing the serialized simulation results.
```

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

### panqec.bsparse.equal

Source: https://panqec.readthedocs.io/en/latest/misc.html

Tests equality between two matrices.

```APIDOC
## panqec.bsparse.equal(a, b)

### Description
Test if two matrices are equal, or if a matrix equals a unique number everywhere.

### Parameters
- **a** (matrix) - Required - First matrix
- **b** (matrix) - Required - Second matrix
```

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

### Display execution index

Source: https://panqec.readthedocs.io/en/latest/tutorials/Adding%20new%20code.html

Represents a standard execution cell index marker.

```text
[12]:
```

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

### Analyze data

Source: https://panqec.readthedocs.io/en/latest/cli.html

Analyze simulation data located at specified paths.

```bash
panqec analyze [OPTIONS] [PATHS]...
```

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

### Submit experiment job

Source: https://panqec.readthedocs.io/en/latest/tutorials/Running%20experiments%20on%20a%20cluster.html

Submit a batch job to the Slurm scheduler.

```bash
sbatch my-experiment/run.sbatch
```

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

### Define simulation input dictionary

Source: https://panqec.readthedocs.io/en/latest/tutorials/Computing%20threshold.html

Configures the simulation parameters including code type, error model, decoder, and error rate range.

```python
input_data = {
    'ranges': {
        'label': 'Toric 2D Experiment',  # Can be any name you want
        'code': {
            'name': 'Toric2DCode',  # Class name of the code
            'parameters': [
                {'L_x': 6},
                {'L_x': 12},
                {'L_x': 18},
            ]
        },
        'error_model': {
            'name': 'PauliErrorModel',  # Class name of the error model
            'parameters': [
                {'r_x': 1/3, 'r_y': 1/3, 'r_z': 1/3}  # Ratios of X, Y and Z errors
            ],
        },
        'decoder': {
            'name': 'MatchingDecoder',  # Class name of the decoder
            'parameters': [{}]
        },
        'error_rate': np.linspace(0.1, 0.2, 8).tolist()  # List of physical error rates
    }
}
```

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

### panqec.bpauli.bsf_wt

Source: https://panqec.readthedocs.io/en/latest/misc.html

Return weight of given binary symplectic form.

```APIDOC
## panqec.bpauli.bsf_wt(bsf)

### Description
Return weight of given binary symplectic form.

### Parameters
- **bsf** (numpy.array or csr_matrix) - Required - Binary symplectic vector or matrix (1d or 2d).

### Returns
- **int** - Weight.
```

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

### Implement get_deformation method

Source: https://panqec.readthedocs.io/en/latest/tutorials/Adding%20new%20code.html

Defines the Pauli mapping for Clifford deformations based on qubit location and deformation axis.

```python
def get_deformation(self, location, deformation_name, deformation_axis='y'):
    if deformation_name == 'XZZX':
        undeformed_dict = {'X': 'X', 'Y': 'Y', 'Z': 'Z'}
        deformed_dict = {'X': 'Z', 'Y': 'Y', 'Z': 'X'}

        if self.qubit_axis(location) == deformation_axis:
            deformation = deformed_dict
        else:
            deformation = undeformed_dict

    else:
        raise ValueError(f"The deformation {deformation_name}"
                         "does not exist")

    return deformation
```

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

### Define Matching Decoder

Source: https://panqec.readthedocs.io/en/latest/tutorials/XZZX%20threshold%20vs%20bias.html

Configures the MatchingDecoder for use in the simulation.

```python
decoder_input = {
    'name': 'MatchingDecoder',
    'parameters': [{}]
}
```

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

### panqec slurm

Source: https://panqec.readthedocs.io/en/latest/cli.html

Routines for generating and running slurm scripts.

```APIDOC
## panqec slurm clear

### Description
Clear generated files.

### Arguments
- **FOLDER** (string) - Required - The target folder type (all, out, or sbatch).

## panqec slurm count

### Description
Count number of input parameters contained.

### Arguments
- **NAME** (string) - Required - The name of the parameter set.

## panqec slurm status

### Description
Show the status of running jobs.
```

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

### Defining qubit coordinates

Source: https://panqec.readthedocs.io/en/latest/tutorials/Adding%20new%20code.html

Method to generate a list of coordinates for all qubits in the 3D toric code.

```python
def get_qubit_coordinates(self):
    coordinates = []
    Lx, Ly, Lz = self.size

    # Qubits along e_x
    for x in range(1, 2*Lx, 2):
        for y in range(0, 2*Ly, 2):
            for z in range(0, 2*Lz, 2):
                coordinates.append((x, y, z))

    # Qubits along e_y
    for x in range(0, 2*Lx, 2):
        for y in range(1, 2*Ly, 2):
            for z in range(0, 2*Lz, 2):
                coordinates.append((x, y, z))

    # Qubits along e_z
    for x in range(0, 2*Lx, 2):
        for y in range(0, 2*Ly, 2):
            for z in range(1, 2*Lz, 2):
                coordinates.append((x, y, z))

    return coordinates
```

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

### get_qubit_coordinates()

Source: https://panqec.readthedocs.io/en/latest/codes.html

Returns the list of all qubit coordinates.

```APIDOC
## get_qubit_coordinates()

### Description
Give the list of all the qubit coordinates, in a coordinate system that should contain both the qubits and the stabilizers.
```

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

### Decode syndrome and verify success

Source: https://panqec.readthedocs.io/en/latest/tutorials/Panqec%20basics.html

Apply the decoder to the syndrome, calculate residual errors, and check if the decoding was successful.

```python
# Obtain the correction by decoding the syndrome
correction = decoder.decode(syndrome)
print("Correction: ", correction)

# Get the remaining error once the correction has been applied
residual_error = (correction + errors) % 2
print("Residual error: ", residual_error)

# Check whether the residual error is in the codespace
# (i.e. whether there is any remaining excitation)
in_codespace = code.in_codespace(residual_error)
print("Is in codespace: ", in_codespace)

# Get the logical errors
logical_errors = code.logical_errors(residual_error)
print("Logical errors: ", logical_errors)

# Check whether the decoding succeeded
success = not code.is_logical_error(residual_error) and in_codespace
print("Success: ", success)
```

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

### Extract Code Properties

Source: https://panqec.readthedocs.io/en/latest/tutorials/Panqec%20basics.html

Retrieve the number of physical qubits (n), logical qubits (k), and distance (d) for a code.

```python
code = code = Toric2DCode(4)

print(f"[[n,k,d]]=[[{code.n},{code.k},{code.d}]]")
```

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

### Generate Threshold vs Bias Plots

Source: https://panqec.readthedocs.io/en/latest/tutorials/XZZX%20threshold%20vs%20bias.html

Visualize the threshold error rate pth as a function of bias ηZ.

```python
analysis.make_threshold_vs_bias_plots()
```

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

### Merge experiment results

Source: https://panqec.readthedocs.io/en/latest/tutorials/Running%20experiments%20on%20a%20cluster.html

Aggregate distributed JSON result files into a single compressed file.

```bash
panqec merge-results my-experiment/results/results_* -o my-experiments/merged-results.json.gz
```

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

### Inspect result data

Source: https://panqec.readthedocs.io/en/latest/tutorials/Running%20experiments%20on%20a%20cluster.html

Retrieve and display the first 10 rows of the results dataframe.

```python
df = analysis.get_results()
df[['code', 'd', 'error_model', 'bias', 'decoder', 'error_rate', 'n_fail', 'n_trials']].head(10)
```

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

### stabilizer_representation(location, rotated_picture=False, json_file=None)

Source: https://panqec.readthedocs.io/en/latest/codes.html

Returns visualization parameters for a stabilizer for use in a web visualizer.

```APIDOC
## stabilizer_representation(location, rotated_picture=False, json_file=None)

### Description
Returns a dictionary of visualization parameters for the input stabilizer, that can be used by the web visualizer.

### Parameters
- **location** (Tuple) - Required - Coordinates of the stabilizer.
- **rotated_picture** (bool) - Optional - Used to differentiate visualizations for codes with a rotated picture.
- **json_file** (str) - Optional - File with the initial configuration for the code.

### Returns
- **representation** (Dict) - Dictionary to send to the GUI.
```
Tokens:
Raw