docs + hugr

Author: ciaranra

crates/pecos-hugr/src/engine.rs

@@ -6,6 +6,19 @@
 
 use crate::{Operation, QuantumOp, with_interface};
 use log::debug;
+use std::cell::Cell;
+
+// Thread-local counter to prevent infinite loops in collection mode.
+// After MAX_COLLECTION_READS, `___read_future_bool` returns true to break out of
+// loops like "repeat_until_one" (while not result: ... result = measure(q)).
+thread_local! {
+    static COLLECTION_MODE_READ_COUNT: Cell<u32> = const { Cell::new(0) };
+}
+
+/// Maximum number of measurement reads in collection mode before returning true.
+/// This prevents infinite loops when collecting operations for programs with
+/// "repeat until success" patterns.
+const MAX_COLLECTION_READS: u32 = 100;
 
 /// Helper to convert i64 to usize
 #[inline]
@@ -682,8 +695,36 @@ pub unsafe extern "C" fn ___read_future_bool(future_id: i64) -> bool {
         log::debug!("___read_future_bool: timeout waiting for result");
     }
 
-    // Default: return false (for first pass or if no dynamic mode)
-    false
+    // Collection mode (non-dynamic): track read count to prevent infinite loops.
+    // For programs with "repeat until success" loops like:
+    //   while not result:
+    //       q = qubit()
+    //       result = measure(q)
+    // Each iteration creates a new result_id, so we track total reads.
+    // After MAX_COLLECTION_READS, we return true to break the loop.
+    let read_count = COLLECTION_MODE_READ_COUNT.with(|c| {
+        let count = c.get() + 1;
+        c.set(count);
+        count
+    });
+
+    if read_count >= MAX_COLLECTION_READS {
+        log::debug!(
+            "___read_future_bool: collection mode read count ({read_count}) >= threshold, returning true to break loop"
+        );
+        true
+    } else {
+        // Default: return false (allows first iterations of loops to proceed)
+        false
+    }
+}
+
+/// Reset the collection mode read counter.
+///
+/// This should be called at the start of each new execution to reset the loop
+/// termination counter used in `___read_future_bool`.
+pub fn reset_collection_read_count() {
+    COLLECTION_MODE_READ_COUNT.with(|c| c.set(0));
 }
 
 /// Increment the reference count of a future (Guppy/HUGR-LLVM style)

crates/pecos-qis-ffi/src/ffi.rs

@@ -239,6 +239,8 @@ where
 /// Reset the thread-local operation collector
 pub fn reset_interface() {
     with_interface(OperationCollector::reset);
+    // Also reset the collection mode read counter for loop termination
+    ffi::reset_collection_read_count();
 }
 
 /// Get a clone of the thread-local operation collector

crates/pecos-qis-ffi/src/lib.rs

