rstim 0.4.0

Stim-aligned stabilizer circuit simulator and detector error model toolkit
Documentation
use crate::compiled::{CompiledBlock, CompiledCircuit, CompiledOp, CompiledRepeatRegion};
use crate::ir::{StimInstr, StimTarget};
use std::collections::BTreeMap;
use std::fmt;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CompiledPathDecision {
    FastPath,
    Fallback(&'static str),
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SamplingFallbackReason {
    Loss,
    MeasurementRecordFeedback,
    SweepDependent,
    UnsupportedOperation(String),
}

impl SamplingFallbackReason {
    pub fn message(&self) -> &'static str {
        match self {
            Self::Loss => "loss instructions require the interpreted path",
            Self::MeasurementRecordFeedback => "feedback instructions require the interpreted path",
            Self::SweepDependent => "sweep-dependent instructions require the interpreted path",
            Self::UnsupportedOperation(_) => {
                "unsupported sampler instructions require the interpreted path"
            }
        }
    }
}

impl fmt::Display for SamplingFallbackReason {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.message())
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SamplerPathDecision {
    FastPath,
    Fallback(SamplingFallbackReason),
}

pub fn choose_sampler_path(compiled: &CompiledCircuit) -> SamplerPathDecision {
    if compiled.flags.has_loss {
        return SamplerPathDecision::Fallback(SamplingFallbackReason::Loss);
    }
    if compiled.flags.has_feedback {
        return SamplerPathDecision::Fallback(SamplingFallbackReason::MeasurementRecordFeedback);
    }
    if compiled.flags.has_sweep_dependency {
        return SamplerPathDecision::Fallback(SamplingFallbackReason::SweepDependent);
    }
    if let Some(name) = first_unsupported_sampler_op(&compiled.blocks) {
        return SamplerPathDecision::Fallback(SamplingFallbackReason::UnsupportedOperation(name));
    }

    SamplerPathDecision::FastPath
}

fn first_unsupported_sampler_op(blocks: &[CompiledBlock]) -> Option<String> {
    blocks.iter().find_map(|block| match block {
        CompiledBlock::Ops(ops) => ops.iter().find_map(|op| match op {
            CompiledOp::UnsupportedSamplerOp { name } => Some(name.clone()),
            _ => None,
        }),
        CompiledBlock::Repeat(region) => first_unsupported_sampler_op(&region.body),
    })
}

pub fn choose_analyzer_path(compiled: &CompiledCircuit) -> CompiledPathDecision {
    if compiled.flags.has_loss {
        return CompiledPathDecision::Fallback("loss instructions require the flattened analyzer");
    }
    if compiled.flags.has_feedback {
        return CompiledPathDecision::Fallback(
            "feedback instructions require the flattened analyzer",
        );
    }
    if compiled.flags.has_nested_repeat {
        return CompiledPathDecision::Fallback(
            "nested repeat blocks require the flattened analyzer",
        );
    }
    if let [CompiledBlock::Repeat(region)] = compiled.blocks.as_slice() {
        if supports_reset_periodic_body(region) {
            return CompiledPathDecision::FastPath;
        }
        return CompiledPathDecision::Fallback(
            "compiled analyzer currently supports only reset-based single top-level repeat regions",
        );
    }

    CompiledPathDecision::Fallback(
        "compiled analyzer currently supports only a single top-level repeat region",
    )
}

fn supports_reset_periodic_body(region: &CompiledRepeatRegion) -> bool {
    let mut has_reset_measurement = false;
    let mut measurements_seen = 0usize;
    let mut last_touch_was_reset_measurement = BTreeMap::<u32, bool>::new();

    for instr in &region.body_source {
        let StimInstr::Op { name, targets, .. } = instr else {
            return false;
        };

        if targets.iter().any(|target| {
            matches!(
                target,
                StimTarget::Rec(offset) if *offset >= 0 || ((-*offset) as usize) > measurements_seen
            )
        }) {
            return false;
        }

        match name.as_str() {
            "MR" | "MRX" | "MRY" | "MRZ" => {
                has_reset_measurement = true;
                measurements_seen += targets.iter().filter_map(StimTarget::qubit_index).count();
                for qubit in targets.iter().filter_map(StimTarget::qubit_index) {
                    last_touch_was_reset_measurement.insert(qubit, true);
                }
            }
            "M" | "MX" | "MY" | "MZ" | "MXX" | "MYY" | "MZZ" | "MPP" | "SPP" | "SPP_DAG" => {
                return false;
            }
            _ => {
                for qubit in targets.iter().filter_map(StimTarget::qubit_index) {
                    last_touch_was_reset_measurement.insert(qubit, false);
                }
            }
        }
    }

    has_reset_measurement
        && !last_touch_was_reset_measurement.is_empty()
        && last_touch_was_reset_measurement
            .values()
            .all(|was_reset| *was_reset)
}

#[cfg(test)]
mod tests {
    use super::supports_reset_periodic_body;
    use crate::compiled::{CompiledBlock, CompiledRepeatRegion, compile_circuit};
    use crate::parser::parse_lines;

    fn top_level_repeat_region<'a>(blocks: &'a [CompiledBlock]) -> &'a CompiledRepeatRegion {
        match blocks {
            [CompiledBlock::Repeat(region)] => region,
            _ => panic!("expected top-level repeat"),
        }
    }

    #[test]
    fn supports_reset_periodic_body_requires_reset_measurements() {
        let reset_repeat =
            compile_circuit(&parse_lines("REPEAT 8 {\n  X_ERROR(0.1) 0\n  MR 0\n}\n").unwrap())
                .unwrap();
        let plain_measure_repeat =
            compile_circuit(&parse_lines("REPEAT 8 {\n  X_ERROR(0.1) 0\n  M 0\n}\n").unwrap())
                .unwrap();

        let reset_region = top_level_repeat_region(reset_repeat.blocks.as_slice());
        let plain_region = top_level_repeat_region(plain_measure_repeat.blocks.as_slice());

        assert!(supports_reset_periodic_body(reset_region));
        assert!(!supports_reset_periodic_body(plain_region));
    }

    #[test]
    fn supports_reset_periodic_body_rejects_nested_repeat_in_body_source() {
        let nested_repeat =
            compile_circuit(&parse_lines("REPEAT 8 {\n  REPEAT 2 {\n    MR 0\n  }\n}\n").unwrap())
                .unwrap();

        let nested_region = top_level_repeat_region(nested_repeat.blocks.as_slice());

        assert!(!supports_reset_periodic_body(nested_region));
    }
}