Quantum Playground

A notebook laboratory for learning quantum error correction, tensor-network simulation, fault-tolerant compilation, and quantum algorithms by building small things and checking them carefully.

This is deliberately a playground, not a production package. It is a collection of teaching notebooks, numerical experiments, benchmarks, and proofs of concept that I use to turn papers and ideas into working code. Some notebooks are polished end-to-end studies; others preserve the exploratory route that got me there.

If you are here for a quick tour, start with the three case studies below. Together they tell the main story of the repository: implement encoded operations, validate them with independent models, then carry the resulting workloads towards fault-tolerant resource estimates.

flowchart LR
    A["Physics model or logical circuit"] --> B["Encoded operation"]
    B --> C["Independent simulation and decoding"]
    C --> D["Logical observables and error rates"]
    D --> E["Clifford + T compilation"]
    E --> F["Resource trade-offs and limitations"]

Loading

Three flagship case studies

1. A logical CNOT built from lattice surgery

Question. Can a measurement-based logical CNOT be implemented on surface-code patches and checked against the exact two-qubit operation?

What is built. The lattice-surgery notebook prepares logical states as matrix-product states, performs the M_ZZ → M_XX → M_Z measurement sequence, tracks the classical by-products, and compares the corrected logical correlators with a dense two-qubit reference.

Key finding. The corrected gadget reproduces the reference CNOT on the tested logical basis states and creates the expected Bell correlations after H₁ followed by CNOT₁→₂. The exercise also makes an easy-to-miss point concrete: the measurement outcomes are not bookkeeping noise—the conditional Pauli corrections are part of the gate.

Limitations. This is a small, idealised tensor-network demonstration, not a hardware-ready lattice-surgery schedule. It does not establish a threshold, include a complete circuit-level noise model, or price routing, concurrent syndrome extraction, feed-forward latency, and physical control.

Reproduce from the Julia project directory:

cd Playground/Surface-Codes/Itensor
julia --project=. -e 'using Pkg; Pkg.instantiate()'
julia --project=. -e 'using IJulia; IJulia.installkernel("Julia 1.12", "--project=@.")'
jupyter nbconvert --to notebook --execute --inplace \
  --ExecutePreprocessor.timeout=1200 \
  05.Lattice-Surgery/example_lattice_surgery_cnot.ipynb

2. Exact MPS simulation versus high-throughput QEC sampling

Question. When should a fault-tolerant circuit be simulated as an exact matrix-product state, and when is a stabiliser-rank sampler the better tool?

What is built. The head-to-head notebook compares two independent implementations of the same small non-Clifford QEC story:

flowchart TB
    A["Clifford + T logical workload"] --> B["ITensor MPS<br/>exact state and observables"]
    A --> C["Tsim + Stim geometry<br/>sampled detector events"]
    C --> D["PyMatching<br/>MWPM decoder"]
    B --> E["Logical correlators and error trends"]
    D --> E
    E --> F["Cross-check physics; compare scaling regimes"]

Loading

The Julia path propagates the physical MPS and reads exact observables. The Python path uses Stim-compatible circuits, bloqade-tsim sampling, and PyMatching decoding.

Key finding. The two stacks agree on the trend and scale of the logical error rate and on the non-Clifford magic-Bell correlators. In the recorded laptop run, the sampler delivered about 39,000 shots/s versus about 0.95 shots/s for the MPS workflow. That number is a machine- and workload-specific benchmark, not a universal speed claim. The useful conclusion is structural: the MPS method is limited by entanglement and code distance but handles T gates naturally; the stabiliser-rank method scales gently in the Clifford body but pays for independent magic.

Limitations. The two paths use related rather than bit-for-bit identical circuits and decoders, and the MPS timings are loaded from a cached benchmark. The comparison is most credible as a cross-check of trends and as a map of complementary use cases—not as a vendor benchmark.

Reproduce the public Python path:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
cd Playground/Surface-Codes/Itensor
jupyter nbconvert --to notebook --execute --inplace \
  --ExecutePreprocessor.timeout=1200 \
  09.tsim/example_tsim_vs_itensor.ipynb

