Added bundled decoder_context struct for measurement extraction

[eliotheinrich]

Description

In order to process enqueued syndromes, the decoder needs access to a measurement map so it knows how to form detectors. Right now, this comes from generate_timelike_sparse_detector_matrix, which does not include boundary detectors.

Rather than refactor this function (which would require it to be aware of the stabilizer structure of the code), I include the m2d map calculated by dem_from_kernel, and bundle it into a new struct decoder_context, and provide a new helper function decoder_context_from_memory_circuit with a similar signature to dem_from_memory_circuit, which it essentially supersedes. This new function returns the DEM as well as the measurement map needed by the decoder. The decoder_context struct also provides helper methods for extracting the X/Z components, alleviating the need for helper functions (in the style of *_dem_from_memory_circuit) as well as allowing a single circuit analysis to provide both the X and Z decoder contexts.

The PR also applies some changes to the real_time_complete documentation examples to use this function.

New tests:
test_dem.py::test_decoder_context_from_memory_circuit_requires_noise_model - asserts a throw on the decoder_context_from_memory_circuit if no noise model is provided
test_dem.py::test_decoder_context_and_components - asserts that decoder_context_from_memory_circuit matches output of superceded *_dem_from_memory_circuit
test_dem.py::test_decoder_context_d_sparse_layout() - asserts that .d_sparse() on decoder_context flattens m2d map into correct -1-terminated sparse vector
test_dem.py::test_decoder_context_single_type_code_empty_component - check that empty component (i.e. x-component of a repetition code) is consistent
test_qec_stim.cpp::checkTealtimeDecodeFromMemoryCircuit - end-to-end check of realtime API using decoder_context
test_qec_stim.cpp::checkDecoderContextAndComponents - Verify DEM output by decoder_context_from_memory_circuit matches superseded *_dem_from_memory_circuit, and that extracting x/z components is idempotent and consistent.

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.

[melody-ren]

Thanks @eliotheinrich! This a great upgrade to the decoder interface. I have some comments regarding API and performance. Please see inline comments.

Probably out of scope for this PR given the timeframe, I think we can consider deprecating the legacy APIs.

[bmhowe23]

The PR introduces two related types whose names make the relationship harder to follow than it needs to be in my opinion:

• decoder_context - the result struct (dem + m2d + m2o), returned by component methods
• decoder_context_handle - the lazy factory returned by decoder_context_from_memory_circuit; call .x/z/full_component() to get a decoder_context

A few specific issues:

1. Python class is named DecoderContext, not DecoderContextHandle (py_code.cpp:534)
   In Python, DecoderContext is what C++ calls decoder_context_handle - the lazy factory, not the final result. The C++ decoder_context struct has no Python binding (component methods return tuples). So Python users see DecoderContext as the object with .x/z/full_component() methods, which reads as "this is the context" when it's really "this is the thing that produces contexts." Either name the Python class DecoderContextHandle to match C++, or flip the naming so the more user-facing object (the handle) gets the simpler name.

2. Stray term memory_circuit_handle in two test comments
   test_qec_stim.cpp:854 and test_dem.py:684 both say "decoder_context_from_memory_circuit returns a memory_circuit_handle" - a type that doesn't exist in the API. Should say decoder_context_handle.

3. Possible naming inversion to consider
   If the intent is that users mostly interact with the factory object (decoder_context_from_memory_circuit(...)) and rarely hold a decoder_context directly, it might read more naturally to give the factory the simpler name (decoder_context) and add a suffix to the result struct (decoder_inputs, decoder_config, or canonicalized_decoder_context). As written, the prominent user-facing object has the longer name with _handle, while the plain data struct has the cleaner name.

[eliotheinrich]

Good points, thank you Ben; I went with calling the factory object the decoder_context, and the returned struct a decoder_input (and fixed the stale comments) in edf1b2c.

[bmhowe23]

Thanks, Eliot,