toric_code_err

MATLAB code for simulating toric-code stabilizer states under random local Clifford noise and extracting several information-theoretic and logical-order diagnostics. The project uses custom MEX kernels for fast GF(2) linear algebra and for sampling random symplectic transformations, then post-processes the resulting CSV data into publication-style PDF figures.

At a high level, the workflow is:

1. Build the MEX accelerators used throughout the simulations.
2. Run one or more experiment families in computations/.
3. Aggregate the generated CSV files into figures with plot_TC.py.

The core ingredients are:

• toric_ops/: toric-code tableau construction, local checks, and measurement projection.
• noise_model/: single-layer and checkerboard two-layer random 4-qubit Clifford noise.
• mex_linear_algebra/: high-performance GF(2) matrix multiply, rank, and null-space routines.
• random_symplectic/: MEX-backed sampler for random symplectic matrices over GF(2).
• computations/: experiment drivers for each observable.

• MATLAB with a working MEX toolchain.
• MATLAB Parallel Computing Toolbox for the parpool / parfor based experiment drivers.
• Optional: MATLAB Optimization Toolbox for exact medium-size signed-sector matching via intlinprog.
• Optional: Blossom V-style source under mwm_backend/vendor/blossom5 for the production toric_mwpm_mex exact matching backend.
• Python 3 with numpy and matplotlib for figure generation.
• Optional: a SLURM cluster if you want to use the provided run.sh batch scripts as-is.
• Optional on Apple Silicon: Homebrew libomp for OpenMP-enabled MEX builds.

Notes:

• The two-layer noise model in noise_model/uni_noise_2layer.m requires even lattice size L.
• The random symplectic backend is used here for 4-qubit Clifford updates, although the standalone helper supports small symplectic groups more generally.

Build all MEX targets from the repository root:

matlab -batch "compile_all_mex; exit"

This compiles the GF(2) linear algebra kernels, the random symplectic sampler, and the commutation-evaluation helper used by the qCMI and distributional calculations.

Run a small local test job for one observable family:

matlab -batch "cd('computations/uni_perturb_TC'); main('8','1','8'); exit"

That command runs the uni_perturb_TC experiment at lattice size L=8, seed 1, and copy_num=8, then writes a CSV to computations/uni_perturb_TC/data/l8/1.csv.

Generate all figures from the available CSV data:

python3 plot_TC.py

This writes PDF figures to figure/.

Each subdirectory under computations/ contains a main.m driver, an rk_diff.m or equivalent observable definition, and a run.sh batch script.

• uni_perturb_TC: logical-gap style rank defect after two-layer noise and toric-check measurement.
• uni_perturb_TC_signed: phase-aware logical-group difference. It tracks Clifford and measurement signs, applies a toric MWM-style syndrome recovery, and reports both signed and sign-free logical intersections after recovery.
• uni_perturb_TC_R: recovery probability derived from the same rank defect via 2^{-Delta}.
• uni_perturb_TC_coInfo_channel: channel co-information using a toric state coupled to reference qubits.
• uni_perturb_TC_distr_cmi: distributional conditional mutual information extracted from the null space of the check commutation matrix.
• uni_perturb_TC_distr_global: global measurement-outcome entropy size(comMat,1) - rank(comMat).
• uni_perturb_TC_qCMI_0: averaged qCMI for a fixed bipartition geometry.
• uni_perturb_TC_qCMI_0L: qCMI as a function of subsystem separation at fixed p = 0.41.
• uni_perturb_TC_op_distr: distribution of emergent logical operator groups, stored as Pauli-string labels.

Most drivers scan p = 1/64, 2/64, ..., 1 and average over many Monte Carlo copies. The batch scripts in this repository are configured for larger cluster runs, typically over L in {8,16,32,64} and multiple seeds.

For local development, it is easiest to call main(...) directly from MATLAB or via matlab -batch with a reduced copy_num.

Examples:

matlab -batch "cd('computations/uni_perturb_TC_R'); main('8','1','8'); exit"
matlab -batch "cd('computations/uni_perturb_TC_qCMI_0L'); main('8','0.41','1','8'); exit"

For cluster execution:

• Each computations/*/run.sh submits one experiment family with sbatch.
• run_all.sh walks over every computation directory and launches its run.sh.
• The SLURM resource requests are cluster-specific and should be reviewed before reuse on another system.

Generated outputs follow a simple convention:

• Numerical results: computations/<experiment>/data/.../*.csv
• Scheduler logs: computations/<experiment>/output_files/
• Figure exports: figure/*.pdf

Probability-resolved datasets use folder names such as l32p0.45, while size-only sweeps use names such as l32.

The .gitignore currently excludes **/data/ and **/output_files/, so fresh clones should treat those folders as generated artifacts.

.
├── compile_all_mex.m
├── toric_setup_paths.m
├── plot_TC.py
├── run_all.sh
├── toric_ops/
├── noise_model/
├── mex_linear_algebra/
├── random_symplectic/
├── bin/
└── computations/

Key entry points:

• compile_all_mex.m: builds every MEX target needed by the repo.
• toric_setup_paths.m: adds shared code and compiled binaries to the MATLAB path.
• plot_TC.py: rebuilds the paper-style figures from CSV outputs.

• mex_linear_algebra/README.md documents the GF(2) MEX kernels in more detail.
• random_symplectic/README.md explains the symplectic sampler and its standalone tests.

If you want to work with the low-level MATLAB functions directly, start MATLAB in the repository root and run:

toric_setup_paths

That adds the toric helpers, noise models, and compiled MEX binaries to the path for the current session.

Run the signed-tableau regression tests with:

matlab -batch "toric_setup_paths; addpath('computations/uni_perturb_TC_signed'); addpath('tests'); test_signed_stabilizer"

The unsigned toric-code workflow can run end-to-end simulations above 10,000 physical qubits. Since the model contains N = 2L^2 qubits, the default capacity test uses L=72, or N=10,368. It exercises state construction, nonzero two-layer Clifford noise, toric-check projection, and the production logical-rank observable.

Run the rigorous capacity suite from the repository root:

matlab -batch "addpath('tests'); test_10k_qubit_simulator"

The default suite tests p = 0.10, 0.25, and 0.50. For every realization it verifies all 10,368 toric checks, full stabilizer rank, sampled pairwise stabilizer commutation, native backends, and agreement with the production observable on a deterministic control case. On one Windows/MATLAB R2026a workstation the three default cases completed in about 277 seconds; the p=0.50 stress case accounted for about 239 seconds. Timings are hardware-dependent, and additional memory beyond the approximately 0.20 GiB dense tableau is required for rank evaluation.

Custom probability and seed sweeps are also supported:

matlab -batch "addpath('tests'); test_10k_qubit_simulator(72,[0.1,0.25,0.5],[11,29])"

This capacity claim refers to the unsigned uni_perturb_TC logical-rank simulation path. The phase-aware signed decoder has different memory and backend requirements.