PECOS-packages
diff --git a/‎.typos.toml‎
Lines changed: 10 additions & 1 deletion b/‎.typos.toml‎
Lines changed: 10 additions & 1 deletion
diff --git a/‎crates/pecos-core/src/angle.rs‎
Lines changed: 69 additions & 0 deletions b/‎crates/pecos-core/src/angle.rs‎
Lines changed: 69 additions & 0 deletions
diff --git a/‎crates/pecos-core/src/gate_type.rs‎
Lines changed: 3 additions & 3 deletions b/‎crates/pecos-core/src/gate_type.rs‎
Lines changed: 3 additions & 3 deletions
diff --git a/‎crates/pecos-llvm/src/llvm_compat.rs‎
Lines changed: 147 additions & 1 deletion b/‎crates/pecos-llvm/src/llvm_compat.rs‎
Lines changed: 147 additions & 1 deletion
diff --git a/‎crates/pecos-simulators/src/arbitrary_rotation_gateable.rs‎
Lines changed: 70 additions & 0 deletions b/‎crates/pecos-simulators/src/arbitrary_rotation_gateable.rs‎
Lines changed: 70 additions & 0 deletions
@@ -8,7 +8,6 @@ IY = "IY"
 IZ = "IZ"
 iz = "iz"
 anc = "anc"
-Pn = "Pn"
 emiss = "emiss"
 fo = "fo"
 # HUGR JSON format uses "typ" as a field name for type information
@@ -42,3 +41,13 @@ agger = "agger"
 CPY = "CPY"
 # Abbreviation for "undetectable" in fault enumeration debug output
 UNDET = "UNDET"
+# Legitimate "mis-" prefix used in comments/messages (mis-ordered,
+# mis-declared, mis-emitted, mis-shape, mis-count, mis-mapping, ...)
+mis = "mis"
+# Valid spelling of "unparseable" (used in comments + a test name)
+unparseable = "unparseable"
+Unparseable = "Unparseable"
+# Prep-gate naming: the "Pn -> PN" entry-point rename (PNX/PNY/PNZ)
+Pn = "Pn"
+PN = "PN"
+pn = "pn"
@@ -148,6 +148,46 @@ where
         }
     }
 
+    /// Converts the angle to turns in `[0, 1)` (the inverse of `from_turns`).
+    ///
+    /// # Panics
+    /// This function will panic if the conversion of `fraction` or `max_value` to `f64` fails.
+    pub fn to_turns(&self) -> f64 {
+        let max_value = T::max_value()
+            .to_f64()
+            .expect("Failed to convert max_value to f64");
+        self.fraction
+            .to_f64()
+            .expect("Failed to convert fraction to f64")
+            / max_value
+    }
+
+    /// Converts the angle to signed turns in `(-0.5, 0.5]`.
+    pub fn to_turns_signed(&self) -> f64 {
+        let t = self.to_turns();
+        if t > 0.5 { t - 1.0 } else { t }
+    }
+
+    /// Converts the angle to half-turns in `[0, 2)` (π radians = 1 half-turn).
+    ///
+    /// Half-turns are the unit used by some backends (e.g. Guppy's `angle`),
+    /// where a full turn is `2.0`.
+    ///
+    /// # Panics
+    /// This function will panic if the conversion of `fraction` or `max_value` to `f64` fails.
+    pub fn to_half_turns(&self) -> f64 {
+        self.to_turns() * 2.0
+    }
+
+    /// Converts the angle to signed half-turns in `(-1, 1]`.
+    ///
+    /// Like [`Self::to_radians_signed`], this principal-value form avoids the
+    /// spurious global phase that the unsigned `[0, 2)` form introduces when a
+    /// half-angle (`θ/2`) computation crosses the 2π wrap point.
+    pub fn to_half_turns_signed(&self) -> f64 {
+        self.to_turns_signed() * 2.0
+    }
+
     /// Creates an angle from a value in radians.
     ///
     /// # Panics
