DOI: 10.5281/zenodo.14861052
title: Logical coherence in 2D compass codes Supplementary Material

description: Logical coherence in 2D compass codes

This repo contains the tools to reproduce and share the data for the paper "Logical Coherence in 2D Compass Codes" by Balint Pato, Will Judd Staples, and Kenneth R. Brown (2025) as well as data for B. Pato, Q. Miao and K. R. Brown, "Optimal Decoding of 2D Compass Codes Under Coherent Noise," 2024 IEEE International Conference on Quantum Computing and Engineering (QCE), Montreal, QC, Canada, 2024, pp. 448-449, doi: 10.1109/QCE60285.2024.10349.

Setup

Python 3.x is required. The instructions for a Unix/Linux system:

cd coherence-in-compass-codes-paper
python3 -m venv ~/.virtualenvs/cicc
. ~/.virtualenvs/cicc/bin/activate 
pip install -r requirements.txt -r msim/requirements.txt -r msim/requirements.dev.txt


Before running any Python file, make sure the source folder is in PYTHONPATH, for example:

export PYTHONPATH="."


A quick end-to-end test that everything works:

check/all


Downloading data

Pregenerated data is available in data/codes.db for the Logical Coherence in 2D Compass Codes paper.

The number of samples per code family:




code family
samples




qshor[0.166667]_13x13_0
2,178,400


qshor[0.166667]_17x17_0
2,185,800


qshor[0.166667]_21x21_0
2,210,800


qshor[0.166667]_9x9_0
2,176,600


qshor[0.333333]_13x13_0
3,310,800


qshor[0.333333]_17x17_0
3,317,870


qshor[0.333333]_21x21_0
3,344,800


qshor[0.333333]_9x9_0
3,308,000


qshor[0.5]_13x13_0
2,381,400


qshor[0.5]_17x17_0
2,388,000


qshor[0.5]_21x21_0
2,398,600


qshor[0.5]_9x9_0
2,379,400


qshor[0.666667]_13x13_0
2,808,400


qshor[0.666667]_17x17_0
2,827,000


qshor[0.666667]_21x21_0
2,876,600


qshor[0.666667]_9x9_0
2,805,600


qshor[0.833333]_13x13_0
3,869,600


qshor[0.833333]_17x17_0
3,883,200


qshor[0.833333]_21x21_0
3,913,400


qshor[0.833333]_9x9_0
3,861,400


surface_13x13
2,004,800


surface_17x17
2,004,800


surface_21x21
2,004,800


surface_9x9
2,004,800


zstackedshor[h11]_11x11_0
612,250


zstackedshor[h1]_11x11_0
200,000


zstackedshor[h1]_1x11_0
200,000


zstackedshor[h1]_1x5_0
200,000


zstackedshor[h1]_1x7_0
200,000


zstackedshor[h1]_1x9_0
200,000


zstackedshor[h1]_5x5_0
200,000


zstackedshor[h1]_7x7_0
200,000


zstackedshor[h1]_9x9_0
200,000


zstackedshor[h2]_11x11_0
200,200


zstackedshor[h2]_5x5_0
200,200


zstackedshor[h2]_7x7_0
200,200


zstackedshor[h2]_9x9_0
200,200


zstackedshor[h3]_11x11_0
200,200


zstackedshor[h3]_5x5_0
200,200


zstackedshor[h3]_7x7_0
200,200


zstackedshor[h3]_9x9_0
200,200


zstackedshor[h5]_5x5_0
700,000


zstackedshor[h7]_7x7_0
700,000




For the surface code ML database:




code family
samples




surface_101x101
40,000


surface_13x13
1,599,200


surface_151x151
40,000


surface_17x17
1,599,200


surface_201x201
40,000


surface_21x21
1,599,200


surface_23x23
1,600,000


surface_251x251
40,000


surface_25x25
1,600,000


surface_27x27
1,600,000


surface_29x29
1,600,000


surface_33x33
1,600,000


surface_37x37
1,600,000


surface_45x45
2,000,000


surface_53x53
2,000,000


surface_61x61
2,000,000


surface_69x69
2,000,000


surface_9x9
1,599,380




Sample queries:



to find the number of samples above:


select code_id, theta_phys, count(*) from logical_angle_samples group by code_id, theta_phys order by theta_phys asc;




to find the number of samples per datapoint for surface codes


select code_id, theta_phys, count(*) from logical_angle_samples group by code_id, theta_phys having code_id like 'surface%' order by theta_phys asc ;




to query data underlying the plots for infidelity metrics for the d=9 qshor=5/6 compass codes:


select * from qshor_loaf where code_id like 'qshor%0.83%9x9%';


Database schema

