1use std::collections::HashMap;
2use std::sync::Arc;
3
4use crate::pauli::pauli_to_xz;
5use crate::{
6 bernoulli_mask, choose_weighted_event, compile_pauli_channel_events, for_each_bernoulli_event,
7 set_shot_bit, word_count, Circuit, HotspotEstimate, IndexedNoiseLocation, LocationCatalog,
8 LogicalObservable, Mask, NoiseModel, NpError, NpResult, SmallRng,
9 TWO_QUBIT_DEPOLARIZING_EVENTS,
10};
11
12#[derive(Debug, Clone, PartialEq)]
25pub struct SamplerProgram {
26 n_qubits: usize,
27 operations: Vec<SamplerOperation>,
28 observables: Vec<LogicalObservable>,
29 compiled_observables: Vec<SamplerObservable>,
30 measurement_keys: Vec<String>,
31 noise_locations: Vec<IndexedNoiseLocation>,
32 location_catalog: LocationCatalog,
33 capacities: RuntimeCapacities,
34 stored_operation_count: usize,
35 logical_operation_count: usize,
36 loop_kernel_count: usize,
37 hotspot_layout_identity: Arc<()>,
38}
39
40impl SamplerProgram {
41 #[allow(clippy::too_many_arguments)]
42 pub(crate) fn from_compiled_parts(
43 n_qubits: usize,
44 operations: Vec<SamplerOperation>,
45 observables: Vec<LogicalObservable>,
46 compiled_observables: Vec<SamplerObservable>,
47 measurement_keys: Vec<String>,
48 noise_locations: Vec<IndexedNoiseLocation>,
49 location_catalog: LocationCatalog,
50 capacities: RuntimeCapacities,
51 stored_operation_count: usize,
52 logical_operation_count: usize,
53 loop_kernel_count: usize,
54 ) -> Self {
55 Self {
56 n_qubits,
57 operations,
58 observables,
59 compiled_observables,
60 measurement_keys,
61 noise_locations,
62 location_catalog,
63 capacities,
64 stored_operation_count,
65 logical_operation_count,
66 loop_kernel_count,
67 hotspot_layout_identity: Arc::new(()),
68 }
69 }
70
71 pub fn n_qubits(&self) -> usize {
72 self.n_qubits
73 }
74
75 pub fn operations(&self) -> &[SamplerOperation] {
76 &self.operations
77 }
78
79 pub fn observables(&self) -> &[LogicalObservable] {
80 &self.observables
81 }
82
83 pub fn compiled_observables(&self) -> &[SamplerObservable] {
84 &self.compiled_observables
85 }
86
87 pub fn measurement_keys(&self) -> &[String] {
88 &self.measurement_keys
89 }
90
91 pub fn noise_locations(&self) -> &[IndexedNoiseLocation] {
92 &self.noise_locations
93 }
94
95 pub fn location_catalog(&self) -> &LocationCatalog {
96 &self.location_catalog
97 }
98
99 pub fn capacities(&self) -> &RuntimeCapacities {
100 &self.capacities
101 }
102
103 pub fn stored_operation_count(&self) -> usize {
104 self.stored_operation_count
105 }
106
107 pub fn logical_operation_count(&self) -> usize {
108 self.logical_operation_count
109 }
110
111 pub fn loop_kernel_count(&self) -> usize {
112 self.loop_kernel_count
113 }
114
115 fn validate_hotspot_state(&self, state: &RuntimeState) -> NpResult<()> {
116 let state_layout = state.hotspot_layout_identity.as_ref().ok_or_else(|| {
117 NpError::new("hotspot state is not bound to a compiled sampler program")
118 })?;
119 if !Arc::ptr_eq(state_layout, &self.hotspot_layout_identity) {
120 return Err(NpError::new(
121 "hotspot state layout does not match the current simulator",
122 ));
123 }
124 if state.shots == 0 {
125 return Err(NpError::new(
126 "forward hotspot estimation requires shots to be positive",
127 ));
128 }
129 if !state.record_events {
130 return Err(NpError::new(
131 "forward hotspot estimation requires recorded event masks",
132 ));
133 }
134 Ok(())
135 }
136
137 pub fn estimate_from_loss(
139 &self,
140 state: &RuntimeState,
141 loss_mask: &Mask,
142 baseline: Option<f64>,
143 top_k: usize,
144 ) -> NpResult<HotspotEstimate> {
145 self.validate_hotspot_state(state)?;
146 crate::hotspot::validate_loss_mask_width("forward hotspot", state.shots, loss_mask)?;
147 Ok(crate::hotspot::compute_packed_estimate_trusted(
148 &self.noise_locations,
149 &self.location_catalog,
150 state,
151 loss_mask,
152 baseline,
153 top_k,
154 ))
155 }
156}
157
158#[derive(Debug, Clone, PartialEq)]
160pub struct SamplerObservable {
161 pub id: i64,
162 pub measurement_ids: Vec<usize>,
163 pub pauli_qubits: Vec<usize>,
164 pub pauli: String,
165}
166
167#[derive(Debug, Clone, Copy, PartialEq, Eq)]
169pub enum PauliBasis {
170 X,
171 Y,
172 Z,
173}
174
175impl PauliBasis {
176 pub(crate) fn parse(value: &str) -> NpResult<Self> {
177 match value {
178 "X" => Ok(Self::X),
179 "Y" => Ok(Self::Y),
180 "Z" => Ok(Self::Z),
181 _ => Err(NpError::new(format!(
182 "unsupported measurement basis {value:?}"
183 ))),
184 }
185 }
186
187 pub(crate) const fn as_str(self) -> &'static str {
188 match self {
189 Self::X => "X",
190 Self::Y => "Y",
191 Self::Z => "Z",
192 }
193 }
194}
195
196#[derive(Debug, Clone, PartialEq)]
198pub enum SamplerOperation {
199 H(usize),
200 S(usize),
201 SDag(usize),
202 Cx(usize, usize),
203 Cz(usize, usize),
204 Swap(usize, usize),
205 Noise(usize),
206 MeasureSingle {
207 qubit: usize,
208 basis: PauliBasis,
209 measurement_id: usize,
210 ideal: crate::Expr,
211 noise: Option<usize>,
212 },
213 MeasurePauli {
214 qubits: Vec<usize>,
215 pauli: String,
216 measurement_id: usize,
217 ideal: crate::Expr,
218 noise: Option<usize>,
219 },
220 Reset {
221 qubit: usize,
222 measurement_id: Option<usize>,
223 basis: PauliBasis,
224 ideal: crate::Expr,
225 },
226 Detector {
227 detector_id: i64,
228 measurement_ids: Vec<usize>,
229 },
230 ObservableInclude {
231 observable_id: i64,
232 measurement_ids: Vec<usize>,
233 },
234}
235
236#[derive(Debug, Clone, PartialEq)]
243pub struct FaultScopeSimulator {
244 program: SamplerProgram,
245}
246
247impl FaultScopeSimulator {
248 pub fn new(circuit: Circuit, observables: Vec<LogicalObservable>) -> NpResult<Self> {
250 Self::from_circuit_ref(&circuit, observables)
251 }
252
253 pub fn from_circuit_ref(
255 circuit: &Circuit,
256 observables: Vec<LogicalObservable>,
257 ) -> NpResult<Self> {
258 let program =
259 crate::compile_sampler_program_ref(circuit.n_qubits, &circuit.operations, observables)?;
260 Ok(Self { program })
261 }
262
263 pub fn program(&self) -> &SamplerProgram {
265 &self.program
266 }
267
268 pub fn run_batch(
273 &self,
274 shots: usize,
275 seed: Option<u64>,
276 record_events: bool,
277 ) -> NpResult<RuntimeState> {
278 if shots == 0 {
279 return Err(NpError::new("shots must be positive"));
280 }
281 run_sampler_program(&self.program, shots, seed, record_events)
282 }
283
284 pub fn estimate_from_loss(
291 &self,
292 state: &RuntimeState,
293 loss_mask: &Mask,
294 baseline: Option<f64>,
295 top_k: usize,
296 ) -> NpResult<HotspotEstimate> {
297 self.program
298 .estimate_from_loss(state, loss_mask, baseline, top_k)
299 }
300}
301
302#[derive(Debug, Clone, PartialEq)]
303pub struct RuntimeState {
304 pub(crate) shots: usize,
305 pub(crate) all_mask: Mask,
306 pub x_frame: Vec<Mask>,
307 pub z_frame: Vec<Mask>,
308 pub measurements: Vec<Option<Mask>>,
309 pub detectors: HashMap<i64, Mask>,
310 pub observables: HashMap<i64, Mask>,
311 pub(crate) event_masks: Vec<Mask>,
312 pub(crate) record_events: bool,
313 hotspot_layout_identity: Option<Arc<()>>,
314}
315
316impl RuntimeState {
317 pub fn shots(&self) -> usize {
318 self.shots
319 }
320
321 pub fn all_mask(&self) -> &Mask {
322 &self.all_mask
323 }
324
325 pub fn event_masks(&self) -> &[Mask] {
326 &self.event_masks
327 }
328
329 pub fn records_events(&self) -> bool {
330 self.record_events
331 }
332
333 pub fn new(
334 n_qubits: usize,
335 shots: usize,
336 measurement_count: usize,
337 noise_location_count: usize,
338 record_events: bool,
339 ) -> Self {
340 Self::new_with_capacities(
341 n_qubits,
342 shots,
343 measurement_count,
344 noise_location_count,
345 record_events,
346 0,
347 0,
348 )
349 }
350
351 fn new_with_capacities(
352 n_qubits: usize,
353 shots: usize,
354 measurement_count: usize,
355 noise_location_count: usize,
356 record_events: bool,
357 detector_capacity: usize,
358 observable_capacity: usize,
359 ) -> Self {
360 let words = word_count(shots);
361 let all_mask = Mask::all(shots);
362 let event_masks = if record_events {
363 vec![Mask::zero(words); noise_location_count]
364 } else {
365 Vec::new()
366 };
367 Self {
368 shots,
369 all_mask,
370 x_frame: vec![Mask::zero(words); n_qubits],
371 z_frame: vec![Mask::zero(words); n_qubits],
372 measurements: vec![None; measurement_count],
373 detectors: HashMap::with_capacity(detector_capacity),
374 observables: HashMap::with_capacity(observable_capacity),
375 event_masks,
376 record_events,
377 hotspot_layout_identity: None,
378 }
379 }
380}
381
382pub fn run_sampler_program(
384 program: &SamplerProgram,
385 shots: usize,
386 seed: Option<u64>,
387 record_events: bool,
388) -> NpResult<RuntimeState> {
389 let mut rng = SmallRng::new(seed.unwrap_or(0x4d59_5df4_d0f3_3173));
390 let mut state = RuntimeState::new_with_capacities(
391 program.n_qubits,
392 shots,
393 program.measurement_keys.len(),
394 program.noise_locations.len(),
395 record_events,
396 program.capacities.detectors,
397 program
398 .capacities
399 .observables
400 .max(program.compiled_observables.len()),
401 );
402 state.hotspot_layout_identity = Some(program.hotspot_layout_identity.clone());
403 let random_masks = random_masks_flat(
404 &mut rng,
405 program.capacities.random_sources,
406 state.all_mask.words.len(),
407 state.shots,
408 );
409 for operation in &program.operations {
410 apply_sampler_operation(operation, program, &mut state, &random_masks, &mut rng)?;
411 }
412 evaluate_sampler_observables(program, &mut state)?;
413 Ok(state)
414}
415
416fn random_masks_flat(
417 rng: &mut SmallRng,
418 random_source_count: usize,
419 mask_words: usize,
420 shots: usize,
421) -> Vec<u64> {
422 let mut random_masks = vec![0u64; random_source_count * mask_words];
423 if mask_words == 0 {
424 return random_masks;
425 }
426 for mask in random_masks.chunks_exact_mut(mask_words) {
427 for word in mask.iter_mut() {
428 *word = rng.next_u64();
429 }
430 if shots % 64 != 0 {
431 mask[mask_words - 1] &= (1u64 << (shots % 64)) - 1;
432 }
433 }
434 random_masks
435}
436
437fn apply_sampler_operation(
438 operation: &SamplerOperation,
439 program: &SamplerProgram,
440 state: &mut RuntimeState,
441 random_masks: &[u64],
442 rng: &mut SmallRng,
443) -> NpResult<()> {
444 let random_mask_words = state.all_mask.words.len();
445 match operation {
446 SamplerOperation::H(qubit) => {
447 std::mem::swap(&mut state.x_frame[*qubit], &mut state.z_frame[*qubit]);
448 }
449 SamplerOperation::S(qubit) | SamplerOperation::SDag(qubit) => {
450 state.z_frame[*qubit].xor_assign(&state.x_frame[*qubit]);
451 }
452 SamplerOperation::Cx(control, target) => {
453 xor_mask_between(&mut state.x_frame, *control, *target);
454 xor_mask_between(&mut state.z_frame, *target, *control);
455 }
456 SamplerOperation::Cz(left, right) => {
457 if left != right {
458 state.z_frame[*left].xor_assign(&state.x_frame[*right]);
459 state.z_frame[*right].xor_assign(&state.x_frame[*left]);
460 }
461 }
462 SamplerOperation::Swap(left, right) => {
463 state.x_frame.swap(*left, *right);
464 state.z_frame.swap(*left, *right);
465 }
466 SamplerOperation::Noise(noise_id) => {
467 sample_noise(*noise_id, &program.noise_locations[*noise_id], state, rng)?;
468 }
469 SamplerOperation::MeasureSingle {
470 qubit,
471 basis,
472 measurement_id,
473 ideal,
474 noise,
475 } => {
476 let mut bit = ideal.eval_flat(random_masks, random_mask_words, &state.all_mask);
477 xor_single_basis_measurement_flip_into(&mut bit, state, *qubit, *basis);
478 if let Some(noise_id) = noise {
479 sample_measurement_noise_into(
480 *noise_id,
481 &program.noise_locations[*noise_id],
482 state,
483 rng,
484 &mut bit,
485 )?;
486 }
487 record_indexed_measurement(&mut state.measurements, *measurement_id, bit)?;
488 }
489 SamplerOperation::MeasurePauli {
490 qubits,
491 pauli,
492 measurement_id,
493 ideal,
494 noise,
495 } => {
496 let mut bit = ideal.eval_flat(random_masks, random_mask_words, &state.all_mask);
497 xor_frame_measurement_flip_into(&mut bit, state, qubits, pauli)?;
498 if let Some(noise_id) = noise {
499 sample_measurement_noise_into(
500 *noise_id,
501 &program.noise_locations[*noise_id],
502 state,
503 rng,
504 &mut bit,
505 )?;
506 }
507 record_indexed_measurement(&mut state.measurements, *measurement_id, bit)?;
508 }
509 SamplerOperation::Reset {
510 qubit,
511 measurement_id,
512 basis,
513 ideal,
514 } => {
515 if let Some(measurement_id) = measurement_id {
516 let mut outcome = ideal.eval_flat(random_masks, random_mask_words, &state.all_mask);
517 xor_single_basis_measurement_flip_into(&mut outcome, state, *qubit, *basis);
518 record_indexed_measurement(&mut state.measurements, *measurement_id, outcome)?;
519 }
520 state.x_frame[*qubit].words.fill(0);
521 state.z_frame[*qubit].words.fill(0);
522 }
523 SamplerOperation::Detector {
524 detector_id,
525 measurement_ids,
526 } => {
527 let value = indexed_measurement_parity(
528 &state.measurements,
529 measurement_ids,
530 state.all_mask.words.len(),
531 )?;
532 state.detectors.insert(*detector_id, value);
533 }
534 SamplerOperation::ObservableInclude {
535 observable_id,
536 measurement_ids,
537 } => {
538 let value = indexed_measurement_parity(
539 &state.measurements,
540 measurement_ids,
541 state.all_mask.words.len(),
542 )?;
543 state
544 .observables
545 .entry(*observable_id)
546 .and_modify(|existing| existing.xor_assign(&value))
547 .or_insert(value);
548 }
549 }
550 Ok(())
551}
552
553fn xor_single_basis_measurement_flip_into(
554 target: &mut Mask,
555 state: &RuntimeState,
556 qubit: usize,
557 basis: PauliBasis,
558) {
559 match basis {
560 PauliBasis::X => target.xor_assign(&state.z_frame[qubit]),
561 PauliBasis::Y => {
562 target.xor_assign(&state.x_frame[qubit]);
563 target.xor_assign(&state.z_frame[qubit]);
564 }
565 PauliBasis::Z => target.xor_assign(&state.x_frame[qubit]),
566 }
567}
568
569fn record_indexed_measurement(
570 measurements: &mut [Option<Mask>],
571 measurement_id: usize,
572 value: Mask,
573) -> NpResult<()> {
574 if measurements[measurement_id].is_some() {
575 return Err(NpError::new(format!(
576 "duplicate internal measurement id {measurement_id}"
577 )));
578 }
579 measurements[measurement_id] = Some(value);
580 Ok(())
581}
582
583fn indexed_measurement_parity(
584 measurements: &[Option<Mask>],
585 measurement_ids: &[usize],
586 words: usize,
587) -> NpResult<Mask> {
588 let mut parity = Mask::zero(words);
589 for measurement_id in measurement_ids {
590 let value = measurements[*measurement_id].as_ref().ok_or_else(|| {
591 NpError::new(format!("unknown internal measurement id {measurement_id}"))
592 })?;
593 parity.xor_assign(value);
594 }
595 Ok(parity)
596}
597
598fn evaluate_sampler_observables(
599 program: &SamplerProgram,
600 state: &mut RuntimeState,
601) -> NpResult<()> {
602 for observable in &program.compiled_observables {
603 let mut value = indexed_measurement_parity(
604 &state.measurements,
605 &observable.measurement_ids,
606 state.all_mask.words.len(),
607 )?;
608 if !observable.pauli.is_empty() {
609 xor_frame_measurement_flip_into(
610 &mut value,
611 state,
612 &observable.pauli_qubits,
613 &observable.pauli,
614 )?;
615 }
616 state.observables.insert(observable.id, value);
617 }
618 Ok(())
619}
620
621#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
623pub struct RuntimeCapacities {
624 pub random_sources: usize,
625 pub measurements: usize,
626 pub detectors: usize,
627 pub observables: usize,
628}
629
630fn xor_mask_between(masks: &mut [Mask], source: usize, target: usize) {
631 if source == target {
632 masks[target].words.fill(0);
633 } else if source < target {
634 let (left, right) = masks.split_at_mut(target);
635 right[0].xor_assign(&left[source]);
636 } else {
637 let (left, right) = masks.split_at_mut(source);
638 left[target].xor_assign(&right[0]);
639 }
640}
641
642fn sample_noise(
643 noise_id: usize,
644 location: &IndexedNoiseLocation,
645 state: &mut RuntimeState,
646 rng: &mut SmallRng,
647) -> NpResult<()> {
648 match &location.model {
649 NoiseModel::MeasurementBitFlip => Err(NpError::new(
650 "MeasurementBitFlip must be attached to a measurement operation",
651 )),
652 NoiseModel::BernoulliPauli(pauli) => {
653 sample_fixed_pauli_noise(noise_id, location, state, rng, pauli)
654 }
655 NoiseModel::SingleQubitDepolarizing => {
656 sample_single_qubit_depolarizing_noise(noise_id, location, state, rng)
657 }
658 NoiseModel::TwoQubitDepolarizing => {
659 sample_two_qubit_depolarizing_noise(noise_id, location, state, rng)
660 }
661 NoiseModel::PauliChannel(weights) => {
662 sample_pauli_channel_noise(noise_id, location, state, rng, weights)
663 }
664 }
665}
666
667fn sample_measurement_noise_into(
668 noise_id: usize,
669 location: &IndexedNoiseLocation,
670 state: &mut RuntimeState,
671 rng: &mut SmallRng,
672 target: &mut Mask,
673) -> NpResult<()> {
674 if !matches!(location.model, NoiseModel::MeasurementBitFlip) {
675 return Err(NpError::new(
676 "native measurement noise supports MeasurementBitFlip only",
677 ));
678 }
679 let mut event_mask = state
680 .record_events
681 .then(|| state.event_masks.get_mut(noise_id))
682 .flatten();
683 for_each_bernoulli_event(rng, state.shots, location.rate, |shot, _| {
684 let word = shot / 64;
685 let bit = 1u64 << (shot % 64);
686 target.words[word] ^= bit;
687 if let Some(mask) = event_mask.as_deref_mut() {
688 mask.words[word] ^= bit;
689 }
690 });
691 Ok(())
692}
693
694fn sample_fixed_pauli_noise(
695 noise_id: usize,
696 location: &IndexedNoiseLocation,
697 state: &mut RuntimeState,
698 rng: &mut SmallRng,
699 pauli: &str,
700) -> NpResult<()> {
701 let event_mask = bernoulli_mask(rng, state.shots, location.rate);
702 if state.record_events {
703 record_location_event_mask(state, noise_id, &event_mask);
704 }
705 apply_masked_pauli_to_frame(state, &location.qubits, pauli, &event_mask)
706}
707
708fn sample_single_qubit_depolarizing_noise(
709 noise_id: usize,
710 location: &IndexedNoiseLocation,
711 state: &mut RuntimeState,
712 rng: &mut SmallRng,
713) -> NpResult<()> {
714 let qubit = one_qubit(&location.qubits, "SingleQubitDepolarizing")?;
715 let mut event_mask = event_union_mask(state);
716 for_each_bernoulli_event(rng, state.shots, location.rate, |shot, rng| {
717 if let Some(mask) = &mut event_mask {
718 set_shot_bit(mask, shot);
719 }
720 match rng.next_u64() % 3 {
721 0 => xor_frame_shot(state, qubit, true, false, shot),
722 1 => xor_frame_shot(state, qubit, true, true, shot),
723 _ => xor_frame_shot(state, qubit, false, true, shot),
724 }
725 });
726 if let Some(mask) = event_mask {
727 record_location_event_mask(state, noise_id, &mask);
728 }
729 Ok(())
730}
731
732fn sample_two_qubit_depolarizing_noise(
733 noise_id: usize,
734 location: &IndexedNoiseLocation,
735 state: &mut RuntimeState,
736 rng: &mut SmallRng,
737) -> NpResult<()> {
738 let (left, right) = two_qubits(&location.qubits, "TwoQubitDepolarizing")?;
739 let mut event_mask = event_union_mask(state);
740 for_each_bernoulli_event(rng, state.shots, location.rate, |shot, rng| {
741 if let Some(mask) = &mut event_mask {
742 set_shot_bit(mask, shot);
743 }
744 let (left_x, left_z, right_x, right_z) = TWO_QUBIT_DEPOLARIZING_EVENTS
745 [(rng.next_u64() % TWO_QUBIT_DEPOLARIZING_EVENTS.len() as u64) as usize];
746 xor_frame_shot(state, left, left_x, left_z, shot);
747 xor_frame_shot(state, right, right_x, right_z, shot);
748 });
749 if let Some(mask) = event_mask {
750 record_location_event_mask(state, noise_id, &mask);
751 }
752 Ok(())
753}
754
755fn sample_pauli_channel_noise(
756 noise_id: usize,
757 location: &IndexedNoiseLocation,
758 state: &mut RuntimeState,
759 rng: &mut SmallRng,
760 weights: &[(String, f64)],
761) -> NpResult<()> {
762 let events = compile_pauli_channel_events(&location.qubits, weights)?;
763 let total: f64 = events.iter().map(|event| event.weight).sum();
764 if total <= 0.0 {
765 return Err(NpError::new(
766 "PauliChannel weights must have positive total weight",
767 ));
768 }
769 let mut event_mask = event_union_mask(state);
770 for_each_bernoulli_event(rng, state.shots, location.rate, |shot, rng| {
771 if let Some(mask) = &mut event_mask {
772 set_shot_bit(mask, shot);
773 }
774 let event_index = choose_weighted_event(&events, total, rng);
775 for (local_index, qubit) in location.qubits.iter().enumerate() {
776 xor_frame_shot(
777 state,
778 *qubit,
779 events[event_index].x[local_index],
780 events[event_index].z[local_index],
781 shot,
782 );
783 }
784 });
785 if let Some(mask) = event_mask {
786 record_location_event_mask(state, noise_id, &mask);
787 }
788 Ok(())
789}
790
791fn event_union_mask(state: &RuntimeState) -> Option<Mask> {
792 if state.record_events {
793 Some(Mask::zero(state.all_mask.words.len()))
794 } else {
795 None
796 }
797}
798
799fn record_location_event_mask(state: &mut RuntimeState, noise_id: usize, event_mask: &Mask) {
800 if state.record_events {
801 if let Some(mask) = state.event_masks.get_mut(noise_id) {
802 mask.or_assign(event_mask);
803 }
804 }
805}
806
807fn xor_frame_shot(state: &mut RuntimeState, qubit: usize, x: bool, z: bool, shot: usize) {
808 let word = shot / 64;
809 let bit = 1u64 << (shot % 64);
810 if x {
811 state.x_frame[qubit].words[word] ^= bit;
812 }
813 if z {
814 state.z_frame[qubit].words[word] ^= bit;
815 }
816}
817
818fn apply_masked_pauli_to_frame(
819 state: &mut RuntimeState,
820 qubits: &[usize],
821 pauli: &str,
822 mask: &Mask,
823) -> NpResult<()> {
824 if mask.is_zero() {
825 return Ok(());
826 }
827 if qubits.len() != pauli.len() {
828 return Err(NpError::new("event Pauli length does not match qubits"));
829 }
830 for (qubit, local) in qubits.iter().zip(pauli.chars()) {
831 let (x, z) = pauli_to_xz(local)?;
832 if x != 0 {
833 state.x_frame[*qubit].xor_assign(mask);
834 }
835 if z != 0 {
836 state.z_frame[*qubit].xor_assign(mask);
837 }
838 }
839 Ok(())
840}
841
842fn xor_frame_measurement_flip_into(
843 target: &mut Mask,
844 state: &RuntimeState,
845 qubits: &[usize],
846 pauli: &str,
847) -> NpResult<()> {
848 if qubits.len() != pauli.len() {
849 return Err(NpError::new("qubits and pauli must have the same length"));
850 }
851 for (qubit, local) in qubits.iter().zip(pauli.chars()) {
852 let (x, z) = pauli_to_xz(local)?;
853 if z != 0 {
854 target.xor_assign(&state.x_frame[*qubit]);
855 }
856 if x != 0 {
857 target.xor_assign(&state.z_frame[*qubit]);
858 }
859 }
860 Ok(())
861}
862
863fn one_qubit(qubits: &[usize], kind: &str) -> NpResult<usize> {
864 if qubits.len() == 1 {
865 Ok(qubits[0])
866 } else {
867 Err(NpError::new(format!("{kind} requires exactly one qubit")))
868 }
869}
870
871fn two_qubits(qubits: &[usize], kind: &str) -> NpResult<(usize, usize)> {
872 if qubits.len() == 2 {
873 Ok((qubits[0], qubits[1]))
874 } else {
875 Err(NpError::new(format!("{kind} requires two qubits")))
876 }
877}
878
879#[cfg(test)]
880mod tests {
881 use super::*;
882 use crate::labels::LocationCatalogBuilder;
883 use crate::{Expr, NoiseLocation, Operation};
884
885 fn patterned_mask(shots: usize, offset: usize) -> Mask {
886 let mut mask = Mask::zero(word_count(shots));
887 for shot in 0..shots {
888 if (shot + offset) % 3 == 0 {
889 set_shot_bit(&mut mask, shot);
890 }
891 }
892 mask
893 }
894
895 fn empty_sampler_program(n_qubits: usize) -> SamplerProgram {
896 SamplerProgram {
897 n_qubits,
898 operations: Vec::new(),
899 observables: Vec::new(),
900 compiled_observables: Vec::new(),
901 measurement_keys: Vec::new(),
902 noise_locations: Vec::new(),
903 location_catalog: LocationCatalog::default(),
904 capacities: RuntimeCapacities::default(),
905 stored_operation_count: 0,
906 logical_operation_count: 0,
907 loop_kernel_count: 0,
908 hotspot_layout_identity: Arc::new(()),
909 }
910 }
911
912 fn apply_test_operation(
913 operation: SamplerOperation,
914 program: &SamplerProgram,
915 state: &mut RuntimeState,
916 rng: &mut SmallRng,
917 ) {
918 apply_sampler_operation(&operation, program, state, &[], rng).unwrap();
919 }
920
921 #[test]
922 fn clifford_frame_updates_preserve_boundary_semantics() {
923 for shots in [1, 63, 64, 65, 129] {
924 let a = patterned_mask(shots, 0);
925 let b = patterned_mask(shots, 1);
926 let c = patterned_mask(shots, 2);
927 let d = patterned_mask(shots, 3);
928 let program = empty_sampler_program(2);
929 let mut rng = SmallRng::new(7);
930
931 let mut state = RuntimeState::new(2, shots, 0, 0, false);
932 state.x_frame[0] = a.clone();
933 state.z_frame[0] = b.clone();
934 apply_test_operation(SamplerOperation::H(0), &program, &mut state, &mut rng);
935 assert_eq!(state.x_frame[0], b);
936 assert_eq!(state.z_frame[0], a);
937
938 let mut state = RuntimeState::new(2, shots, 0, 0, false);
939 state.x_frame[0] = a.clone();
940 state.z_frame[0] = b.clone();
941 let mut expected = b.clone();
942 expected.xor_assign(&a);
943 apply_test_operation(SamplerOperation::S(0), &program, &mut state, &mut rng);
944 assert_eq!(state.z_frame[0], expected);
945 state.z_frame[0] = b.clone();
946 apply_test_operation(SamplerOperation::SDag(0), &program, &mut state, &mut rng);
947 assert_eq!(state.z_frame[0], expected);
948
949 let mut state = RuntimeState::new(2, shots, 0, 0, false);
950 state.x_frame = vec![a.clone(), b.clone()];
951 state.z_frame = vec![c.clone(), d.clone()];
952 let mut expected_x_target = b.clone();
953 expected_x_target.xor_assign(&a);
954 let mut expected_z_control = c.clone();
955 expected_z_control.xor_assign(&d);
956 apply_test_operation(SamplerOperation::Cx(0, 1), &program, &mut state, &mut rng);
957 assert_eq!(state.x_frame, vec![a.clone(), expected_x_target]);
958 assert_eq!(state.z_frame, vec![expected_z_control, d.clone()]);
959
960 let mut state = RuntimeState::new(2, shots, 0, 0, false);
961 state.x_frame = vec![a.clone(), b.clone()];
962 state.z_frame = vec![c.clone(), d.clone()];
963 let mut expected_z_left = c.clone();
964 expected_z_left.xor_assign(&b);
965 let mut expected_z_right = d.clone();
966 expected_z_right.xor_assign(&a);
967 apply_test_operation(SamplerOperation::Cz(0, 1), &program, &mut state, &mut rng);
968 assert_eq!(state.z_frame, vec![expected_z_left, expected_z_right]);
969
970 let mut state = RuntimeState::new(2, shots, 0, 0, false);
971 state.x_frame = vec![a.clone(), b.clone()];
972 state.z_frame = vec![c.clone(), d.clone()];
973 apply_test_operation(SamplerOperation::Swap(0, 1), &program, &mut state, &mut rng);
974 assert_eq!(state.x_frame, vec![b.clone(), a.clone()]);
975 assert_eq!(state.z_frame, vec![d.clone(), c.clone()]);
976
977 let mut state = RuntimeState::new(1, shots, 1, 0, false);
978 state.x_frame[0] = a.clone();
979 state.z_frame[0] = b;
980 let mut reset_program = empty_sampler_program(1);
981 reset_program.measurement_keys.push("reset".to_string());
982 apply_test_operation(
983 SamplerOperation::Reset {
984 qubit: 0,
985 measurement_id: Some(0),
986 basis: PauliBasis::Z,
987 ideal: Expr::constant(false),
988 },
989 &reset_program,
990 &mut state,
991 &mut rng,
992 );
993 assert_eq!(state.measurements[0], Some(a));
994 assert_eq!(state.x_frame[0], Mask::zero(word_count(shots)));
995 assert_eq!(state.z_frame[0], Mask::zero(word_count(shots)));
996 }
997 }
998
999 #[test]
1000 fn faultscope_simulator_owns_the_canonical_sampler_program() {
1001 let circuit = Circuit {
1002 n_qubits: 2,
1003 operations: vec![
1004 Operation::H(0),
1005 Operation::Cx(0, 1),
1006 Operation::Noise(NoiseLocation {
1007 id: "n".to_string(),
1008 model: NoiseModel::BernoulliPauli("X".to_string()),
1009 rate: 0.2,
1010 qubits: vec![0],
1011 tags: HashMap::new(),
1012 }),
1013 Operation::Measure {
1014 qubit: 0,
1015 key: Some("m0".to_string()),
1016 basis: "Z".to_string(),
1017 noise: Some(NoiseLocation {
1018 id: "nm".to_string(),
1019 model: NoiseModel::MeasurementBitFlip,
1020 rate: 0.15,
1021 qubits: vec![0],
1022 tags: HashMap::new(),
1023 }),
1024 },
1025 Operation::Reset {
1026 qubit: 1,
1027 key: Some("m1".to_string()),
1028 basis: "X".to_string(),
1029 },
1030 Operation::Detector {
1031 detector_id: Some(3),
1032 measurement_keys: vec!["m0".to_string(), "m1".to_string()],
1033 coords: Vec::new(),
1034 },
1035 Operation::ObservableInclude {
1036 observable_id: 5,
1037 measurement_keys: vec!["m0".to_string()],
1038 },
1039 ],
1040 };
1041 let observables = vec![LogicalObservable {
1042 id: 6,
1043 measurement_keys: vec!["m1".to_string()],
1044 pauli_qubits: vec![0],
1045 pauli: "X".to_string(),
1046 }];
1047 let public = FaultScopeSimulator::from_circuit_ref(&circuit, observables.clone()).unwrap();
1048 let compact =
1049 crate::compile_sampler_program_ref(circuit.n_qubits, &circuit.operations, observables)
1050 .unwrap();
1051
1052 assert_eq!(compact, public.program);
1053 let public_state = public.run_batch(129, Some(9182), true).unwrap();
1054 let compact_state = run_sampler_program(&compact, 129, Some(9182), true).unwrap();
1055 assert_eq!(compact_state, public_state);
1056 }
1057
1058 #[test]
1059 fn compact_sampler_preserves_unknown_measurement_error() {
1060 let circuit = Circuit {
1061 n_qubits: 1,
1062 operations: vec![Operation::Detector {
1063 detector_id: Some(0),
1064 measurement_keys: vec!["missing".to_string()],
1065 coords: Vec::new(),
1066 }],
1067 };
1068 let public = FaultScopeSimulator::from_circuit_ref(&circuit, Vec::new()).unwrap();
1069 let compact =
1070 crate::compile_sampler_program_ref(1, &circuit.operations, Vec::new()).unwrap();
1071
1072 let public_error = public.run_batch(65, Some(1), false).unwrap_err();
1073 let compact_error = run_sampler_program(&compact, 65, Some(1), false).unwrap_err();
1074 assert_eq!(compact_error.message(), public_error.message());
1075 }
1076
1077 #[test]
1078 fn faultscope_simulator_repeat_program_matches_direct_compile() {
1079 let circuit = Circuit {
1080 n_qubits: 2,
1081 operations: vec![Operation::Repeat {
1082 count: 8,
1083 body: vec![
1084 Operation::H(0),
1085 Operation::Cx(0, 1),
1086 Operation::MeasureReset {
1087 qubit: 0,
1088 basis: "Z".to_string(),
1089 },
1090 Operation::MeasureReset {
1091 qubit: 1,
1092 basis: "X".to_string(),
1093 },
1094 Operation::DetectorRec {
1095 detector_id: None,
1096 lookbacks: vec![1, 2],
1097 coords: Vec::new(),
1098 },
1099 Operation::ObservableIncludeRec {
1100 observable_id: 0,
1101 lookbacks: vec![2],
1102 },
1103 ],
1104 }],
1105 };
1106 let public = FaultScopeSimulator::from_circuit_ref(&circuit, Vec::new()).unwrap();
1107 let compact =
1108 crate::compile_sampler_program_ref(2, &circuit.operations, Vec::new()).unwrap();
1109
1110 assert_eq!(compact, public.program);
1111 let public_state = public.run_batch(130, Some(73), false).unwrap();
1112 let compact_state = run_sampler_program(&compact, 130, Some(73), false).unwrap();
1113 assert_eq!(compact_state, public_state);
1114 }
1115
1116 #[test]
1117 fn in_place_measurement_noise_matches_mask_sampler() {
1118 for shots in [1, 63, 64, 65, 129] {
1119 let location = NoiseLocation {
1120 id: "measurement".to_string(),
1121 model: NoiseModel::MeasurementBitFlip,
1122 rate: 0.17,
1123 qubits: vec![0],
1124 tags: HashMap::new(),
1125 };
1126 let mut expected_rng = SmallRng::new(1234);
1127 let expected = bernoulli_mask(&mut expected_rng, shots, location.rate);
1128 let mut program = empty_sampler_program(1);
1129 program.measurement_keys.push("m".to_string());
1130 let mut catalog = LocationCatalogBuilder::with_capacity(1);
1131 let location_id = catalog.intern(location.id.clone(), location.tags.clone());
1132 program
1133 .noise_locations
1134 .push(IndexedNoiseLocation::from_input(location_id, location));
1135 program.location_catalog = catalog.finish();
1136 program.capacities.measurements = 1;
1137 program.operations.push(SamplerOperation::MeasureSingle {
1138 qubit: 0,
1139 basis: PauliBasis::Z,
1140 measurement_id: 0,
1141 ideal: Expr::constant(false),
1142 noise: Some(0),
1143 });
1144 let state = run_sampler_program(&program, shots, Some(1234), true).unwrap();
1145 assert_eq!(state.measurements[0].as_ref(), Some(&expected));
1146 assert_eq!(state.event_masks[0], expected);
1147 }
1148 }
1149
1150 #[test]
1151 fn sampler_program_records_measurement_and_detector() {
1152 let mut program = empty_sampler_program(1);
1153 program.measurement_keys.push("m0".to_string());
1154 program.capacities.measurements = 1;
1155 program.capacities.detectors = 1;
1156 program.operations = vec![
1157 SamplerOperation::MeasureSingle {
1158 qubit: 0,
1159 basis: PauliBasis::Z,
1160 measurement_id: 0,
1161 ideal: Expr::constant(false),
1162 noise: None,
1163 },
1164 SamplerOperation::Detector {
1165 detector_id: 0,
1166 measurement_ids: vec![0],
1167 },
1168 ];
1169
1170 let state = run_sampler_program(&program, 5, Some(1), true).unwrap();
1171
1172 assert_eq!(state.measurements[0], Some(Mask::zero(1)));
1173 assert_eq!(state.detectors[&0], Mask::zero(1));
1174 }
1175
1176 #[test]
1177 fn sampler_program_preserves_zero_shot_behavior() {
1178 let mut program = empty_sampler_program(1);
1179 program.measurement_keys.push("m0".to_string());
1180 program.capacities.random_sources = 1;
1181 program.capacities.measurements = 1;
1182 program.operations.push(SamplerOperation::MeasureSingle {
1183 qubit: 0,
1184 basis: PauliBasis::Z,
1185 measurement_id: 0,
1186 ideal: Expr::random(0),
1187 noise: None,
1188 });
1189
1190 let state = run_sampler_program(&program, 0, Some(1), false).unwrap();
1191
1192 assert_eq!(state.shots, 0);
1193 assert!(state.measurements[0].as_ref().unwrap().words.is_empty());
1194 }
1195
1196 #[test]
1197 fn measurement_free_parity_and_frame_observables_preserve_batch_width() {
1198 let simulator = FaultScopeSimulator::new(
1199 Circuit {
1200 n_qubits: 1,
1201 operations: vec![
1202 Operation::Noise(NoiseLocation {
1203 id: "x0".to_string(),
1204 model: NoiseModel::BernoulliPauli("X".to_string()),
1205 rate: 1.0,
1206 qubits: vec![0],
1207 tags: HashMap::new(),
1208 }),
1209 Operation::Detector {
1210 detector_id: Some(7),
1211 measurement_keys: Vec::new(),
1212 coords: Vec::new(),
1213 },
1214 Operation::ObservableInclude {
1215 observable_id: 8,
1216 measurement_keys: Vec::new(),
1217 },
1218 ],
1219 },
1220 vec![LogicalObservable {
1221 id: 9,
1222 measurement_keys: Vec::new(),
1223 pauli_qubits: vec![0],
1224 pauli: "Z".to_string(),
1225 }],
1226 )
1227 .unwrap();
1228
1229 for shots in [0, 1, 63, 64, 65, 129, 513] {
1230 let state = run_sampler_program(&simulator.program, shots, Some(1), true).unwrap();
1231 let words = word_count(shots);
1232
1233 assert_eq!(state.all_mask.words.len(), words);
1234 assert_eq!(state.detectors[&7], Mask::zero(words));
1235 assert_eq!(state.observables[&8], Mask::zero(words));
1236 assert_eq!(state.observables[&9], state.all_mask);
1237 for mask in state
1238 .x_frame
1239 .iter()
1240 .chain(&state.z_frame)
1241 .chain(state.detectors.values())
1242 .chain(state.observables.values())
1243 .chain(&state.event_masks)
1244 {
1245 assert_eq!(mask.words.len(), words);
1246 }
1247 }
1248 }
1249
1250 #[test]
1251 fn simulator_compiles_and_estimates_loss_mask() {
1252 let location = NoiseLocation {
1253 id: "x0".to_string(),
1254 model: NoiseModel::BernoulliPauli("X".to_string()),
1255 rate: 1.0,
1256 qubits: vec![0],
1257 tags: HashMap::new(),
1258 };
1259 let simulator = FaultScopeSimulator::new(
1260 Circuit {
1261 n_qubits: 1,
1262 operations: vec![
1263 Operation::Noise(location),
1264 Operation::Measure {
1265 qubit: 0,
1266 key: Some("m0".to_string()),
1267 basis: "Z".to_string(),
1268 noise: None,
1269 },
1270 ],
1271 },
1272 Vec::new(),
1273 )
1274 .unwrap();
1275
1276 let state = simulator.run_batch(8, Some(1), true).unwrap();
1277 let measurement = state.measurements[0].as_ref().unwrap();
1278 let estimate = simulator
1279 .estimate_from_loss(&state, measurement, None, 1)
1280 .unwrap();
1281
1282 assert_eq!(measurement, &state.all_mask);
1283 assert_eq!(estimate.mean_loss, 1.0);
1284 assert_eq!(estimate.top_locations, vec!["x0"]);
1285 }
1286
1287 #[test]
1288 fn simulator_hotspot_rejects_unrecorded_foreign_and_unbound_states() {
1289 let circuit = Circuit {
1290 n_qubits: 1,
1291 operations: vec![Operation::Noise(NoiseLocation {
1292 id: "x0".to_string(),
1293 model: NoiseModel::BernoulliPauli("X".to_string()),
1294 rate: 0.25,
1295 qubits: vec![0],
1296 tags: HashMap::new(),
1297 })],
1298 };
1299 let simulator = FaultScopeSimulator::new(circuit.clone(), Vec::new()).unwrap();
1300 let foreign = FaultScopeSimulator::new(circuit, Vec::new()).unwrap();
1301 let state = simulator.run_batch(8, Some(1), true).unwrap();
1302 let loss = state.event_masks[0].clone();
1303
1304 let err = foreign
1305 .estimate_from_loss(&state, &loss, None, 1)
1306 .unwrap_err();
1307 assert!(err.to_string().contains("layout does not match"));
1308 simulator
1309 .clone()
1310 .estimate_from_loss(&state, &loss, None, 1)
1311 .unwrap();
1312
1313 let state = simulator.run_batch(8, Some(1), false).unwrap();
1314 let err = simulator
1315 .estimate_from_loss(&state, &Mask::zero(1), None, 1)
1316 .unwrap_err();
1317 assert!(err.to_string().contains("recorded event masks"));
1318
1319 let unbound = RuntimeState::new(1, 8, 0, 1, true);
1320 let err = simulator
1321 .estimate_from_loss(&unbound, &Mask::zero(1), None, 1)
1322 .unwrap_err();
1323 assert!(err.to_string().contains("not bound"));
1324 }
1325
1326 #[test]
1327 fn simulator_rejects_duplicate_noise_location_ids() {
1328 let location = NoiseLocation {
1329 id: "dup".to_string(),
1330 model: NoiseModel::BernoulliPauli("X".to_string()),
1331 rate: 0.1,
1332 qubits: vec![0],
1333 tags: HashMap::new(),
1334 };
1335
1336 let err = FaultScopeSimulator::new(
1337 Circuit {
1338 n_qubits: 1,
1339 operations: vec![
1340 Operation::Noise(location.clone()),
1341 Operation::Noise(location),
1342 ],
1343 },
1344 Vec::new(),
1345 )
1346 .unwrap_err();
1347
1348 assert!(err.message().contains("unique noise location ids"));
1349 }
1350}