Skip to main content

faultscope_core/
packed.rs

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/// Integer-indexed program used by the native forward sampler.
13///
14/// The program is an immutable, compiler-validated representation. Its
15/// collections are exposed as read-only slices so downstream safe Rust code
16/// cannot invalidate the indices trusted by the packed runtime.
17///
18/// ```compile_fail
19/// use faultscope_core::{compile_sampler_program_ref, SamplerOperation};
20///
21/// let mut program = compile_sampler_program_ref(1, &[], Vec::new()).unwrap();
22/// program.operations.push(SamplerOperation::H(usize::MAX));
23/// ```
24#[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    /// Estimate hotspots from a state produced by this program or one of its clones.
138    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/// Integer-indexed logical observable compiled against a sampler program.
159#[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/// Single-qubit Pauli measurement basis.
168#[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/// Executable instruction in a compact sampler program.
197#[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/// Compiled forward bit-packed simulator.
237///
238/// This is the Rust core counterpart of the Python
239/// `FaultScopeSimulator` API. It owns the canonical compact sampler program and
240/// can run batches without depending on PyO3 or Python callback objects. Custom
241/// decoder and loss callback integration remains in the Python binding crate.
242#[derive(Debug, Clone, PartialEq)]
243pub struct FaultScopeSimulator {
244    program: SamplerProgram,
245}
246
247impl FaultScopeSimulator {
248    /// Compile a typed circuit into the bit-packed forward simulator.
249    pub fn new(circuit: Circuit, observables: Vec<LogicalObservable>) -> NpResult<Self> {
250        Self::from_circuit_ref(&circuit, observables)
251    }
252
253    /// Compile a borrowed typed circuit without cloning its operation tree.
254    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    /// Return the immutable compiled sampler program.
264    pub fn program(&self) -> &SamplerProgram {
265        &self.program
266    }
267
268    /// Run a batch of forward trajectories.
269    ///
270    /// Set `record_events` when hotspot estimation needs per-location event
271    /// masks. `seed=None` uses the core default deterministic seed.
272    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    /// Estimate hotspot scores from an externally supplied loss mask.
285    ///
286    /// This method is useful when a decoder or loss function is implemented
287    /// outside of the core crate. The returned estimate is fully aggregated in
288    /// Rust. The state must come from this compiled program (or one of its
289    /// clones) and must have event recording enabled.
290    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
382/// Execute a previously compiled compact sampler program.
383pub 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/// Precomputed capacities used to allocate packed sampler runtime state.
622#[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}