fix: example_batch.py used weight-4 surface code with weight<=2-only decoders

CPUBatchDecoder/OpenCLBatchDecoder/CUDABatchDecoder are Union-Find-based
and only support weight <= 2 checks. generate_surface_code_checks()
produces weight-4 (four-body) checks, which these decoders correctly
reject at construction. Switched the demo to generate_ring_code_checks(),
the natural weight-2 graph-like code family for this decoder class.

Verified: examples/example_batch.py runs cleanly end-to-end (CPU path,
OpenCL/CUDA skip gracefully when unavailable). python/tests/test_examples.py
now passes (1 passed in 154.39s).

Author: qectorlab

examples/example_batch.py

@@ -21,72 +21,79 @@
     CUDABatchDecoder,
     cuda_is_available,
     opencl_is_available,
-    generate_surface_code_checks,
+    generate_ring_code_checks,
 )
 
+
 def main():
-    # Use distance 5 surface code
-    checks, n_qubits = generate_surface_code_checks(5)
+    # CPUBatchDecoder / OpenCLBatchDecoder / CUDABatchDecoder are all
+    # Union-Find-based and only support weight <= 2 checks (graph-like
+    # codes). Surface-code stabilizers are weight-4 and are NOT supported
+    # here -- use BlossomDecoder, SparseBlossomDecoder, or BPOSDDecoder for
+    # those instead. A ring code (each check ties 2 neighboring qubits in a
+    # cycle) is the natural weight-2 code family for this decoder family.
+    distance = 50
+    checks, n_qubits = generate_ring_code_checks(distance)
     n_checks = len(checks)
     batch_size = 10000  # larger batch size to show GPU speedup
-    
+
     # Generate random syndromes using NumPy
     rng = np.random.default_rng(42)
     syndromes = rng.integers(0, 2, size=(batch_size, n_checks), dtype=np.uint8)
-    
+
     print("=" * 60)
     print("QECTOR v3 - Batch & GPU Demo")
     print("=" * 60)
-    print(f"Code: Surface Code d=5 ({n_qubits} qubits, {n_checks} checks)")
+    print(f"Code: Ring Code d={distance} ({n_qubits} qubits, {n_checks} checks)")
     print(f"Batch size: {batch_size}")
-    
+
     # 1. CPU Batch decoder
     print("\n1. CPUBatchDecoder (CPU parallel execution):")
     cpu_batch = CPUBatchDecoder(checks, n_qubits)
     # Warm up
     _ = cpu_batch.batch_decode(syndromes[:10])
-    
+
     t0 = time.perf_counter()
     results_cpu = cpu_batch.batch_decode(syndromes)
     t1 = time.perf_counter()
     cpu_time = (t1 - t0) * 1000
     print(f"   Time: {cpu_time:.2f} ms")
     print(f"   Throughput: {batch_size / (cpu_time / 1000):.0f} dec/s")
-    
+
     # 2. GPU OpenCL Batch decoder (if available)
     cl_avail = opencl_is_available()
     print("\n2. OpenCLBatchDecoder (GPU OpenCL):")
     print(f"   OpenCL available: {cl_avail}")
-    
+
     if cl_avail:
         gpu_cl = OpenCLBatchDecoder(checks, n_qubits)
         # Warm up
         _ = gpu_cl.batch_decode(syndromes[:10])
-        
+
         t0 = time.perf_counter()
         results_gpu_cl = gpu_cl.batch_decode(syndromes)
         t1 = time.perf_counter()
         cl_time = (t1 - t0) * 1000
         print(f"   Time: {cl_time:.2f} ms")
         print(f"   Throughput: {batch_size / (cl_time / 1000):.0f} dec/s")
         print(f"   Speedup vs CPU: {cpu_time / cl_time:.2f}x")
-        
+
         # Verify correctness
         matches = np.array_equal(results_cpu, results_gpu_cl)
         print(f"   Output matches CPU: {'yes' if matches else 'no'}")
     else:
         print("   (Skipped — OpenCL GPU not available)")
-        
+
     # 3. GPU CUDA Batch decoder (if available)
     cuda_avail = cuda_is_available()
     print("\n3. CUDABatchDecoder (GPU Native CUDA):")
     print(f"   CUDA available: {cuda_avail}")
-    
+
     if cuda_avail and CUDABatchDecoder is not None:
         gpu_cuda = CUDABatchDecoder(checks, n_qubits)
         # Warm up
         _ = gpu_cuda.batch_decode(syndromes[:10])
-        
+
         t0 = time.perf_counter()
         results_gpu_cuda = gpu_cuda.batch_decode(syndromes)
         t1 = time.perf_counter()
@@ -96,16 +103,17 @@ def main():
         print(f"   Time: {cuda_time:.2f} ms")
         print(f"   Throughput: {batch_size / (cuda_time / 1000):.0f} dec/s")
         print(f"   Speedup vs CPU: {cpu_time / cuda_time:.2f}x")
-        
+
         # Verify correctness
         matches = np.array_equal(results_cpu, results_gpu_cuda)
         print(f"   Output matches CPU: {'yes' if matches else 'no'}")
     else:
         print("   (Skipped — CUDA not available or not built)")
-    
+
     print("\n" + "=" * 60)
     print("Demo complete!")
     print("=" * 60)
 
+
 if __name__ == "__main__":
     main()