@@ -768,25 +768,14 @@ impl ClassicalEngine for QisEngine {
         // Convert stored measurement results to PECOS shot format
         let mut shot = Shot::default();
 
-        // Add measurements from stored results (numeric IDs)
-        for (result_id, value) in &self.measurement_results {
-            shot.data.insert(
-                format!("measurement_{result_id}"),
-                Data::U32(u32::from(*value)),
-            );
-            debug!(
-                "QisEngine: Added to shot: measurement_{} = {}",
-                result_id,
-                i32::from(*value)
-            );
-        }
-
-        // Add named results from print_bool/print_bool_arr calls
+        // First, try to get named results from print_bool/print_bool_arr calls
+        let mut has_named_results = false;
         if let Some(state) = &self.dynamic_state
             && let Some(handle) = &state.sync_handle
         {
             match handle.get_named_results() {
                 Ok(named_results) => {
+                    has_named_results = !named_results.is_empty();
                     for (name, values) in named_results {
                         // Convert Vec<bool> to Data
                         // For single values, store as U32; for arrays, store as Vec<U32>
@@ -807,10 +796,29 @@ impl ClassicalEngine for QisEngine {
             }
         }
 
+        // Only add raw measurements if there are no named results.
+        // This handles circuits with variable loop iterations where each shot
+        // may produce a different number of raw measurements, but the named
+        // results (from result() calls) are consistent.
+        if !has_named_results {
+            for (result_id, value) in &self.measurement_results {
+                shot.data.insert(
+                    format!("measurement_{result_id}"),
+                    Data::U32(u32::from(*value)),
+                );
+                debug!(
+                    "QisEngine: Added to shot: measurement_{} = {}",
+                    result_id,
+                    i32::from(*value)
+                );
+            }
+        }
+
         debug!("QisEngine: Final shot data: {:?}", shot.data);
         debug!(
-            "Returning shot with {} measurement results",
-            self.measurement_results.len()
+            "Returning shot with {} measurement results (has_named_results={})",
+            self.measurement_results.len(),
+            has_named_results
         );
         Ok(shot)
     }

crates/pecos-qis/src/ccengine.rs

@@ -191,7 +191,10 @@ struct QuantumOp {
 /// Check if a gate type is a rotation gate that takes angle parameters.
 #[must_use]
 pub fn is_rotation_gate(gate_type: GateType) -> bool {
-    matches!(gate_type, GateType::RX | GateType::RY | GateType::RZ)
+    matches!(
+        gate_type,
+        GateType::RX | GateType::RY | GateType::RZ | GateType::CRZ
+    )
 }
 
 /// Try to extract a constant numeric value from a HUGR Const node.
@@ -437,6 +440,16 @@ fn trace_back_for_const(hugr: &Hugr, node: Node, depth: usize) -> Option<(f64, b
                 return trace_back_for_const(hugr, src_node, depth + 1);
             }
         }
+
+        // Handle float negation (fneg) - used for negative rotation angles
+        if op_name == "fneg" {
+            let input_port = IncomingPort::from(0);
+            if let Some((src_node, _)) = hugr.single_linked_output(node, input_port)
+                && let Some((val, is_half_turns)) = trace_back_for_const(hugr, src_node, depth + 1)
+            {
+                return Some((-val, is_half_turns));
+            }
+        }
     }
 
     // For UnpackTuple, trace through
@@ -456,7 +469,8 @@ fn trace_back_for_const(hugr: &Hugr, node: Node, depth: usize) -> Option<(f64, b
         // 2. Numeric argument values
         let mut is_division = false;
         let mut is_multiplication = false;
-        let mut numeric_values: Vec<(usize, f64)> = Vec::new();
+        let mut is_negation = false;
+        let mut numeric_values: Vec<(usize, f64, bool)> = Vec::new();
 
         // Get the number of input ports for this node
         let num_inputs = hugr.num_inputs(node);
@@ -476,19 +490,29 @@ fn trace_back_for_const(hugr: &Hugr, node: Node, depth: usize) -> Option<(f64, b
                     if func_name.contains("__mul__") || func_name.contains("__rmul__") {
                         is_multiplication = true;
                     }
+                    if func_name.contains("__neg__") {
+                        is_negation = true;
+                    }
                 }
 
                 // Try to get a numeric value from this input
-                if let Some((val, _)) = trace_back_for_const(hugr, src_node, depth + 1) {
-                    numeric_values.push((port_idx, val));
+                if let Some((val, is_half_turns)) = trace_back_for_const(hugr, src_node, depth + 1)
+                {
+                    numeric_values.push((port_idx, val, is_half_turns));
                 }
             }
         }
 
+        // If this is a negation call and we have a numeric value, negate it
+        if is_negation && !numeric_values.is_empty() {
+            let (_, val, is_half_turns) = numeric_values[0];
+            return Some((-val, is_half_turns));
+        }
+
         // If this is a division call and we have two numeric values, compute the result
         if is_division && numeric_values.len() >= 2 {
             // Sort by port index to get correct order (numerator first, denominator second)
-            numeric_values.sort_by_key(|(idx, _)| *idx);
+            numeric_values.sort_by_key(|(idx, _, _)| *idx);
             let numerator = numeric_values[0].1;
             let denominator = numeric_values[1].1;
             if denominator != 0.0 {
@@ -498,14 +522,14 @@ fn trace_back_for_const(hugr: &Hugr, node: Node, depth: usize) -> Option<(f64, b
 
         // If this is a multiplication call and we have two numeric values, compute the result
         if is_multiplication && numeric_values.len() >= 2 {
-            numeric_values.sort_by_key(|(idx, _)| *idx);
+            numeric_values.sort_by_key(|(idx, _, _)| *idx);
             let factor1 = numeric_values[0].1;
             let factor2 = numeric_values[1].1;
             return Some((factor1 * factor2, false));
         }
 
         // For other calls, try to return the first numeric value found
-        if let Some((_, val)) = numeric_values.first() {
+        if let Some((_, val, _)) = numeric_values.first() {
             return Some((*val, false));
         }
     }

crates/pecos-quantum/src/hugr_convert.rs

@@ -32,6 +32,12 @@ Let's create a Bell state using Guppy. First, define a quantum function:
 
 === ":fontawesome-brands-python: Python"
 
+    ```hidden-python
+    import os
+    # Create shared directory for HUGR files that Rust tests can use
+    os.makedirs("/tmp/pecos-doc-tests", exist_ok=True)
+    ```
+
     ```python
     from guppylang import guppy
     from guppylang.std.quantum import h, cx, measure, qubit
@@ -61,11 +67,16 @@ Let's create a Bell state using Guppy. First, define a quantum function:
 
     print(results.to_dict())
     # Results: always correlated (00 or 11)
+
+    # Save compiled HUGR for other examples
+    _hugr = bell_state.compile()
+    with open("/tmp/pecos-doc-tests/bell_state.hugr", "w") as f:
+        f.write(_hugr.to_str())
     ```
 
 === ":fontawesome-brands-rust: Rust"
 
-    <!--skip: requires pre-compiled bell_state.hugr file-->
+    <!--test-data: bell_state.hugr-->
     ```rust
     use pecos_hugr::{hugr_engine, hugr_sim};
     use pecos_engines::{ClassicalControlEngineBuilder, ClassicalEngine};
@@ -119,6 +130,13 @@ If you have HUGR files (compiled from Guppy or other tools), you can run them di
 
 === ":fontawesome-brands-python: Python"
 
+    ```hidden-python
+    import os
+    # Ensure circuit.hugr doesn't exist so we get FileNotFoundError
+    if os.path.exists("circuit.hugr"):
+        os.remove("circuit.hugr")
+    ```
+
     <!--expect-error: FileNotFoundError.*circuit\.hugr-->
     ```python
     from pecos import sim, Hugr
@@ -129,17 +147,26 @@ If you have HUGR files (compiled from Guppy or other tools), you can run them di
 
     With an actual HUGR file:
 
-    <!--skip: requires pre-compiled .hugr file-->
+    ```hidden-python
+    import shutil
+    from pecos import sim, Hugr
+    from pecos_rslib import state_vector
+    # Use the bell_state.hugr generated earlier
+    shutil.copy("/tmp/pecos-doc-tests/bell_state.hugr", "circuit.hugr")
+    # Also save as circuit.hugr for Rust tests
+    shutil.copy("/tmp/pecos-doc-tests/bell_state.hugr", "/tmp/pecos-doc-tests/circuit.hugr")
+    ```
+
     ```python
     # From bytes
     with open("circuit.hugr", "rb") as f:
         hugr_bytes = f.read()
-    results = sim(Hugr(hugr_bytes)).run(1000)
+    results = sim(Hugr(hugr_bytes)).qubits(2).quantum(state_vector()).run(1000)
     ```
 
 === ":fontawesome-brands-rust: Rust"
 
-    <!--skip: requires pre-compiled circuit.hugr file-->
+    <!--test-data: circuit.hugr-->
     ```rust
     use pecos_hugr::{hugr_engine, hugr_sim};
     use pecos_engines::{ClassicalControlEngineBuilder, ClassicalEngine};
@@ -239,7 +266,7 @@ One of HUGR's key advantages is native support for control flow based on measure
 
 === ":fontawesome-brands-python: Python"
 
-    <!--skip: while loop may exceed 60s timeout-->
+    <!--skip: HUGR while loop interpreter has known performance issues-->
     ```python
     from guppylang import guppy
     from guppylang.std.quantum import h, measure, qubit