QEC Quantum Error Correction

Documentation

Quantum_Error_Correction

All docs Raw markdown View on GitHub

Quantum_Error_Correction

MATLAB/Octave implementations of small quantum error-correction (QEC) codes and visualization scripts. This repo is a learning project: encode logical states, simulate Pauli errors, measure stabilizer syndromes, correct, decode, and visualize.

Structure

Quantum_Error_Correction/
├── docs/
├── src/       # Core functions for encoding, noise, correction, etc.
├── images/    # Generated pngs
├── examples/  # Scripts that run simulations and produce plots
└── tests/     # Unit tests

Capabilities

  • 3-qubit repetition bit-flip code
  • 3-qubit repetition phase-flip code
  • 9-qubit Shor code single-Pauli recovery
  • 5-qubit perfect code single-Pauli recovery
  • 7-qubit Steane code single-Pauli recovery
  • 3x3 Bacon-Shor subsystem-code Pauli-frame recovery
  • Minimum-weight decoder for 1D repetition-code syndromes
  • Projective stabilizer measurements for +/-1 Pauli observables
  • Independent depolarizing-noise simulations
  • Repeated noisy syndrome measurement simulations with raw syndrome and detector-history outputs
  • Small distance-3 surface-code prototype with X/Z/Pauli code-capacity sweeps and a minimum-weight matching-style decoder
  • Generic odd-distance surface-layout decoder benchmarks for d=3/5/7 with lookup-plus-peeling and bounded graph-search decoder comparisons
  • Monte‑Carlo sweeps and confusion matrices
  • Publication‑quality PNG outputs (saved to images/)

Requirements

or MATLAB R2021b+ (if you have a MathWorks license).

  • GNU Octave (tested in GitHub Codespaces)
  • Standard linear algebra and plotting functionality only.

Quickstart (Codespace / dev container)

Prerequisites

  • GNU Octave (or MATLAB R2021b+)
  • git

Install (Ubuntu)

sudo apt update
sudo apt install -y octave

Run an example

# from repo root
octave --no-gui examples/plot_confusion.m
"$BROWSER" file:///workspaces/Quantum_Error_Correction/images/bitflip_decoder_confusion_matrix.png

Run a minimal text example

octave --no-gui examples/minimal_bitflip_recovery.m

Run the longer surface-code walkthrough

octave --no-gui examples/surface3_walkthrough.m

Run the generic surface-layout distance benchmark

octave --no-gui examples/benchmark_surface_distance_decoder.m
octave --no-gui examples/plot_surface_distance_scaling.m

Override the generic surface-layout benchmark settings

octave --no-gui examples/benchmark_surface_distance_decoder.m -- --trials=200 --seed=7 --ps="0 0.02 0.04" --distances="3 5" --decoders=min_weight,mwpm,graph_matching

Run all text examples

octave --no-gui examples/run_text_examples.m

Run the full local validation set

octave --no-gui tests/run_all_tests.m
octave --no-gui examples/run_text_examples.m
octave --no-gui examples/generate_simulation_report.m
octave --no-gui examples/check_generated_images.m

Run tests

octave --no-gui tests/run_all_tests.m

Load a cloned checkout into the Octave/MATLAB path

octave --no-gui --eval "qec_setup; qec_about"

Build and install the Octave package archive

make package
octave --no-gui --eval "pkg install dist/qec-0.3.0.tar.gz"
octave --no-gui --eval "pkg load qec; qec_about"

Generate a compact simulation report

octave --no-gui examples/generate_simulation_report.m

Regenerate all figures

octave --no-gui examples/run_all_plots.m

Usage

From the repo root in a terminal:

octave --no-gui examples/plot_logical_vs_p.m

Short text examples:

  • examples/minimal_bitflip_recovery.m
  • examples/minimal_phaseflip_recovery.m
  • examples/minimal_fivequbit_recovery.m
  • examples/minimal_steane_recovery.m
  • examples/minimal_shor_recovery.m
  • examples/minimal_bacon_shor_recovery.m
  • examples/minimal_repetition_decoder.m
  • examples/minimal_surface_distance_decoder.m
  • examples/benchmark_surface_distance_decoder.m
  • examples/minimal_surface3_syndrome.m

Longer walkthrough:

  • examples/surface3_walkthrough.m

Example runners:

  • examples/run_text_examples.m
  • examples/check_generated_images.m

Surface-3 Monte Carlo plots cache sweep data under cache/. Delete that directory or set force_cache = true before running a plot script to force regeneration.

Generic surface-layout benchmark scripts also accept QEC_SURFACE_TRIALS, QEC_SURFACE_SEED, QEC_SURFACE_PS, QEC_SURFACE_DISTANCES, and QEC_SURFACE_DECODERS environment overrides.

Each script saves its figure in images/ as a .png. For example, running the plotting scripts produces:

  • images/bitflip_logical_error_vs_physical_error.png
  • images/bitflip_syndrome_distribution.png
  • images/bitflip_decoder_confusion_matrix.png
  • images/bitflip_error_weight_distribution.png
  • images/bitflip_monte_carlo_demo.png
  • images/qec_recovery_failure_by_error_weight.png
  • images/qec_depolarizing_logical_error_comparison.png
  • images/bitflip_noisy_syndrome_rounds.png
  • images/surface3_logical_error_vs_x_error.png
  • images/surface3_channel_logical_error_comparison.png
  • images/surface3_noisy_syndrome_rounds.png
  • images/surface_distance_logical_error_scaling.png

The generated report is written to docs/SIMULATION_REPORT.md.

Tests

Unit tests are in tests/. Run with:

octave --no-gui tests/run_all_tests.m

---

Citation

If you use this repository in a project, cite it as:

Sid Richards (2026). Quantum_Error_Correction: MATLAB/Octave implementations of quantum error-correction codes and simulations.

Author

Sid Richards

License

MIT. See LICENSE.