Logical coherence in 2D compass codes Supplementary Material

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,
)