@@ -668,6 +708,35 @@ mod tests {
     use rand::RngExt;
     use std::f64::consts::{FRAC_PI_2, FRAC_PI_4, PI, TAU};
 
+    #[test]
+    fn test_to_turns_and_half_turns() {
+        // Quarter turn = pi/2 rad = 0.25 turns = 0.5 half-turns.
+        let q = Angle64::QUARTER_TURN;
+        assert!((q.to_turns() - 0.25).abs() < 1e-12);
+        assert!((q.to_half_turns() - 0.5).abs() < 1e-12);
+        assert!((q.to_turns_signed() - 0.25).abs() < 1e-12);
+        assert!((q.to_half_turns_signed() - 0.5).abs() < 1e-12);
+
+        // Half-turn boundary: to_turns stays unsigned (0.5), signed maps to 0.5.
+        let h = Angle64::HALF_TURN;
+        assert!((h.to_turns() - 0.5).abs() < 1e-12);
+        assert!((h.to_half_turns() - 1.0).abs() < 1e-12);
+
+        // Three-quarter turn: unsigned 0.75 turns; signed wraps to -0.25 turns
+        // (-0.5 half-turns), mirroring to_radians_signed.
+        let tq = Angle64::THREE_QUARTERS_TURN;
+        assert!((tq.to_turns() - 0.75).abs() < 1e-12);
+        assert!((tq.to_turns_signed() - (-0.25)).abs() < 1e-12);
+        assert!((tq.to_half_turns_signed() - (-0.5)).abs() < 1e-12);
+
+        // half-turns == radians / pi for the unsigned form.
+        let a = Angle64::from_radians(0.7);
+        assert!((a.to_half_turns() - a.to_radians() / PI).abs() < 1e-9);
+        // round-trip turns.
+        let b = Angle64::from_turns(0.3);
+        assert!((b.to_turns() - 0.3).abs() < 1e-9);
+    }
+
     // Basic Construction and Properties
     #[test]
     fn test_constructors() {
 
@@ -97,12 +97,12 @@ pub enum GateType {
     // TODO: MPauli instead of the other variants?
 
     // PX = 130
-    // PnX = 131
+    // PNX = 131
     // PY = 132
-    // PnY = 133
+    // PNY = 133
     // PZ = 134
     PZ = 134,
-    // PnZ
+    // PNZ
     /// Allocate a qubit in the |0⟩ state
     QAlloc = 135,
     /// Free/deallocate a qubit
 
@@ -226,7 +226,7 @@ impl<'ctx> LLFunctionType<'ctx> {
 }
 
 /// Wrapper for LLVM types that mirrors llvmlite's type hierarchy
-#[derive(Clone, Copy)]
+#[derive(Clone, Copy, PartialEq, Eq)]
 pub enum LLType<'ctx> {
     Void,
     Int(IntType<'ctx>),
@@ -236,6 +236,38 @@ pub enum LLType<'ctx> {
     Array(ArrayType<'ctx>),
 }
 
+// inkwell 0.8.0 only derives `Hash` for `IntType`; the other type wrappers
+// are `Eq` (LLVM type-ref pointer equality) but not `Hash`. Hash the same
+// `LLVMTypeRef` pointer so `Hash` stays consistent with that `Eq`.
+impl std::hash::Hash for LLType<'_> {
+    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+        use inkwell::types::AsTypeRef;
+        match self {
+            LLType::Void => 0u8.hash(state),
+            LLType::Int(t) => {
+                1u8.hash(state);
+                (t.as_type_ref() as usize).hash(state);
+            }
+            LLType::Float(t) => {
+                2u8.hash(state);
+                (t.as_type_ref() as usize).hash(state);
+            }
+            LLType::Pointer(t) => {
+                3u8.hash(state);
+                (t.as_type_ref() as usize).hash(state);
+            }
+            LLType::Struct(t) => {
+                4u8.hash(state);
+                (t.as_type_ref() as usize).hash(state);
+            }
+            LLType::Array(t) => {
+                5u8.hash(state);
+                (t.as_type_ref() as usize).hash(state);
+            }
+        }
+    }
+}
+
 impl<'ctx> LLType<'ctx> {
     /// Create void type
     #[must_use]
@@ -717,6 +749,106 @@ impl<'ctx> LLIRBuilder<'ctx> {
             Ok(LLValue::Pointer(result))
         }
     }
+
+    // ========================================================================
+    // Memory ops + casts (unblocks the standard CReg model)
+    // ========================================================================
+
+    /// `alloca <ty>` -- stack slot. Caller positions the builder (B2
+    /// places `CReg` buffers in the entry block via `position_at_end`).
+    pub fn alloca(&self, ll_type: LLType<'ctx>, name: &str) -> LLResult<LLValue<'ctx>> {
+        let basic_ty = ll_type
+            .to_basic_metadata_type()
+            .ok_or_else(|| PecosError::Generic("Cannot alloca a void type".into()))?;
+        let result = self
+            .builder
+            .build_alloca(basic_ty, name)
+            .map_err(|e| PecosError::Generic(format!("Failed to build alloca: {e}")))?;
+        Ok(LLValue::Pointer(result))
+    }
+
+    /// `load` (LLVM-14 typed pointer: pointee inferred from `ptr`).
+    pub fn load(&self, ptr: LLValue<'ctx>, name: &str) -> LLResult<LLValue<'ctx>> {
+        let result = self
+            .builder
+            .build_load(ptr.as_pointer_value(), name)
+            .map_err(|e| PecosError::Generic(format!("Failed to build load: {e}")))?;
+        Ok(match result {
+            BasicValueEnum::IntValue(v) => LLValue::Int(v),
+            BasicValueEnum::FloatValue(v) => LLValue::Float(v),
+            BasicValueEnum::PointerValue(v) => LLValue::Pointer(v),
+            BasicValueEnum::ArrayValue(v) => LLValue::Array(v),
+            other => {
+                return Err(PecosError::Generic(format!(
+                    "load: unsupported loaded value type: {other:?}"
+                )));
+            }
+        })
+    }
+
+    /// `store` -- discards inkwell's returned pointer (Python `-> None`).
+    pub fn store(&self, ptr: LLValue<'ctx>, value: LLValue<'ctx>) -> LLResult<()> {
+        self.builder
+            .build_store(ptr.as_pointer_value(), value.to_basic_value())
+            .map_err(|e| PecosError::Generic(format!("Failed to build store: {e}")))?;
+        Ok(())
+    }
+
+    /// `zext` int value to a wider int type.
+    pub fn zext(
+        &self,
+        value: LLValue<'ctx>,
+        dest_type: LLType<'ctx>,
+        name: &str,
+    ) -> LLResult<LLValue<'ctx>> {
+        let result = self
+            .builder
+            .build_int_z_extend(value.as_int_value(), dest_type.as_int_type(), name)
+            .map_err(|e| PecosError::Generic(format!("Failed to build zext: {e}")))?;
+        Ok(LLValue::Int(result))
+    }
+
+    /// `trunc` int value to a narrower int type.
+    pub fn trunc(
+        &self,
+        value: LLValue<'ctx>,
+        dest_type: LLType<'ctx>,
+        name: &str,
+    ) -> LLResult<LLValue<'ctx>> {
+        let result = self
+            .builder
+            .build_int_truncate(value.as_int_value(), dest_type.as_int_type(), name)
+            .map_err(|e| PecosError::Generic(format!("Failed to build trunc: {e}")))?;
+        Ok(LLValue::Int(result))
+    }
+
+    /// Unsigned integer comparison (mirrors `icmp_signed` with U-predicates).
+    pub fn icmp_unsigned(
+        &self,
+        op: &str,
+        lhs: LLValue<'ctx>,
+        rhs: LLValue<'ctx>,
+        name: &str,
+    ) -> LLResult<LLValue<'ctx>> {
+        let predicate = match op {
+            "==" => IntPredicate::EQ,
+            "!=" => IntPredicate::NE,
+            "<" => IntPredicate::ULT,
+            ">" => IntPredicate::UGT,
+            "<=" => IntPredicate::ULE,
+            ">=" => IntPredicate::UGE,
+            _ => {
+                return Err(PecosError::Generic(format!(
+                    "Unknown comparison operator: {op}"
+                )));
+            }
+        };
+        let result = self
+            .builder
+            .build_int_compare(predicate, lhs.as_int_value(), rhs.as_int_value(), name)
+            .map_err(|e| PecosError::Generic(format!("Failed to build icmp: {e}")))?;
+        Ok(LLValue::Int(result))
+    }
 }
 
 // ============================================================================
