Add an example notebook for decoding tqec circuits

[HaoTy]

Addresses #402.

MWPM doesn't compile correctly. BP-OSD works, so I tend to think the issue is on the qLDPC side or due to an incompatibility between tqec and qLDPC. @perlinm could you take a look at the MWPM error?

[perlinm]

IIRC we also had issues with tqec returning non-matchable circuits in arXiv:2511.20947, for which we also needed to use BP-OSD at some point.

I'll take a look at the error, and meanwhile also see whether we can reproduce our old tqec/matching issue with @jmusullivan .

[HaoTy]

Yeah I also recall, but I don't remember what caused it and how we solved it.

This issue might be different, as the default pymatching in sinter works fine.

[perlinm]

It's possible that the default pymatching in sinter simply ignores non-graphlike errors. That's what oscarhiggott/PyMatching does if you call Matching.from_detector_error_model instead of Matching.from_check_matrix.

[HaoTy]

Interesting, I see.

[perlinm]

Yep, looks like the notebook runs fine (and shows reasonable results) if I run with

custom_decoders = {
    f"{d=}": decoders.SlidingWindowDecoder(
        d,
        d // 2,
        with_MWPM=True,
        ignore_non_graphlike_errors=True,
    )
    for d in distances
}

I flagged this in tqec/tqec#913.

[perlinm]

Let's go ahead and set ignore_non_graphlike_errors=True for now. Otherwise this looks good to me! I can make minor tweaks for language/style in a follow-up PR.

[perlinm]

I do not understand the installation error in the failed check:

Run uv sync --extra dev
  uv sync --extra dev
  shell: /usr/bin/bash -e {0}
  env:
    UV_PYTHON_INSTALL_DIR: /home/runner/work/_temp/uv-python-dir
    UV_PYTHON: 3.12
    UV_CACHE_DIR: /home/runner/work/_temp/setup-uv-cache
Using CPython 3.12.3 interpreter at: /usr/bin/python3.12
Creating virtual environment at: .venv
Resolved 209 packages in 691ms
error: Distribution `stim==1.16.dev1776477515 @ registry+[https://pypi.org/simple`](https://pypi.org/simple%60) can't be installed because it doesn't have a source distribution or wheel for the current platform

hint: You're using CPython 3.12 (`cp312`), but `stim` (v1.16.dev1776477515) only has wheels with the following Python ABI tag: `cp310`
Error: Process completed with exit code 2.

The checks clearly worked for other recent PRs, which used the same github workflow files...

[perlinm]

One minor request

[HaoTy]

I do not understand the installation error in the failed check:

Run uv sync --extra dev
  uv sync --extra dev
  shell: /usr/bin/bash -e {0}
  env:
    UV_PYTHON_INSTALL_DIR: /home/runner/work/_temp/uv-python-dir
    UV_PYTHON: 3.12
    UV_CACHE_DIR: /home/runner/work/_temp/setup-uv-cache
Using CPython 3.12.3 interpreter at: /usr/bin/python3.12
Creating virtual environment at: .venv
Resolved 209 packages in 691ms
error: Distribution `stim==1.16.dev1776477515 @ registry+[https://pypi.org/simple`](https://pypi.org/simple%60) can't be installed because it doesn't have a source distribution or wheel for the current platform

hint: You're using CPython 3.12 (`cp312`), but `stim` (v1.16.dev1776477515) only has wheels with the following Python ABI tag: `cp310`
Error: Process completed with exit code 2.

The checks clearly worked for other recent PRs, which used the same github workflow files...

This is due to the workflow trying to install stim==1.16.dev1776477515, which is the latest pre-release on PyPI (https://pypi.org/project/stim/1.16.dev1776477515/, 2 days ago) and doesn't have a wheel for 3.12, whereas previously the workflow installed earlier versions of stim that had wheels.

Do you want to place an upper bound on stim for now?

[perlinm]

Yeah, I think it would be okay to bound or pin the version of Stim for now.

[perlinm]

Could we tackle #402 here? Maybe have one example with ordinary decoding and an identical example switching out the decodr, hopefully showing similar logical error rates.

I'd be happy to punt it to a future PR if it's significantly more work than expected.

[HaoTy]

Could we tackle #402 here? Maybe have one example with ordinary decoding and an identical example switching out the decodr, hopefully showing similar logical error rates.

I'd be happy to punt it to a future PR if it's significantly more work than expected.

It's easy to add, but the ordinary decoding doesn't need to simulate separately for each distance, so the code reuse/repetition won't be very elegant.

[perlinm]

What do you mean by

the ordinary decoding doesn't need to simulate separately for each distance

?

Each distance corresponds to a different circuit, and in turn a different simulation+decoding problem, no?

[HaoTy]

What do you mean by

the ordinary decoding doesn't need to simulate separately for each distance

?

Each distance corresponds to a different circuit, and in turn a different simulation+decoding problem, no?

Ah, my phrasing was confusing. I meant that because tqec's simulation interface doesn't support assigning decoders by distance, sliding window decoding needs to call it for each distance, whereas ordinary decoding only needs to call it once for all distances. Anyway, you can take a look at my last commit.

[perlinm]

Looks like there was a bona-fide bug in the sliding window decoder, which was preventing it from working in this example. I pushed a fix, so the example now works! So this PR fixes #402

I'll leave ignore_non_graphlike_errors=True in place for now, and flag it for removal in #462.

I now just need to do some final review + cleanup (including a new unit test) before merging.

changes complete

[perlinm]

@HaoTy thanks again for drafting the notebook! I took a detailed pass over it. I have just two outstanding questions regarding missing documentation in tqec that I would like to explain here before merging. Can you please take a look if+when you get the chance?

[perlinm]

Alright, looks good to merge!

@jviszlai I'll note that the sliding window decoder does not perform as well as one might hope on the CNOT experiment in the example notebook here. Any idea as to why that might be? One thought is that the sliding window decoder was written with a memory experiment in mind, so maybe it's not quite doing what one would like for a lattice surgery experiment involving multiple surface code patches.