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 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#[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
562pub 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
645pub 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
711pub 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
726pub 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
747pub 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
762pub 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}