@@ -766,4 +898,18 @@ impl LLConstant {
             )),
         }
     }
+
+    /// Zero/`zeroinitializer` constant of `ll_type` (backs
+    /// `Constant(ty, None)`; Array -> `zeroinitializer`, Int -> `iN 0`).
+    pub fn zero(ll_type: LLType<'_>) -> LLResult<LLValue<'_>> {
+        match ll_type {
+            LLType::Int(t) => Ok(LLValue::Int(t.const_zero())),
+            LLType::Float(t) => Ok(LLValue::Float(t.const_zero())),
+            LLType::Pointer(t) => Ok(LLValue::Pointer(t.const_zero())),
+            LLType::Array(t) => Ok(LLValue::Array(t.const_zero())),
+            LLType::Void | LLType::Struct(_) => Err(PecosError::Generic(
+                "Cannot create a zero constant for void/struct type".to_string(),
+            )),
+        }
+    }
 }
@@ -254,6 +254,76 @@ pub trait ArbitraryRotationGateable: CliffordGateable {
         self.rxx(theta, pairs).ryy(phi, pairs).rzz(lambda, pairs)
     }
 
+    /// Applies a controlled-RZ rotation: target qubit gets RZ(theta) when control = |1>.
+    ///
+    /// `CRZ(theta) = block-diag(I, RZ(theta)) = diag(1, 1, exp(-i*theta/2), exp(i*theta/2))`.
+    ///
+    /// Default 2q-minimal decomposition (1 RZZ + 1 single-qubit RZ on the
+    /// target): `CRZ(theta) = (I o RZ(theta/2)) . RZZ(-theta/2)`.
+    /// Verified: with the trait's `RZ = exp(-i*theta/2*Z)` and `RZZ =
+    /// exp(-i*theta/2*Z*Z)` conventions, the product on the c=0 sector
+    /// gives `RZ(theta/2) . exp(i*theta/4*I) = I` up to global phase, and
+    /// on c=1 (where ZZ acts as -Z on target) gives `RZ(theta/2) . X .
+    /// RZ(theta/2) . X = RZ(theta)` -- i.e. the convention-1 controlled
+    /// rotation. The non-PECOS-prefactor convention requires no extra
+    /// RZ on the control.
+    ///
+    /// # Parameters
+    /// - `theta`: The rotation angle on the target.
+    /// - `pairs`: Pairs of qubit indices `[(control, target), ...]`.
+    ///
+    /// # Returns
+    /// A mutable reference to `Self` for method chaining.
+    #[inline]
+    fn crz(&mut self, theta: Angle64, pairs: &[(QubitId, QubitId)]) -> &mut Self {
+        // Half-angle first, THEN negate -- `Angle<T>` is a wrapping fraction
+        // of a full turn (modulo 2pi), so `-theta / 2` would halve the wrapped
+        // 2*pi - theta and produce pi - theta/2, not -theta/2.
+        let half = theta / 2u64;
+        let targets: QubitBuf = pairs.iter().map(|&(_, t)| t).collect();
+        self.rzz(-half, pairs).rz(half, &targets)
+    }
+
+    /// Applies a controlled-RX rotation: target qubit gets RX(theta) when control = |1>.
+    ///
+    /// Default decomposition: `CRX(theta) = (I o H) . CRZ(theta) . (I o H)`,
+    /// using `H.Z.H = X` so the c=1 sector applies `H.RZ(theta).H = RX(theta)`.
+    /// Same 2q cost as `crz` (1 RZZ).
+    ///
+    /// # Parameters
+    /// - `theta`: The rotation angle on the target.
+    /// - `pairs`: Pairs of qubit indices `[(control, target), ...]`.
+    ///
+    /// # Returns
+    /// A mutable reference to `Self` for method chaining.
+    #[inline]
+    fn crx(&mut self, theta: Angle64, pairs: &[(QubitId, QubitId)]) -> &mut Self {
+        let targets: QubitBuf = pairs.iter().map(|&(_, t)| t).collect();
+        self.h(&targets).crz(theta, pairs).h(&targets)
+    }
+
+    /// Applies a controlled-RY rotation: target qubit gets RY(theta) when control = |1>.
+    ///
+    /// Default decomposition: `CRY(theta) = (I o S.H) . CRZ(theta) . (I o H.Sdg)`,
+    /// using `S.X.Sdg = Y` (so `S.Rx.Sdg = Ry`) and `H.Rz.H = Rx`, giving
+    /// `S.H.RZ.H.Sdg = RY`. Same 2q cost as `crz` (1 RZZ).
+    ///
+    /// # Parameters
+    /// - `theta`: The rotation angle on the target.
+    /// - `pairs`: Pairs of qubit indices `[(control, target), ...]`.
+    ///
+    /// # Returns
+    /// A mutable reference to `Self` for method chaining.
+    #[inline]
+    fn cry(&mut self, theta: Angle64, pairs: &[(QubitId, QubitId)]) -> &mut Self {
+        let targets: QubitBuf = pairs.iter().map(|&(_, t)| t).collect();
+        self.szdg(&targets)
+            .h(&targets)
+            .crz(theta, pairs)
+            .h(&targets)
+            .sz(&targets)
+    }
+
     /// Applies a general 2-qubit unitary via KAK decomposition:
     /// U = (U3(before[0]) x U3(before[1])) * RXXRYYRZZ(interaction) * (U3(after[0]) x U3(after[1]))
     ///