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:

For the surface code ML database:

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:

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