Skip to main content

faultscope_collection/
api.rs

1use std::collections::{HashMap, HashSet};
2use std::sync::Arc;
3use std::time::Instant;
4
5use crate::counting::{
6    prepare_dem_count_plan, prepare_forward_count_plan, sample_dem_logical_error_stats_with_rng,
7    sample_forward_logical_error_stats as sample_forward_logical_error_stats_batch,
8    validate_decoder_observable_layout, validate_mask_shape, CountOptions,
9};
10use crate::scheduler::{
11    batch_seed, collect_task_set, collect_task_set_with_progress, next_batch_size, resolve_run_seed,
12};
13use faultscope_core::{
14    validate_decoder_batch_formats, validate_decoder_detector_ids, DemHotspotEstimator,
15    DetectorBatchFormat, NativeDecoderFactory, NativeDecoderWorker, NpError, NpResult,
16    SamplerOperation, SamplerProgram, SmallRng,
17};
18
19pub const DEM_LOGICAL_COUNTER_SCHEMA_VERSION: u32 = 1;
20
21pub(crate) const DETECTION_EVENTS_KEY: &str = "detection_events";
22pub(crate) const DETECTORS_CHECKED_KEY: &str = "detectors_checked";
23pub(crate) const OBSERVABLE_COMBO_PREFIX: &str = "obs_mistake_mask=";
24
25#[derive(Debug, Clone, Copy, PartialEq, Eq)]
26pub struct DemLogicalCounterSchema {
27    pub schema_version: u32,
28    pub count_observable_error_combos: bool,
29    pub count_detection_events: bool,
30}
31
32impl Default for DemLogicalCounterSchema {
33    fn default() -> Self {
34        Self {
35            schema_version: DEM_LOGICAL_COUNTER_SCHEMA_VERSION,
36            count_observable_error_combos: false,
37            count_detection_events: false,
38        }
39    }
40}
41
42impl DemLogicalCounterSchema {
43    pub fn new(count_observable_error_combos: bool, count_detection_events: bool) -> Self {
44        Self {
45            schema_version: DEM_LOGICAL_COUNTER_SCHEMA_VERSION,
46            count_observable_error_combos,
47            count_detection_events,
48        }
49    }
50
51    pub fn validate(self) -> NpResult<()> {
52        if self.schema_version != DEM_LOGICAL_COUNTER_SCHEMA_VERSION {
53            return Err(NpError::new(format!(
54                "unsupported collection counter schema version {}; expected {}",
55                self.schema_version, DEM_LOGICAL_COUNTER_SCHEMA_VERSION
56            )));
57        }
58        Ok(())
59    }
60
61    fn empty_custom_counts(self) -> HashMap<String, usize> {
62        let mut counts = HashMap::new();
63        if self.count_detection_events {
64            counts.insert(DETECTION_EVENTS_KEY.to_string(), 0);
65            counts.insert(DETECTORS_CHECKED_KEY.to_string(), 0);
66        }
67        counts
68    }
69}
70
71#[derive(Debug, Clone, Copy, PartialEq)]
72pub struct DemLogicalCollectionOptions {
73    pub max_shots: usize,
74    pub min_shots: usize,
75    pub max_errors: Option<usize>,
76    pub batch_size: usize,
77    /// Explicit task root seed. When absent in a task collection, use the run
78    /// root unchanged, then derive each batch seed from that root. Task identity
79    /// never creates an independent random stream.
80    pub seed: Option<u64>,
81    pub start_batch_size: Option<usize>,
82    pub max_batch_size: Option<usize>,
83    pub max_batch_seconds: Option<f64>,
84}
85
86#[derive(Debug, Clone, PartialEq)]
87pub struct DemLogicalCollectionStats {
88    pub task_id: String,
89    pub strong_id: String,
90    pub decoder: Option<String>,
91    pub metadata_json: String,
92    pub shots: usize,
93    pub errors: usize,
94    pub discards: usize,
95    pub seconds: f64,
96    pub counter_schema: DemLogicalCounterSchema,
97    pub custom_counts: HashMap<String, usize>,
98}
99
100impl DemLogicalCollectionStats {
101    pub fn empty_for_task(
102        task: &DemLogicalCollectionTask,
103        counter_schema: DemLogicalCounterSchema,
104    ) -> Self {
105        Self {
106            task_id: task.task_id.clone(),
107            strong_id: task.strong_id.clone(),
108            decoder: task.decoder_name.clone(),
109            metadata_json: task.metadata_json.clone(),
110            shots: 0,
111            errors: 0,
112            discards: 0,
113            seconds: 0.0,
114            counter_schema,
115            custom_counts: counter_schema.empty_custom_counts(),
116        }
117    }
118
119    pub(crate) fn empty_for_logical_task(
120        task: &LogicalCollectionTask,
121        counter_schema: DemLogicalCounterSchema,
122    ) -> Self {
123        Self {
124            task_id: task.task_id.clone(),
125            strong_id: task.strong_id.clone(),
126            decoder: task.decoder_name.clone(),
127            metadata_json: task.metadata_json.clone(),
128            shots: 0,
129            errors: 0,
130            discards: 0,
131            seconds: 0.0,
132            counter_schema,
133            custom_counts: counter_schema.empty_custom_counts(),
134        }
135    }
136
137    pub fn with_identity(
138        mut self,
139        task_id: String,
140        strong_id: String,
141        decoder: Option<String>,
142        metadata_json: String,
143    ) -> Self {
144        self.task_id = task_id;
145        self.strong_id = strong_id;
146        self.decoder = decoder;
147        self.metadata_json = metadata_json;
148        self
149    }
150
151    pub fn add_assign_checked(&mut self, other: &Self) -> NpResult<()> {
152        self.validate_counter_schema()?;
153        other.validate_counter_schema()?;
154        if self.strong_id != other.strong_id {
155            return Err(NpError::new(format!(
156                "cannot merge stats with different strong_id values: {:?} != {:?}",
157                self.strong_id, other.strong_id
158            )));
159        }
160        if self.decoder != other.decoder || self.metadata_json != other.metadata_json {
161            return Err(NpError::new(
162                "stats with the same strong_id have different decoder or metadata",
163            ));
164        }
165        if self.counter_schema != other.counter_schema {
166            return Err(NpError::new(
167                "stats with the same strong_id have different counter schemas",
168            ));
169        }
170        self.shots += other.shots;
171        self.errors += other.errors;
172        self.discards += other.discards;
173        self.seconds += other.seconds;
174        for (key, value) in &other.custom_counts {
175            *self.custom_counts.entry(key.clone()).or_insert(0) += *value;
176        }
177        Ok(())
178    }
179
180    pub fn validate_counter_schema(&self) -> NpResult<()> {
181        self.counter_schema.validate()?;
182        for fixed_key in [DETECTION_EVENTS_KEY, DETECTORS_CHECKED_KEY] {
183            let present = self.custom_counts.contains_key(fixed_key);
184            if self.counter_schema.count_detection_events != present {
185                let expectation = if self.counter_schema.count_detection_events {
186                    "must contain"
187                } else {
188                    "must not contain"
189                };
190                return Err(NpError::new(format!(
191                    "collection stats {expectation} counter {fixed_key:?} for their counter schema"
192                )));
193            }
194        }
195        for key in self.custom_counts.keys() {
196            if key == DETECTION_EVENTS_KEY || key == DETECTORS_CHECKED_KEY {
197                continue;
198            }
199            let Some(mask) = key.strip_prefix(OBSERVABLE_COMBO_PREFIX) else {
200                return Err(NpError::new(format!(
201                    "collection stats contain unsupported custom counter {key:?}"
202                )));
203            };
204            if !self.counter_schema.count_observable_error_combos {
205                return Err(NpError::new(format!(
206                    "collection stats contain observable combo counter {key:?} but their counter schema disables observable combos"
207                )));
208            }
209            validate_observable_combo_mask_syntax(mask)?;
210        }
211        Ok(())
212    }
213}
214
215#[derive(Clone)]
216pub struct DemLogicalCollectionTask {
217    pub task_id: String,
218    pub strong_id: String,
219    pub sampling_id: String,
220    pub sampler: Arc<DemHotspotEstimator>,
221    pub decoder: Option<Arc<dyn NativeDecoderFactory>>,
222    pub decoder_name: Option<String>,
223    pub metadata_json: String,
224    pub options: DemLogicalCollectionOptions,
225    pub postselection_mask: Option<Vec<u8>>,
226    pub postselected_observables_mask: Option<Vec<u8>>,
227}
228
229/// A forward-circuit logical-error collection task.
230#[derive(Clone)]
231pub struct ForwardLogicalCollectionTask {
232    pub task_id: String,
233    pub strong_id: String,
234    pub sampling_id: String,
235    pub sampler: Arc<SamplerProgram>,
236    pub decoder: Option<Arc<dyn NativeDecoderFactory>>,
237    pub decoder_name: Option<String>,
238    pub metadata_json: String,
239    pub options: DemLogicalCollectionOptions,
240    pub postselection_mask: Option<Vec<u8>>,
241    pub postselected_observables_mask: Option<Vec<u8>>,
242}
243
244#[derive(Clone)]
245pub(crate) enum CollectionSampler {
246    Dem(Arc<DemHotspotEstimator>),
247    Forward(Arc<ForwardCollectionSampler>),
248}
249
250#[derive(Debug)]
251pub(crate) struct ForwardCollectionSampler {
252    program: Arc<SamplerProgram>,
253    detector_ids: Vec<i64>,
254    observable_ids: Vec<i64>,
255}
256
257impl ForwardCollectionSampler {
258    fn new(program: Arc<SamplerProgram>) -> Self {
259        let (detector_ids, observable_ids) = forward_sampler_layout(&program);
260        Self {
261            program,
262            detector_ids,
263            observable_ids,
264        }
265    }
266
267    pub(crate) fn program(&self) -> &SamplerProgram {
268        &self.program
269    }
270
271    pub(crate) fn detector_ids(&self) -> &[i64] {
272        &self.detector_ids
273    }
274
275    pub(crate) fn observable_ids(&self) -> &[i64] {
276        &self.observable_ids
277    }
278
279    pub(crate) fn view(&self) -> ForwardSamplerView<'_> {
280        ForwardSamplerView::new(&self.program, &self.detector_ids, &self.observable_ids)
281    }
282}
283
284#[derive(Clone, Copy)]
285pub(crate) struct ForwardSamplerView<'a> {
286    program: &'a SamplerProgram,
287    detector_ids: &'a [i64],
288    observable_ids: &'a [i64],
289}
290
291impl<'a> ForwardSamplerView<'a> {
292    pub(crate) fn new(
293        program: &'a SamplerProgram,
294        detector_ids: &'a [i64],
295        observable_ids: &'a [i64],
296    ) -> Self {
297        Self {
298            program,
299            detector_ids,
300            observable_ids,
301        }
302    }
303
304    pub(crate) fn program(self) -> &'a SamplerProgram {
305        self.program
306    }
307
308    pub(crate) fn detector_ids(self) -> &'a [i64] {
309        self.detector_ids
310    }
311
312    pub(crate) fn observable_ids(self) -> &'a [i64] {
313        self.observable_ids
314    }
315}
316
317pub(crate) fn forward_sampler_layout(program: &SamplerProgram) -> (Vec<i64>, Vec<i64>) {
318    let mut detector_ids = Vec::new();
319    let mut observable_ids = Vec::new();
320    let mut seen_detector_ids = HashSet::new();
321    let mut seen_observable_ids = HashSet::new();
322    for operation in program.operations() {
323        match operation {
324            SamplerOperation::Detector { detector_id, .. } => {
325                if seen_detector_ids.insert(*detector_id) {
326                    detector_ids.push(*detector_id);
327                }
328            }
329            SamplerOperation::ObservableInclude { observable_id, .. }
330                if seen_observable_ids.insert(*observable_id) =>
331            {
332                observable_ids.push(*observable_id);
333            }
334            _ => {}
335        }
336    }
337    for observable in program.compiled_observables() {
338        if seen_observable_ids.insert(observable.id) {
339            observable_ids.push(observable.id);
340        }
341    }
342    (detector_ids, observable_ids)
343}
344
345impl CollectionSampler {
346    pub(crate) fn detector_ids(&self) -> &[i64] {
347        match self {
348            Self::Dem(sampler) => sampler.detector_ids(),
349            Self::Forward(sampler) => sampler.detector_ids(),
350        }
351    }
352
353    pub(crate) fn observable_ids(&self) -> &[i64] {
354        match self {
355            Self::Dem(sampler) => sampler.observable_ids(),
356            Self::Forward(sampler) => sampler.observable_ids(),
357        }
358    }
359
360    fn description(&self) -> &'static str {
361        match self {
362            Self::Dem(_) => "DEM sampler",
363            Self::Forward(_) => "forward sampler",
364        }
365    }
366}
367
368#[derive(Clone)]
369pub(crate) struct LogicalCollectionTask {
370    pub(crate) task_id: String,
371    pub(crate) strong_id: String,
372    pub(crate) sampling_id: String,
373    pub(crate) sampler: CollectionSampler,
374    pub(crate) decoder: Option<Arc<dyn NativeDecoderFactory>>,
375    pub(crate) decoder_name: Option<String>,
376    pub(crate) metadata_json: String,
377    pub(crate) options: DemLogicalCollectionOptions,
378    pub(crate) postselection_mask: Option<Vec<u8>>,
379    pub(crate) postselected_observables_mask: Option<Vec<u8>>,
380}
381
382impl From<DemLogicalCollectionTask> for LogicalCollectionTask {
383    fn from(task: DemLogicalCollectionTask) -> Self {
384        Self {
385            task_id: task.task_id,
386            strong_id: task.strong_id,
387            sampling_id: task.sampling_id,
388            sampler: CollectionSampler::Dem(task.sampler),
389            decoder: task.decoder,
390            decoder_name: task.decoder_name,
391            metadata_json: task.metadata_json,
392            options: task.options,
393            postselection_mask: task.postselection_mask,
394            postselected_observables_mask: task.postselected_observables_mask,
395        }
396    }
397}
398
399impl From<ForwardLogicalCollectionTask> for LogicalCollectionTask {
400    fn from(task: ForwardLogicalCollectionTask) -> Self {
401        Self {
402            task_id: task.task_id,
403            strong_id: task.strong_id,
404            sampling_id: task.sampling_id,
405            sampler: CollectionSampler::Forward(Arc::new(ForwardCollectionSampler::new(
406                task.sampler,
407            ))),
408            decoder: task.decoder,
409            decoder_name: task.decoder_name,
410            metadata_json: task.metadata_json,
411            options: task.options,
412            postselection_mask: task.postselection_mask,
413            postselected_observables_mask: task.postselected_observables_mask,
414        }
415    }
416}
417
418#[derive(Debug, Clone, PartialEq, Eq)]
419pub struct DemLogicalCollectionRunOptions {
420    pub num_workers: usize,
421    pub seed: Option<u64>,
422    pub count_observable_error_combos: bool,
423    pub count_detection_events: bool,
424    pub custom_error_count_key: Option<String>,
425}
426
427impl DemLogicalCollectionRunOptions {
428    pub fn counter_schema(&self) -> DemLogicalCounterSchema {
429        DemLogicalCounterSchema::new(
430            self.count_observable_error_combos,
431            self.count_detection_events,
432        )
433    }
434}
435
436pub fn collect_dem_logical_error_stats(
437    sampler: &DemHotspotEstimator,
438    options: DemLogicalCollectionOptions,
439    mut decoder: Option<&mut dyn NativeDecoderWorker>,
440) -> NpResult<DemLogicalCollectionStats> {
441    validate_collection_options(options)?;
442    if let Some(decoder) = decoder.as_deref() {
443        validate_decoder_layout(
444            sampler.detector_ids(),
445            sampler.observable_ids(),
446            "DEM sampler",
447            decoder.name(),
448            decoder.detector_ids(),
449            decoder.observable_ids(),
450            decoder.batch_formats(),
451        )?;
452    }
453
454    let decoder_name = decoder.as_ref().map(|decoder| decoder.name().to_string());
455    let started = Instant::now();
456    let mut shots_done = 0usize;
457    let mut errors = 0usize;
458    let mut batch_ordinal = 0usize;
459    let mut last_batch: Option<(usize, f64)> = None;
460    if !collection_limits_reached(options, shots_done, errors) {
461        let run_seed = resolve_run_seed(options.seed);
462        let count_options = CountOptions::default();
463        let prepared_plan = prepare_dem_count_plan(
464            sampler,
465            decoder
466                .as_deref()
467                .map(|worker| (worker.detector_ids(), worker.batch_formats())),
468            &count_options,
469            false,
470        )?;
471
472        while !collection_limits_reached(options, shots_done, errors) {
473            let batch_shots = next_batch_size(options, shots_done, last_batch);
474            let mut batch_rng = SmallRng::new(batch_seed(run_seed, 0, batch_ordinal));
475            let batch_started = Instant::now();
476            let batch_stats = match decoder.as_mut() {
477                Some(decoder) => sample_dem_logical_error_stats_with_rng(
478                    sampler,
479                    batch_shots,
480                    &mut batch_rng,
481                    Some(&mut **decoder),
482                    None,
483                    &count_options,
484                    &prepared_plan,
485                )?,
486                None => sample_dem_logical_error_stats_with_rng(
487                    sampler,
488                    batch_shots,
489                    &mut batch_rng,
490                    None,
491                    None,
492                    &count_options,
493                    &prepared_plan,
494                )?,
495            };
496            let elapsed = batch_started.elapsed().as_secs_f64();
497            shots_done += batch_stats.shots;
498            errors += batch_stats.errors;
499            last_batch = Some((batch_shots, elapsed));
500            batch_ordinal += 1;
501        }
502    }
503
504    Ok(DemLogicalCollectionStats {
505        task_id: String::new(),
506        strong_id: String::new(),
507        decoder: decoder_name,
508        metadata_json: "null".to_string(),
509        shots: shots_done,
510        errors,
511        discards: 0,
512        seconds: started.elapsed().as_secs_f64(),
513        counter_schema: DemLogicalCounterSchema::default(),
514        custom_counts: HashMap::new(),
515    })
516}
517
518pub fn sample_dem_logical_error_stats(
519    sampler: &DemHotspotEstimator,
520    shots: usize,
521    seed: Option<u64>,
522    decoder: Option<&mut dyn NativeDecoderWorker>,
523) -> NpResult<DemLogicalCollectionStats> {
524    if shots == 0 {
525        return Err(NpError::new("shots must be positive"));
526    }
527    let started = Instant::now();
528    let mut rng = SmallRng::new(seed.unwrap_or(0x95f2_04dc_4291_a715));
529    let decoder_name = decoder.as_ref().map(|decoder| decoder.name().to_string());
530    let count_options = CountOptions::default();
531    let prepared_plan = prepare_dem_count_plan(
532        sampler,
533        decoder
534            .as_deref()
535            .map(|worker| (worker.detector_ids(), worker.batch_formats())),
536        &count_options,
537        false,
538    )?;
539    let batch = sample_dem_logical_error_stats_with_rng(
540        sampler,
541        shots,
542        &mut rng,
543        decoder,
544        Some(started),
545        &count_options,
546        &prepared_plan,
547    )?;
548    Ok(DemLogicalCollectionStats {
549        task_id: String::new(),
550        strong_id: String::new(),
551        decoder: decoder_name,
552        metadata_json: "null".to_string(),
553        shots: batch.shots,
554        errors: batch.errors,
555        discards: batch.discards,
556        seconds: batch.seconds,
557        counter_schema: DemLogicalCounterSchema::default(),
558        custom_counts: batch.custom_counts,
559    })
560}
561
562/// Collect logical-error statistics by repeatedly executing a forward sampler program.
563pub fn collect_forward_logical_error_stats(
564    program: &SamplerProgram,
565    options: DemLogicalCollectionOptions,
566    mut decoder: Option<&mut dyn NativeDecoderWorker>,
567) -> NpResult<DemLogicalCollectionStats> {
568    validate_collection_options(options)?;
569    let (detector_ids, observable_ids) = forward_sampler_layout(program);
570    let sampler = ForwardSamplerView::new(program, &detector_ids, &observable_ids);
571    if let Some(decoder) = decoder.as_deref() {
572        validate_decoder_layout(
573            &detector_ids,
574            &observable_ids,
575            "forward sampler",
576            decoder.name(),
577            decoder.detector_ids(),
578            decoder.observable_ids(),
579            decoder.batch_formats(),
580        )?;
581    }
582
583    let decoder_name = decoder.as_ref().map(|decoder| decoder.name().to_string());
584    let started = Instant::now();
585    let mut shots_done = 0usize;
586    let mut errors = 0usize;
587    let mut batch_ordinal = 0usize;
588    let mut last_batch: Option<(usize, f64)> = None;
589    if !collection_limits_reached(options, shots_done, errors) {
590        let run_seed = resolve_run_seed(options.seed);
591        let count_options = CountOptions::default();
592        let prepared_plan = prepare_forward_count_plan(
593            decoder
594                .as_deref()
595                .map(|worker| (worker.detector_ids(), worker.batch_formats())),
596            false,
597        )?;
598
599        while !collection_limits_reached(options, shots_done, errors) {
600            let batch_shots = next_batch_size(options, shots_done, last_batch);
601            let seed = batch_seed(run_seed, 0, batch_ordinal);
602            let batch_started = Instant::now();
603            let batch_stats = match decoder.as_mut() {
604                Some(decoder) => sample_forward_logical_error_stats_batch(
605                    sampler,
606                    batch_shots,
607                    seed,
608                    Some(&mut **decoder),
609                    None,
610                    &count_options,
611                    &prepared_plan,
612                )?,
613                None => sample_forward_logical_error_stats_batch(
614                    sampler,
615                    batch_shots,
616                    seed,
617                    None,
618                    None,
619                    &count_options,
620                    &prepared_plan,
621                )?,
622            };
623            let elapsed = batch_started.elapsed().as_secs_f64();
624            shots_done += batch_stats.shots;
625            errors += batch_stats.errors;
626            last_batch = Some((batch_shots, elapsed));
627            batch_ordinal += 1;
628        }
629    }
630
631    Ok(DemLogicalCollectionStats {
632        task_id: String::new(),
633        strong_id: String::new(),
634        decoder: decoder_name,
635        metadata_json: "null".to_string(),
636        shots: shots_done,
637        errors,
638        discards: 0,
639        seconds: started.elapsed().as_secs_f64(),
640        counter_schema: DemLogicalCounterSchema::default(),
641        custom_counts: HashMap::new(),
642    })
643}
644
645/// Execute one seeded forward batch and return its logical-error statistics.
646pub fn sample_forward_logical_error_stats(
647    program: &SamplerProgram,
648    shots: usize,
649    seed: Option<u64>,
650    mut decoder: Option<&mut dyn NativeDecoderWorker>,
651) -> NpResult<DemLogicalCollectionStats> {
652    if shots == 0 {
653        return Err(NpError::new("shots must be positive"));
654    }
655    let (detector_ids, observable_ids) = forward_sampler_layout(program);
656    let sampler = ForwardSamplerView::new(program, &detector_ids, &observable_ids);
657    if let Some(decoder) = decoder.as_deref() {
658        validate_decoder_layout(
659            &detector_ids,
660            &observable_ids,
661            "forward sampler",
662            decoder.name(),
663            decoder.detector_ids(),
664            decoder.observable_ids(),
665            decoder.batch_formats(),
666        )?;
667    }
668    let started = Instant::now();
669    let decoder_name = decoder.as_ref().map(|decoder| decoder.name().to_string());
670    let count_options = CountOptions::default();
671    let prepared_plan = prepare_forward_count_plan(
672        decoder
673            .as_deref()
674            .map(|worker| (worker.detector_ids(), worker.batch_formats())),
675        false,
676    )?;
677    let batch = match decoder.as_mut() {
678        Some(decoder) => sample_forward_logical_error_stats_batch(
679            sampler,
680            shots,
681            seed.unwrap_or(0x95f2_04dc_4291_a715),
682            Some(&mut **decoder),
683            Some(started),
684            &count_options,
685            &prepared_plan,
686        )?,
687        None => sample_forward_logical_error_stats_batch(
688            sampler,
689            shots,
690            seed.unwrap_or(0x95f2_04dc_4291_a715),
691            None,
692            Some(started),
693            &count_options,
694            &prepared_plan,
695        )?,
696    };
697    Ok(DemLogicalCollectionStats {
698        task_id: String::new(),
699        strong_id: String::new(),
700        decoder: decoder_name,
701        metadata_json: "null".to_string(),
702        shots: batch.shots,
703        errors: batch.errors,
704        discards: batch.discards,
705        seconds: batch.seconds,
706        counter_schema: DemLogicalCounterSchema::default(),
707        custom_counts: batch.custom_counts,
708    })
709}
710
711/// Collect detector-error-model logical-error tasks.
712///
713/// Returns an error before worker creation when two tasks share a `strong_id`.
714pub fn collect_dem_logical_error_tasks(
715    tasks: Vec<DemLogicalCollectionTask>,
716    run_options: DemLogicalCollectionRunOptions,
717    existing_data: HashMap<String, DemLogicalCollectionStats>,
718) -> NpResult<Vec<DemLogicalCollectionStats>> {
719    collect_task_set(
720        tasks.into_iter().map(LogicalCollectionTask::from).collect(),
721        run_options,
722        existing_data,
723    )
724}
725
726/// Collect detector-error-model logical-error tasks and report committed deltas.
727///
728/// Returns an error before worker creation or progress when two tasks share a `strong_id`.
729pub fn collect_dem_logical_error_tasks_with_progress<F>(
730    tasks: Vec<DemLogicalCollectionTask>,
731    run_options: DemLogicalCollectionRunOptions,
732    existing_data: HashMap<String, DemLogicalCollectionStats>,
733    progress_callback: F,
734) -> NpResult<Vec<DemLogicalCollectionStats>>
735where
736    F: FnMut(&DemLogicalCollectionStats) -> NpResult<()>,
737{
738    let mut progress_callback = progress_callback;
739    collect_task_set_with_progress(
740        tasks.into_iter().map(LogicalCollectionTask::from).collect(),
741        run_options,
742        existing_data,
743        &mut progress_callback,
744    )
745}
746
747/// Collect forward-circuit logical-error tasks.
748///
749/// Returns an error before worker creation when two tasks share a `strong_id`.
750pub fn collect_forward_logical_error_tasks(
751    tasks: Vec<ForwardLogicalCollectionTask>,
752    run_options: DemLogicalCollectionRunOptions,
753    existing_data: HashMap<String, DemLogicalCollectionStats>,
754) -> NpResult<Vec<DemLogicalCollectionStats>> {
755    collect_task_set(
756        tasks.into_iter().map(LogicalCollectionTask::from).collect(),
757        run_options,
758        existing_data,
759    )
760}
761
762/// Collect forward-circuit logical-error tasks and report committed deltas.
763///
764/// Returns an error before worker creation or progress when two tasks share a `strong_id`.
765pub fn collect_forward_logical_error_tasks_with_progress<F>(
766    tasks: Vec<ForwardLogicalCollectionTask>,
767    run_options: DemLogicalCollectionRunOptions,
768    existing_data: HashMap<String, DemLogicalCollectionStats>,
769    progress_callback: F,
770) -> NpResult<Vec<DemLogicalCollectionStats>>
771where
772    F: FnMut(&DemLogicalCollectionStats) -> NpResult<()>,
773{
774    let mut progress_callback = progress_callback;
775    collect_task_set_with_progress(
776        tasks.into_iter().map(LogicalCollectionTask::from).collect(),
777        run_options,
778        existing_data,
779        &mut progress_callback,
780    )
781}
782
783pub(crate) fn validate_task(task: &LogicalCollectionTask) -> NpResult<()> {
784    validate_collection_options(task.options)?;
785    validate_mask_shape(
786        task.postselection_mask.as_deref(),
787        task.sampler.detector_ids().len(),
788        "postselection_mask",
789    )?;
790    validate_mask_shape(
791        task.postselected_observables_mask.as_deref(),
792        task.sampler.observable_ids().len(),
793        "postselected_observables_mask",
794    )?;
795    if let Some(decoder) = &task.decoder {
796        validate_decoder_layout(
797            task.sampler.detector_ids(),
798            task.sampler.observable_ids(),
799            task.sampler.description(),
800            decoder.name(),
801            decoder.detector_ids(),
802            decoder.observable_ids(),
803            decoder.batch_formats(),
804        )?;
805    }
806    if task.strong_id.is_empty() {
807        return Err(NpError::new("strong_id must not be empty"));
808    }
809    if task.sampling_id.is_empty() {
810        return Err(NpError::new("sampling_id must not be empty"));
811    }
812    Ok(())
813}
814
815pub(crate) fn validate_unique_strong_ids(tasks: &[LogicalCollectionTask]) -> NpResult<()> {
816    if tasks.len() < 2 {
817        return Ok(());
818    }
819
820    let mut seen: HashMap<&str, (usize, &str)> = HashMap::with_capacity(tasks.len());
821    for (index, task) in tasks.iter().enumerate() {
822        if let Some((first_index, first_task_id)) =
823            seen.insert(task.strong_id.as_str(), (index, task.task_id.as_str()))
824        {
825            return Err(NpError::new(format!(
826                "duplicate collection strong_id {:?} at task indices {} ({:?}) and {} ({:?}); task_id is not part of collection identity",
827                task.strong_id, first_index, first_task_id, index, task.task_id
828            )));
829        }
830    }
831    Ok(())
832}
833
834fn validate_decoder_layout(
835    sampler_detector_ids: &[i64],
836    sampler_observable_ids: &[i64],
837    sampler_description: &str,
838    decoder_name: &str,
839    detector_ids: &[i64],
840    observable_ids: &[i64],
841    batch_formats: &[DetectorBatchFormat],
842) -> NpResult<()> {
843    validate_decoder_detector_ids(detector_ids)?;
844    let sampler_detector_ids = sampler_detector_ids.iter().copied().collect::<HashSet<_>>();
845    for &detector_id in detector_ids {
846        if !sampler_detector_ids.contains(&detector_id) {
847            let message = if sampler_description == "DEM sampler" {
848                format!(
849                    "decoder DEM sampler requested detector id {detector_id}, but it is not declared by the DEM"
850                )
851            } else {
852                format!(
853                    "decoder {decoder_name} requested detector id {detector_id}, but it is not declared by the {sampler_description}"
854                )
855            };
856            return Err(NpError::new(message));
857        }
858    }
859    validate_decoder_batch_formats(batch_formats)?;
860    validate_decoder_observable_layout(sampler_observable_ids, observable_ids, decoder_name)
861}
862
863fn validate_collection_options(options: DemLogicalCollectionOptions) -> NpResult<()> {
864    if options.max_shots == 0 {
865        return Err(NpError::new("max_shots must be positive"));
866    }
867    if options.min_shots > options.max_shots {
868        return Err(NpError::new("min_shots must not exceed max_shots"));
869    }
870    if options.batch_size == 0 {
871        return Err(NpError::new("batch_size must be positive"));
872    }
873    if options.start_batch_size.is_some_and(|value| value == 0) {
874        return Err(NpError::new("start_batch_size must be positive"));
875    }
876    if options.max_batch_size.is_some_and(|value| value == 0) {
877        return Err(NpError::new("max_batch_size must be positive"));
878    }
879    if options
880        .max_batch_seconds
881        .is_some_and(|value| value <= 0.0 || !value.is_finite())
882    {
883        return Err(NpError::new("max_batch_seconds must be positive"));
884    }
885    Ok(())
886}
887
888pub(crate) fn collection_limits_reached(
889    options: DemLogicalCollectionOptions,
890    shots: usize,
891    error_count: usize,
892) -> bool {
893    shots >= options.max_shots
894        || (shots >= options.min_shots
895            && options.max_errors.is_some_and(|limit| error_count >= limit))
896}
897
898#[derive(Debug, Clone, PartialEq, Eq)]
899pub(crate) enum ValidatedStopCounter {
900    Errors,
901    DetectionEvents,
902    DetectorsChecked,
903    ObservableCombo(String),
904}
905
906pub(crate) fn validate_stop_counter_for_tasks(
907    tasks: &[LogicalCollectionTask],
908    run_options: &DemLogicalCollectionRunOptions,
909) -> NpResult<ValidatedStopCounter> {
910    let schema = run_options.counter_schema();
911    schema.validate()?;
912    let Some(key) = run_options.custom_error_count_key.as_deref() else {
913        return Ok(ValidatedStopCounter::Errors);
914    };
915
916    if key == DETECTION_EVENTS_KEY {
917        if !schema.count_detection_events {
918            return Err(NpError::new(format!(
919                "custom_error_count_key {key:?} requires count_detection_events=True"
920            )));
921        }
922        return Ok(ValidatedStopCounter::DetectionEvents);
923    }
924    if key == DETECTORS_CHECKED_KEY {
925        if !schema.count_detection_events {
926            return Err(NpError::new(format!(
927                "custom_error_count_key {key:?} requires count_detection_events=True"
928            )));
929        }
930        return Ok(ValidatedStopCounter::DetectorsChecked);
931    }
932
933    let Some(mask) = key.strip_prefix(OBSERVABLE_COMBO_PREFIX) else {
934        return Err(NpError::new(format!(
935            "unsupported custom_error_count_key {key:?}; use None for logical errors, {DETECTION_EVENTS_KEY:?}, {DETECTORS_CHECKED_KEY:?}, or {OBSERVABLE_COMBO_PREFIX}<mask>"
936        )));
937    };
938    if !schema.count_observable_error_combos {
939        return Err(NpError::new(format!(
940            "custom_error_count_key {key:?} requires count_observable_error_combos=True"
941        )));
942    }
943    validate_observable_combo_mask_syntax(mask)?;
944    for task in tasks {
945        validate_observable_combo_mask_for_task(mask, task)?;
946    }
947    Ok(ValidatedStopCounter::ObservableCombo(key.to_string()))
948}
949
950pub(crate) fn stop_error_count(
951    stats: &DemLogicalCollectionStats,
952    stop_counter: &ValidatedStopCounter,
953) -> NpResult<usize> {
954    stats.counter_schema.validate()?;
955    match stop_counter {
956        ValidatedStopCounter::Errors => Ok(stats.errors),
957        ValidatedStopCounter::ObservableCombo(key) => {
958            Ok(stats.custom_counts.get(key).copied().unwrap_or(0))
959        }
960        ValidatedStopCounter::DetectionEvents => required_stop_count(stats, DETECTION_EVENTS_KEY),
961        ValidatedStopCounter::DetectorsChecked => required_stop_count(stats, DETECTORS_CHECKED_KEY),
962    }
963}
964
965pub(crate) fn task_is_complete(
966    stats: &DemLogicalCollectionStats,
967    options: &DemLogicalCollectionOptions,
968    stop_counter: &ValidatedStopCounter,
969) -> NpResult<bool> {
970    if stats.shots >= options.max_shots {
971        return Ok(collection_limits_reached(*options, stats.shots, 0));
972    }
973    if stats.shots < options.min_shots || options.max_errors.is_none() {
974        return Ok(collection_limits_reached(*options, stats.shots, 0));
975    }
976    let error_count = stop_error_count(stats, stop_counter)?;
977    Ok(collection_limits_reached(
978        *options,
979        stats.shots,
980        error_count,
981    ))
982}
983
984fn required_stop_count(stats: &DemLogicalCollectionStats, key: &str) -> NpResult<usize> {
985    stats.custom_counts.get(key).copied().ok_or_else(|| {
986        NpError::new(format!(
987            "collection stats are missing configured stop counter {key:?}"
988        ))
989    })
990}
991
992fn validate_observable_combo_mask_syntax(mask: &str) -> NpResult<()> {
993    if mask.is_empty()
994        || !mask.bytes().all(|value| matches!(value, b'E' | b'_'))
995        || !mask.as_bytes().contains(&b'E')
996    {
997        return Err(NpError::new(format!(
998            "observable combo mask {mask:?} must be non-empty, contain only 'E' and '_', and include at least one 'E'"
999        )));
1000    }
1001    Ok(())
1002}
1003
1004pub(crate) fn validate_observable_combo_mask_for_task(
1005    mask: &str,
1006    task: &LogicalCollectionTask,
1007) -> NpResult<()> {
1008    let observable_count = task.sampler.observable_ids().len();
1009    if mask.len() != observable_count {
1010        return Err(NpError::new(format!(
1011            "custom observable combo mask {mask:?} has width {}, but task {:?} has {observable_count} observables",
1012            mask.len(), task.task_id
1013        )));
1014    }
1015    for (index, value) in mask.bytes().enumerate() {
1016        if value == b'E' && packed_mask_bit(task.postselected_observables_mask.as_deref(), index) {
1017            return Err(NpError::new(format!(
1018                "custom observable combo mask {mask:?} marks postselected observable index {index} as an error for task {:?}",
1019                task.task_id
1020            )));
1021        }
1022    }
1023    Ok(())
1024}
1025
1026fn packed_mask_bit(mask: Option<&[u8]>, index: usize) -> bool {
1027    mask.and_then(|bytes| bytes.get(index / 8))
1028        .is_some_and(|byte| byte & (1 << (index % 8)) != 0)
1029}