-- code families are the roots of parametrized code hierarchies, e.g. surface, qshor. The convention is to also use the code_family as table names describing the parametrized members.  
CREATE TABLE CODE_FAMILIES(CODE_FAMILY, UNIQUE(CODE_FAMILY));
-- surface code members. Technically possible to create non-square surface codes, but in this paper we only explored square ones. 
CREATE TABLE SURFACE(CODE_ID, DX, DZ, UNIQUE(CODE_ID));
-- families of qshor (x check density) parametrized random compass codes. 
CREATE TABLE qshor(CODE_ID, QSHOR, DX, DZ, UNIQUE(CODE_ID));

--the main samples table, for a given code, and physical rotation angle the logical rotation angle is recorded
CREATE TABLE LOGICAL_ANGLE_SAMPLES(CODE_ID,THETA_PHYS TEXT, THETA_LOGICAL TEXT);

-- diamond distance metrics aggregated from the logical angle samples table for qshor
CREATE TABLE qshor_dd(code_id, theta_phys, mean, std, num_records);
-- loss of average fidelity metrics aggregated from the logical angle samples table for qshor
CREATE TABLE qshor_loaf(code_id, theta_phys, mean, std, num_records);

-- diamond distance metrics aggregated from the logical angle samples table for surface codes
CREATE TABLE surface_dd(code_id, theta_phys, mean, std, num_records);
-- loss of average fidelity metrics aggregated from the logical angle samples table for surface codes
CREATE TABLE surface_loaf(code_id, theta_phys, mean, std, num_records);

CREATE TABLE pub.zstackedshor(CODE_ID, ZSHOR_HEIGHT, DX, DZ, UNIQUE(CODE_ID));
CREATE TABLE pub.zstackedshor_loaf(code_id, theta_phys, mean, std, num_records);
CREATE TABLE pub.zstackedshor_loaf_ml(code_id, theta_phys, mean, std, num_records);


-- ML decoder version 
CREATE TABLE qshor_dd_ml(code_id, theta_phys, mean, std, num_records);
CREATE TABLE qshor_loaf_ml(code_id, theta_phys, mean, std, num_records);
CREATE TABLE surface_dd_ml(code_id, theta_phys, mean, std, num_records);
CREATE TABLE surface_loaf_ml(code_id, theta_phys, mean, std, num_records);


Plots

Make sure that you have the data under data/codes.db - this needs to be a SQLite database. See the previous section on how to create it from the published data.

Plots are generated under the folder figures. There are separate entry points for each figure in the paper:



combined thresholds in the appendix resulting in figures/threshold_plot-combined_full.pdf and figures/threshold_plot-combined_zoom.pdf:


python cicc/plot/combined_threshold.py




the main plot containing the manually extracted thresholds for the random compass codes and the surface code:


python cicc/plot/qshor_family.py




the QCE2024 poster / extended abstract plots


python cicc/plot/qce2024_figures.py




the repetition code and Z-stacked Shor code plots matching the formulae plots


python cicc/plot/zstack_zshor_thresholds.py


A note on angle conventions

All rotations in this project are around the Z-axis. There are two ways one can interpret the rotation angle based on the unitary rotation:



spin angles: Rz(theta_spin) = exp(-i theta_spin/2 Z)

direct angles: Rz(theta_direct) = exp(i theta_direct Z)


Thus, for the same rotation unitary, theta_spin = - 2 * theta_direct. The paper by Bravyi, Engelbrecht, Konig and Peard [^bravyi2018] for the rotated surface code uses the direct angles convention, and similarly, msim uses direct angles. However, this paper uses spin angles closer to the physics convention.

[^bravyi2018]:Bravyi, Sergey, Matthias Englbrecht, Robert König, and Nolan Peard, ‘Correcting Coherent Errors with Surface Codes’, Npj Quantum Information, 4.1 (2018), 55 https://doi.org/10.1038/s41534-018-0106-y

The table below summarizes the angle conventions in different parts of the codebase to avoid confusion:




Place
convention




physical angles for the samplers in this project
direct angles / pi


msim simulator
direct angles


msim coeffs framework
spin angles


database logical angles
direct angles


database physical angles
direct angles


plots
spin angles / pi




Generating your own data

Random Compass Codes

Generating data for random compass codes for a given set of qshor values, distances and physical theta values:

 python cicc/sample_angles/qshor_angles.py --help
usage: qshor_angles.py [-h] [--db DB] --dz DZ --q Q --theta_phys THETA_PHYS [--num_runs NUM_RUNS]

options:
  -h, --help            show this help message and exit
  --db DB               database file
  --dz DZ               code Z distance
  --q Q                 Qshor probability metric
  --theta_phys THETA_PHYS
                        physical rotation (direct angles) divided by pi
  --num_runs NUM_RUNS   number of iterations: the total number of samples, which is divided across sqrt(num_runs) randomly generated codes


