Long-Range Parity

Tools for generating and analyzing quantum error correction circuits for the paper "Stairway Codes: Floquetifying Bivariate Bicycle Codes and Beyond".

Installation

Prerequisites

• Python 3.10 or higher
• pip package manager

Setup Virtual Environment

It's recommended to use a virtual environment to avoid dependency conflicts:

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
# On macOS/Linux:
source venv/bin/activate

# On Windows:
# venv\Scripts\activate

Basic Installation

# Install everything
pip install -e ".[all]"

Usage

These are the operations required for reproducing the paper's result. Use the --help option for advanced use.

Plots are generated using the jupyter notebooks in notebooks directory.

0. Generate data for scan

This is used to generate sets of periodicity vectors ($\Lambda'$) for scanning. The showcased codes from the paper are already available in the repo under out/scanning/showcased_codes.csv.

python ./tools/generate_scanning_data.py \
   --d1 4 \
   --d2 6 \
   --output_dir ./out/scanning/

1. Scan Distance for Pairwise 2BGA Codes

Analyze embedded code distance properties. Should use Gurobi if installed (recommended).

python ./tools/scan_distance.py \
    --file ./out/scanning/showcased_codes.csv \
    --filter "index < 200" \
    --time_limit 100 \
    --params k d1 d2 d3

Scanning Options

• --file: Path to input CSV file
• --filter: Pandas query string to filter results
• --time_limit: Time limit for ILP calculation (default: 100)
• --params: Parameters to compute (choices: n, k, d1, d2, d3)
• --cores: Number of CPU cores to use
• --no_logs: Disable logging for better performance

2. Generate Circuits

Generate BB circuits with various configurations:

Stairway codes memory circuit generation:

python ./tools/make_2BGA_circuits.py \
    --input_file "out/scanning/showcased_codes.csv" \
    --query "index==index" \
    --output_dir out/circuits/showcased_all \
    --noise_model "em3" \
    --p "$p" \
    --rounds -1 #-1 generates d rounds (based on the input file)

BB codes with SEC compiled to pairwise measurements:

python ./tools/make_circuits.py \
    --output_dir out/circuits/BB_pairwise \
    --code_params "$code_param" \
    --p "$p" \
    --rounds "$rounds" \
    --noise_model "em3" \
    --decompose_CNOTs \
    --memory_type "Z"

3. Decode Circuits

Sample and decode circuits. Note that decoding for Stairway codes is resource intensive and requires dividing the load on multiple machines.

python ./tools/decode.py \
    --max_shots 1000 \
    --circuit_files ./out/circuits/showcased_all/*.stim \
    --print_progress \
    --decoder "tesseract_short" \
    --comment "showcased_all"

Decoding Options

• --max_shots: Maximum number of shots to simulate (default: 10)
• --max_errors: Maximum number of errors to collect (default: 100)
• --circuit_files: List of circuit files to decode (supports wildcards)
• --print_progress: Display progress during decoding
• --detect_errors: Detect errors instead of correcting them
• --decoder: Decoder to use (default: 'bposd')
• --output_preamble: Prefix for output files (default: 'output')
• --comment: Additional comment for metadata

4. Scan Circuit Distance

Combined tool that filters CSV data, generates 2BGA circuits, and calculates circuit distance:

python ./tools/scan_circuit_distance.py \
    --file ./out/scanning/showcased_codes.csv \
    --query "index < 50" \
    --p 1e-3 \
    --rounds 2 \
    --noise_model em3 \
    --decoder mip \
    --memory_type both \
    --no_cache \
    --cores 1 \
    --config basic_cell

This tool combines three operations:

1. Reads and filters a CSV file (like scan_distance.py)
2. Generates 2BGA circuits for each filtered row (like make_2BGA_circuits.py)
3. Calculates the circuit distance using a decoder

Circuit Distance Scanning Options

• --file: Path to input CSV file (required)
• --query: Pandas query string to filter results (required)
• --p: Physical error rate for circuit generation (required)
• --rounds: Number of syndrome measurement rounds (required)
• --noise_model: Noise model name to use (required)
• --decoder: Decoder for distance calculation (choices: bposd, bposd_long_bp, tesseract, tesseract_long, tesseract_short; default: bposd)
• --decoder_kwargs: Decoder arguments as comma-separated key=value pairs (e.g., "max_iter=100,bp_method=ms")
• --memory_type: Type of memory experiment (choices: X, Z, both; default: Z)
• --cores: Number of CPU cores to use
• --no_logs: Disable logging for better performance

5. For the hyperbolic floquet circuits from Oscar's repo

python tools/add_noise_hyperbolic.py "out/circuits/hyperbolic_oscar/semi_hyperbolic_floquet_l=2_n=2048_k=66_d=8_basis=Z_num_sub_rounds=42.stim" --noise_model em3 --p 0.005 --output_dir out/hyperbolic_noisy

6. Find Circuit-level Distance for a circuit file

with ILP decoder:

python ./tools/find_circuit_distance.py \
    circuit.stim \
    --decoder mip \
    --decoder-kwargs "time_limit=100" \
    --output-preamble "circuit_distance" \

with bposd or another:

python ./tools/find_circuit_distance.py \
    circuit.stim \
    --decoder bposd \
    --decoder-kwargs "max_bp_iters=5000,osd_order=10" \
    --output-preamble "circuit_distance" \
    --verbose

Project Structure

• src/: Core library code
  • BB.py: BB code implementations
  • stabilizer.py: Stabilizer code utilities
  • circuit_distance.py: Circuit distance calculations
  • decoder_utils.py: Decoder utilities
  • fers_idea/: FERS-related implementations
• tools/: Command-line tools
  • make_circuits.py: Circuit generation
  • make_2BGA_circuits.py: 2BGA circuit generation
  • decode.py: Error correction decoding
  • scan_distance.py: Distance scanning
  • scan_circuit_distance.py: Combined circuit generation and distance calculation
• notebooks/: Jupyter notebooks for analysis and plots
• out/: Output directory for generated files

Output Files

Generated circuits and results are saved in the out/ directory:

• out/circuits/: Generated Stim circuit files (.stim) and metadata (.json)
• out/collection/: Decoding results (CSV format)
• out/fer/: Distance scanning results
• out/circuit_distance/: Circuit distance scanning results
• out/logs/: Log files