Return Python decode result as NumPy arrays (#558)

## Description

Updates Python decoder result access so decoded correction data is
exposed as NumPy arrays instead of Python lists.

This is a breaking Python API change: `DecoderResult.result` now returns
a 1-D NumPy array. This affects:

- `decoder.decode(...).result`
- `decoder.decode_async(...).get().result`
- tuple unpacking of `DecoderResult`
- `decoder.decode_batch(...)[i].result`
- iteration over `BatchDecoderResult`

Existing code that reads, indexes, iterates, or numerically consumes
`result` should generally continue to work. Code that requires `result`
to be an actual Python `list`, mutates it with list APIs, compares it
with list equality, or serializes it directly should migrate to NumPy
semantics or call `.tolist()`.

Also updates `decode_batch(...)` to return `BatchDecoderResult` instead
of `list[DecoderResult]`.

`BatchDecoderResult` exposes vectorized batch fields:

- `result`: 2D NumPy array
- `converged`: 1D NumPy bool array
- `opt_results`: list-like per-shot optional results

Compatibility for existing batch consumers is preserved through
indexing, slicing, `len(...)`, and iteration:

- `batch[i]` materializes a per-shot `DecoderResult`
- `batch[a:b]` returns another `BatchDecoderResult`
- `for r in batch` continues to yield per-shot `DecoderResult` objects

This avoids forcing user code onto the old per-shot Python list
extraction path when the natural batch output is already array-shaped.

Python decoder plugin authors with custom `decode_batch(...)` overrides
must now return `BatchDecoderResult`, not `list[DecoderResult]`.

User-facing Sphinx documentation will be updated in a separate docs PR,
per project guidance that feature docs should not land before release.

## Runtime / performance impact

This change is intended to reduce Python-side result extraction overhead
for batch decoding by allowing users to read batch results directly as
NumPy arrays instead of iterating through a list of `DecoderResult`
objects.

Minibench run on commit `246114b0a33e9a58ff3a96e9abb77ac72e945fd1` using
the C++ `single_error_lut` decoder.

The benchmark uses a CUDA-Q/Stim Steane memory syndrome workload, then
splits the fixed shot set into chunks of `batch_size`. Each timed repeat
loops over all chunks and measures wall-clock time from calling
`decode_batch(...)` through reading the decoded result.

Two current-branch access patterns are compared:

- `numpy_view`: `decoded = decoder.decode_batch(chunk)`, then read
`decoded.result` and `decoded.converged`
- `compat_iteration`: `decoded = decoder.decode_batch(chunk)`, then
iterate `for r in decoded` and read `r.result` and `r.converged` (this
is the backward compatible list access pattern)

Each row reports the median of 5 measured repeats. Speedup is
`compat_iteration median / numpy_view median`.

| shots | batch size | decode_batch calls | result width | NumPy view
median ms | compat iteration median ms | speedup |
| ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| 1000 | 1 | 1000 | 697 | 3.892 | 7.234 | 1.86x |
| 1000 | 32 | 32 | 697 | 1.990 | 4.111 | 2.07x |
| 1000 | 256 | 4 | 697 | 2.399 | 3.936 | 1.64x |
| 3000 | 1 | 3000 | 697 | 11.748 | 21.462 | 1.83x |
| 3000 | 32 | 94 | 697 | 6.040 | 12.162 | 2.01x |
| 3000 | 256 | 12 | 697 | 5.923 | 11.818 | 1.99x |

In this minibench, direct NumPy batch access is about `1.6x-2.1x` faster
than compatibility iteration for the measured `single_error_lut` cases.

---------

Signed-off-by: Melody Ren <melodyr@nvidia.com>

Author: melody-ren

libs/qec/python/bindings/py_decoder.cpp

@@ -18,6 +18,8 @@ def _ensure_cuda_runtime_loaded():
 _ensure_cuda_runtime_loaded()
 del _ensure_cuda_runtime_loaded
 
+import functools
+
 from .patch import patch
 try:
     from ._pycudaqx_qec_the_suffix_matters_cudaq_qec import *
@@ -39,15 +41,51 @@ def _ensure_cuda_runtime_loaded():
 __version__ = qecrt.__version__
 code = qecrt.code
 Code = qecrt.Code
-decoder = qecrt.decoder
+_native_decoder = qecrt.decoder
 Decoder = qecrt.Decoder
+
+
+def decoder(name):
+    """Register a Python class as a decoder plugin under `name`.
+
+    Wraps the native registration decorator so that any user-defined
+    `decode_batch` override is checked at runtime to return a
+    BatchDecoderResult. Returning a list[DecoderResult] (the pre-batch API)
+    is no longer supported.
+    """
+    native = _native_decoder(name)
+
+    def wrap(cls):
+        if "decode_batch" in cls.__dict__:
+            original = cls.decode_batch
+            cls_name = cls.__name__
+
+            @functools.wraps(original)
+            def checked_decode_batch(self, *args, **kwargs):
+                result = original(self, *args, **kwargs)
+                if not isinstance(result, qecrt.BatchDecoderResult):
+                    raise TypeError(
+                        f"{cls_name}.decode_batch must return a "
+                        f"BatchDecoderResult; got "
+                        f"{type(result).__name__}. See BatchDecoderResult "
+                        f"in the cudaq_qec docs for the supported "
+                        f"construction surface.")
+                return result
+
+            cls.decode_batch = checked_decode_batch
+        return native(cls)
+
+    return wrap
+
+
 TwoQubitDepolarization = qecrt.TwoQubitDepolarization
 TwoQubitBitFlip = qecrt.TwoQubitBitFlip
 operation = qecrt.operation
 get_code = qecrt.get_code
 get_available_codes = qecrt.get_available_codes
 get_decoder = qecrt.get_decoder
 DecoderResult = qecrt.DecoderResult
+BatchDecoderResult = qecrt.BatchDecoderResult
 DetectorErrorModel = qecrt.DetectorErrorModel
 generate_random_bit_flips = qecrt.generate_random_bit_flips
 sample_memory_circuit = qecrt.sample_memory_circuit

libs/qec/python/cudaq_qec/__init__.py

@@ -10,6 +10,7 @@
 
 from typing import Any
 import cudaq_qec as qec
+import numpy as np
 
 import numpy.typing as npt
 from quimb.tensor import TensorNetwork
@@ -416,15 +417,17 @@ def decode(
     def decode_batch(
         self,
         syndrome_batch: npt.NDArray[Any],
-    ) -> list["qec.DecoderResult"]:
+    ) -> "qec.BatchDecoderResult":
         """Decode a batch of detection events.
 
         Args:
             syndrome_batch (np.ndarray): A numpy array of shape (batch_size, syndrome_length) where each row is a detection event.
 
         Returns:
-            list[qec.DecoderResult]: list of results for each detection event in the batch.
-                The probabilities that the logical observable flipped for each syndrome.
+            qec.BatchDecoderResult: batched results for each detection event in
+                the batch. The `result` field has shape (batch_size, 1) and
+                contains the probabilities that the logical observable flipped
+                for each syndrome.
         """
 
         assert hasattr(self, "noise_model")
@@ -459,16 +462,20 @@ def decode_batch(
             device_id=self.contractor_config.device_id,
         )
 
-        res = []
+        probabilities = []
         for r in range(syndrome_batch.shape[0]):
-            res.append(qec.DecoderResult())
-            res[r].converged = True
-            res[r].result = [
+            probabilities.append(
                 float(contraction_value[r, 1] /
-                      (contraction_value[r, 1] + contraction_value[r, 0]))
-            ]
-
-        return res
+                      (contraction_value[r, 1] + contraction_value[r, 0])))
+
+        # Python `decode_batch` override: construct a BatchDecoderResult
+        # directly, bypassing the native decoder aggregation path. This is
+        # the only sanctioned caller of the BatchDecoderResult constructor;
+        # see its docstring for the supported construction surface.
+        return qec.BatchDecoderResult(
+            np.asarray(probabilities, dtype=np.float64).reshape((-1, 1)),
+            np.ones(syndrome_batch.shape[0], dtype=bool),
+        )
 
     def optimize_path(
         self,

libs/qec/python/cudaq_qec/plugins/decoders/tensor_network_decoder.py

@@ -41,13 +41,41 @@ def test_decoder_api():
     decoder = qec.get_decoder('example_byod', H)
     result = decoder.decode_batch(
         [create_test_syndrome(), create_test_syndrome()])
+    assert isinstance(result, qec.BatchDecoderResult)
     assert len(result) == 2
-    for r in result:
-        assert hasattr(r, 'converged')
-        assert hasattr(r, 'result')
-        assert isinstance(r.converged, bool)
-        assert isinstance(r.result, list)
-        assert len(r.result) == 10
+    assert hasattr(result, 'converged')
+    assert hasattr(result, 'result')
+    assert hasattr(result, 'opt_results')
+    assert isinstance(result.converged, np.ndarray)
+    assert result.converged.shape == (2,)
+    assert isinstance(result.result, np.ndarray)
+    assert result.result.shape == (2, 10)
+    assert len(result.opt_results) == 2
+    assert all(opt is None for opt in result.opt_results)
+    first = result[0]
+    assert isinstance(first, qec.DecoderResult)
+    assert first.converged == result.converged[0]
+    np.testing.assert_array_equal(first.result, result.result[0])
+    assert first.opt_results is None
+    last = result[-1]
+    np.testing.assert_array_equal(last.result, result.result[-1])
+    sliced = result[:1]
+    assert isinstance(sliced, qec.BatchDecoderResult)
+    assert sliced.result.shape == (1, 10)
+    assert sliced.converged.shape == (1,)
+    assert len(sliced.opt_results) == 1
+    iterated = list(result)
+    assert len(iterated) == 2
+    assert all(isinstance(r, qec.DecoderResult) for r in iterated)
+    np.testing.assert_array_equal(iterated[1].result, result.result[1])
+
+    # Empty batch: shape (0, 0); per-shot width is undefined without input.
+    empty_result = decoder.decode_batch([])
+    assert isinstance(empty_result, qec.BatchDecoderResult)
+    assert empty_result.result.shape == (0, 0)
+    assert empty_result.converged.shape == (0,)
+    assert len(empty_result) == 0
+    assert len(empty_result.opt_results) == 0
 
     # Test decode_async
     decoder = qec.get_decoder('example_byod', H)
@@ -59,8 +87,8 @@ def test_decoder_api():
     assert hasattr(result, 'converged')
     assert hasattr(result, 'result')
     assert isinstance(result.converged, bool)
-    assert isinstance(result.result, list)
-    assert len(result.result) == 10
+    assert isinstance(result.result, np.ndarray)
+    assert result.result.shape == (10,)
 
 
 def test_decoder_result_structure():
@@ -72,8 +100,8 @@ def test_decoder_result_structure():
     assert hasattr(result, 'result')
     assert hasattr(result, 'opt_results')
     assert isinstance(result.converged, bool)
-    assert isinstance(result.result, list)
-    assert len(result.result) == 10
+    assert isinstance(result.result, np.ndarray)
+    assert result.result.shape == (10,)
 
     # Test opt_results functionality
     assert result.opt_results is None  # Default should be None
@@ -85,6 +113,107 @@ def test_decoder_result_structure():
     assert result.opt_results is None
 
 
+def test_batch_decoder_result_constructor():
+    result = np.zeros((2, 3), dtype=np.float64)
+    converged = np.array([True, False], dtype=np.bool_)
+    batch_result = qec.BatchDecoderResult(result, converged)
+
+    assert isinstance(batch_result.result, np.ndarray)
+    assert batch_result.result.shape == (2, 3)
+    assert batch_result.converged.tolist() == [True, False]
+    assert batch_result.opt_results == [None, None]
+    assert batch_result[np.int64(0)].converged is True
+    assert batch_result[::2].result.shape == (1, 3)
+    assert np.shares_memory(batch_result[::2].result, batch_result.result)
+
+    empty_result = qec.BatchDecoderResult(np.empty((0, 3), dtype=np.float64),
+                                          np.array([], dtype=np.bool_))
+    assert len(empty_result) == 0
+    assert empty_result.result.shape == (0, 3)
+    assert empty_result.converged.shape == (0,)
+    assert list(empty_result) == []
+    with pytest.raises(IndexError):
+        empty_result[0]
+
+    # Cross-array invariants we still enforce.
+    with pytest.raises(RuntimeError, match="row count must match"):
+        qec.BatchDecoderResult(result,
+                               np.array([True, False, True], dtype=np.bool_))
+
+    with pytest.raises(RuntimeError, match="opt_results length must match"):
+        qec.BatchDecoderResult(result, converged, [None])
+
+    # Rank is enforced by nanobind, surfaced as TypeError.
+    with pytest.raises(TypeError):
+        qec.BatchDecoderResult(np.zeros(3, dtype=np.float64), converged)
+
+    # dtype and contiguity are coerced silently, not rejected.
+    int_result = qec.BatchDecoderResult(np.zeros((2, 3), dtype=np.int32),
+                                        converged)
+    assert int_result.result.dtype == batch_result.result.dtype
+    assert int_result.result.flags.c_contiguous
+
+    f_order = np.asfortranarray(np.zeros((2, 3), dtype=np.float64))
+    assert not f_order.flags.c_contiguous
+    f_result = qec.BatchDecoderResult(f_order, converged)
+    assert f_result.result.flags.c_contiguous
+
+
+def test_python_decoder_batch_preserves_opt_results():
+
+    @qec.decoder("python_opt_results_byod")
+    class PythonOptResultsDecoder:
+
+        def __init__(self, H, **kwargs):
+            qec.Decoder.__init__(self, H)
+            self.H = H
+
+        def decode(self, syndrome):
+            res = qec.DecoderResult()
+            res.converged = True
+            res.result = np.arange(self.H.shape[1], dtype=np.float64)
+            res.opt_results = {
+                "syndrome_weight": int(np.count_nonzero(syndrome)),
+                "tag": "python"
+            }
+            return res
+
+    decoder = qec.get_decoder("python_opt_results_byod", H)
+    batch_result = decoder.decode_batch(
+        [np.zeros(H.shape[0]), np.ones(H.shape[0])])
+
+    assert isinstance(batch_result, qec.BatchDecoderResult)
+    assert batch_result.result.shape == (2, H.shape[1])
+    assert batch_result.converged.tolist() == [True, True]
+    assert batch_result.opt_results[0]["syndrome_weight"] == 0
+    assert batch_result.opt_results[1]["syndrome_weight"] == H.shape[0]
+    assert batch_result[1].opt_results["tag"] == "python"
+
+
+def test_python_decoder_batch_override_must_return_batch_decoder_result():
+
+    @qec.decoder("python_bad_batch_byod")
+    class PythonBadBatchDecoder:
+
+        def __init__(self, H, **kwargs):
+            qec.Decoder.__init__(self, H)
+            self.H = H
+
+        def decode(self, syndrome):
+            res = qec.DecoderResult()
+            res.converged = True
+            res.result = np.zeros(self.H.shape[1], dtype=np.float64)
+            return res
+
+        def decode_batch(self, syndromes):
+            # Pre-batch return shape; the decorator should reject this.
+            return [self.decode(s) for s in syndromes]
+
+    decoder = qec.get_decoder("python_bad_batch_byod", H)
+    with pytest.raises(TypeError, match="must return a BatchDecoderResult"):
+        decoder.decode_batch([np.zeros(H.shape[0]), np.ones(H.shape[0])])
+
+
 def test_decoder_plugin_initialization():
     decoder = qec.get_decoder('single_error_lut_example', H)
     assert decoder is not None
@@ -133,16 +262,16 @@ def test_decoder_plugin_result_structure():
     assert hasattr(result, 'converged')
     assert hasattr(result, 'result')
     assert isinstance(result.converged, bool)
-    assert isinstance(result.result, list)
+    assert isinstance(result.result, np.ndarray)
 
 
 def test_decoder_result_values():
     decoder = qec.get_decoder('example_byod', H)
     result = decoder.decode(create_test_syndrome())
 
     assert result.converged is True
-    assert all(isinstance(x, float) for x in result.result)
-    assert all(0 <= x <= 1 for x in result.result)
+    assert isinstance(result.result, np.ndarray)
+    assert np.all((0 <= result.result) & (result.result <= 1))
 
 
 @pytest.mark.parametrize("matrix_shape,syndrome_size", [((5, 10), 5),
@@ -158,8 +287,8 @@ def test_decoder_different_matrix_sizes(matrix_shape, syndrome_size):
 
     assert len(result) == syndrome_size
     assert convergence is True
-    assert all(isinstance(x, float) for x in result)
-    assert all(0 <= x <= 1 for x in result)
+    assert isinstance(result, np.ndarray)
+    assert np.all((0 <= result) & (result <= 1))
 
 
 # FIXME add this back
@@ -187,7 +316,7 @@ def test_decoder_reproducibility():
     np.random.seed(42)
     convergence2, result2, opt2 = decoder.decode(create_test_syndrome())
 
-    assert result1 == result2
+    np.testing.assert_array_equal(result1, result2)
     assert convergence1 == convergence2
 
 
@@ -338,6 +467,19 @@ def test_single_error_lut_opt_results():
     assert "syndrome_weight" in result.opt_results
     assert "decoding_time" not in result.opt_results  # Was set to False
 
+    batch_result = decoder.decode_batch(
+        [create_test_syndrome(), create_test_syndrome()])
+    assert isinstance(batch_result.result, np.ndarray)
+    assert batch_result.result.shape == (2, H.shape[1])
+    assert isinstance(batch_result.converged, np.ndarray)
+    assert batch_result.converged.shape == (2,)
+    assert len(batch_result.opt_results) == 2
+    for opt_results in batch_result.opt_results:
+        assert opt_results is not None
+        assert "error_probability" in opt_results
+        assert "syndrome_weight" in opt_results
+        assert "decoding_time" not in opt_results
+
 
 def test_decoder_pymatching_results():
     pcm = qec.generate_random_pcm(n_rounds=2,
@@ -353,8 +495,8 @@ def test_decoder_pymatching_results():
     decoder = qec.get_decoder('pymatching', pcm)
     result = decoder.decode(syndrome)
     assert result.converged is True
-    assert all(isinstance(x, float) for x in result.result)
-    assert all(0 <= x <= 1 for x in result.result)
+    assert isinstance(result.result, np.ndarray)
+    assert np.all((0 <= result.result) & (result.result <= 1))
     actual_errors = np.zeros(pcm.shape[1], dtype=np.uint8)
     actual_errors[columns] = 1
     assert np.array_equal(result.result, actual_errors)