The companion walkthrough is a gentler introduction to detector error models, decoding, magic-state injection, and threshold-style sweeps.

3. From a Hubbard Hamiltonian to fault-tolerant resource trade-offs

Question. How do modelling and compiler choices propagate into the Clifford+T cost of simulating an interacting fermion system?

What is built. The Hubbard compilation study maps a one-dimensional open-boundary Hubbard model through:

1. a Jordan–Wigner transformation, independently checked against a Fock-space Hamiltonian;
2. first-, second-, and fourth-order product-formula schedules at fixed final evolution time;
3. exact symbolic merging of commuting Pauli rotations;
4. deterministic ancilla-free Ross–Selinger synthesis; and
5. an ancilla-assisted Hamming-weight-phasing estimate.

Key finding. For the small audit case, the Jordan–Wigner Hamiltonian matches the independent Fock-space construction to numerical precision and the symbolic rewrite preserves the unitary. Across the fixed schedules, Hamming-weight phasing reduces the reported T count by roughly 6–18%, but introduces work and parity ancillas. The notebook therefore treats “lower T count” as a trade-off, not a free improvement.

Limitations. These are compiler-level resource estimates. Fixed schedules are not the same as fixed achieved simulation error, and T count alone omits code distance, logical failure budgets, magic-state throughput, routing, factory footprint, and spacetime volume. The largest study points are symbolic counts rather than state-vector simulations.

Reproduce:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
cd Playground/Surface-Codes/Itensor/13.Compilation
jupyter nbconvert --to notebook --execute --inplace \
  --ExecutePreprocessor.timeout=1200 \
  example_hubbard_compilation_scaling.ipynb

What else is in the lab?

The numbered folders are the development history, not fourteen separate products. The notebook catalogue records the question, maturity, environment, and run profile of every committed study. A shorter mental map is:

• Surface-code foundations: logical states, syndrome extraction, decoding, multiple patches, lattice surgery, noisy circuits, and sliding-window decoding.
• Simulation and architecture: MPS scaling, bloqade-tsim, quantum trajectories, photonic fusion networks, and Pauli-based computation.
• Algorithms and compilation: Hubbard dynamics, phase estimation, PDE-inspired examples, Clifford+T synthesis, and early resource models.

There are rough edges on purpose. In particular, working/ directories, generated solver exports, local datasets, and private working notes are development material and are excluded from version control.

Reproducibility notes

• Run commands from the directories shown above; notebooks use paths relative to their local project.
• The Julia environment is defined by Project.toml and its committed manifest. Julia 1.12 is the reference interpreter.
• requirements.txt covers the open-source Python notebooks used by the flagship studies. The 10.PsiQDK experiments require separate access to PsiQuantum's SDK and are intentionally not presented as one-command public reproductions.
• Cached benchmark data are kept when they are small and explain an expensive run. Machine-specific logs, crash dumps, virtual environments, downloaded papers, large datasets, and generated optimisation models are not.
• Timings in notebooks are observations from one machine. Re-run them before making performance decisions.

Reading and attribution

Downloaded papers are not stored in the repository. The reading list links to arXiv records, journal pages, and software documentation instead. Individual notebooks also cite the work that most directly informed them.

Code and original explanatory text in this repository are available under the MIT licence. Papers, datasets, third-party software, and quoted material remain under their respective owners' terms.

Machine-readable citation metadata are provided in CITATION.cff.

Companion package

A separate package-oriented companion is in development. It will hold the reusable, tested APIs that grow out of selected experiments; this repository will remain the notebook lab and teaching trail behind that work. The two repositories will link to each other once the package is public.

Status

This repository is active learning in public. Expect experiments to move, assumptions to become more explicit, and conclusions to sharpen as I learn more. Issues that point out a physics mistake, a misleading claim, or a broken reproduction step are especially welcome. The lightweight contribution guide explains the boundary between a useful lab improvement and work that belongs in the companion package.