use std::collections::{BTreeMap, BTreeSet};
use crate::dem::{DemInstruction, DemTarget};
use crate::dem_provenance::{HighlightRecord, TrackedDemResult};
use crate::ir::{PauliBasis, StimInstr, StimTarget};
use crate::sample_trace::{MeasurementComponent, MeasurementEvent, SampleTrace};
use serde::{Deserialize, Serialize};
use serde_json::json;
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct Qp101Document {
pub standard: String,
pub version: String,
pub num_qubits: usize,
pub operations: Vec<Qp101Operation>,
#[serde(skip_serializing_if = "Option::is_none")]
pub metadata: Option<serde_json::Value>,
#[serde(skip_serializing_if = "Option::is_none")]
pub extensions: Option<serde_json::Value>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct Qp101Annotation {
pub kind: String,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub target_slots: Vec<usize>,
#[serde(skip_serializing_if = "Option::is_none")]
pub label: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub text: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub style: Option<Qp101AnnotationStyle>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub tags: Vec<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub context: Option<serde_json::Value>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct Qp101AnnotationStyle {
#[serde(skip_serializing_if = "Option::is_none")]
pub preset: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub color: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub highlight: Option<bool>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(tag = "type")]
pub enum Qp101Operation {
#[serde(rename = "gate")]
Gate {
gate: String,
targets: Vec<u32>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
controls: Vec<u32>,
#[serde(skip_serializing_if = "Option::is_none")]
control_configs: Option<Vec<bool>>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
params: Vec<f64>,
#[serde(skip_serializing_if = "Option::is_none")]
raw_targets: Option<Vec<Qp101TargetRef>>,
#[serde(skip_serializing_if = "Option::is_none")]
display: Option<Qp101Display>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
tags: Vec<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
annotations: Vec<Qp101Annotation>,
},
#[serde(rename = "tick")]
Tick {
#[serde(default, skip_serializing_if = "Vec::is_empty")]
annotations: Vec<Qp101Annotation>,
},
#[serde(rename = "repeat")]
Repeat {
count: u64,
body: Vec<Qp101Operation>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
annotations: Vec<Qp101Annotation>,
},
#[serde(rename = "qubit_coords")]
QubitCoords {
coords: Vec<f64>,
targets: Vec<u32>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
annotations: Vec<Qp101Annotation>,
},
#[serde(rename = "shift_coords")]
ShiftCoords {
delta: Vec<f64>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
annotations: Vec<Qp101Annotation>,
},
#[serde(rename = "detector")]
Detector {
coords: Vec<f64>,
sources: Vec<Qp101TargetRef>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
annotations: Vec<Qp101Annotation>,
},
#[serde(rename = "observable_include")]
ObservableInclude {
index: u32,
sources: Vec<Qp101TargetRef>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
annotations: Vec<Qp101Annotation>,
},
#[serde(rename = "noise")]
Noise {
gate: String,
params: Vec<f64>,
raw_targets: Vec<Qp101TargetRef>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
annotations: Vec<Qp101Annotation>,
},
#[serde(rename = "annotation")]
Annotation {
kind: String,
text: String,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
annotations: Vec<Qp101Annotation>,
},
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(tag = "kind")]
pub enum Qp101TargetRef {
#[serde(rename = "qubit")]
Qubit {
index: u32,
#[serde(skip_serializing_if = "Option::is_none")]
inverted: Option<bool>,
},
#[serde(rename = "rec")]
Rec {
offset: i32,
},
#[serde(rename = "pauli")]
Pauli {
basis: Qp101PauliBasis,
qubit: u32,
#[serde(skip_serializing_if = "Option::is_none")]
inverted: Option<bool>,
},
#[serde(rename = "combiner")]
Combiner,
#[serde(rename = "sweep")]
Sweep {
index: u32,
},
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct Qp101Display {
#[serde(skip_serializing_if = "Option::is_none")]
pub label: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum Qp101PauliBasis {
X,
Y,
Z,
}
pub fn export_qp101(instrs: &[StimInstr]) -> Result<Qp101Document, String> {
Ok(Qp101Document {
standard: "QP101-ZY".to_string(),
version: "1.0".to_string(),
num_qubits: crate::stats::num_qubits(instrs),
operations: export_operations(instrs)?,
metadata: Some(json!({ "framework": "rstim" })),
extensions: None,
})
}
pub fn export_qp101_with_sample_trace(
instrs: &[StimInstr],
trace: &SampleTrace,
) -> Result<Qp101Document, String> {
validate_sample_trace_visualization_support(instrs)?;
let mut doc = export_qp101(instrs)?;
add_sample_noise_annotations(&mut doc.operations, trace)?;
add_sample_measurement_annotations(&mut doc.operations, trace)?;
add_sample_detector_annotations(&mut doc.operations, trace)?;
Ok(doc)
}
pub fn export_qp101_with_highlighted_dem_error(
instrs: &[StimInstr],
tracked: &TrackedDemResult,
dem_error_index: usize,
) -> Result<Qp101Document, String> {
let source_ids = tracked
.dem_error_to_sources
.get(dem_error_index)
.ok_or_else(|| {
format!(
"DEM error index {dem_error_index} out of range for {} tracked DEM errors",
tracked.dem_error_to_sources.len()
)
})?;
let mut source_highlights = Vec::with_capacity(source_ids.len());
for &source_id in source_ids {
let source = tracked.sources.get(source_id).ok_or_else(|| {
format!("tracked source index {source_id} missing for DEM error {dem_error_index}")
})?;
source_highlights.push((source, HighlightRecord::from_source(source)));
}
let dem_targets = match tracked.dem.instructions().get(dem_error_index) {
Some(DemInstruction::Error { targets, .. }) => targets.clone(),
Some(_) => {
return Err(format!(
"DEM error index {dem_error_index} does not point to an error instruction"
));
}
None => {
return Err(format!(
"DEM error index {dem_error_index} out of range for {} tracked DEM errors",
tracked.dem_error_to_sources.len()
));
}
};
let mut doc = export_qp101(instrs)?;
let mut seen = BTreeSet::new();
for (source, highlight) in source_highlights {
let dedupe_key = (
highlight.op_path.clone(),
highlight.repeat_iterations.clone(),
highlight.target_slots.clone(),
highlight.branch.clone(),
);
if seen.insert(dedupe_key) {
let annotation = Qp101Annotation {
kind: "marker".to_string(),
target_slots: highlight.target_slots.clone(),
label: Some(highlight.label.clone()),
text: format_repeat_annotation_text(&highlight.repeat_iterations),
style: Some(danger_annotation_style()),
tags: vec!["dem-origin".to_string(), "query-result".to_string()],
context: Some(json!({
"query_kind": "dem_error_origin",
"dem_error_index": dem_error_index,
"op_path": highlight.op_path,
"repeat_iterations": highlight.repeat_iterations,
"target_qubits": highlight.target_qubits,
"source_branch": highlight.branch,
})),
};
add_annotation_at_path(&mut doc.operations, &source.op_path, annotation)?;
}
}
add_symptom_annotations(&mut doc.operations, instrs, &dem_targets, dem_error_index)?;
Ok(doc)
}
fn export_operations(instrs: &[StimInstr]) -> Result<Vec<Qp101Operation>, String> {
let mut ops = Vec::with_capacity(instrs.len());
for instr in instrs {
match instr {
StimInstr::Repeat { count, body } => ops.push(Qp101Operation::Repeat {
count: *count,
body: export_operations(body)?,
annotations: Vec::new(),
}),
StimInstr::Op {
name,
tag,
args,
targets,
..
} => {
let op = match name.as_str() {
"TICK" => {
validate_no_args_or_targets(name, args, targets)?;
Qp101Operation::Tick {
annotations: Vec::new(),
}
}
"QUBIT_COORDS" => Qp101Operation::QubitCoords {
coords: args.clone(),
targets: export_plain_qubit_targets(name, targets)?,
annotations: Vec::new(),
},
"SHIFT_COORDS" => {
validate_no_targets(name, targets)?;
Qp101Operation::ShiftCoords {
delta: args.clone(),
annotations: Vec::new(),
}
}
"DETECTOR" => Qp101Operation::Detector {
coords: args.clone(),
sources: export_rec_sources(name, targets)?,
annotations: Vec::new(),
},
"OBSERVABLE_INCLUDE" => Qp101Operation::ObservableInclude {
index: parse_observable_index(args)?,
sources: export_rec_sources(name, targets)?,
annotations: Vec::new(),
},
n if is_noise_op(n) => Qp101Operation::Noise {
gate: n.to_string(),
params: args.clone(),
raw_targets: export_targets(targets),
annotations: Vec::new(),
},
_ => {
let targets_out: Vec<u32> =
targets.iter().filter_map(StimTarget::qubit_index).collect();
let has_non_plain_targets = targets
.iter()
.any(|target| !matches!(target, StimTarget::Qubit(_)));
Qp101Operation::Gate {
gate: name.clone(),
targets: targets_out,
controls: Vec::new(),
control_configs: None,
params: args.clone(),
raw_targets: if has_non_plain_targets {
Some(export_targets(targets))
} else {
None
},
display: None,
tags: tag.iter().cloned().collect(),
annotations: Vec::new(),
}
}
};
ops.push(op);
}
}
}
Ok(ops)
}
fn format_repeat_annotation_text(repeat_iterations: &[u64]) -> Option<String> {
(!repeat_iterations.is_empty()).then(|| {
format!(
"repeat[{}]",
repeat_iterations
.iter()
.map(u64::to_string)
.collect::<Vec<_>>()
.join(",")
)
})
}
fn danger_annotation_style() -> Qp101AnnotationStyle {
Qp101AnnotationStyle {
preset: Some("danger".to_string()),
color: Some("red".to_string()),
highlight: Some(true),
}
}
fn info_annotation_style() -> Qp101AnnotationStyle {
Qp101AnnotationStyle {
preset: Some("info".to_string()),
color: Some("blue".to_string()),
highlight: Some(true),
}
}
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
struct LossVisibleMeasurementKey {
op_path: Vec<usize>,
repeat_iterations: Vec<u64>,
target_slot: usize,
target_qubit: u32,
instr_name: String,
}
#[derive(Debug, Clone)]
struct LossVisibleMeasurementGroup {
key: LossVisibleMeasurementKey,
loss_flag: Option<MeasurementEvent>,
value: Option<MeasurementEvent>,
}
#[derive(Debug, Clone)]
struct QueryAnnotationLocation {
op_path: Vec<usize>,
repeat_iterations: Vec<u64>,
}
#[derive(Debug, Clone, Default)]
struct QueryTraversalContext {
op_path: Vec<usize>,
repeat_iterations: Vec<u64>,
}
impl QueryTraversalContext {
fn with_op_index(&self, op_index: usize) -> Self {
let mut op_path = self.op_path.clone();
op_path.push(op_index);
Self {
op_path,
repeat_iterations: self.repeat_iterations.clone(),
}
}
fn with_repeat_iteration(&self, repeat_op_index: usize, iteration: u64) -> Self {
let mut op_path = self.op_path.clone();
op_path.push(repeat_op_index);
let mut repeat_iterations = self.repeat_iterations.clone();
repeat_iterations.push(iteration);
Self {
op_path,
repeat_iterations,
}
}
}
fn add_symptom_annotations(
operations: &mut [Qp101Operation],
instrs: &[StimInstr],
dem_targets: &[DemTarget],
dem_error_index: usize,
) -> Result<(), String> {
let mut detector_locations = Vec::new();
let mut observable_locations = Vec::new();
collect_query_annotation_locations(
instrs,
&QueryTraversalContext::default(),
&mut detector_locations,
&mut observable_locations,
)?;
let mut seen = BTreeSet::new();
for target in dem_targets {
match target {
DemTarget::Detector(index) => {
let location = detector_locations.get(*index).ok_or_else(|| {
format!("detector index {index} missing from exported QP101 operations")
})?;
let key = (
"D".to_string(),
*index,
location.op_path.clone(),
location.repeat_iterations.clone(),
);
if seen.insert(key) {
add_annotation_at_path(
operations,
&location.op_path,
Qp101Annotation {
kind: "marker".to_string(),
target_slots: Vec::new(),
label: Some(format!("D{index}")),
text: format_repeat_annotation_text(&location.repeat_iterations),
style: Some(danger_annotation_style()),
tags: vec!["dem-symptom".to_string(), "query-result".to_string()],
context: Some(json!({
"query_kind": "dem_error_origin",
"dem_error_index": dem_error_index,
"detector_index": index,
"op_path": location.op_path,
"repeat_iterations": location.repeat_iterations,
})),
},
)?;
}
}
DemTarget::Observable(index) => {
let matching_locations: Vec<_> = observable_locations
.iter()
.filter(|entry| entry.0 == *index)
.collect();
if let [location] = matching_locations.as_slice() {
let key = (
"L".to_string(),
*index,
location.1.op_path.clone(),
location.1.repeat_iterations.clone(),
);
if seen.insert(key) {
add_annotation_at_path(
operations,
&location.1.op_path,
Qp101Annotation {
kind: "marker".to_string(),
target_slots: Vec::new(),
label: Some(format!("L{index}")),
text: format_repeat_annotation_text(&location.1.repeat_iterations),
style: Some(danger_annotation_style()),
tags: vec!["dem-symptom".to_string(), "query-result".to_string()],
context: Some(json!({
"query_kind": "dem_error_origin",
"dem_error_index": dem_error_index,
"observable_index": index,
"op_path": location.1.op_path,
"repeat_iterations": location.1.repeat_iterations,
})),
},
)?;
}
}
}
DemTarget::Separator => {}
}
}
Ok(())
}
fn collect_query_annotation_locations(
instrs: &[StimInstr],
context: &QueryTraversalContext,
detector_locations: &mut Vec<QueryAnnotationLocation>,
observable_locations: &mut Vec<(usize, QueryAnnotationLocation)>,
) -> Result<(), String> {
for (i, instr) in instrs.iter().enumerate() {
match instr {
StimInstr::Repeat { count, body } => {
for iteration in 0..*count {
let repeat_context = context.with_repeat_iteration(i, iteration);
collect_query_annotation_locations(
body,
&repeat_context,
detector_locations,
observable_locations,
)?;
}
}
StimInstr::Op { name, args, .. } => {
let op_context = context.with_op_index(i);
if name == "DETECTOR" {
detector_locations.push(QueryAnnotationLocation {
op_path: op_context.op_path,
repeat_iterations: op_context.repeat_iterations,
});
} else if name == "OBSERVABLE_INCLUDE" {
let index = args.first().copied().unwrap_or(0.0) as usize;
observable_locations.push((
index,
QueryAnnotationLocation {
op_path: op_context.op_path,
repeat_iterations: op_context.repeat_iterations,
},
));
}
}
}
}
Ok(())
}
fn add_sample_noise_annotations(
operations: &mut [Qp101Operation],
trace: &SampleTrace,
) -> Result<(), String> {
for event in &trace.noise_events {
if !event.occurred {
continue;
}
let branch_label = event.branch_label.as_ref().ok_or_else(|| {
format!(
"sample trace noise event at {:?} is marked occurred but has no branch label",
event.op_path
)
})?;
add_annotation_at_path(
operations,
&event.op_path,
Qp101Annotation {
kind: "marker".to_string(),
target_slots: event.target_slots.clone(),
label: Some(branch_label.clone()),
text: format_repeat_annotation_text(&event.repeat_iterations),
style: Some(danger_annotation_style()),
tags: vec!["sample-trace".to_string(), "query-result".to_string()],
context: Some(json!({
"query_kind": "sample_trace",
"annotation_kind": "noise",
"instr_name": event.instr_name,
"op_path": event.op_path,
"repeat_iterations": event.repeat_iterations,
"target_qubits": event.target_qubits,
"branch_label": branch_label,
})),
},
)?;
}
Ok(())
}
fn add_sample_measurement_annotations(
operations: &mut [Qp101Operation],
trace: &SampleTrace,
) -> Result<(), String> {
let mut grouped = BTreeMap::<LossVisibleMeasurementKey, LossVisibleMeasurementGroup>::new();
let mut grouped_order = Vec::new();
for event in &trace.measurement_events {
if is_loss_visible_measurement_op(&event.instr_name) {
let key = LossVisibleMeasurementKey {
op_path: event.op_path.clone(),
repeat_iterations: event.repeat_iterations.clone(),
target_slot: event.target_slot,
target_qubit: event.target_qubit,
instr_name: event.instr_name.clone(),
};
let group = grouped.entry(key.clone()).or_insert_with(|| {
grouped_order.push(key.clone());
LossVisibleMeasurementGroup {
key,
loss_flag: None,
value: None,
}
});
match event.component {
MeasurementComponent::LossFlag => {
if group.loss_flag.is_some() {
return Err(format!(
"duplicate loss_flag component for loss-visible measurement at {:?} slot {}",
group.key.op_path, group.key.target_slot
));
}
group.loss_flag = Some(event.clone());
}
MeasurementComponent::Value => {
if group.value.is_some() {
return Err(format!(
"duplicate value component for loss-visible measurement at {:?} slot {}",
group.key.op_path, group.key.target_slot
));
}
group.value = Some(event.clone());
}
}
continue;
}
add_annotation_at_path(
operations,
&event.op_path,
Qp101Annotation {
kind: "marker".to_string(),
target_slots: vec![event.target_slot],
label: Some(format_measurement_label(event)),
text: format_repeat_annotation_text(&event.repeat_iterations),
style: None,
tags: vec!["sample-trace".to_string(), "query-result".to_string()],
context: Some(json!({
"query_kind": "sample_trace",
"annotation_kind": "measurement",
"instr_name": event.instr_name,
"op_path": event.op_path,
"repeat_iterations": event.repeat_iterations,
"measurement_index": event.measurement_index,
"target_qubit": event.target_qubit,
"bit": event.bit,
"loss_cause": event.loss_cause,
"component": measurement_component_name(&event.component),
})),
},
)?;
}
for key in grouped_order {
let Some(group) = grouped.remove(&key) else {
continue;
};
let (loss_flag, value) = loss_visible_group_components(&group)?;
add_annotation_at_path(
operations,
&group.key.op_path,
Qp101Annotation {
kind: "marker".to_string(),
target_slots: vec![group.key.target_slot],
label: Some(format_loss_visible_measurement_label(loss_flag, value)),
text: format_repeat_annotation_text(&group.key.repeat_iterations),
style: None,
tags: vec!["sample-trace".to_string(), "query-result".to_string()],
context: Some(loss_visible_measurement_context(&group, loss_flag, value)),
},
)?;
}
Ok(())
}
fn add_sample_detector_annotations(
operations: &mut [Qp101Operation],
trace: &SampleTrace,
) -> Result<(), String> {
for event in &trace.detector_events {
if !event.flipped {
continue;
}
add_annotation_at_path(
operations,
&event.op_path,
Qp101Annotation {
kind: "marker".to_string(),
target_slots: Vec::new(),
label: Some(format!("D{}", event.detector_index)),
text: format_repeat_annotation_text(&event.repeat_iterations),
style: Some(info_annotation_style()),
tags: vec!["dem-symptom".to_string(), "query-result".to_string()],
context: Some(json!({
"query_kind": "sample_trace",
"annotation_kind": "detector",
"detector_index": event.detector_index,
"op_path": event.op_path,
"repeat_iterations": event.repeat_iterations,
"flipped": event.flipped,
})),
},
)?;
}
Ok(())
}
fn is_loss_visible_measurement_op(name: &str) -> bool {
matches!(
name,
"ML" | "MXL" | "MYL" | "MZL" | "MRL" | "MRXL" | "MRYL" | "MRZL"
)
}
fn validate_sample_trace_visualization_support(instrs: &[StimInstr]) -> Result<(), String> {
validate_sample_trace_visualization_support_inner(instrs, &mut Vec::new())
}
fn validate_sample_trace_visualization_support_inner(
instrs: &[StimInstr],
op_path: &mut Vec<usize>,
) -> Result<(), String> {
for (op_index, instr) in instrs.iter().enumerate() {
op_path.push(op_index);
match instr {
StimInstr::Repeat { body, .. } => {
validate_sample_trace_visualization_support_inner(body, op_path)?;
}
StimInstr::Op { name, .. }
if emits_measurement_bits(name)
&& !is_sample_trace_visualization_measurement_op(name) =>
{
return Err(format!(
"sample trace visualization does not yet support instruction {name} at op_path {:?}",
op_path
));
}
_ => {}
}
op_path.pop();
}
Ok(())
}
fn is_sample_trace_visualization_measurement_op(name: &str) -> bool {
matches!(
name,
"M"
| "MX"
| "MY"
| "MZ"
| "MR"
| "MRX"
| "MRY"
| "MRZ"
| "ML"
| "MXL"
| "MYL"
| "MZL"
| "MRL"
| "MRXL"
| "MRYL"
| "MRZL"
| "MPP"
| "MXX"
| "MYY"
| "MZZ"
| "MPAD"
| "HERALDED_ERASE"
| "HERALDED_PAULI_CHANNEL_1"
)
}
fn emits_measurement_bits(name: &str) -> bool {
matches!(
name,
"M"
| "MX"
| "MY"
| "MZ"
| "MR"
| "MRX"
| "MRY"
| "MRZ"
| "ML"
| "MXL"
| "MYL"
| "MZL"
| "MRL"
| "MRXL"
| "MRYL"
| "MRZL"
| "MPP"
| "MXX"
| "MYY"
| "MZZ"
| "MPAD"
| "HERALDED_ERASE"
| "HERALDED_PAULI_CHANNEL_1"
)
}
fn format_measurement_label(event: &MeasurementEvent) -> String {
if event.loss_cause {
"1[L]".to_string()
} else if event.bit {
"1".to_string()
} else {
"0".to_string()
}
}
fn loss_visible_group_components(
group: &LossVisibleMeasurementGroup,
) -> Result<(&MeasurementEvent, &MeasurementEvent), String> {
let loss_flag = group.loss_flag.as_ref().ok_or_else(|| {
format!(
"loss-visible measurement at {:?} slot {} is missing loss_flag component",
group.key.op_path, group.key.target_slot
)
})?;
let value = group.value.as_ref().ok_or_else(|| {
format!(
"loss-visible measurement at {:?} slot {} is missing value component",
group.key.op_path, group.key.target_slot
)
})?;
Ok((loss_flag, value))
}
fn format_loss_visible_measurement_label(
loss_flag: &MeasurementEvent,
value: &MeasurementEvent,
) -> String {
let loss_flag = if loss_flag.bit { "1" } else { "0" };
let value = format_measurement_label(value);
format!("L={loss_flag} | M={value}")
}
fn measurement_component_name(component: &MeasurementComponent) -> &'static str {
match component {
MeasurementComponent::Value => "value",
MeasurementComponent::LossFlag => "loss_flag",
}
}
fn loss_visible_measurement_context(
group: &LossVisibleMeasurementGroup,
loss_flag: &MeasurementEvent,
value: &MeasurementEvent,
) -> serde_json::Value {
json!({
"query_kind": "sample_trace",
"annotation_kind": "measurement",
"loss_visible": true,
"instr_name": group.key.instr_name,
"op_path": group.key.op_path,
"repeat_iterations": group.key.repeat_iterations,
"target_qubit": group.key.target_qubit,
"components": {
"loss_flag": {
"measurement_index": loss_flag.measurement_index,
"bit": loss_flag.bit,
},
"value": {
"measurement_index": value.measurement_index,
"bit": value.bit,
"loss_cause": value.loss_cause,
}
},
})
}
fn add_annotation_at_path(
operations: &mut [Qp101Operation],
op_path: &[usize],
annotation: Qp101Annotation,
) -> Result<(), String> {
let Some((&head, tail)) = op_path.split_first() else {
return Err("highlight source is missing an op_path".to_string());
};
let op = operations
.get_mut(head)
.ok_or_else(|| format!("highlight op_path component {head} out of range"))?;
if tail.is_empty() {
op.annotations_mut().push(annotation);
return Ok(());
}
match op {
Qp101Operation::Repeat { body, .. } => add_annotation_at_path(body, tail, annotation),
_ => Err(format!(
"highlight op_path descends into non-repeat operation at component {head}"
)),
}
}
impl Qp101Operation {
fn annotations_mut(&mut self) -> &mut Vec<Qp101Annotation> {
match self {
Qp101Operation::Gate { annotations, .. }
| Qp101Operation::Tick { annotations }
| Qp101Operation::Repeat { annotations, .. }
| Qp101Operation::QubitCoords { annotations, .. }
| Qp101Operation::ShiftCoords { annotations, .. }
| Qp101Operation::Detector { annotations, .. }
| Qp101Operation::ObservableInclude { annotations, .. }
| Qp101Operation::Noise { annotations, .. }
| Qp101Operation::Annotation { annotations, .. } => annotations,
}
}
}
fn export_plain_qubit_targets(name: &str, targets: &[StimTarget]) -> Result<Vec<u32>, String> {
targets
.iter()
.map(|target| match target {
StimTarget::Qubit(q) => Ok(*q),
other => Err(format!("{name} expects qubit targets, got {other:?}")),
})
.collect()
}
fn validate_no_args_or_targets(name: &str, args: &[f64], targets: &[StimTarget]) -> Result<(), String> {
if !args.is_empty() {
return Err(format!("{name} expects no args, got {}", args.len()));
}
validate_no_targets(name, targets)
}
fn validate_no_targets(name: &str, targets: &[StimTarget]) -> Result<(), String> {
if !targets.is_empty() {
return Err(format!("{name} expects no targets, got {}", targets.len()));
}
Ok(())
}
fn parse_observable_index(args: &[f64]) -> Result<u32, String> {
if args.len() != 1 {
return Err(format!(
"OBSERVABLE_INCLUDE requires exactly one argument, got {}",
args.len()
));
}
let Some(raw) = args.first().copied() else {
return Err("OBSERVABLE_INCLUDE requires an observable index".to_string());
};
if raw < 0.0 || raw.fract() != 0.0 {
return Err(format!(
"OBSERVABLE_INCLUDE index must be a non-negative integer, got {raw}"
));
}
if raw > u32::MAX as f64 {
return Err(format!(
"OBSERVABLE_INCLUDE index exceeds u32 range, got {raw}"
));
}
Ok(raw as u32)
}
fn export_rec_sources(name: &str, targets: &[StimTarget]) -> Result<Vec<Qp101TargetRef>, String> {
targets
.iter()
.map(|target| match target {
StimTarget::Rec(offset) => Ok(Qp101TargetRef::Rec { offset: *offset }),
other => Err(format!("{name} expects rec sources, got {other:?}")),
})
.collect()
}
fn export_targets(targets: &[StimTarget]) -> Vec<Qp101TargetRef> {
targets.iter().map(export_target).collect()
}
fn export_target(target: &StimTarget) -> Qp101TargetRef {
match target {
StimTarget::Qubit(index) => Qp101TargetRef::Qubit {
index: *index,
inverted: None,
},
StimTarget::QubitInv(index) => Qp101TargetRef::Qubit {
index: *index,
inverted: Some(true),
},
StimTarget::Rec(offset) => Qp101TargetRef::Rec { offset: *offset },
StimTarget::Pauli {
qubit,
basis,
inverted,
} => Qp101TargetRef::Pauli {
basis: export_pauli_basis(*basis),
qubit: *qubit,
inverted: if *inverted { Some(true) } else { None },
},
StimTarget::Combiner => Qp101TargetRef::Combiner,
StimTarget::Sweep(index) => Qp101TargetRef::Sweep { index: *index },
}
}
fn export_pauli_basis(basis: PauliBasis) -> Qp101PauliBasis {
match basis {
PauliBasis::X => Qp101PauliBasis::X,
PauliBasis::Y => Qp101PauliBasis::Y,
PauliBasis::Z => Qp101PauliBasis::Z,
}
}
fn is_noise_op(name: &str) -> bool {
matches!(
name,
"X_ERROR"
| "Y_ERROR"
| "Z_ERROR"
| "DEPOLARIZE1"
| "DEPOLARIZE2"
| "PAULI_CHANNEL_1"
| "PAULI_CHANNEL_2"
| "CORRELATED_ERROR"
| "ELSE_CORRELATED_ERROR"
| "E"
| "HERALDED_ERASE"
| "HERALDED_PAULI_CHANNEL_1"
| "I_ERROR"
| "II_ERROR"
| "LOSS"
)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::sample_trace::{
DetectorEvent, MeasurementComponent, MeasurementEvent, NoiseEvent, SampleTrace,
};
#[test]
fn sample_trace_annotation_helpers_cover_continues_and_errors() {
let circuit = crate::parser::parse_lines("LOSS(1) 0\nMRL 0\nDETECTOR rec[-1]\n").unwrap();
let mut doc = export_qp101(&circuit).unwrap();
let trace = SampleTrace {
noise_events: vec![NoiseEvent {
op_path: vec![0],
repeat_iterations: vec![],
instr_name: "LOSS".to_string(),
target_slots: vec![0],
target_qubits: vec![0],
occurred: false,
branch_label: None,
}],
measurement_events: vec![
MeasurementEvent {
op_path: vec![1],
repeat_iterations: vec![],
target_slot: 0,
target_qubit: 0,
instr_name: "MRL".to_string(),
measurement_index: 1,
bit: true,
loss_cause: false,
component: MeasurementComponent::LossFlag,
},
MeasurementEvent {
op_path: vec![1],
repeat_iterations: vec![],
target_slot: 0,
target_qubit: 0,
instr_name: "MRL".to_string(),
measurement_index: 2,
bit: true,
loss_cause: true,
component: MeasurementComponent::Value,
},
],
detector_events: vec![DetectorEvent {
op_path: vec![2],
repeat_iterations: vec![],
detector_index: 0,
flipped: true,
}],
};
add_sample_noise_annotations(&mut doc.operations, &trace).unwrap();
add_sample_measurement_annotations(&mut doc.operations, &trace).unwrap();
add_sample_detector_annotations(&mut doc.operations, &trace).unwrap();
match &doc.operations[0] {
Qp101Operation::Noise { annotations, .. } => assert!(annotations.is_empty()),
other => panic!("unexpected op: {other:?}"),
}
match &doc.operations[1] {
Qp101Operation::Gate { annotations, .. } => assert_eq!(annotations.len(), 1),
other => panic!("unexpected op: {other:?}"),
}
match &doc.operations[2] {
Qp101Operation::Detector { annotations, .. } => assert_eq!(annotations.len(), 1),
other => panic!("unexpected op: {other:?}"),
}
let mut repeat_doc = export_qp101(&crate::parser::parse_lines("REPEAT 1 {\n MRL 0\n}\n").unwrap()).unwrap();
let err = add_annotation_at_path(
&mut repeat_doc.operations,
&[],
Qp101Annotation {
kind: "marker".to_string(),
target_slots: vec![],
label: None,
text: None,
style: None,
tags: vec![],
context: None,
},
)
.unwrap_err();
assert!(err.contains("missing an op_path"));
assert!(add_annotation_at_path(
&mut repeat_doc.operations,
&[99],
Qp101Annotation {
kind: "marker".to_string(),
target_slots: vec![],
label: None,
text: None,
style: None,
tags: vec![],
context: None,
},
)
.is_err());
assert!(add_annotation_at_path(
&mut repeat_doc.operations,
&[0, 0],
Qp101Annotation {
kind: "marker".to_string(),
target_slots: vec![],
label: None,
text: None,
style: None,
tags: vec![],
context: None,
},
)
.is_ok());
}
#[test]
fn export_helpers_cover_remaining_target_and_basis_paths() {
assert_eq!(
export_pauli_basis(PauliBasis::X),
Qp101PauliBasis::X
);
assert_eq!(
export_pauli_basis(PauliBasis::Y),
Qp101PauliBasis::Y
);
assert_eq!(
export_pauli_basis(PauliBasis::Z),
Qp101PauliBasis::Z
);
assert_eq!(
export_targets(&[
StimTarget::Qubit(1),
StimTarget::QubitInv(2),
StimTarget::Rec(-3),
StimTarget::Pauli {
qubit: 4,
basis: PauliBasis::X,
inverted: true,
},
StimTarget::Combiner,
StimTarget::Sweep(9),
]),
vec![
Qp101TargetRef::Qubit {
index: 1,
inverted: None,
},
Qp101TargetRef::Qubit {
index: 2,
inverted: Some(true),
},
Qp101TargetRef::Rec { offset: -3 },
Qp101TargetRef::Pauli {
basis: Qp101PauliBasis::X,
qubit: 4,
inverted: Some(true),
},
Qp101TargetRef::Combiner,
Qp101TargetRef::Sweep { index: 9 },
]
);
assert_eq!(
export_rec_sources("DETECTOR", &[StimTarget::Rec(-1)]).unwrap(),
vec![Qp101TargetRef::Rec { offset: -1 }]
);
assert!(export_rec_sources("DETECTOR", &[StimTarget::Qubit(0)]).is_err());
assert!(validate_no_args_or_targets("TICK", &[1.0], &[]).is_err());
assert!(validate_no_args_or_targets("TICK", &[], &[StimTarget::Qubit(0)]).is_err());
assert!(validate_no_targets("TICK", &[StimTarget::Qubit(0)]).is_err());
assert!(validate_no_targets("TICK", &[]).is_ok());
assert_eq!(parse_observable_index(&[2.0]).unwrap(), 2);
assert!(parse_observable_index(&[]).is_err());
assert!(parse_observable_index(&[-1.0]).is_err());
assert!(parse_observable_index(&[0.5]).is_err());
assert!(parse_observable_index(&[u32::MAX as f64 + 1.0]).is_err());
assert!(export_plain_qubit_targets("QUBIT_COORDS", &[StimTarget::Qubit(0)]).is_ok());
assert!(export_plain_qubit_targets("QUBIT_COORDS", &[StimTarget::Rec(-1)]).is_err());
assert!(is_noise_op("LOSS"));
assert!(!is_noise_op("H"));
}
}