For example:

python cicc/sample_angles/qshor_angles.py --dz "[9, 13, 17, 21]" --theta_phys="np.linspace(0.01,0.25, 10)" --qshor="[1/6, 2/6, 3/6, 4/6, 5/6]"


Surface code

Generating data for the rotated surface code:

python cicc/sample_angles/rsc_angles.py --help
usage: rsc_angles.py [-h] [--db DB] --dz DZ --theta_phys THETA_PHYS [--batch_size BATCH_SIZE] [--num_workers NUM_WORKERS] [--num_runs NUM_RUNS]

options:
  -h, --help            show this help message and exit
  --db DB               database file
  --dz DZ               code Z distance
  --theta_phys THETA_PHYS
                        physical rotation (direct angles) divided by pi
  --batch_size BATCH_SIZE
                        batch size for writing to the db
  --num_workers NUM_WORKERS
                        parallelism
  --num_runs NUM_RUNS   number of iterations: the total number of samples


For example

python cicc/sample_angles/rsc_angles.py --dz "[5, 9, 13, 17, 21, 25, 29]" --theta_phys="np.linspace(0.01,0.25, 10)"


Repetition codes

Generating data for the repetition codes:

python cicc/sample_angles/repcodes_angles.py --help
usage: repcodes_angles.py [-h] [--db DB] --dz DZ --theta_phys THETA_PHYS [--num_runs NUM_RUNS] [--batch_size BATCH_SIZE]

options:
  -h, --help            show this help message and exit
  --db DB               database file
  --dz DZ               code Z distance
  --theta_phys THETA_PHYS
                        physical rotation (direct angles) divided by pi
  --num_runs NUM_RUNS   number of iterations: the total number of samples
  --batch_size BATCH_SIZE
                        batch size


For example

python cicc/sample_angles/repcodes_angles.py --dz "[5,7,9,11]"  --theta_phys "list(reversed(list(np.linspace(0.04,0.18,20))))"  --num_runs 10000


Z-stacked Shor codes

Generating data for the repetition codes:

python cicc/sample_angles/repcodes_angles.py --help
usage: zstacked_shor_angles.py [-h] [--db DB] --dz DZ [--height HEIGHT] [--zshor ZSHOR] --theta_phys THETA_PHYS [--num_runs NUM_RUNS] [--batch_size BATCH_SIZE]

Sample angles for ZStackedShor codes. Example usage: 
Run 10,000 samples for height-2 and height-3 ZStackedShor codes with Z distance 3, 5, and 7, and angles 0.1, 0.15, and 0.17: 
python -m cicc.sample_angles.zstacked_shor_angles --dz '[3,5,7]' --height [2,3] --theta_phys '[0.1,0.15,0.17]' --num_runs 10000 --batch_size 10 

Run 10,000 samples for Z-Shor codes with Z distance 3, 5, and 7, and angles 0.1, 0.15, and 0.17: 
python -m cicc.sample_angles.zstacked_shor_angles --dz '[3,5,7]' --zshor --theta_phys '[0.1,0.15,0.17]' --num_runs 10000 --batch_size 10 

Run 10,000 samples for X-Shor codes with Z distance 3, 5, and 7, and angles 0.1, 0.15, and 0.17: 
python -m cicc.sample_angles.zstacked_shor_angles --dz '[3,5,7]' --height 1 --theta_phys '[0.1,0.15,0.17]' --num_runs 10000 --batch_size 10

options:
  -h, --help            show this help message and exit
  --db DB               database file
  --dz DZ               code Z distance
  --height HEIGHT       height of the Z-Shor code block
  --zshor ZSHOR         Z-shor code - Z-Shor height equals to dz
  --theta_phys THETA_PHYS
                        physical rotation (direct angles) divided by pi
  --num_runs NUM_RUNS   number of iterations: the total number of samples
  --batch_size BATCH_SIZE
                        batch size


Regenerating aggregated statistics

In the combined plot (cicc/plot/combined_threshold.py), by default, the already computed statistics are plotted. Hence, when new data is generated, these need to be recalculated. In cicc/plot/combined_threshold.py there is a section that can be modified to trigger the required recalculation (slow):

    recompute(
        conn,
        # set to True to recompute qshor statistics 
        recompute_qshor=False, 
        # set to True to recompute surface code statistics 
        recompute_rsc=False,
        # set to True to recompute qshor statistics with ML decoding 
        recompute_ml_qshor=False,
        # set to True to recompute surface code statistics with ML decoding
        recompute_ml_rsc=False,
    )