Add boundary-aware overloads for canonicalize_for_rounds and sliding window decoder

[eliotheinrich]

Description

Closes #649

The addition of boundary detectors offsets the syndromes output by memory circuit experiments by introducing num_boundary_syndromes at the beginning and end of the syndrome block. The means that canonicalize_for_rounds straddles the new boundaries between rounds, leading to error mechanisms being associated to incorrect rounds when the boundary syndromes have a different length than the inter-round syndromes. This is a cosmetic error for PCMs representing entire memory circuits, but is incorrect when followed up with get_pcm_for_rounds for the purpose of, i.e., the sliding window decoder.

This PR adds round-aware overloads to canonicalize_for_rounds and the sliding window decoder, bringing them up-to-date with syndrome format.

canonicalize_for_rounds has a new overload which accepts num_boundary_syndromes, which appropriately treats the first and last num_boundary_syndromes columns as distinct rounds for the purpose of round-based topological sorting.

The sliding window decoder now takes an additional parameter num_boundary_syndromes (default 0). The PCM of the decoder is zero-padded to have uniform width num_syndromes_per_round. Syndromes passed to the decoder are automatically padded to the uniform length. If num_boundary_syndromes is 0, then the boundary syndromes are presumed to be the same width as the interior syndromes (as is the case in X/Z-only experiments).

New tests:

test_qec.cpp:PCMUtilsTester.checkGetSortedColumnIndicesWithBoundary: Verifies the boundary-aware column sort orders
test_qec.cpp:DetectorErrorModelTest.CanonicalizeBoundaryRejectsWideBoundary: Assertrs canonicalize_for_rounds(S, B, ...) throws when the boundary is wider than the interior (B > S).
test_decoders.cpp::SlidingWindowDecoder.PreparePcmRejectsBadBoundaryLayout: Confirms the sliding-window decoder throws during construction for inconsistent boundary layouts (B > S, or a row count that can't fit [B | K·S | B]).
test_qec_stim.cpp::QECCodeTester.checkDemFromMemoryCircuitShor9: Checks the Shor [[9,1,3]] full DEM has the expected non-uniform shape, consistent column counts, and correct round ordering.
test_qec_stim.cpp::QECCodeTester.checkSlidingWindowShor9Boundary: A single all-rounds window decoding the Shor boundary DEM must match a full decoder for every DEM column.
test_qec_stim.cpp:QECCodeTester.checkSlidingWindowShor9Streaming: Streams variable-width detector layers for X(Z) (6(2) at boundaries, 8 interior) through a sliding config (window=2, step=1) and requires results to match a full decoder.
test_sliding_window.py::test_sliding_window_boundary_layout: Parametrized over 3 codes × 3 window counts; injects errors over 300 shots and asserts sliding-window observable predictions match a single_error_lut full decoder.

Runtime / performance impact

N/A

Self-review checklist

Please confirm each item before requesting review. Check [x] or strike
through and explain.

Before requesting review

• I reviewed my own full diff in GitHub or my editor.
• PR is in Draft if it is not yet ready for review.
• Temporary / debugging changes have been removed.
• Local test logs reviewed; no unexplained warnings or errors.
• CI logs reviewed; no unexplained warnings or errors.
• Full CI has been run.

Scope and size

• PR is under ~1000 lines, or an exception is justified in the description.
• Refactoring-only changes are isolated in their own PR(s).
• No existing tests were disabled or modified just to make this PR pass
  (if so, an issue has been raised).

Tests

• New functionality has new tests.
• Tests fail if the new functionality is broken (including crashes), not
  just when it is missing.
• Negative tests added where exceptions are expected.
• Truth data added where simple EXPECT_* / assert checks are
  insufficient for algorithmic correctness.
• CI runtime impact considered; team notified if significant.

Documentation

• Public-facing APIs have Doxygen docs.
• User-visible behavior changes have public docs, or a follow-up is
  tracked.

Code style

• Naming follows the existing convention (snake_case vs camelCase) for
  the area being modified.

Dependencies

• No new third-party dependencies, or the team has been notified and
  OSRB tickets filed.

[bmhowe23]

Can you please move this section to a .cpp file? I don't think it needs to be in a public header file if we are calling it an "internal helper".

[eliotheinrich]

I can, but I deliberately left it accessible here so that the round layout logic can be shared here and in the sliding window decoder (and perhaps other places that may need a mapping between rounds and detector indices): https://github.com/NVIDIA/cudaqx/pull/656/changes#diff-30af01af4513a257ae4040df674193bc2cce9d3ce09e81adc3493db11a0dba4dR60.

Open to moving it to a .cpp file if we'd rather not expose it.

[bmhowe23]

In that case, I'd recommend 2 things.

1. Pull them into a private header file (not in the libs/qec/include directory because that entire directly should only contain our public interfaces that we are committed to maintaining some form of backwards compatibility on). I'd recommend libs/qec/lib.
2. Only put the declarations in header files and put implementations in .cpp files. Implementations in header files can lead to duplicate symbols and general compilation bloat since every target compilation unit must recompile the source code. We should only do that when it is trivial code or needed by for templates.

If you do the above 2 things, I believe the sliding window decoder and other internal code can use it.