1use std::collections::{HashMap, HashSet};
2use std::ffi::c_void;
3use std::os::raw::c_char;
4use std::sync::Arc;
5
6use crate::{GraphlikeDecodingProblem, Mask, NpError, NpResult};
7
8pub const NATIVE_DECODER_PLUGIN_ABI_VERSION: u32 = 4;
9pub const NATIVE_DECODER_PLUGIN_ABI_NAME: &str = "faultscope.native_decoder_plugin.v4";
10pub const NATIVE_DECODER_PLUGIN_CAPSULE_NAME: &str = "faultscope.native_decoder_plugin.v4";
11pub const NATIVE_DECODER_PLUGIN_CAPSULE_METHOD: &str = "__faultscope_native_decoder_capsule__";
12pub const NATIVE_DECODER_PLUGIN_ENTRY_POINT_GROUP: &str = "faultscope.native_decoders";
13pub const NATIVE_DECODER_FACTORY_FLAG_THREAD_SAFE: u64 = 1 << 0;
14pub const NATIVE_DECODER_PLUGIN_STATUS_OK: i32 = 0;
15pub const NATIVE_DECODER_PLUGIN_STATUS_ERROR: i32 = 1;
16pub const NATIVE_DECODER_BATCH_FORMAT_MASKS: u32 = 1;
17pub const NATIVE_DECODER_BATCH_FORMAT_PACKED: u32 = 2;
18pub const NATIVE_DECODER_BATCH_FORMAT_EVENTS: u32 = 3;
19
20#[repr(C)]
21#[derive(Debug, Clone, Copy)]
22pub struct FaultScopeNativeDecoderStringViewV1 {
23 pub ptr: *const c_char,
24 pub len: usize,
25}
26
27impl FaultScopeNativeDecoderStringViewV1 {
28 pub const fn empty() -> Self {
29 Self {
30 ptr: std::ptr::null(),
31 len: 0,
32 }
33 }
34}
35
36#[repr(C)]
37#[derive(Debug, Clone, Copy)]
38pub struct FaultScopeNativeDecoderI64SliceV1 {
39 pub ptr: *const i64,
40 pub len: usize,
41}
42
43impl FaultScopeNativeDecoderI64SliceV1 {
44 pub const fn empty() -> Self {
45 Self {
46 ptr: std::ptr::null(),
47 len: 0,
48 }
49 }
50}
51
52#[repr(C)]
53#[derive(Debug, Clone, Copy)]
54pub struct FaultScopeNativeDecoderU32SliceV1 {
55 pub ptr: *const u32,
56 pub len: usize,
57}
58
59impl FaultScopeNativeDecoderU32SliceV1 {
60 pub const fn empty() -> Self {
61 Self {
62 ptr: std::ptr::null(),
63 len: 0,
64 }
65 }
66}
67
68#[repr(C)]
69#[derive(Debug, Clone, Copy)]
70pub struct FaultScopeNativeDecoderMaskViewV1 {
71 pub words: *const u64,
72 pub word_count: usize,
73}
74
75#[repr(C)]
76#[derive(Debug, Clone, Copy)]
77pub struct FaultScopeNativeDecoderMaskMutViewV1 {
78 pub words: *mut u64,
79 pub word_count: usize,
80}
81
82#[repr(C)]
83#[derive(Debug, Clone, Copy)]
84pub struct FaultScopeNativeDetectorMaskBatchViewV1 {
85 pub detector_ids: *const i64,
86 pub detector_count: usize,
87 pub masks: *const FaultScopeNativeDecoderMaskViewV1,
88 pub shots: usize,
89 pub word_count: usize,
90}
91
92#[repr(C)]
93#[derive(Debug, Clone, Copy)]
94pub struct FaultScopeNativeCorrectionMaskBatchMutViewV1 {
95 pub observable_ids: *const i64,
96 pub observable_count: usize,
97 pub masks: *mut FaultScopeNativeDecoderMaskMutViewV1,
98 pub shots: usize,
99 pub word_count: usize,
100}
101
102#[repr(C)]
103#[derive(Debug, Clone, Copy)]
104pub struct FaultScopeNativePackedDetectorShotBatchViewV1 {
105 pub detector_ids: *const i64,
106 pub detector_count: usize,
107 pub data: *const u8,
108 pub shots: usize,
109 pub detector_byte_count: usize,
110}
111
112#[repr(C)]
113#[derive(Debug, Clone, Copy)]
114pub struct FaultScopeNativeDetectorEventShotBatchViewV1 {
115 pub detector_ids: *const i64,
116 pub detector_count: usize,
117 pub offsets: *const usize,
118 pub offsets_len: usize,
119 pub events: *const usize,
120 pub event_count: usize,
121 pub shots: usize,
122}
123
124#[repr(C)]
125#[derive(Debug, Clone, Copy)]
126pub struct FaultScopeNativePackedObservableShotBatchMutViewV1 {
127 pub observable_ids: *const i64,
128 pub observable_count: usize,
129 pub data: *mut u8,
130 pub shots: usize,
131 pub observable_byte_count: usize,
132}
133
134#[repr(C)]
135#[derive(Debug, Clone, Copy)]
136pub struct FaultScopeNativeDecoderStatusV1 {
137 pub code: i32,
138 pub message: FaultScopeNativeDecoderStringViewV1,
139}
140
141impl FaultScopeNativeDecoderStatusV1 {
142 pub const fn ok() -> Self {
143 Self {
144 code: NATIVE_DECODER_PLUGIN_STATUS_OK,
145 message: FaultScopeNativeDecoderStringViewV1::empty(),
146 }
147 }
148}
149
150#[repr(C)]
151#[derive(Clone, Copy)]
152pub union FaultScopeNativeDetectorBatchPayloadV4 {
153 pub masks: FaultScopeNativeDetectorMaskBatchViewV1,
154 pub packed: FaultScopeNativePackedDetectorShotBatchViewV1,
155 pub events: FaultScopeNativeDetectorEventShotBatchViewV1,
156}
157
158#[repr(C)]
159#[derive(Clone, Copy)]
160pub struct FaultScopeNativeDetectorBatchViewV4 {
161 pub format: u32,
162 pub reserved: u32,
163 pub payload: FaultScopeNativeDetectorBatchPayloadV4,
164}
165
166#[repr(C)]
167#[derive(Clone, Copy)]
168pub union FaultScopeNativeCorrectionBatchPayloadV4 {
169 pub masks: FaultScopeNativeCorrectionMaskBatchMutViewV1,
170 pub packed: FaultScopeNativePackedObservableShotBatchMutViewV1,
171}
172
173#[repr(C)]
174#[derive(Clone, Copy)]
175pub struct FaultScopeNativeCorrectionBatchMutViewV4 {
176 pub format: u32,
177 pub reserved: u32,
178 pub payload: FaultScopeNativeCorrectionBatchPayloadV4,
179}
180
181#[repr(C)]
182#[derive(Clone, Copy)]
183pub struct FaultScopeNativeDecoderFactoryV4 {
184 pub abi_version: u32,
185 pub struct_size: usize,
186 pub flags: u64,
187 pub factory_state: *mut c_void,
188 pub drop_factory_state: Option<unsafe extern "C" fn(*mut c_void)>,
189 pub name: Option<
190 unsafe extern "C" fn(
191 *const c_void,
192 *mut FaultScopeNativeDecoderStringViewV1,
193 ) -> FaultScopeNativeDecoderStatusV1,
194 >,
195 pub detector_ids: Option<
196 unsafe extern "C" fn(
197 *const c_void,
198 *mut FaultScopeNativeDecoderI64SliceV1,
199 ) -> FaultScopeNativeDecoderStatusV1,
200 >,
201 pub observable_ids: Option<
202 unsafe extern "C" fn(
203 *const c_void,
204 *mut FaultScopeNativeDecoderI64SliceV1,
205 ) -> FaultScopeNativeDecoderStatusV1,
206 >,
207 pub batch_formats: Option<
208 unsafe extern "C" fn(
209 *const c_void,
210 *mut FaultScopeNativeDecoderU32SliceV1,
211 ) -> FaultScopeNativeDecoderStatusV1,
212 >,
213 pub create_worker: Option<
214 unsafe extern "C" fn(
215 *const c_void,
216 *mut FaultScopeNativeDecoderWorkerV4,
217 usize,
218 ) -> FaultScopeNativeDecoderStatusV1,
219 >,
220}
221
222#[repr(C)]
223#[derive(Clone, Copy)]
224pub struct FaultScopeNativeDecoderWorkerV4 {
225 pub struct_size: usize,
226 pub worker_state: *mut c_void,
227 pub drop_worker_state: Option<unsafe extern "C" fn(*mut c_void)>,
228 pub decode_batch: Option<
229 unsafe extern "C" fn(
230 *mut c_void,
231 *const FaultScopeNativeDetectorBatchViewV4,
232 *mut FaultScopeNativeCorrectionBatchMutViewV4,
233 ) -> FaultScopeNativeDecoderStatusV1,
234 >,
235}
236
237#[repr(u32)]
239#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
240pub enum DetectorBatchFormat {
241 Masks = NATIVE_DECODER_BATCH_FORMAT_MASKS,
242 Packed = NATIVE_DECODER_BATCH_FORMAT_PACKED,
243 Events = NATIVE_DECODER_BATCH_FORMAT_EVENTS,
244}
245
246impl DetectorBatchFormat {
247 pub const STABLE_ORDER: [Self; 3] = [Self::Masks, Self::Packed, Self::Events];
248
249 pub const fn correction_format(self) -> Self {
250 match self {
251 Self::Masks => Self::Masks,
252 Self::Packed | Self::Events => Self::Packed,
253 }
254 }
255}
256
257impl TryFrom<u32> for DetectorBatchFormat {
258 type Error = NpError;
259
260 fn try_from(value: u32) -> Result<Self, Self::Error> {
261 match value {
262 NATIVE_DECODER_BATCH_FORMAT_MASKS => Ok(Self::Masks),
263 NATIVE_DECODER_BATCH_FORMAT_PACKED => Ok(Self::Packed),
264 NATIVE_DECODER_BATCH_FORMAT_EVENTS => Ok(Self::Events),
265 _ => Err(NpError::new(format!(
266 "unknown native decoder batch format tag {value}"
267 ))),
268 }
269 }
270}
271
272#[derive(Debug, Clone, Copy)]
273pub struct DetectorMaskBatchView<'a> {
274 pub detector_ids: &'a [i64],
275 pub masks: &'a [Mask],
276 pub shots: usize,
277}
278
279impl<'a> DetectorMaskBatchView<'a> {
280 pub fn new(detector_ids: &'a [i64], masks: &'a [Mask], shots: usize) -> NpResult<Self> {
281 validate_decoder_detector_ids(detector_ids)?;
282 let view = Self {
283 detector_ids,
284 masks,
285 shots,
286 };
287 view.validate_shape()?;
288 Ok(view)
289 }
290
291 fn validate_shape(self) -> NpResult<()> {
292 if self.detector_ids.len() != self.masks.len() {
293 return Err(NpError::new(
294 "detector ids and detector masks must have the same length",
295 ));
296 }
297 let expected_words = crate::word_count(self.shots);
298 for (detector_id, mask) in self.detector_ids.iter().zip(self.masks) {
299 if mask.words.len() != expected_words {
300 return Err(NpError::new(format!(
301 "detector mask for detector id {detector_id} has {} words; expected {expected_words} for {} shots",
302 mask.words.len(),
303 self.shots
304 )));
305 }
306 validate_zero_mask_padding(mask, self.shots, &format!("detector mask {detector_id}"))?;
307 }
308 Ok(())
309 }
310}
311
312#[derive(Debug, Clone, Copy)]
313pub struct PackedDetectorShotBatchView<'a> {
314 pub detector_ids: &'a [i64],
315 pub data: &'a [u8],
316 pub shots: usize,
317 pub detector_byte_count: usize,
318}
319
320#[derive(Debug, Clone, Copy)]
321pub struct DetectorEventShotBatchView<'a> {
322 pub detector_ids: &'a [i64],
323 pub offsets: &'a [usize],
324 pub events: &'a [usize],
325 pub shots: usize,
326}
327
328#[derive(Debug, Clone, Copy)]
330pub enum DetectorBatchView<'a> {
331 Masks(DetectorMaskBatchView<'a>),
332 Packed(PackedDetectorShotBatchView<'a>),
333 Events(DetectorEventShotBatchView<'a>),
334}
335
336impl<'a> DetectorBatchView<'a> {
337 pub const fn format(self) -> DetectorBatchFormat {
338 match self {
339 Self::Masks(_) => DetectorBatchFormat::Masks,
340 Self::Packed(_) => DetectorBatchFormat::Packed,
341 Self::Events(_) => DetectorBatchFormat::Events,
342 }
343 }
344
345 pub const fn detector_ids(self) -> &'a [i64] {
346 match self {
347 Self::Masks(view) => view.detector_ids,
348 Self::Packed(view) => view.detector_ids,
349 Self::Events(view) => view.detector_ids,
350 }
351 }
352
353 pub const fn shots(self) -> usize {
354 match self {
355 Self::Masks(view) => view.shots,
356 Self::Packed(view) => view.shots,
357 Self::Events(view) => view.shots,
358 }
359 }
360
361 pub fn validate(self) -> NpResult<()> {
362 validate_decoder_detector_ids(self.detector_ids())?;
363 self.validate_shape()
364 }
365
366 pub(crate) fn validate_shape(self) -> NpResult<()> {
367 match self {
368 Self::Masks(view) => view.validate_shape()?,
369 Self::Packed(view) => {
370 view.validate_shape()?;
371 }
372 Self::Events(view) => view.validate_shape()?,
373 }
374 Ok(())
375 }
376}
377
378impl<'a> From<DetectorMaskBatchView<'a>> for DetectorBatchView<'a> {
379 fn from(value: DetectorMaskBatchView<'a>) -> Self {
380 Self::Masks(value)
381 }
382}
383
384impl<'a> From<PackedDetectorShotBatchView<'a>> for DetectorBatchView<'a> {
385 fn from(value: PackedDetectorShotBatchView<'a>) -> Self {
386 Self::Packed(value)
387 }
388}
389
390impl<'a> From<DetectorEventShotBatchView<'a>> for DetectorBatchView<'a> {
391 fn from(value: DetectorEventShotBatchView<'a>) -> Self {
392 Self::Events(value)
393 }
394}
395
396impl<'a> DetectorEventShotBatchView<'a> {
397 pub fn new(
398 detector_ids: &'a [i64],
399 offsets: &'a [usize],
400 events: &'a [usize],
401 shots: usize,
402 ) -> NpResult<Self> {
403 validate_decoder_detector_ids(detector_ids)?;
404 let view = Self {
405 detector_ids,
406 offsets,
407 events,
408 shots,
409 };
410 view.validate_shape()?;
411 Ok(view)
412 }
413
414 fn validate_shape(self) -> NpResult<()> {
415 let expected_offsets_len = self
416 .shots
417 .checked_add(1)
418 .ok_or_else(|| NpError::new("detector event batch offset length overflowed usize"))?;
419 if self.offsets.len() != expected_offsets_len {
420 return Err(NpError::new(format!(
421 "detector event batch offsets has length {}; expected {}",
422 self.offsets.len(),
423 expected_offsets_len
424 )));
425 }
426 if self.offsets.first().copied().unwrap_or(0) != 0
427 || self.offsets.last().copied().unwrap_or(0) != self.events.len()
428 {
429 return Err(NpError::new(
430 "detector event batch offsets must start at 0 and end at events length",
431 ));
432 }
433 for pair in self.offsets.windows(2) {
434 if pair[0] > pair[1] {
435 return Err(NpError::new(
436 "detector event batch offsets must be nondecreasing",
437 ));
438 }
439 }
440 for &event in self.events {
441 if event >= self.detector_ids.len() {
442 return Err(NpError::new(format!(
443 "detector event index {event} exceeds detector count {}",
444 self.detector_ids.len()
445 )));
446 }
447 }
448 Ok(())
449 }
450}
451
452impl<'a> PackedDetectorShotBatchView<'a> {
453 pub fn new(detector_ids: &'a [i64], data: &'a [u8], shots: usize) -> NpResult<Self> {
454 validate_decoder_detector_ids(detector_ids)?;
455 let view = Self {
456 detector_ids,
457 data,
458 shots,
459 detector_byte_count: detector_ids.len().div_ceil(8),
460 };
461 view.validate_shape()?;
462 Ok(view)
463 }
464
465 fn validate_shape(self) -> NpResult<()> {
466 let expected_byte_count = self.detector_ids.len().div_ceil(8);
467 if self.detector_byte_count != expected_byte_count {
468 return Err(NpError::new(format!(
469 "packed detector byte count is {}; expected {expected_byte_count}",
470 self.detector_byte_count
471 )));
472 }
473 let expected_len = self.shots.checked_mul(expected_byte_count).ok_or_else(|| {
474 NpError::new("packed detector shot batch byte length overflowed usize")
475 })?;
476 if self.data.len() != expected_len {
477 return Err(NpError::new(format!(
478 "packed detector shot batch has {} bytes; expected {expected_len} for {} shots and {} detectors",
479 self.data.len(),
480 self.shots,
481 self.detector_ids.len()
482 )));
483 }
484 validate_zero_packed_padding(
485 self.data,
486 self.shots,
487 expected_byte_count,
488 self.detector_ids.len(),
489 "packed detector batch",
490 )?;
491 Ok(())
492 }
493}
494
495#[derive(Debug, Clone, PartialEq)]
497pub enum DetectorBatch {
498 Masks {
499 detector_ids: Vec<i64>,
500 masks: Vec<Mask>,
501 shots: usize,
502 },
503 Packed {
504 detector_ids: Vec<i64>,
505 data: Vec<u8>,
506 shots: usize,
507 detector_byte_count: usize,
508 },
509 Events {
510 detector_ids: Vec<i64>,
511 offsets: Vec<usize>,
512 events: Vec<usize>,
513 shots: usize,
514 },
515}
516
517impl DetectorBatch {
518 pub const fn format(&self) -> DetectorBatchFormat {
519 match self {
520 Self::Masks { .. } => DetectorBatchFormat::Masks,
521 Self::Packed { .. } => DetectorBatchFormat::Packed,
522 Self::Events { .. } => DetectorBatchFormat::Events,
523 }
524 }
525
526 pub fn detector_ids(&self) -> &[i64] {
527 match self {
528 Self::Masks { detector_ids, .. }
529 | Self::Packed { detector_ids, .. }
530 | Self::Events { detector_ids, .. } => detector_ids,
531 }
532 }
533
534 pub const fn shots(&self) -> usize {
535 match self {
536 Self::Masks { shots, .. } | Self::Packed { shots, .. } | Self::Events { shots, .. } => {
537 *shots
538 }
539 }
540 }
541
542 pub fn view(&self) -> DetectorBatchView<'_> {
543 match self {
544 Self::Masks {
545 detector_ids,
546 masks,
547 shots,
548 } => DetectorBatchView::Masks(DetectorMaskBatchView {
549 detector_ids,
550 masks,
551 shots: *shots,
552 }),
553 Self::Packed {
554 detector_ids,
555 data,
556 shots,
557 detector_byte_count,
558 } => DetectorBatchView::Packed(PackedDetectorShotBatchView {
559 detector_ids,
560 data,
561 shots: *shots,
562 detector_byte_count: *detector_byte_count,
563 }),
564 Self::Events {
565 detector_ids,
566 offsets,
567 events,
568 shots,
569 } => DetectorBatchView::Events(DetectorEventShotBatchView {
570 detector_ids,
571 offsets,
572 events,
573 shots: *shots,
574 }),
575 }
576 }
577
578 pub fn validate(&self) -> NpResult<()> {
579 self.view().validate()
580 }
581
582 pub(crate) fn validate_shape(&self) -> NpResult<()> {
583 self.view().validate_shape()
584 }
585}
586
587pub(crate) fn empty_detector_event_offsets(shots: usize) -> NpResult<Vec<usize>> {
588 let offset_count = shots
589 .checked_add(1)
590 .ok_or_else(|| NpError::new("detector event offset length overflowed usize"))?;
591 let mut offsets = Vec::new();
592 offsets.try_reserve_exact(offset_count).map_err(|error| {
593 NpError::new(format!(
594 "detector event offset storage for {shots} shots could not be allocated: {error}"
595 ))
596 })?;
597 offsets.push(0);
598 Ok(offsets)
599}
600
601pub fn convert_detector_batch(
606 source: DetectorBatchView<'_>,
607 target: DetectorBatchFormat,
608) -> NpResult<DetectorBatch> {
609 convert_detector_batch_impl(source, target, true)
610}
611
612fn convert_detector_batch_prevalidated(
613 source: DetectorBatchView<'_>,
614 target: DetectorBatchFormat,
615) -> NpResult<DetectorBatch> {
616 convert_detector_batch_impl(source, target, false)
617}
618
619fn convert_detector_batch_impl(
620 source: DetectorBatchView<'_>,
621 target: DetectorBatchFormat,
622 validate_metadata: bool,
623) -> NpResult<DetectorBatch> {
624 if validate_metadata {
625 source.validate()?;
626 } else {
627 source.validate_shape()?;
628 }
629 let detector_ids = source.detector_ids().to_vec();
630 let shots = source.shots();
631 let detector_count = detector_ids.len();
632 let detector_byte_count = detector_count.div_ceil(8);
633 let words = crate::word_count(shots);
634
635 let converted = match (source, target) {
636 (DetectorBatchView::Masks(view), DetectorBatchFormat::Masks) => DetectorBatch::Masks {
637 detector_ids,
638 masks: view.masks.to_vec(),
639 shots,
640 },
641 (DetectorBatchView::Packed(view), DetectorBatchFormat::Packed) => DetectorBatch::Packed {
642 detector_ids,
643 data: view.data.to_vec(),
644 shots,
645 detector_byte_count,
646 },
647 (DetectorBatchView::Events(view), DetectorBatchFormat::Events) => {
648 let mut offsets = empty_detector_event_offsets(shots)?;
649 let mut events = Vec::new();
650 let mut parity = vec![false; detector_count];
651 for shot in 0..shots {
652 parity.fill(false);
653 for &detector in &view.events[view.offsets[shot]..view.offsets[shot + 1]] {
654 parity[detector] ^= true;
655 }
656 events.extend(
657 parity
658 .iter()
659 .enumerate()
660 .filter_map(|(detector, set)| set.then_some(detector)),
661 );
662 offsets.push(events.len());
663 }
664 DetectorBatch::Events {
665 detector_ids,
666 offsets,
667 events,
668 shots,
669 }
670 }
671 (DetectorBatchView::Masks(view), DetectorBatchFormat::Packed) => {
672 let len = shots.checked_mul(detector_byte_count).ok_or_else(|| {
673 NpError::new("packed detector conversion length overflowed usize")
674 })?;
675 let mut data = vec![0u8; len];
676 for (detector, mask) in view.masks.iter().enumerate() {
677 for shot in 0..shots {
678 if mask.words[shot >> 6] & (1u64 << (shot & 63)) != 0 {
679 data[shot * detector_byte_count + (detector >> 3)] |= 1u8 << (detector & 7);
680 }
681 }
682 }
683 DetectorBatch::Packed {
684 detector_ids,
685 data,
686 shots,
687 detector_byte_count,
688 }
689 }
690 (DetectorBatchView::Packed(view), DetectorBatchFormat::Masks) => {
691 let mut masks = vec![Mask::zero(words); detector_count];
692 for shot in 0..shots {
693 let row = shot * detector_byte_count;
694 for (detector, mask) in masks.iter_mut().enumerate() {
695 if view.data[row + (detector >> 3)] & (1u8 << (detector & 7)) != 0 {
696 mask.words[shot >> 6] |= 1u64 << (shot & 63);
697 }
698 }
699 }
700 DetectorBatch::Masks {
701 detector_ids,
702 masks,
703 shots,
704 }
705 }
706 (DetectorBatchView::Events(view), DetectorBatchFormat::Masks) => {
707 let mut masks = vec![Mask::zero(words); detector_count];
708 for shot in 0..shots {
709 for &detector in &view.events[view.offsets[shot]..view.offsets[shot + 1]] {
710 masks[detector].words[shot >> 6] ^= 1u64 << (shot & 63);
711 }
712 }
713 DetectorBatch::Masks {
714 detector_ids,
715 masks,
716 shots,
717 }
718 }
719 (DetectorBatchView::Events(view), DetectorBatchFormat::Packed) => {
720 let len = shots.checked_mul(detector_byte_count).ok_or_else(|| {
721 NpError::new("packed detector conversion length overflowed usize")
722 })?;
723 let mut data = vec![0u8; len];
724 for shot in 0..shots {
725 let row = shot * detector_byte_count;
726 for &detector in &view.events[view.offsets[shot]..view.offsets[shot + 1]] {
727 data[row + (detector >> 3)] ^= 1u8 << (detector & 7);
728 }
729 }
730 DetectorBatch::Packed {
731 detector_ids,
732 data,
733 shots,
734 detector_byte_count,
735 }
736 }
737 (DetectorBatchView::Masks(view), DetectorBatchFormat::Events) => {
738 let mut offsets = empty_detector_event_offsets(shots)?;
739 let mut events = Vec::new();
740 for shot in 0..shots {
741 for (detector, mask) in view.masks.iter().enumerate() {
742 if mask.words[shot >> 6] & (1u64 << (shot & 63)) != 0 {
743 events.push(detector);
744 }
745 }
746 offsets.push(events.len());
747 }
748 DetectorBatch::Events {
749 detector_ids,
750 offsets,
751 events,
752 shots,
753 }
754 }
755 (DetectorBatchView::Packed(view), DetectorBatchFormat::Events) => {
756 let mut offsets = empty_detector_event_offsets(shots)?;
757 let mut events = Vec::new();
758 for shot in 0..shots {
759 let row = shot * detector_byte_count;
760 for detector in 0..detector_count {
761 if view.data[row + (detector >> 3)] & (1u8 << (detector & 7)) != 0 {
762 events.push(detector);
763 }
764 }
765 offsets.push(events.len());
766 }
767 DetectorBatch::Events {
768 detector_ids,
769 offsets,
770 events,
771 shots,
772 }
773 }
774 };
775 if validate_metadata {
776 converted.validate()?;
777 } else {
778 converted.validate_shape()?;
779 }
780 Ok(converted)
781}
782
783#[derive(Debug, Clone, PartialEq)]
784pub struct PackedObservableShotBatch {
785 pub observable_ids: Vec<i64>,
786 pub data: Vec<u8>,
787 pub shots: usize,
788 pub observable_byte_count: usize,
789}
790
791impl PackedObservableShotBatch {
792 pub fn new(observable_ids: Vec<i64>, data: Vec<u8>, shots: usize) -> NpResult<Self> {
793 let observable_byte_count = observable_ids.len().div_ceil(8);
794 let batch = Self {
795 observable_ids,
796 data,
797 shots,
798 observable_byte_count,
799 };
800 batch.validate_shape()?;
801 Ok(batch)
802 }
803
804 pub fn zero(observable_ids: Vec<i64>, shots: usize) -> NpResult<Self> {
805 let observable_byte_count = observable_ids.len().div_ceil(8);
806 let len = shots
807 .checked_mul(observable_byte_count)
808 .ok_or_else(|| NpError::new("packed correction byte length overflowed usize"))?;
809 let mut data = Vec::new();
810 data.try_reserve_exact(len).map_err(|error| {
811 NpError::new(format!(
812 "packed correction storage for {shots} shots could not be allocated: {error}"
813 ))
814 })?;
815 data.resize(len, 0);
816 Self::new(observable_ids, data, shots)
817 }
818
819 pub fn validate_against(&self, declared_observable_ids: &[i64], shots: usize) -> NpResult<()> {
820 if self.shots != shots {
821 return Err(NpError::new(format!(
822 "packed correction batch has {} shots; expected {shots}",
823 self.shots
824 )));
825 }
826 self.validate_shape()?;
827 if self.observable_ids != declared_observable_ids {
828 return Err(NpError::new(format!(
829 "packed correction observable layout mismatch: expected {:?}, got {:?}",
830 declared_observable_ids, self.observable_ids
831 )));
832 }
833 Ok(())
834 }
835
836 fn validate_shape(&self) -> NpResult<()> {
837 let expected_byte_count = self.observable_ids.len().div_ceil(8);
838 if self.observable_byte_count != expected_byte_count {
839 return Err(NpError::new(format!(
840 "packed correction observable byte count is {}; expected {expected_byte_count}",
841 self.observable_byte_count
842 )));
843 }
844 let expected_len = self
845 .shots
846 .checked_mul(self.observable_byte_count)
847 .ok_or_else(|| NpError::new("packed correction byte length overflowed usize"))?;
848 if self.data.len() != expected_len {
849 return Err(NpError::new(format!(
850 "packed correction batch has {} bytes; expected {expected_len} for {} shots and {} observables",
851 self.data.len(),
852 self.shots,
853 self.observable_ids.len()
854 )));
855 }
856 for (index, observable_id) in self.observable_ids.iter().enumerate() {
857 if self.observable_ids[..index].contains(observable_id) {
858 return Err(NpError::new(format!(
859 "duplicate packed correction observable id {observable_id}"
860 )));
861 }
862 }
863 validate_zero_packed_padding(
864 &self.data,
865 self.shots,
866 self.observable_byte_count,
867 self.observable_ids.len(),
868 "packed correction batch",
869 )?;
870 Ok(())
871 }
872}
873
874fn validate_zero_packed_padding(
875 data: &[u8],
876 shots: usize,
877 byte_count: usize,
878 bit_count: usize,
879 batch_name: &str,
880) -> NpResult<()> {
881 let used_bits = bit_count & 7;
882 if used_bits == 0 {
883 return Ok(());
884 }
885 let padding_mask = !((1u8 << used_bits) - 1);
886 for shot in 0..shots {
887 let final_byte = data[(shot + 1) * byte_count - 1];
888 if final_byte & padding_mask != 0 {
889 return Err(NpError::new(format!(
890 "{batch_name} shot {shot} has non-zero padding bits"
891 )));
892 }
893 }
894 Ok(())
895}
896
897fn validate_zero_mask_padding(mask: &Mask, shots: usize, name: &str) -> NpResult<()> {
898 let used_bits = shots & 63;
899 if used_bits == 0 {
900 return Ok(());
901 }
902 let padding_mask = !((1u64 << used_bits) - 1);
903 if mask.words.last().copied().unwrap_or(0) & padding_mask != 0 {
904 return Err(NpError::new(format!(
905 "{name} has non-zero padding bits for {shots} shots"
906 )));
907 }
908 Ok(())
909}
910
911pub fn packed_residual_failure_count(
916 observable_ids: &[i64],
917 observable_data: &[u8],
918 observable_byte_count: usize,
919 corrections: &PackedObservableShotBatch,
920 shots: usize,
921) -> NpResult<usize> {
922 let expected_observable_byte_count = observable_ids.len().div_ceil(8);
923 if observable_byte_count != expected_observable_byte_count {
924 return Err(NpError::new(format!(
925 "packed observable byte count is {observable_byte_count}; expected {expected_observable_byte_count}"
926 )));
927 }
928 let expected_observable_data_len = shots
929 .checked_mul(observable_byte_count)
930 .ok_or_else(|| NpError::new("packed observable byte length overflowed usize"))?;
931 if observable_data.len() != expected_observable_data_len {
932 return Err(NpError::new(format!(
933 "packed observable batch has {} bytes; expected {expected_observable_data_len} for {shots} shots and {} observables",
934 observable_data.len(),
935 observable_ids.len()
936 )));
937 }
938 validate_zero_packed_padding(
939 observable_data,
940 shots,
941 observable_byte_count,
942 observable_ids.len(),
943 "packed observable batch",
944 )?;
945 corrections.validate_against(observable_ids, shots)?;
946
947 Ok((0..shots)
948 .filter(|shot| {
949 let begin = shot * observable_byte_count;
950 let end = begin + observable_byte_count;
951 observable_data[begin..end]
952 .iter()
953 .zip(&corrections.data[begin..end])
954 .any(|(actual, correction)| (actual ^ correction) != 0)
955 })
956 .count())
957}
958
959#[derive(Debug, Clone, PartialEq)]
960pub struct CorrectionMaskBatch {
961 pub observable_ids: Vec<i64>,
962 pub masks: Vec<Mask>,
963 pub shots: usize,
964}
965
966impl CorrectionMaskBatch {
967 pub fn new(observable_ids: Vec<i64>, masks: Vec<Mask>, shots: usize) -> NpResult<Self> {
968 if observable_ids.len() != masks.len() {
969 return Err(NpError::new(
970 "observable ids and correction masks must have the same length",
971 ));
972 }
973 let batch = Self {
974 observable_ids,
975 masks,
976 shots,
977 };
978 batch.validate_shape()?;
979 Ok(batch)
980 }
981
982 pub fn empty(shots: usize) -> Self {
983 Self {
984 observable_ids: Vec::new(),
985 masks: Vec::new(),
986 shots,
987 }
988 }
989
990 pub fn get(&self, observable_id: i64) -> Option<&Mask> {
991 self.observable_ids
992 .iter()
993 .position(|id| *id == observable_id)
994 .and_then(|index| self.masks.get(index))
995 }
996
997 pub fn validate_against(&self, declared_observable_ids: &[i64], shots: usize) -> NpResult<()> {
998 if self.shots != shots {
999 return Err(NpError::new(format!(
1000 "correction batch has {} shots; expected {shots}",
1001 self.shots
1002 )));
1003 }
1004 self.validate_shape()?;
1005 if self.observable_ids != declared_observable_ids {
1006 return Err(NpError::new(format!(
1007 "correction observable layout mismatch: expected {:?}, got {:?}",
1008 declared_observable_ids, self.observable_ids
1009 )));
1010 }
1011 Ok(())
1012 }
1013
1014 fn validate_shape(&self) -> NpResult<()> {
1015 if self.observable_ids.len() != self.masks.len() {
1016 return Err(NpError::new(
1017 "observable ids and correction masks must have the same length",
1018 ));
1019 }
1020 let expected_words = crate::word_count(self.shots);
1021 for (observable_id, mask) in self.observable_ids.iter().zip(&self.masks) {
1022 if mask.words.len() != expected_words {
1023 return Err(NpError::new(format!(
1024 "correction mask for observable id {observable_id} has {} words; expected {expected_words} for {} shots",
1025 mask.words.len(),
1026 self.shots
1027 )));
1028 }
1029 validate_zero_mask_padding(
1030 mask,
1031 self.shots,
1032 &format!("correction mask {observable_id}"),
1033 )?;
1034 }
1035 for (index, observable_id) in self.observable_ids.iter().enumerate() {
1036 if self.observable_ids[..index].contains(observable_id) {
1037 return Err(NpError::new(format!(
1038 "duplicate correction observable id {observable_id}"
1039 )));
1040 }
1041 }
1042 Ok(())
1043 }
1044}
1045
1046#[derive(Debug, Clone, PartialEq)]
1048pub enum DecoderCorrectionBatch {
1049 Masks(CorrectionMaskBatch),
1050 Packed(PackedObservableShotBatch),
1051}
1052
1053impl DecoderCorrectionBatch {
1054 pub const fn format(&self) -> DetectorBatchFormat {
1055 match self {
1056 Self::Masks(_) => DetectorBatchFormat::Masks,
1057 Self::Packed(_) => DetectorBatchFormat::Packed,
1058 }
1059 }
1060
1061 pub const fn shots(&self) -> usize {
1062 match self {
1063 Self::Masks(batch) => batch.shots,
1064 Self::Packed(batch) => batch.shots,
1065 }
1066 }
1067
1068 pub fn validate_against(&self, observable_ids: &[i64], shots: usize) -> NpResult<()> {
1069 match self {
1070 Self::Masks(batch) => batch.validate_against(observable_ids, shots),
1071 Self::Packed(batch) => batch.validate_against(observable_ids, shots),
1072 }
1073 }
1074
1075 pub fn into_masks(self) -> NpResult<CorrectionMaskBatch> {
1076 match self {
1077 Self::Masks(batch) => Ok(batch),
1078 Self::Packed(batch) => packed_corrections_to_masks(batch),
1079 }
1080 }
1081
1082 pub fn into_packed(self) -> NpResult<PackedObservableShotBatch> {
1083 match self {
1084 Self::Masks(batch) => mask_corrections_to_packed(batch),
1085 Self::Packed(batch) => Ok(batch),
1086 }
1087 }
1088}
1089
1090pub fn mask_corrections_to_packed(
1091 batch: CorrectionMaskBatch,
1092) -> NpResult<PackedObservableShotBatch> {
1093 batch.validate_shape()?;
1094 let observable_byte_count = batch.observable_ids.len().div_ceil(8);
1095 let len = batch
1096 .shots
1097 .checked_mul(observable_byte_count)
1098 .ok_or_else(|| NpError::new("packed correction conversion length overflowed usize"))?;
1099 let mut data = vec![0u8; len];
1100 for (observable, mask) in batch.masks.iter().enumerate() {
1101 for shot in 0..batch.shots {
1102 if mask.words[shot >> 6] & (1u64 << (shot & 63)) != 0 {
1103 data[shot * observable_byte_count + (observable >> 3)] |= 1u8 << (observable & 7);
1104 }
1105 }
1106 }
1107 PackedObservableShotBatch::new(batch.observable_ids, data, batch.shots)
1108}
1109
1110pub fn packed_corrections_to_masks(
1111 batch: PackedObservableShotBatch,
1112) -> NpResult<CorrectionMaskBatch> {
1113 batch.validate_shape()?;
1114 let mut masks = vec![Mask::zero(crate::word_count(batch.shots)); batch.observable_ids.len()];
1115 for shot in 0..batch.shots {
1116 let row = shot * batch.observable_byte_count;
1117 for (observable, mask) in masks.iter_mut().enumerate() {
1118 if batch.data[row + (observable >> 3)] & (1u8 << (observable & 7)) != 0 {
1119 mask.words[shot >> 6] |= 1u64 << (shot & 63);
1120 }
1121 }
1122 }
1123 CorrectionMaskBatch::new(batch.observable_ids, masks, batch.shots)
1124}
1125
1126pub trait NativeDecoderFactory: Send + Sync {
1127 fn name(&self) -> &str;
1128 fn detector_ids(&self) -> &[i64];
1130 fn observable_ids(&self) -> &[i64];
1131 fn batch_formats(&self) -> &[DetectorBatchFormat];
1133 fn create_worker(&self) -> NpResult<Box<dyn NativeDecoderWorker>>;
1134}
1135
1136pub trait NativeDecoderWorker: Send {
1137 fn name(&self) -> &str;
1138 fn detector_ids(&self) -> &[i64];
1140 fn observable_ids(&self) -> &[i64];
1141 fn batch_formats(&self) -> &[DetectorBatchFormat];
1143 fn decode_batch(
1144 &mut self,
1145 detectors: DetectorBatchView<'_>,
1146 ) -> NpResult<DecoderCorrectionBatch>;
1147
1148 fn decode_batch_checked(
1149 &mut self,
1150 detectors: DetectorBatchView<'_>,
1151 ) -> NpResult<DecoderCorrectionBatch> {
1152 validate_decoder_batch_formats(self.batch_formats())?;
1153 detectors.validate_shape()?;
1154 if detectors.detector_ids() != self.detector_ids() {
1155 return Err(NpError::new(format!(
1156 "decoder `{}` received detector ids {:?}; expected {:?}",
1157 self.name(),
1158 detectors.detector_ids(),
1159 self.detector_ids()
1160 )));
1161 }
1162 if !self.batch_formats().contains(&detectors.format()) {
1163 return Err(NpError::new(format!(
1164 "decoder `{}` does not declare support for {:?} detector batches",
1165 self.name(),
1166 detectors.format()
1167 )));
1168 }
1169 let shots = detectors.shots();
1170 let expected_format = detectors.format().correction_format();
1171 let corrections = self.decode_batch(detectors)?;
1172 if corrections.format() != expected_format {
1173 return Err(NpError::new(format!(
1174 "decoder `{}` returned {:?} corrections for {:?} detector input; expected {:?} corrections",
1175 self.name(),
1176 corrections.format(),
1177 detectors.format(),
1178 expected_format
1179 )));
1180 }
1181 corrections.validate_against(self.observable_ids(), shots)?;
1182 Ok(corrections)
1183 }
1184}
1185
1186pub fn validate_decoder_batch_formats(formats: &[DetectorBatchFormat]) -> NpResult<()> {
1188 if formats.is_empty() {
1189 return Err(NpError::new(
1190 "native decoder batch format preference list must not be empty",
1191 ));
1192 }
1193 let mut seen = [false; 3];
1194 for &format in formats {
1195 let index = match format {
1196 DetectorBatchFormat::Masks => 0,
1197 DetectorBatchFormat::Packed => 1,
1198 DetectorBatchFormat::Events => 2,
1199 };
1200 if std::mem::replace(&mut seen[index], true) {
1201 return Err(NpError::new(format!(
1202 "native decoder batch format preference list contains duplicate format {format:?}"
1203 )));
1204 }
1205 }
1206 Ok(())
1207}
1208
1209pub fn select_detector_batch_format(
1212 decoder_formats: &[DetectorBatchFormat],
1213 producer_formats: &[DetectorBatchFormat],
1214) -> NpResult<DetectorBatchFormat> {
1215 validate_decoder_batch_formats(decoder_formats)?;
1216 if producer_formats.is_empty() {
1217 return Err(NpError::new(
1218 "detector batch producer format list must not be empty",
1219 ));
1220 }
1221 Ok(decoder_formats
1222 .iter()
1223 .copied()
1224 .find(|format| producer_formats.contains(format))
1225 .unwrap_or(decoder_formats[0]))
1226}
1227
1228const MASKS_BATCH_FORMATS: [DetectorBatchFormat; 1] = [DetectorBatchFormat::Masks];
1229#[cfg(feature = "decoder-fusion-blossom")]
1230const PACKED_BATCH_FORMATS: [DetectorBatchFormat; 1] = [DetectorBatchFormat::Packed];
1231const ALL_BATCH_FORMATS: [DetectorBatchFormat; 3] = DetectorBatchFormat::STABLE_ORDER;
1232
1233pub fn validate_decoder_detector_ids(detector_ids: &[i64]) -> NpResult<()> {
1235 validate_decoder_ids(detector_ids, "detector")
1236}
1237
1238pub fn validate_decoder_observable_ids(observable_ids: &[i64]) -> NpResult<()> {
1240 validate_decoder_ids(observable_ids, "observable")
1241}
1242
1243fn validate_decoder_ids(ids: &[i64], kind: &str) -> NpResult<()> {
1244 let mut seen = HashSet::with_capacity(ids.len());
1245 for &id in ids {
1246 if !seen.insert(id) {
1247 return Err(NpError::new(format!(
1248 "decoder {kind} ids must be unique; duplicate {kind} id {id}"
1249 )));
1250 }
1251 }
1252 Ok(())
1253}
1254
1255pub struct NativeCompositeDecoder {
1256 children: Vec<Arc<dyn NativeDecoderFactory>>,
1257 detector_ids: Vec<i64>,
1258 observable_ids: Vec<i64>,
1259 observable_indices: HashMap<i64, usize>,
1260 child_plans: Vec<CompositeChildPlan>,
1261 batch_formats: Vec<DetectorBatchFormat>,
1262}
1263
1264#[derive(Clone)]
1265struct CompositeChildPlan {
1266 detector_indices: Vec<usize>,
1267 detector_ids: Vec<i64>,
1268 global_to_local: Vec<Option<usize>>,
1269}
1270
1271impl std::fmt::Debug for NativeCompositeDecoder {
1272 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1273 formatter
1274 .debug_struct("NativeCompositeDecoder")
1275 .field("detector_ids", &self.detector_ids)
1276 .field("observable_ids", &self.observable_ids)
1277 .field("child_count", &self.children.len())
1278 .finish()
1279 }
1280}
1281
1282impl NativeCompositeDecoder {
1283 pub fn new(children: Vec<Arc<dyn NativeDecoderFactory>>) -> NpResult<Self> {
1284 if children.is_empty() {
1285 return Err(NpError::new(
1286 "native composite decoder requires at least one child decoder",
1287 ));
1288 }
1289 let mut detector_ids = Vec::new();
1290 let mut detector_indices = HashMap::new();
1291 let mut observable_ids = Vec::new();
1292 let mut seen_observables = HashSet::new();
1293 let mut child_detector_indices = Vec::with_capacity(children.len());
1294 for (child_index, child) in children.iter().enumerate() {
1295 validate_decoder_batch_formats(child.batch_formats()).map_err(|err| {
1296 NpError::new(format!(
1297 "native composite decoder child {child_index} (`{}`) has invalid batch format metadata: {}",
1298 child.name(),
1299 err.message()
1300 ))
1301 })?;
1302 validate_decoder_detector_ids(child.detector_ids()).map_err(|err| {
1303 NpError::new(format!(
1304 "native composite decoder child {child_index} (`{}`) has invalid detector metadata: {}",
1305 child.name(),
1306 err.message()
1307 ))
1308 })?;
1309 let mut indices = Vec::with_capacity(child.detector_ids().len());
1310 for &detector_id in child.detector_ids() {
1311 let index = *detector_indices.entry(detector_id).or_insert_with(|| {
1312 let index = detector_ids.len();
1313 detector_ids.push(detector_id);
1314 index
1315 });
1316 indices.push(index);
1317 }
1318 child_detector_indices.push(indices);
1319 for &observable_id in child.observable_ids() {
1320 if !seen_observables.insert(observable_id) {
1321 return Err(NpError::new(format!(
1322 "native composite decoder has duplicate observable id {observable_id}"
1323 )));
1324 }
1325 observable_ids.push(observable_id);
1326 }
1327 }
1328 let observable_indices = observable_ids
1329 .iter()
1330 .copied()
1331 .enumerate()
1332 .map(|(index, id)| (id, index))
1333 .collect();
1334 let child_plans = child_detector_indices
1335 .into_iter()
1336 .map(|detector_indices| {
1337 let mut mapping = vec![None; detector_ids.len()];
1338 for (local, &global) in detector_indices.iter().enumerate() {
1339 mapping[global] = Some(local);
1340 }
1341 let child_detector_ids = detector_indices
1342 .iter()
1343 .map(|&index| detector_ids[index])
1344 .collect();
1345 CompositeChildPlan {
1346 detector_indices,
1347 detector_ids: child_detector_ids,
1348 global_to_local: mapping,
1349 }
1350 })
1351 .collect();
1352 let mut batch_formats = DetectorBatchFormat::STABLE_ORDER.to_vec();
1353 batch_formats.sort_by_key(|format| {
1354 let conversion_count = children
1355 .iter()
1356 .filter(|child| !child.batch_formats().contains(format))
1357 .count();
1358 let preference_rank = children
1359 .iter()
1360 .map(|child| {
1361 child
1362 .batch_formats()
1363 .iter()
1364 .position(|candidate| candidate == format)
1365 .unwrap_or(0)
1366 })
1367 .sum::<usize>();
1368 let stable_rank = DetectorBatchFormat::STABLE_ORDER
1369 .iter()
1370 .position(|candidate| candidate == format)
1371 .expect("candidate is in the stable format order");
1372 (conversion_count, preference_rank, stable_rank)
1373 });
1374 Ok(Self {
1375 children,
1376 detector_ids,
1377 observable_ids,
1378 observable_indices,
1379 child_plans,
1380 batch_formats,
1381 })
1382 }
1383}
1384
1385impl NativeDecoderFactory for NativeCompositeDecoder {
1386 fn name(&self) -> &str {
1387 "composite"
1388 }
1389
1390 fn detector_ids(&self) -> &[i64] {
1391 &self.detector_ids
1392 }
1393
1394 fn observable_ids(&self) -> &[i64] {
1395 &self.observable_ids
1396 }
1397
1398 fn batch_formats(&self) -> &[DetectorBatchFormat] {
1399 &self.batch_formats
1400 }
1401
1402 fn create_worker(&self) -> NpResult<Box<dyn NativeDecoderWorker>> {
1403 let children = self
1404 .children
1405 .iter()
1406 .enumerate()
1407 .map(|(index, child)| {
1408 let worker = child.create_worker().map_err(|err| {
1409 NpError::new(format!(
1410 "composite decoder `{}` child {index} (`{}`) worker factory failed: {}",
1411 self.name(),
1412 child.name(),
1413 err.message()
1414 ))
1415 })?;
1416 if worker.name() != child.name() {
1417 return Err(NpError::new(format!(
1418 "composite decoder `{}` child {index} (`{}`) worker name `{}` does not match factory name",
1419 self.name(),
1420 child.name(),
1421 worker.name()
1422 )));
1423 }
1424 if worker.detector_ids() != child.detector_ids() {
1425 return Err(NpError::new(format!(
1426 "composite decoder `{}` child {index} (`{}`) worker detector ids {:?} do not match factory detector ids {:?}",
1427 self.name(),
1428 child.name(),
1429 worker.detector_ids(),
1430 child.detector_ids()
1431 )));
1432 }
1433 if worker.observable_ids() != child.observable_ids() {
1434 return Err(NpError::new(format!(
1435 "composite decoder `{}` child {index} (`{}`) worker observable ids {:?} do not match factory observable ids {:?}",
1436 self.name(),
1437 child.name(),
1438 worker.observable_ids(),
1439 child.observable_ids()
1440 )));
1441 }
1442 validate_decoder_batch_formats(worker.batch_formats())?;
1443 if worker.batch_formats() != child.batch_formats() {
1444 return Err(NpError::new(format!(
1445 "composite decoder `{}` child {index} (`{}`) worker batch formats {:?} do not match factory batch formats {:?}",
1446 self.name(),
1447 child.name(),
1448 worker.batch_formats(),
1449 child.batch_formats()
1450 )));
1451 }
1452 Ok(worker)
1453 })
1454 .collect::<NpResult<Vec<_>>>()?;
1455 Ok(Box::new(NativeCompositeDecoderWorker {
1456 children,
1457 detector_ids: self.detector_ids.clone(),
1458 observable_ids: self.observable_ids.clone(),
1459 observable_indices: self.observable_indices.clone(),
1460 child_plans: self.child_plans.clone(),
1461 batch_formats: self.batch_formats.clone(),
1462 }))
1463 }
1464}
1465
1466struct NativeCompositeDecoderWorker {
1467 children: Vec<Box<dyn NativeDecoderWorker>>,
1468 detector_ids: Vec<i64>,
1469 observable_ids: Vec<i64>,
1470 observable_indices: HashMap<i64, usize>,
1471 child_plans: Vec<CompositeChildPlan>,
1472 batch_formats: Vec<DetectorBatchFormat>,
1473}
1474
1475impl NativeCompositeDecoderWorker {
1476 fn validate_detector_order(&self, detector_ids: &[i64]) -> NpResult<()> {
1477 if detector_ids != self.detector_ids {
1478 return Err(NpError::new(
1479 "native composite decoder received detectors in an unexpected order",
1480 ));
1481 }
1482 Ok(())
1483 }
1484
1485 fn merge_packed_child(
1486 observable_ids: &[i64],
1487 observable_indices: &HashMap<i64, usize>,
1488 output: &mut [u8],
1489 child: &PackedObservableShotBatch,
1490 ) -> NpResult<()> {
1491 let output_byte_count = observable_ids.len().div_ceil(8);
1492 for shot in 0..child.shots {
1493 for (child_index, observable_id) in child.observable_ids.iter().enumerate() {
1494 if child.data[shot * child.observable_byte_count + (child_index >> 3)]
1495 & (1 << (child_index & 7))
1496 == 0
1497 {
1498 continue;
1499 }
1500 let output_index = observable_indices.get(observable_id).ok_or_else(|| {
1501 NpError::new(format!(
1502 "native composite child returned unknown observable id {observable_id}"
1503 ))
1504 })?;
1505 output[shot * output_byte_count + (output_index >> 3)] |= 1 << (output_index & 7);
1506 }
1507 }
1508 Ok(())
1509 }
1510
1511 fn project_batch(
1512 source: DetectorBatchView<'_>,
1513 plan: &CompositeChildPlan,
1514 ) -> NpResult<DetectorBatch> {
1515 match source {
1516 DetectorBatchView::Masks(view) => DetectorBatch::Masks {
1517 detector_ids: plan.detector_ids.clone(),
1518 masks: plan
1519 .detector_indices
1520 .iter()
1521 .map(|index| view.masks[*index].clone())
1522 .collect(),
1523 shots: view.shots,
1524 }
1525 .validated_shape(),
1526 DetectorBatchView::Packed(view) => {
1527 let child_byte_count = plan.detector_indices.len().div_ceil(8);
1528 let len = view.shots.checked_mul(child_byte_count).ok_or_else(|| {
1529 NpError::new("composite packed detector projection length overflowed usize")
1530 })?;
1531 let mut data = vec![0u8; len];
1532 for shot in 0..view.shots {
1533 for (child_detector, source_detector) in
1534 plan.detector_indices.iter().copied().enumerate()
1535 {
1536 if view.data[shot * view.detector_byte_count + (source_detector >> 3)]
1537 & (1u8 << (source_detector & 7))
1538 != 0
1539 {
1540 data[shot * child_byte_count + (child_detector >> 3)] |=
1541 1u8 << (child_detector & 7);
1542 }
1543 }
1544 }
1545 DetectorBatch::Packed {
1546 detector_ids: plan.detector_ids.clone(),
1547 data,
1548 shots: view.shots,
1549 detector_byte_count: child_byte_count,
1550 }
1551 .validated_shape()
1552 }
1553 DetectorBatchView::Events(view) => {
1554 let mut offsets = empty_detector_event_offsets(view.shots)?;
1555 let mut events = Vec::new();
1556 for shot in 0..view.shots {
1557 for source_detector in &view.events[view.offsets[shot]..view.offsets[shot + 1]]
1558 {
1559 if let Some(child_detector) = plan.global_to_local[*source_detector] {
1560 events.push(child_detector);
1561 }
1562 }
1563 offsets.push(events.len());
1564 }
1565 DetectorBatch::Events {
1566 detector_ids: plan.detector_ids.clone(),
1567 offsets,
1568 events,
1569 shots: view.shots,
1570 }
1571 .validated_shape()
1572 }
1573 }
1574 }
1575}
1576
1577trait ValidatedDetectorBatch {
1578 fn validated_shape(self) -> NpResult<DetectorBatch>;
1579}
1580
1581impl ValidatedDetectorBatch for DetectorBatch {
1582 fn validated_shape(self) -> NpResult<DetectorBatch> {
1583 self.validate_shape()?;
1584 Ok(self)
1585 }
1586}
1587
1588impl NativeDecoderWorker for NativeCompositeDecoderWorker {
1589 fn name(&self) -> &str {
1590 "composite"
1591 }
1592
1593 fn detector_ids(&self) -> &[i64] {
1594 &self.detector_ids
1595 }
1596
1597 fn observable_ids(&self) -> &[i64] {
1598 &self.observable_ids
1599 }
1600
1601 fn batch_formats(&self) -> &[DetectorBatchFormat] {
1602 &self.batch_formats
1603 }
1604
1605 fn decode_batch(
1606 &mut self,
1607 detectors: DetectorBatchView<'_>,
1608 ) -> NpResult<DecoderCorrectionBatch> {
1609 self.validate_detector_order(detectors.detector_ids())?;
1610 detectors.validate_shape()?;
1611 let input_format = detectors.format();
1612 let shots = detectors.shots();
1613
1614 let child_targets = self
1615 .children
1616 .iter()
1617 .map(|child| {
1618 if child.batch_formats().contains(&input_format) {
1619 input_format
1620 } else {
1621 child.batch_formats()[0]
1622 }
1623 })
1624 .collect::<Vec<_>>();
1625 let mut shared = Vec::<(DetectorBatchFormat, DetectorBatch)>::new();
1626 for target in child_targets.iter().copied() {
1627 if !shared.iter().any(|(format, _)| *format == target) {
1628 shared.push((
1629 target,
1630 convert_detector_batch_prevalidated(detectors, target)?,
1631 ));
1632 }
1633 }
1634
1635 let mut mask_output = (input_format == DetectorBatchFormat::Masks)
1636 .then(|| vec![Mask::zero(crate::word_count(shots)); self.observable_ids.len()]);
1637 let mut packed_output = (input_format != DetectorBatchFormat::Masks)
1638 .then(|| PackedObservableShotBatch::zero(self.observable_ids.clone(), shots))
1639 .transpose()?;
1640
1641 for (((child, plan), target), child_index) in self
1642 .children
1643 .iter_mut()
1644 .zip(&self.child_plans)
1645 .zip(child_targets)
1646 .zip(0usize..)
1647 {
1648 let source = shared
1649 .iter()
1650 .find_map(|(format, batch)| (*format == target).then(|| batch.view()))
1651 .expect("shared conversion exists for every child target");
1652 let child_batch = Self::project_batch(source, plan)?;
1653 let corrections = child
1654 .decode_batch_checked(child_batch.view())
1655 .map_err(|err| {
1656 NpError::new(format!(
1657 "composite decoder child {child_index} (`{}`) failed: {}",
1658 child.name(),
1659 err.message()
1660 ))
1661 })?;
1662 if let Some(output) = &mut mask_output {
1663 let corrections = corrections.into_masks()?;
1664 for (observable_id, mask) in corrections
1665 .observable_ids
1666 .into_iter()
1667 .zip(corrections.masks)
1668 {
1669 let output_index =
1670 self.observable_indices.get(&observable_id).ok_or_else(|| {
1671 NpError::new(format!(
1672 "native composite child returned unknown observable id {observable_id}"
1673 ))
1674 })?;
1675 output[*output_index] = mask;
1676 }
1677 } else if let Some(output) = &mut packed_output {
1678 let corrections = corrections.into_packed()?;
1679 Self::merge_packed_child(
1680 &self.observable_ids,
1681 &self.observable_indices,
1682 &mut output.data,
1683 &corrections,
1684 )?;
1685 }
1686 }
1687
1688 if let Some(masks) = mask_output {
1689 Ok(DecoderCorrectionBatch::Masks(CorrectionMaskBatch::new(
1690 self.observable_ids.clone(),
1691 masks,
1692 shots,
1693 )?))
1694 } else {
1695 Ok(DecoderCorrectionBatch::Packed(
1696 packed_output.expect("non-mask inputs allocate packed output"),
1697 ))
1698 }
1699 }
1700}
1701
1702#[derive(Debug, Clone, PartialEq)]
1703pub struct NativeNoCorrectionDecoder {
1704 detector_ids: Vec<i64>,
1705 observable_ids: Vec<i64>,
1706}
1707
1708impl NativeNoCorrectionDecoder {
1709 pub fn new(observable_ids: Vec<i64>) -> Self {
1710 Self {
1711 detector_ids: Vec::new(),
1712 observable_ids,
1713 }
1714 }
1715
1716 pub fn with_detector_ids(detector_ids: Vec<i64>, observable_ids: Vec<i64>) -> NpResult<Self> {
1717 validate_decoder_detector_ids(&detector_ids)?;
1718 Ok(Self {
1719 detector_ids,
1720 observable_ids,
1721 })
1722 }
1723}
1724
1725impl NativeDecoderFactory for NativeNoCorrectionDecoder {
1726 fn name(&self) -> &str {
1727 "no-correction"
1728 }
1729
1730 fn detector_ids(&self) -> &[i64] {
1731 &self.detector_ids
1732 }
1733
1734 fn observable_ids(&self) -> &[i64] {
1735 &self.observable_ids
1736 }
1737
1738 fn batch_formats(&self) -> &[DetectorBatchFormat] {
1739 &ALL_BATCH_FORMATS
1740 }
1741
1742 fn create_worker(&self) -> NpResult<Box<dyn NativeDecoderWorker>> {
1743 Ok(Box::new(NativeNoCorrectionDecoderWorker {
1744 detector_ids: self.detector_ids.clone(),
1745 observable_ids: self.observable_ids.clone(),
1746 }))
1747 }
1748}
1749
1750#[derive(Debug)]
1751struct NativeNoCorrectionDecoderWorker {
1752 detector_ids: Vec<i64>,
1753 observable_ids: Vec<i64>,
1754}
1755
1756impl NativeDecoderWorker for NativeNoCorrectionDecoderWorker {
1757 fn name(&self) -> &str {
1758 "no-correction"
1759 }
1760
1761 fn detector_ids(&self) -> &[i64] {
1762 &self.detector_ids
1763 }
1764
1765 fn observable_ids(&self) -> &[i64] {
1766 &self.observable_ids
1767 }
1768
1769 fn batch_formats(&self) -> &[DetectorBatchFormat] {
1770 &ALL_BATCH_FORMATS
1771 }
1772
1773 fn decode_batch(
1774 &mut self,
1775 detectors: DetectorBatchView<'_>,
1776 ) -> NpResult<DecoderCorrectionBatch> {
1777 match detectors {
1778 DetectorBatchView::Masks(view) => {
1779 Ok(DecoderCorrectionBatch::Masks(CorrectionMaskBatch::new(
1780 self.observable_ids.clone(),
1781 vec![Mask::zero(crate::word_count(view.shots)); self.observable_ids.len()],
1782 view.shots,
1783 )?))
1784 }
1785 DetectorBatchView::Packed(view) => Ok(DecoderCorrectionBatch::Packed(
1786 PackedObservableShotBatch::zero(self.observable_ids.clone(), view.shots)?,
1787 )),
1788 DetectorBatchView::Events(view) => Ok(DecoderCorrectionBatch::Packed(
1789 PackedObservableShotBatch::zero(self.observable_ids.clone(), view.shots)?,
1790 )),
1791 }
1792 }
1793}
1794
1795#[derive(Debug, Clone, PartialEq)]
1796pub struct NativeGraphlikeDetectorCopyDecoder {
1797 detector_ids: Vec<i64>,
1798 observable_ids: Vec<i64>,
1799 observable_detector_indices: Vec<Option<usize>>,
1800}
1801
1802impl NativeGraphlikeDetectorCopyDecoder {
1803 pub fn from_graphlike_problem(problem: GraphlikeDecodingProblem) -> NpResult<Self> {
1804 let detector_count = problem.detector_ids().len();
1805 let observable_count = problem.observable_ids().len();
1806 let mut observable_detector_indices = vec![None; observable_count];
1807 for edge in problem.iter_edges() {
1808 if edge.detector_count() != 1 || edge.fault_observables().len() != 1 {
1809 continue;
1810 }
1811 let detector_index = edge
1812 .detectors()
1813 .next()
1814 .expect("single-detector edge has one detector");
1815 let observable_index = edge
1816 .fault_observables()
1817 .next()
1818 .expect("single-observable edge has one observable");
1819 if detector_index >= detector_count {
1820 return Err(NpError::new(format!(
1821 "graphlike-detector-copy edge {} references detector index {} but only {} detectors exist",
1822 edge.dem_edge_index(),
1823 detector_index,
1824 detector_count
1825 )));
1826 }
1827 if observable_index >= observable_count {
1828 return Err(NpError::new(format!(
1829 "graphlike-detector-copy edge {} references observable index {} but only {} observables exist",
1830 edge.dem_edge_index(),
1831 observable_index,
1832 observable_count
1833 )));
1834 }
1835 if let Some(existing_detector_index) = observable_detector_indices[observable_index] {
1836 return Err(NpError::new(format!(
1837 "graphlike-detector-copy found multiple single-detector candidate edges for observable id {}; detector indices {} and {}",
1838 problem.observable_ids()[observable_index],
1839 existing_detector_index,
1840 detector_index
1841 )));
1842 }
1843 observable_detector_indices[observable_index] = Some(detector_index);
1844 }
1845 let (detector_ids, observable_ids) = problem.into_ids();
1846 Ok(Self {
1847 detector_ids,
1848 observable_ids,
1849 observable_detector_indices,
1850 })
1851 }
1852
1853 pub fn observable_detector_indices(&self) -> &[Option<usize>] {
1854 &self.observable_detector_indices
1855 }
1856}
1857
1858impl NativeDecoderFactory for NativeGraphlikeDetectorCopyDecoder {
1859 fn name(&self) -> &str {
1860 "graphlike-detector-copy"
1861 }
1862
1863 fn detector_ids(&self) -> &[i64] {
1864 &self.detector_ids
1865 }
1866
1867 fn observable_ids(&self) -> &[i64] {
1868 &self.observable_ids
1869 }
1870
1871 fn batch_formats(&self) -> &[DetectorBatchFormat] {
1872 &MASKS_BATCH_FORMATS
1873 }
1874
1875 fn create_worker(&self) -> NpResult<Box<dyn NativeDecoderWorker>> {
1876 Ok(Box::new(NativeGraphlikeDetectorCopyDecoderWorker {
1877 detector_ids: self.detector_ids.clone(),
1878 observable_ids: self.observable_ids.clone(),
1879 observable_detector_indices: self.observable_detector_indices.clone(),
1880 }))
1881 }
1882}
1883
1884#[derive(Debug)]
1885struct NativeGraphlikeDetectorCopyDecoderWorker {
1886 detector_ids: Vec<i64>,
1887 observable_ids: Vec<i64>,
1888 observable_detector_indices: Vec<Option<usize>>,
1889}
1890
1891impl NativeDecoderWorker for NativeGraphlikeDetectorCopyDecoderWorker {
1892 fn name(&self) -> &str {
1893 "graphlike-detector-copy"
1894 }
1895
1896 fn detector_ids(&self) -> &[i64] {
1897 &self.detector_ids
1898 }
1899
1900 fn observable_ids(&self) -> &[i64] {
1901 &self.observable_ids
1902 }
1903
1904 fn batch_formats(&self) -> &[DetectorBatchFormat] {
1905 &MASKS_BATCH_FORMATS
1906 }
1907
1908 fn decode_batch(
1909 &mut self,
1910 detectors: DetectorBatchView<'_>,
1911 ) -> NpResult<DecoderCorrectionBatch> {
1912 let DetectorBatchView::Masks(detectors) = detectors else {
1913 return Err(NpError::new(
1914 "graphlike-detector-copy only accepts Masks detector batches",
1915 ));
1916 };
1917 if detectors.detector_ids != self.detector_ids.as_slice() {
1918 return Err(NpError::new(
1919 "graphlike-detector-copy received detector masks in an unexpected order",
1920 ));
1921 }
1922 let words = crate::word_count(detectors.shots);
1923 let masks = self
1924 .observable_detector_indices
1925 .iter()
1926 .map(|detector_index| match detector_index {
1927 Some(detector_index) => detectors
1928 .masks
1929 .get(*detector_index)
1930 .cloned()
1931 .ok_or_else(|| {
1932 NpError::new(format!(
1933 "graphlike-detector-copy missing detector mask at index {detector_index}"
1934 ))
1935 }),
1936 None => Ok(Mask::zero(words)),
1937 })
1938 .collect::<NpResult<Vec<_>>>()?;
1939 Ok(DecoderCorrectionBatch::Masks(CorrectionMaskBatch::new(
1940 self.observable_ids.clone(),
1941 masks,
1942 detectors.shots,
1943 )?))
1944 }
1945}
1946
1947#[cfg(feature = "decoder-fusion-blossom")]
1948#[derive(Debug, Clone, PartialEq)]
1949pub struct NativeFusionBlossomDecoder {
1950 detector_ids: Vec<i64>,
1951 observable_ids: Vec<i64>,
1952 edge_count: usize,
1953}
1954
1955#[cfg(feature = "decoder-fusion-blossom")]
1956impl NativeFusionBlossomDecoder {
1957 pub fn from_graphlike_problem(problem: GraphlikeDecodingProblem) -> NpResult<Self> {
1958 let edge_count = problem.edge_count();
1959 let (detector_ids, observable_ids) = problem.into_ids();
1960 Ok(Self {
1961 detector_ids,
1962 observable_ids,
1963 edge_count,
1964 })
1965 }
1966
1967 pub fn edge_count(&self) -> usize {
1968 self.edge_count
1969 }
1970
1971 fn unavailable_error() -> NpError {
1972 NpError::new(
1973 "fusion-blossom native backend scaffold is compiled, but no stable Rust dependency is linked yet",
1974 )
1975 }
1976}
1977
1978#[cfg(feature = "decoder-fusion-blossom")]
1979impl NativeDecoderFactory for NativeFusionBlossomDecoder {
1980 fn name(&self) -> &str {
1981 "fusion-blossom"
1982 }
1983
1984 fn detector_ids(&self) -> &[i64] {
1985 &self.detector_ids
1986 }
1987
1988 fn observable_ids(&self) -> &[i64] {
1989 &self.observable_ids
1990 }
1991
1992 fn batch_formats(&self) -> &[DetectorBatchFormat] {
1993 &PACKED_BATCH_FORMATS
1994 }
1995
1996 fn create_worker(&self) -> NpResult<Box<dyn NativeDecoderWorker>> {
1997 Ok(Box::new(NativeFusionBlossomDecoderWorker {
1998 detector_ids: self.detector_ids.clone(),
1999 observable_ids: self.observable_ids.clone(),
2000 }))
2001 }
2002}
2003
2004#[cfg(feature = "decoder-fusion-blossom")]
2005#[derive(Debug)]
2006struct NativeFusionBlossomDecoderWorker {
2007 detector_ids: Vec<i64>,
2008 observable_ids: Vec<i64>,
2009}
2010
2011#[cfg(feature = "decoder-fusion-blossom")]
2012impl NativeDecoderWorker for NativeFusionBlossomDecoderWorker {
2013 fn name(&self) -> &str {
2014 "fusion-blossom"
2015 }
2016
2017 fn detector_ids(&self) -> &[i64] {
2018 &self.detector_ids
2019 }
2020
2021 fn observable_ids(&self) -> &[i64] {
2022 &self.observable_ids
2023 }
2024
2025 fn batch_formats(&self) -> &[DetectorBatchFormat] {
2026 &PACKED_BATCH_FORMATS
2027 }
2028
2029 fn decode_batch(
2030 &mut self,
2031 _detectors: DetectorBatchView<'_>,
2032 ) -> NpResult<DecoderCorrectionBatch> {
2033 Err(NativeFusionBlossomDecoder::unavailable_error())
2034 }
2035}
2036
2037pub fn logical_residual_loss_mask_native(
2038 observables: &HashMap<i64, Mask>,
2039 corrections: &CorrectionMaskBatch,
2040 observable_ids: &[i64],
2041 all_mask: &Mask,
2042) -> Mask {
2043 let mut ids = observable_ids.to_vec();
2044 for observable_id in observables.keys() {
2045 if !ids.contains(observable_id) {
2046 ids.push(*observable_id);
2047 }
2048 }
2049 for observable_id in &corrections.observable_ids {
2050 if !ids.contains(observable_id) {
2051 ids.push(*observable_id);
2052 }
2053 }
2054
2055 let mut loss = Mask::zero(all_mask.words.len());
2056 let zero = Mask::zero(all_mask.words.len());
2057 for observable_id in ids {
2058 let observable = observables.get(&observable_id).unwrap_or(&zero);
2059 let correction = corrections.get(observable_id).unwrap_or(&zero);
2060 let mut residual = observable.clone();
2061 residual.xor_assign(correction);
2062 loss.or_assign(&residual);
2063 }
2064 loss.and_assign(all_mask);
2065 loss
2066}
2067
2068#[cfg(test)]
2069mod tests {
2070 use super::*;
2071 use crate::GraphlikeEdge;
2072 use std::sync::Arc;
2073
2074 struct FixedCorrectionDecoder {
2075 detector_ids: Vec<i64>,
2076 observable_ids: Vec<i64>,
2077 correction: Mask,
2078 }
2079
2080 struct FixedCorrectionDecoderWorker {
2081 detector_ids: Vec<i64>,
2082 observable_ids: Vec<i64>,
2083 correction: Mask,
2084 }
2085
2086 struct FastCopyDecoder {
2087 detector_ids: Vec<i64>,
2088 observable_ids: Vec<i64>,
2089 }
2090
2091 struct FastCopyDecoderWorker {
2092 detector_ids: Vec<i64>,
2093 observable_ids: Vec<i64>,
2094 }
2095
2096 struct SingleFormatCopyDecoder {
2097 detector_ids: Vec<i64>,
2098 observable_ids: Vec<i64>,
2099 formats: Vec<DetectorBatchFormat>,
2100 }
2101
2102 struct SingleFormatCopyDecoderWorker {
2103 detector_ids: Vec<i64>,
2104 observable_ids: Vec<i64>,
2105 formats: Vec<DetectorBatchFormat>,
2106 }
2107
2108 fn graphlike_edges() -> Vec<GraphlikeEdge> {
2109 vec![
2110 GraphlikeEdge {
2111 detectors: vec![1],
2112 fault_observables: vec![0],
2113 probability: 0.1,
2114 dem_edge_index: 0,
2115 },
2116 GraphlikeEdge {
2117 detectors: vec![0, 1],
2118 fault_observables: vec![1],
2119 probability: 0.2,
2120 dem_edge_index: 1,
2121 },
2122 ]
2123 }
2124
2125 fn graphlike_problem() -> GraphlikeDecodingProblem {
2126 GraphlikeDecodingProblem::new(
2127 vec![10, 20],
2128 vec![Vec::new(), Vec::new()],
2129 vec![0, 1],
2130 graphlike_edges(),
2131 )
2132 .unwrap()
2133 }
2134
2135 #[test]
2136 fn packed_residual_count_uses_the_canonical_layout_path() {
2137 let empty_corrections = PackedObservableShotBatch::zero(vec![], 3).unwrap();
2138 assert_eq!(
2139 packed_residual_failure_count(&[], &[], 0, &empty_corrections, 3).unwrap(),
2140 0
2141 );
2142
2143 let corrections =
2144 PackedObservableShotBatch::new(vec![10, 20], vec![0b00, 0b01, 0b00, 0b01], 4).unwrap();
2145
2146 let failures =
2147 packed_residual_failure_count(&[10, 20], &[0b00, 0b01, 0b10, 0b11], 1, &corrections, 4)
2148 .unwrap();
2149
2150 assert_eq!(failures, 2);
2151 }
2152
2153 #[test]
2154 fn packed_residual_count_rejects_noncanonical_layouts() {
2155 let reordered =
2156 PackedObservableShotBatch::new(vec![20, 10], vec![0b10, 0b01, 0b11], 3).unwrap();
2157 let err = packed_residual_failure_count(&[10, 20], &[0b01, 0b10, 0b11], 1, &reordered, 3)
2158 .unwrap_err();
2159 assert!(err.to_string().contains("observable layout mismatch"));
2160
2161 for ids in [vec![10], vec![10, 20, 30], vec![20, 30]] {
2162 let corrections = PackedObservableShotBatch::zero(ids, 1).unwrap();
2163 let err =
2164 packed_residual_failure_count(&[10, 20], &[0], 1, &corrections, 1).unwrap_err();
2165 assert!(err.to_string().contains("observable layout mismatch"));
2166 }
2167 }
2168
2169 #[test]
2170 fn packed_observable_batches_require_zero_padding() {
2171 for (ids, data) in [
2172 (vec![0], vec![0b1000_0000]),
2173 ((0..7).collect(), vec![0b1000_0000]),
2174 ((0..9).collect(), vec![0, 0b0000_0010]),
2175 ] {
2176 let err = PackedObservableShotBatch::new(ids, data, 1).unwrap_err();
2177 assert!(err.to_string().contains("non-zero padding bits"));
2178 }
2179
2180 assert!(PackedObservableShotBatch::new((0..8).collect(), vec![0xff], 1).is_ok());
2181 assert!(
2182 PackedObservableShotBatch::new((0..9).collect(), vec![0xff, 0b0000_0001], 1,).is_ok()
2183 );
2184
2185 let corrections = PackedObservableShotBatch::zero(vec![0], 1).unwrap();
2186 let err =
2187 packed_residual_failure_count(&[0], &[0b1000_0000], 1, &corrections, 1).unwrap_err();
2188 assert!(err
2189 .to_string()
2190 .contains("packed observable batch shot 0 has non-zero padding bits"));
2191 }
2192
2193 #[test]
2194 fn packed_residual_count_rejects_malformed_rows() {
2195 let corrections = PackedObservableShotBatch::zero(vec![10], 1).unwrap();
2196
2197 let err = packed_residual_failure_count(&[10], &[], 0, &corrections, 1).unwrap_err();
2198
2199 assert!(err.to_string().contains("observable byte count"));
2200 }
2201
2202 fn patterned_detector_masks(detector_count: usize, shots: usize) -> Vec<Mask> {
2203 let mut masks = vec![Mask::zero(crate::word_count(shots)); detector_count];
2204 for (detector, mask) in masks.iter_mut().enumerate() {
2205 for shot in 0..shots {
2206 if (shot * 5 + detector * 3 + 1) % 7 < 3 {
2207 mask.words[shot >> 6] |= 1u64 << (shot & 63);
2208 }
2209 }
2210 }
2211 masks
2212 }
2213
2214 #[test]
2215 fn detector_formats_round_trip_across_byte_and_word_boundaries() {
2216 let detector_ids = (100..109).collect::<Vec<_>>();
2217 for shots in [0, 1, 7, 8, 63, 64, 65, 129] {
2218 let expected = patterned_detector_masks(detector_ids.len(), shots);
2219 let source = DetectorMaskBatchView::new(&detector_ids, &expected, shots).unwrap();
2220 for first_format in DetectorBatchFormat::STABLE_ORDER {
2221 let first = convert_detector_batch(source.into(), first_format).unwrap();
2222 assert_eq!(first.format(), first_format);
2223 for second_format in DetectorBatchFormat::STABLE_ORDER {
2224 let second = convert_detector_batch(first.view(), second_format).unwrap();
2225 let round_trip =
2226 convert_detector_batch(second.view(), DetectorBatchFormat::Masks).unwrap();
2227 let DetectorBatch::Masks {
2228 detector_ids: actual_ids,
2229 masks: actual_masks,
2230 shots: actual_shots,
2231 } = round_trip
2232 else {
2233 unreachable!()
2234 };
2235 assert_eq!(actual_ids, detector_ids);
2236 assert_eq!(actual_masks, expected);
2237 assert_eq!(actual_shots, shots);
2238 }
2239 }
2240 }
2241 }
2242
2243 #[test]
2244 fn detector_events_combine_duplicates_by_gf2_xor_and_canonicalize_output() {
2245 let detector_ids = [10, 20, 30];
2246 let offsets = [0, 4, 7, 7];
2247 let events = [0, 0, 1, 2, 1, 1, 1];
2248 let source = DetectorEventShotBatchView::new(&detector_ids, &offsets, &events, 3).unwrap();
2249
2250 let masks = convert_detector_batch(source.into(), DetectorBatchFormat::Masks).unwrap();
2251 let DetectorBatch::Masks { masks, .. } = masks else {
2252 unreachable!()
2253 };
2254 assert_eq!(masks[0].words, [0]);
2255 assert_eq!(masks[1].words, [0b011]);
2256 assert_eq!(masks[2].words, [0b001]);
2257
2258 let packed = convert_detector_batch(source.into(), DetectorBatchFormat::Packed).unwrap();
2259 let DetectorBatch::Packed { data, .. } = packed else {
2260 unreachable!()
2261 };
2262 assert_eq!(data, [0b110, 0b010, 0]);
2263
2264 let canonical = convert_detector_batch(source.into(), DetectorBatchFormat::Events).unwrap();
2265 let DetectorBatch::Events {
2266 offsets, events, ..
2267 } = canonical
2268 else {
2269 unreachable!()
2270 };
2271 assert_eq!(offsets, [0, 2, 3, 3]);
2272 assert_eq!(events, [1, 2, 1]);
2273 }
2274
2275 #[test]
2276 fn detector_event_offset_allocation_overflow_returns_an_error() {
2277 let masks = DetectorMaskBatchView::new(&[], &[], usize::MAX).unwrap();
2278 let error = convert_detector_batch(masks.into(), DetectorBatchFormat::Events).unwrap_err();
2279 assert_eq!(
2280 error.message(),
2281 "detector event offset length overflowed usize"
2282 );
2283
2284 let packed = PackedDetectorShotBatchView::new(&[], &[], usize::MAX - 1).unwrap();
2285 let error = convert_detector_batch(packed.into(), DetectorBatchFormat::Events).unwrap_err();
2286 assert!(error
2287 .message()
2288 .contains("detector event offset storage for"));
2289 assert!(error.message().contains("could not be allocated"));
2290 }
2291
2292 #[test]
2293 fn packed_zero_and_no_correction_report_length_overflow() {
2294 let observable_ids = (0..9).collect::<Vec<_>>();
2295 let error =
2296 PackedObservableShotBatch::zero(observable_ids.clone(), usize::MAX).unwrap_err();
2297 assert_eq!(
2298 error.message(),
2299 "packed correction byte length overflowed usize"
2300 );
2301
2302 let factory = NativeNoCorrectionDecoder::new(observable_ids);
2303 let mut worker = factory.create_worker().unwrap();
2304 let packed = PackedDetectorShotBatchView::new(&[], &[], usize::MAX).unwrap();
2305 let error = worker.decode_batch_checked(packed.into()).unwrap_err();
2306 assert_eq!(
2307 error.message(),
2308 "packed correction byte length overflowed usize"
2309 );
2310
2311 let events = DetectorEventShotBatchView {
2312 detector_ids: &[],
2313 offsets: &[],
2314 events: &[],
2315 shots: usize::MAX,
2316 };
2317 let error = worker.decode_batch(events.into()).unwrap_err();
2318 assert_eq!(
2319 error.message(),
2320 "packed correction byte length overflowed usize"
2321 );
2322
2323 let child: Arc<dyn NativeDecoderFactory> =
2324 Arc::new(NativeNoCorrectionDecoder::new(vec![0]));
2325 let factory = NativeCompositeDecoder::new(vec![child]).unwrap();
2326 let mut worker = factory.create_worker().unwrap();
2327 let capacity_overflow_shots = (isize::MAX as usize).checked_add(1).unwrap();
2328 let packed = PackedDetectorShotBatchView::new(&[], &[], capacity_overflow_shots).unwrap();
2329 let error = worker.decode_batch_checked(packed.into()).unwrap_err();
2330 assert!(error.message().contains("packed correction storage for"));
2331 assert!(error.message().contains("could not be allocated"));
2332 }
2333
2334 #[test]
2335 fn public_detector_views_reject_duplicate_ids() {
2336 let ids = [7, 7];
2337 let masks = [Mask::zero(1), Mask::zero(1)];
2338 assert!(DetectorMaskBatchView::new(&ids, &masks, 1).is_err());
2339 assert!(PackedDetectorShotBatchView::new(&ids, &[0], 1).is_err());
2340 assert!(DetectorEventShotBatchView::new(&ids, &[0, 0], &[], 1).is_err());
2341 }
2342
2343 #[test]
2344 fn checked_dispatch_trusts_prevalidated_detector_id_metadata() {
2345 struct TrustedMetadataWorker {
2346 calls: usize,
2347 }
2348
2349 impl NativeDecoderWorker for TrustedMetadataWorker {
2350 fn name(&self) -> &str {
2351 "trusted-metadata"
2352 }
2353
2354 fn detector_ids(&self) -> &[i64] {
2355 &[7, 7]
2356 }
2357
2358 fn observable_ids(&self) -> &[i64] {
2359 &[]
2360 }
2361
2362 fn batch_formats(&self) -> &[DetectorBatchFormat] {
2363 &MASKS_BATCH_FORMATS
2364 }
2365
2366 fn decode_batch(
2367 &mut self,
2368 detectors: DetectorBatchView<'_>,
2369 ) -> NpResult<DecoderCorrectionBatch> {
2370 self.calls += 1;
2371 Ok(DecoderCorrectionBatch::Masks(CorrectionMaskBatch::empty(
2372 detectors.shots(),
2373 )))
2374 }
2375 }
2376
2377 let ids = [7, 7];
2378 let masks = [Mask::zero(1), Mask::zero(1)];
2379 let raw_view = DetectorMaskBatchView {
2380 detector_ids: &ids,
2381 masks: &masks,
2382 shots: 1,
2383 };
2384 let mut worker = TrustedMetadataWorker { calls: 0 };
2385
2386 worker.decode_batch_checked(raw_view.into()).unwrap();
2387 worker.decode_batch_checked(raw_view.into()).unwrap();
2388
2389 assert_eq!(worker.calls, 2);
2390 }
2391
2392 #[test]
2393 fn decoder_format_metadata_and_selection_are_strict_and_ordered() {
2394 assert!(validate_decoder_batch_formats(&[]).is_err());
2395 assert!(validate_decoder_batch_formats(&[
2396 DetectorBatchFormat::Packed,
2397 DetectorBatchFormat::Packed,
2398 ])
2399 .is_err());
2400 assert_eq!(
2401 select_detector_batch_format(
2402 &[DetectorBatchFormat::Events, DetectorBatchFormat::Packed],
2403 &[DetectorBatchFormat::Masks, DetectorBatchFormat::Packed],
2404 )
2405 .unwrap(),
2406 DetectorBatchFormat::Packed
2407 );
2408 assert_eq!(
2409 select_detector_batch_format(
2410 &[DetectorBatchFormat::Events, DetectorBatchFormat::Packed],
2411 &[DetectorBatchFormat::Masks],
2412 )
2413 .unwrap(),
2414 DetectorBatchFormat::Events
2415 );
2416 }
2417
2418 #[test]
2419 fn checked_decode_enforces_the_fixed_input_to_correction_mapping() {
2420 struct WrongVariantWorker;
2421
2422 impl NativeDecoderWorker for WrongVariantWorker {
2423 fn name(&self) -> &str {
2424 "wrong-variant"
2425 }
2426
2427 fn detector_ids(&self) -> &[i64] {
2428 &[]
2429 }
2430
2431 fn observable_ids(&self) -> &[i64] {
2432 &[]
2433 }
2434
2435 fn batch_formats(&self) -> &[DetectorBatchFormat] {
2436 &ALL_BATCH_FORMATS
2437 }
2438
2439 fn decode_batch(
2440 &mut self,
2441 detectors: DetectorBatchView<'_>,
2442 ) -> NpResult<DecoderCorrectionBatch> {
2443 match detectors {
2444 DetectorBatchView::Masks(view) => Ok(DecoderCorrectionBatch::Packed(
2445 PackedObservableShotBatch::zero(vec![], view.shots)?,
2446 )),
2447 DetectorBatchView::Packed(view) => Ok(DecoderCorrectionBatch::Masks(
2448 CorrectionMaskBatch::empty(view.shots),
2449 )),
2450 DetectorBatchView::Events(view) => Ok(DecoderCorrectionBatch::Masks(
2451 CorrectionMaskBatch::empty(view.shots),
2452 )),
2453 }
2454 }
2455 }
2456
2457 let mut worker = WrongVariantWorker;
2458 let masks = DetectorMaskBatchView::new(&[], &[], 1).unwrap();
2459 let packed = PackedDetectorShotBatchView::new(&[], &[], 1).unwrap();
2460 let offsets = [0, 0];
2461 let events = DetectorEventShotBatchView::new(&[], &offsets, &[], 1).unwrap();
2462 for input in [masks.into(), packed.into(), events.into()] {
2463 let error = worker.decode_batch_checked(input).unwrap_err();
2464 assert!(error.message().contains("expected"));
2465 assert!(error.message().contains("corrections"));
2466 }
2467 }
2468
2469 impl NativeDecoderFactory for FixedCorrectionDecoder {
2470 fn name(&self) -> &str {
2471 "fixed-correction"
2472 }
2473
2474 fn detector_ids(&self) -> &[i64] {
2475 &self.detector_ids
2476 }
2477
2478 fn observable_ids(&self) -> &[i64] {
2479 &self.observable_ids
2480 }
2481
2482 fn batch_formats(&self) -> &[DetectorBatchFormat] {
2483 &MASKS_BATCH_FORMATS
2484 }
2485
2486 fn create_worker(&self) -> NpResult<Box<dyn NativeDecoderWorker>> {
2487 Ok(Box::new(FixedCorrectionDecoderWorker {
2488 detector_ids: self.detector_ids.clone(),
2489 observable_ids: self.observable_ids.clone(),
2490 correction: self.correction.clone(),
2491 }))
2492 }
2493 }
2494
2495 impl NativeDecoderWorker for FixedCorrectionDecoderWorker {
2496 fn name(&self) -> &str {
2497 "fixed-correction"
2498 }
2499
2500 fn detector_ids(&self) -> &[i64] {
2501 &self.detector_ids
2502 }
2503
2504 fn observable_ids(&self) -> &[i64] {
2505 &self.observable_ids
2506 }
2507
2508 fn batch_formats(&self) -> &[DetectorBatchFormat] {
2509 &MASKS_BATCH_FORMATS
2510 }
2511
2512 fn decode_batch(
2513 &mut self,
2514 detectors: DetectorBatchView<'_>,
2515 ) -> NpResult<DecoderCorrectionBatch> {
2516 let DetectorBatchView::Masks(detectors) = detectors else {
2517 return Err(NpError::new("fixed-correction only accepts Masks"));
2518 };
2519 Ok(DecoderCorrectionBatch::Masks(CorrectionMaskBatch::new(
2520 self.observable_ids.clone(),
2521 vec![self.correction.clone()],
2522 detectors.shots,
2523 )?))
2524 }
2525 }
2526
2527 impl NativeDecoderFactory for FastCopyDecoder {
2528 fn name(&self) -> &str {
2529 "fast-copy"
2530 }
2531
2532 fn detector_ids(&self) -> &[i64] {
2533 &self.detector_ids
2534 }
2535
2536 fn observable_ids(&self) -> &[i64] {
2537 &self.observable_ids
2538 }
2539
2540 fn batch_formats(&self) -> &[DetectorBatchFormat] {
2541 &ALL_BATCH_FORMATS
2542 }
2543
2544 fn create_worker(&self) -> NpResult<Box<dyn NativeDecoderWorker>> {
2545 Ok(Box::new(FastCopyDecoderWorker {
2546 detector_ids: self.detector_ids.clone(),
2547 observable_ids: self.observable_ids.clone(),
2548 }))
2549 }
2550 }
2551
2552 impl NativeDecoderWorker for FastCopyDecoderWorker {
2553 fn name(&self) -> &str {
2554 "fast-copy"
2555 }
2556
2557 fn detector_ids(&self) -> &[i64] {
2558 &self.detector_ids
2559 }
2560
2561 fn observable_ids(&self) -> &[i64] {
2562 &self.observable_ids
2563 }
2564
2565 fn batch_formats(&self) -> &[DetectorBatchFormat] {
2566 &ALL_BATCH_FORMATS
2567 }
2568
2569 fn decode_batch(
2570 &mut self,
2571 detectors: DetectorBatchView<'_>,
2572 ) -> NpResult<DecoderCorrectionBatch> {
2573 match detectors {
2574 DetectorBatchView::Masks(detectors) => {
2575 Ok(DecoderCorrectionBatch::Masks(CorrectionMaskBatch::new(
2576 self.observable_ids.clone(),
2577 vec![detectors.masks[0].clone()],
2578 detectors.shots,
2579 )?))
2580 }
2581 DetectorBatchView::Packed(detectors) => {
2582 let data = (0..detectors.shots)
2583 .map(|shot| detectors.data[shot * detectors.detector_byte_count] & 1)
2584 .collect();
2585 Ok(DecoderCorrectionBatch::Packed(
2586 PackedObservableShotBatch::new(
2587 self.observable_ids.clone(),
2588 data,
2589 detectors.shots,
2590 )?,
2591 ))
2592 }
2593 DetectorBatchView::Events(detectors) => {
2594 let data = (0..detectors.shots)
2595 .map(|shot| {
2596 (detectors.events[detectors.offsets[shot]..detectors.offsets[shot + 1]]
2597 .iter()
2598 .filter(|&&event| event == 0)
2599 .count()
2600 & 1) as u8
2601 })
2602 .collect();
2603 Ok(DecoderCorrectionBatch::Packed(
2604 PackedObservableShotBatch::new(
2605 self.observable_ids.clone(),
2606 data,
2607 detectors.shots,
2608 )?,
2609 ))
2610 }
2611 }
2612 }
2613 }
2614
2615 impl NativeDecoderFactory for SingleFormatCopyDecoder {
2616 fn name(&self) -> &str {
2617 "single-format-copy"
2618 }
2619
2620 fn detector_ids(&self) -> &[i64] {
2621 &self.detector_ids
2622 }
2623
2624 fn observable_ids(&self) -> &[i64] {
2625 &self.observable_ids
2626 }
2627
2628 fn batch_formats(&self) -> &[DetectorBatchFormat] {
2629 &self.formats
2630 }
2631
2632 fn create_worker(&self) -> NpResult<Box<dyn NativeDecoderWorker>> {
2633 Ok(Box::new(SingleFormatCopyDecoderWorker {
2634 detector_ids: self.detector_ids.clone(),
2635 observable_ids: self.observable_ids.clone(),
2636 formats: self.formats.clone(),
2637 }))
2638 }
2639 }
2640
2641 impl NativeDecoderWorker for SingleFormatCopyDecoderWorker {
2642 fn name(&self) -> &str {
2643 "single-format-copy"
2644 }
2645
2646 fn detector_ids(&self) -> &[i64] {
2647 &self.detector_ids
2648 }
2649
2650 fn observable_ids(&self) -> &[i64] {
2651 &self.observable_ids
2652 }
2653
2654 fn batch_formats(&self) -> &[DetectorBatchFormat] {
2655 &self.formats
2656 }
2657
2658 fn decode_batch(
2659 &mut self,
2660 detectors: DetectorBatchView<'_>,
2661 ) -> NpResult<DecoderCorrectionBatch> {
2662 let input_format = detectors.format();
2663 let shots = detectors.shots();
2664 let masks = convert_detector_batch(detectors, DetectorBatchFormat::Masks)?;
2665 let DetectorBatch::Masks { masks, .. } = masks else {
2666 unreachable!()
2667 };
2668 let corrections = CorrectionMaskBatch::new(
2669 self.observable_ids.clone(),
2670 vec![masks[0].clone()],
2671 shots,
2672 )?;
2673 if input_format == DetectorBatchFormat::Masks {
2674 Ok(DecoderCorrectionBatch::Masks(corrections))
2675 } else {
2676 Ok(DecoderCorrectionBatch::Packed(mask_corrections_to_packed(
2677 corrections,
2678 )?))
2679 }
2680 }
2681 }
2682
2683 #[test]
2684 fn fixed_decoder_correction_controls_native_residual_loss() {
2685 let factory = FixedCorrectionDecoder {
2686 detector_ids: vec![],
2687 observable_ids: vec![0],
2688 correction: Mask {
2689 words: vec![0b0011],
2690 },
2691 };
2692 let mut decoder = factory.create_worker().unwrap();
2693 let detector_ids = vec![];
2694 let detector_masks = vec![];
2695 let view = DetectorMaskBatchView::new(&detector_ids, &detector_masks, 4).unwrap();
2696 let corrections = decoder
2697 .decode_batch(view.into())
2698 .unwrap()
2699 .into_masks()
2700 .unwrap();
2701 let observables = HashMap::from([(
2702 0,
2703 Mask {
2704 words: vec![0b0110],
2705 },
2706 )]);
2707
2708 let loss =
2709 logical_residual_loss_mask_native(&observables, &corrections, &[0], &Mask::all(4));
2710
2711 assert_eq!(
2712 loss,
2713 Mask {
2714 words: vec![0b0101]
2715 }
2716 );
2717 }
2718
2719 #[test]
2720 fn composite_decoder_builds_stable_unions_and_merges_corrections() {
2721 let first: Arc<dyn NativeDecoderFactory> = Arc::new(FixedCorrectionDecoder {
2722 detector_ids: vec![10, 20],
2723 observable_ids: vec![2],
2724 correction: Mask {
2725 words: vec![0b0011],
2726 },
2727 });
2728 let second: Arc<dyn NativeDecoderFactory> = Arc::new(FixedCorrectionDecoder {
2729 detector_ids: vec![20, 30],
2730 observable_ids: vec![5],
2731 correction: Mask {
2732 words: vec![0b1100],
2733 },
2734 });
2735 let factory = NativeCompositeDecoder::new(vec![first, second]).unwrap();
2736 let mut decoder = factory.create_worker().unwrap();
2737 let detector_masks = vec![Mask::zero(1); 3];
2738 let detector_ids = decoder.detector_ids().to_vec();
2739 let view = DetectorMaskBatchView::new(&detector_ids, &detector_masks, 4).unwrap();
2740
2741 let corrections = decoder
2742 .decode_batch_checked(view.into())
2743 .unwrap()
2744 .into_masks()
2745 .unwrap();
2746
2747 assert_eq!(factory.detector_ids(), &[10, 20, 30]);
2748 assert_eq!(factory.observable_ids(), &[2, 5]);
2749 assert_eq!(
2750 corrections.masks,
2751 vec![
2752 Mask {
2753 words: vec![0b0011]
2754 },
2755 Mask {
2756 words: vec![0b1100]
2757 }
2758 ]
2759 );
2760 }
2761
2762 #[test]
2763 fn composite_decoder_rejects_empty_and_duplicate_observables() {
2764 assert!(NativeCompositeDecoder::new(vec![]).is_err());
2765 let children: Vec<Arc<dyn NativeDecoderFactory>> = vec![
2766 Arc::new(NativeNoCorrectionDecoder::new(vec![1])),
2767 Arc::new(NativeNoCorrectionDecoder::new(vec![1])),
2768 ];
2769 let err = NativeCompositeDecoder::new(children).unwrap_err();
2770 assert!(err.to_string().contains("duplicate observable id 1"));
2771 }
2772
2773 #[test]
2774 fn composite_decoder_rejects_duplicate_child_detector_ids() {
2775 let child: Arc<dyn NativeDecoderFactory> = Arc::new(FixedCorrectionDecoder {
2776 detector_ids: vec![10, 10],
2777 observable_ids: vec![2],
2778 correction: Mask::zero(1),
2779 });
2780
2781 let error = NativeCompositeDecoder::new(vec![child]).unwrap_err();
2782
2783 assert_eq!(
2784 error.message(),
2785 "native composite decoder child 0 (`fixed-correction`) has invalid detector metadata: decoder detector ids must be unique; duplicate detector id 10"
2786 );
2787 }
2788
2789 #[test]
2790 fn composite_decoder_dispatches_packed_and_event_fast_paths() {
2791 let children: Vec<Arc<dyn NativeDecoderFactory>> = vec![
2792 Arc::new(FastCopyDecoder {
2793 detector_ids: vec![10],
2794 observable_ids: vec![2],
2795 }),
2796 Arc::new(FastCopyDecoder {
2797 detector_ids: vec![20],
2798 observable_ids: vec![5],
2799 }),
2800 ];
2801 let factory = NativeCompositeDecoder::new(children).unwrap();
2802 let mut decoder = factory.create_worker().unwrap();
2803 let packed_data = [0b01, 0b10, 0b11, 0b00];
2804 let detector_ids = decoder.detector_ids().to_vec();
2805 let packed_view = PackedDetectorShotBatchView::new(&detector_ids, &packed_data, 4).unwrap();
2806 let packed = decoder
2807 .decode_batch_checked(packed_view.into())
2808 .unwrap()
2809 .into_packed()
2810 .unwrap();
2811 assert_eq!(packed.observable_ids, vec![2, 5]);
2812 assert_eq!(packed.data, vec![0b01, 0b10, 0b11, 0b00]);
2813
2814 let offsets = [0, 1, 2, 4, 4];
2815 let events = [0, 1, 0, 1];
2816 let event_view =
2817 DetectorEventShotBatchView::new(&detector_ids, &offsets, &events, 4).unwrap();
2818 let event = decoder.decode_batch_checked(event_view.into()).unwrap();
2819 let event = event.into_packed().unwrap();
2820 assert_eq!(event.observable_ids, vec![2, 5]);
2821 assert_eq!(event.data, vec![0b01, 0b10, 0b11, 0b00]);
2822 }
2823
2824 #[test]
2825 fn heterogeneous_composite_ranks_formats_converts_once_and_merges() {
2826 let children: Vec<Arc<dyn NativeDecoderFactory>> = vec![
2827 Arc::new(SingleFormatCopyDecoder {
2828 detector_ids: vec![10],
2829 observable_ids: vec![2],
2830 formats: vec![DetectorBatchFormat::Masks],
2831 }),
2832 Arc::new(SingleFormatCopyDecoder {
2833 detector_ids: vec![20],
2834 observable_ids: vec![5],
2835 formats: vec![DetectorBatchFormat::Packed],
2836 }),
2837 Arc::new(SingleFormatCopyDecoder {
2838 detector_ids: vec![30],
2839 observable_ids: vec![7],
2840 formats: vec![DetectorBatchFormat::Events],
2841 }),
2842 ];
2843 let factory = NativeCompositeDecoder::new(children).unwrap();
2844 assert_eq!(factory.detector_ids(), [10, 20, 30]);
2845 assert_eq!(factory.observable_ids(), [2, 5, 7]);
2846 assert_eq!(factory.batch_formats(), DetectorBatchFormat::STABLE_ORDER);
2847 let mut worker = factory.create_worker().unwrap();
2848
2849 let offsets = [0, 1, 2, 3, 6];
2850 let events = [0, 1, 2, 0, 1, 2];
2851 let view =
2852 DetectorEventShotBatchView::new(factory.detector_ids(), &offsets, &events, 4).unwrap();
2853 let corrections = worker
2854 .decode_batch_checked(view.into())
2855 .unwrap()
2856 .into_packed()
2857 .unwrap();
2858
2859 assert_eq!(corrections.observable_ids, [2, 5, 7]);
2860 assert_eq!(corrections.data, [0b001, 0b010, 0b100, 0b111]);
2861 }
2862
2863 #[test]
2864 fn composite_decoder_reuses_scratch_across_batch_shapes() {
2865 let children: Vec<Arc<dyn NativeDecoderFactory>> = vec![
2866 Arc::new(FastCopyDecoder {
2867 detector_ids: vec![10],
2868 observable_ids: vec![2],
2869 }),
2870 Arc::new(FastCopyDecoder {
2871 detector_ids: vec![20],
2872 observable_ids: vec![5],
2873 }),
2874 ];
2875 let factory = NativeCompositeDecoder::new(children).unwrap();
2876 let mut decoder = factory.create_worker().unwrap();
2877 let detector_ids = decoder.detector_ids().to_vec();
2878
2879 for (shots, words) in [(4, vec![0b1010]), (65, vec![u64::MAX, 1])] {
2880 let first = Mask { words };
2881 let mut second = Mask::all(shots);
2882 second.xor_assign(&first);
2883 let masks = vec![first, second];
2884 let view = DetectorMaskBatchView::new(&detector_ids, &masks, shots).unwrap();
2885 let corrections = decoder
2886 .decode_batch_checked(view.into())
2887 .unwrap()
2888 .into_masks()
2889 .unwrap();
2890 assert_eq!(corrections.masks, masks);
2891 }
2892
2893 for data in [vec![0b01, 0b10, 0b11, 0b00], vec![0b11; 9]] {
2894 let view = PackedDetectorShotBatchView::new(&detector_ids, &data, data.len()).unwrap();
2895 let corrections = decoder
2896 .decode_batch_checked(view.into())
2897 .unwrap()
2898 .into_packed()
2899 .unwrap();
2900 assert_eq!(corrections.data, data);
2901 }
2902
2903 let offsets = [0, 2, 2, 3];
2904 let events = [0, 1, 1];
2905 let view = DetectorEventShotBatchView::new(&detector_ids, &offsets, &events, 3).unwrap();
2906 let corrections = decoder
2907 .decode_batch_checked(view.into())
2908 .unwrap()
2909 .into_packed()
2910 .unwrap();
2911 assert_eq!(corrections.data, vec![0b11, 0b00, 0b10]);
2912 }
2913
2914 #[test]
2915 fn correction_batch_rejects_wrong_word_count() {
2916 let err =
2917 CorrectionMaskBatch::new(vec![0], vec![Mask { words: vec![0, 0] }], 4).unwrap_err();
2918
2919 assert!(err.to_string().contains("expected 1"));
2920 }
2921
2922 #[test]
2923 fn correction_batch_rejects_duplicate_observable_ids() {
2924 let err = CorrectionMaskBatch::new(
2925 vec![0, 0],
2926 vec![Mask { words: vec![0] }, Mask { words: vec![0] }],
2927 4,
2928 )
2929 .unwrap_err();
2930
2931 assert!(err
2932 .to_string()
2933 .contains("duplicate correction observable id 0"));
2934 }
2935
2936 #[test]
2937 fn correction_batch_validation_rejects_mismatched_public_field_lengths() {
2938 let corrections = CorrectionMaskBatch {
2939 observable_ids: vec![0],
2940 masks: Vec::new(),
2941 shots: 1,
2942 };
2943
2944 let err = corrections.validate_against(&[0], 1).unwrap_err();
2945
2946 assert_eq!(
2947 err.message(),
2948 "observable ids and correction masks must have the same length"
2949 );
2950 }
2951
2952 #[test]
2953 fn correction_batches_require_the_complete_declared_layout() {
2954 for observable_ids in [vec![10], vec![20, 10], vec![10, 20, 30]] {
2955 let masks = vec![Mask::zero(1); observable_ids.len()];
2956 let corrections = CorrectionMaskBatch::new(observable_ids, masks, 1).unwrap();
2957 let err = corrections.validate_against(&[10, 20], 1).unwrap_err();
2958 assert!(err.to_string().contains("observable layout mismatch"));
2959 }
2960 }
2961
2962 #[test]
2963 fn all_checked_decode_paths_require_the_complete_declared_layout() {
2964 struct LayoutOutputWorker {
2965 declared: Vec<i64>,
2966 actual: Vec<i64>,
2967 }
2968
2969 impl NativeDecoderWorker for LayoutOutputWorker {
2970 fn name(&self) -> &str {
2971 "layout-output"
2972 }
2973
2974 fn detector_ids(&self) -> &[i64] {
2975 &[]
2976 }
2977
2978 fn observable_ids(&self) -> &[i64] {
2979 &self.declared
2980 }
2981
2982 fn batch_formats(&self) -> &[DetectorBatchFormat] {
2983 &ALL_BATCH_FORMATS
2984 }
2985
2986 fn decode_batch(
2987 &mut self,
2988 detectors: DetectorBatchView<'_>,
2989 ) -> NpResult<DecoderCorrectionBatch> {
2990 match detectors {
2991 DetectorBatchView::Masks(view) => {
2992 Ok(DecoderCorrectionBatch::Masks(CorrectionMaskBatch::new(
2993 self.actual.clone(),
2994 vec![Mask::zero(crate::word_count(view.shots)); self.actual.len()],
2995 view.shots,
2996 )?))
2997 }
2998 DetectorBatchView::Packed(view) => Ok(DecoderCorrectionBatch::Packed(
2999 PackedObservableShotBatch::zero(self.actual.clone(), view.shots)?,
3000 )),
3001 DetectorBatchView::Events(view) => Ok(DecoderCorrectionBatch::Packed(
3002 PackedObservableShotBatch::zero(self.actual.clone(), view.shots)?,
3003 )),
3004 }
3005 }
3006 }
3007
3008 for actual in [vec![10, 20], vec![10], vec![20, 10], vec![10, 20, 30]] {
3009 let succeeds = actual == [10, 20];
3010 let mut worker = LayoutOutputWorker {
3011 declared: vec![10, 20],
3012 actual,
3013 };
3014
3015 let mask_view = DetectorMaskBatchView::new(&[], &[], 1).unwrap();
3016 assert_eq!(
3017 worker.decode_batch_checked(mask_view.into()).is_ok(),
3018 succeeds
3019 );
3020
3021 let packed_view = PackedDetectorShotBatchView::new(&[], &[], 1).unwrap();
3022 assert_eq!(
3023 worker.decode_batch_checked(packed_view.into()).is_ok(),
3024 succeeds
3025 );
3026
3027 let offsets = [0, 0];
3028 let event_view = DetectorEventShotBatchView::new(&[], &offsets, &[], 1).unwrap();
3029 assert_eq!(
3030 worker.decode_batch_checked(event_view.into()).is_ok(),
3031 succeeds
3032 );
3033 }
3034 }
3035
3036 #[test]
3037 fn checked_decode_rejects_unknown_observable_id() {
3038 struct UnknownObservableFactory;
3039 struct UnknownObservableWorker;
3040
3041 impl NativeDecoderFactory for UnknownObservableFactory {
3042 fn name(&self) -> &str {
3043 "unknown-observable"
3044 }
3045
3046 fn detector_ids(&self) -> &[i64] {
3047 &[]
3048 }
3049
3050 fn observable_ids(&self) -> &[i64] {
3051 &[0]
3052 }
3053
3054 fn batch_formats(&self) -> &[DetectorBatchFormat] {
3055 &MASKS_BATCH_FORMATS
3056 }
3057
3058 fn create_worker(&self) -> NpResult<Box<dyn NativeDecoderWorker>> {
3059 Ok(Box::new(UnknownObservableWorker))
3060 }
3061 }
3062
3063 impl NativeDecoderWorker for UnknownObservableWorker {
3064 fn name(&self) -> &str {
3065 "unknown-observable"
3066 }
3067
3068 fn detector_ids(&self) -> &[i64] {
3069 &[]
3070 }
3071
3072 fn observable_ids(&self) -> &[i64] {
3073 &[0]
3074 }
3075
3076 fn batch_formats(&self) -> &[DetectorBatchFormat] {
3077 &MASKS_BATCH_FORMATS
3078 }
3079
3080 fn decode_batch(
3081 &mut self,
3082 detectors: DetectorBatchView<'_>,
3083 ) -> NpResult<DecoderCorrectionBatch> {
3084 let DetectorBatchView::Masks(detectors) = detectors else {
3085 return Err(NpError::new("expected Masks"));
3086 };
3087 Ok(DecoderCorrectionBatch::Masks(CorrectionMaskBatch::new(
3088 vec![1],
3089 vec![Mask::zero(crate::word_count(detectors.shots))],
3090 detectors.shots,
3091 )?))
3092 }
3093 }
3094
3095 let factory = UnknownObservableFactory;
3096 let mut decoder = factory.create_worker().unwrap();
3097 let view = DetectorMaskBatchView::new(&[], &[], 4).unwrap();
3098 let err = decoder.decode_batch_checked(view.into()).unwrap_err();
3099
3100 assert!(err
3101 .to_string()
3102 .contains("correction observable layout mismatch: expected [0], got [1]"));
3103 }
3104
3105 #[test]
3106 fn checked_decode_rejects_shots_mismatch() {
3107 struct MismatchedShotsFactory;
3108 struct MismatchedShotsWorker;
3109
3110 impl NativeDecoderFactory for MismatchedShotsFactory {
3111 fn name(&self) -> &str {
3112 "mismatched-shots"
3113 }
3114
3115 fn detector_ids(&self) -> &[i64] {
3116 &[]
3117 }
3118
3119 fn observable_ids(&self) -> &[i64] {
3120 &[0]
3121 }
3122
3123 fn batch_formats(&self) -> &[DetectorBatchFormat] {
3124 &MASKS_BATCH_FORMATS
3125 }
3126
3127 fn create_worker(&self) -> NpResult<Box<dyn NativeDecoderWorker>> {
3128 Ok(Box::new(MismatchedShotsWorker))
3129 }
3130 }
3131
3132 impl NativeDecoderWorker for MismatchedShotsWorker {
3133 fn name(&self) -> &str {
3134 "mismatched-shots"
3135 }
3136
3137 fn detector_ids(&self) -> &[i64] {
3138 &[]
3139 }
3140
3141 fn observable_ids(&self) -> &[i64] {
3142 &[0]
3143 }
3144
3145 fn batch_formats(&self) -> &[DetectorBatchFormat] {
3146 &MASKS_BATCH_FORMATS
3147 }
3148
3149 fn decode_batch(
3150 &mut self,
3151 _detectors: DetectorBatchView<'_>,
3152 ) -> NpResult<DecoderCorrectionBatch> {
3153 Ok(DecoderCorrectionBatch::Masks(CorrectionMaskBatch::new(
3154 vec![0],
3155 vec![Mask::zero(crate::word_count(5))],
3156 5,
3157 )?))
3158 }
3159 }
3160
3161 let factory = MismatchedShotsFactory;
3162 let mut decoder = factory.create_worker().unwrap();
3163 let view = DetectorMaskBatchView::new(&[], &[], 4).unwrap();
3164 let err = decoder.decode_batch_checked(view.into()).unwrap_err();
3165
3166 assert!(err.to_string().contains("expected 4"));
3167 }
3168
3169 #[test]
3170 fn missing_correction_observable_is_zero_residual_correction() {
3171 let corrections = CorrectionMaskBatch::empty(4);
3172 let observables = HashMap::from([(
3173 0,
3174 Mask {
3175 words: vec![0b1010],
3176 },
3177 )]);
3178
3179 let loss =
3180 logical_residual_loss_mask_native(&observables, &corrections, &[0], &Mask::all(4));
3181
3182 assert_eq!(
3183 loss,
3184 Mask {
3185 words: vec![0b1010]
3186 }
3187 );
3188 }
3189
3190 #[test]
3191 fn no_correction_decoder_returns_zero_masks_for_observables() {
3192 let factory = NativeNoCorrectionDecoder::new(vec![0, 2]);
3193 let mut decoder = factory.create_worker().unwrap();
3194 let detector_ids = vec![1];
3195 let detector_masks = vec![Mask {
3196 words: vec![0b1010],
3197 }];
3198 let view = DetectorMaskBatchView::new(&detector_ids, &detector_masks, 4).unwrap();
3199
3200 let corrections = decoder
3201 .decode_batch(view.into())
3202 .unwrap()
3203 .into_masks()
3204 .unwrap();
3205
3206 assert_eq!(corrections.observable_ids, vec![0, 2]);
3207 assert_eq!(corrections.masks, vec![Mask { words: vec![0] }; 2]);
3208 }
3209
3210 #[test]
3211 fn no_correction_decoder_returns_zero_packed_rows_for_observables() {
3212 let factory = NativeNoCorrectionDecoder::with_detector_ids(vec![1, 2], vec![0, 3]).unwrap();
3213 let mut decoder = factory.create_worker().unwrap();
3214 let detector_data = vec![0b11, 0b01, 0b10, 0b00];
3215 let detector_ids = decoder.detector_ids().to_vec();
3216 let view = PackedDetectorShotBatchView::new(&detector_ids, &detector_data, 4).unwrap();
3217
3218 let corrections = decoder
3219 .decode_batch_checked(view.into())
3220 .unwrap()
3221 .into_packed()
3222 .unwrap();
3223
3224 assert_eq!(corrections.observable_ids, vec![0, 3]);
3225 assert_eq!(corrections.shots, 4);
3226 assert_eq!(corrections.observable_byte_count, 1);
3227 assert_eq!(corrections.data, vec![0; 4]);
3228 }
3229
3230 #[test]
3231 fn no_correction_decoder_rejects_duplicate_detector_ids() {
3232 let err = NativeNoCorrectionDecoder::with_detector_ids(vec![1, 2, 1], vec![0]).unwrap_err();
3233
3234 assert_eq!(
3235 err.message(),
3236 "decoder detector ids must be unique; duplicate detector id 1"
3237 );
3238 }
3239
3240 #[test]
3241 fn graphlike_detector_copy_constructs_unique_mapping() {
3242 let decoder =
3243 NativeGraphlikeDetectorCopyDecoder::from_graphlike_problem(graphlike_problem())
3244 .unwrap();
3245
3246 assert_eq!(decoder.detector_ids(), &[10, 20]);
3247 assert_eq!(decoder.observable_ids(), &[0, 1]);
3248 assert_eq!(decoder.observable_detector_indices(), &[Some(1), None]);
3249 }
3250
3251 #[test]
3252 fn graphlike_detector_copy_rejects_ambiguous_observable_mapping() {
3253 let mut edges = graphlike_edges();
3254 edges.push(GraphlikeEdge {
3255 detectors: vec![0],
3256 fault_observables: vec![0],
3257 probability: 0.3,
3258 dem_edge_index: 2,
3259 });
3260 let problem = GraphlikeDecodingProblem::new(
3261 vec![10, 20],
3262 vec![Vec::new(), Vec::new()],
3263 vec![0, 1],
3264 edges,
3265 )
3266 .unwrap();
3267
3268 let err = NativeGraphlikeDetectorCopyDecoder::from_graphlike_problem(problem).unwrap_err();
3269
3270 assert!(err
3271 .to_string()
3272 .contains("multiple single-detector candidate edges for observable id 0"));
3273 }
3274
3275 #[test]
3276 fn graphlike_detector_copy_decodes_by_copying_detector_masks() {
3277 let factory =
3278 NativeGraphlikeDetectorCopyDecoder::from_graphlike_problem(graphlike_problem())
3279 .unwrap();
3280 let mut decoder = factory.create_worker().unwrap();
3281 let detector_masks = vec![
3282 Mask {
3283 words: vec![0b0011],
3284 },
3285 Mask {
3286 words: vec![0b1010],
3287 },
3288 ];
3289 let detector_ids = decoder.detector_ids().to_vec();
3290 let view = DetectorMaskBatchView::new(&detector_ids, &detector_masks, 4).unwrap();
3291
3292 let corrections = decoder
3293 .decode_batch_checked(view.into())
3294 .unwrap()
3295 .into_masks()
3296 .unwrap();
3297
3298 assert_eq!(corrections.observable_ids, vec![0, 1]);
3299 assert_eq!(
3300 corrections.masks,
3301 vec![
3302 Mask {
3303 words: vec![0b1010]
3304 },
3305 Mask { words: vec![0] }
3306 ]
3307 );
3308 }
3309
3310 #[test]
3311 fn graphlike_detector_copy_rejects_wrong_detector_order() {
3312 let factory =
3313 NativeGraphlikeDetectorCopyDecoder::from_graphlike_problem(graphlike_problem())
3314 .unwrap();
3315 let mut decoder = factory.create_worker().unwrap();
3316 let detector_ids = vec![20, 10];
3317 let detector_masks = vec![Mask { words: vec![0] }, Mask { words: vec![0] }];
3318 let view = DetectorMaskBatchView::new(&detector_ids, &detector_masks, 4).unwrap();
3319
3320 let err = decoder.decode_batch(view.into()).unwrap_err();
3321
3322 assert!(err.to_string().contains("unexpected order"));
3323 }
3324
3325 #[cfg(feature = "decoder-fusion-blossom")]
3326 #[test]
3327 fn fusion_blossom_scaffold_constructs_from_graphlike_problem() {
3328 let decoder =
3329 NativeFusionBlossomDecoder::from_graphlike_problem(graphlike_problem()).unwrap();
3330
3331 assert_eq!(decoder.name(), "fusion-blossom");
3332 assert_eq!(decoder.detector_ids(), &[10, 20]);
3333 assert_eq!(decoder.observable_ids(), &[0, 1]);
3334 assert_eq!(decoder.edge_count(), 2);
3335 }
3336
3337 #[cfg(feature = "decoder-fusion-blossom")]
3338 #[test]
3339 fn fusion_blossom_scaffold_reports_unavailable_on_decode() {
3340 let factory =
3341 NativeFusionBlossomDecoder::from_graphlike_problem(graphlike_problem()).unwrap();
3342 let mut decoder = factory.create_worker().unwrap();
3343 let detector_data = vec![0; 4];
3344 let detector_ids = decoder.detector_ids().to_vec();
3345 let view = PackedDetectorShotBatchView::new(&detector_ids, &detector_data, 4).unwrap();
3346
3347 let err = decoder.decode_batch_checked(view.into()).unwrap_err();
3348
3349 assert!(err
3350 .to_string()
3351 .contains("no stable Rust dependency is linked yet"));
3352 }
3353}