qsengine 1.0.1__tar.gz → 1.0.2__tar.gz

{qsengine-1.0.1 → qsengine-1.0.2}/Cargo.lock

@@ -799,7 +799,7 @@ dependencies = [
 
 [[package]]
 name = "qsengine"
-version = "1.0.1"
+version = "1.0.2"
 dependencies = [
  "bytemuck",
  "num-complex",

{qsengine-1.0.1 → qsengine-1.0.2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "qsengine"
-version = "1.0.1"
+version = "1.0.2"
 edition = "2024"
 license = "MIT"
 description = "High-performance state-vector quantum simulator (CPU + portable GPU backends)"

{qsengine-1.0.1 → qsengine-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qsengine
-Version: 1.0.1
+Version: 1.0.2
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Intended Audience :: Education
@@ -81,6 +81,7 @@ qc.h(0)
 qc.cx(0, 1)
 qc.cx(1, 2)
 
+print(qc)                   # text drawing, one wire per qubit
 qc.run(shots=1000)          # measurement counts: {'000': ..., '111': ...}
 qc.probabilities()          # exact probabilities of all 8 basis states (NumPy array)
 qc.statevector()            # exact complex amplitudes (NumPy array)

{qsengine-1.0.1 → qsengine-1.0.2}/README.md

@@ -48,6 +48,7 @@ qc.h(0)
 qc.cx(0, 1)
 qc.cx(1, 2)
 
+print(qc)                   # text drawing, one wire per qubit
 qc.run(shots=1000)          # measurement counts: {'000': ..., '111': ...}
 qc.probabilities()          # exact probabilities of all 8 basis states (NumPy array)
 qc.statevector()            # exact complex amplitudes (NumPy array)

{qsengine-1.0.1 → qsengine-1.0.2}/qsengine.pyi

@@ -21,6 +21,8 @@ class QuantumCircuit:
     def num_qubits(self) -> int: ...
     def __len__(self) -> int:
         """Number of gates recorded so far."""
+    def __str__(self) -> str:
+        """Text drawing of the circuit, one wire per qubit: `print(qc)`."""
 
     # Single-qubit gates
     def x(self, qubit: int) -> None: ...

{qsengine-1.0.1 → qsengine-1.0.2}/src/backend.rs

@@ -39,6 +39,12 @@ pub trait QuantumBackend {
     /// Copy of all `2^n` amplitudes, in basis-index order.
     fn amplitudes(&self) -> Vec<Complex64>;
 
+    /// All `2^n` amplitudes, consuming the backend. Backends that already hold
+    /// them in host memory override this to hand the vector over without a copy.
+    fn into_amplitudes(self: Box<Self>) -> Vec<Complex64> {
+        self.amplitudes()
+    }
+
     /// Replace the state with the basis state `|index>` (amplitude 1 there, 0 elsewhere).
     fn collapse_to(&mut self, index: usize);
 
@@ -63,6 +69,7 @@ pub trait QuantumBackend {
         gate: &Gate,
     ) -> Result<()> {
         let mask = control_mask(self.num_qubits(), controls, target)?;
+        check_finite(gate)?;
         self.apply_gate_kernel(mask, target, gate);
         Ok(())
     }
@@ -122,7 +129,7 @@ pub trait QuantumBackend {
     /// Picks basis state `i` with probability `|amp_i|^2`, collapses the state
     /// to `|i>`, and returns `i`. Use [`crate::format_bitstring`] to print it.
     fn measure(&mut self, rng: &mut dyn RngCore) -> usize {
-        let cumulative = cumulative_probabilities(&self.probabilities());
+        let cumulative = cumulative_probabilities(self.probabilities());
         let outcome = sample_index(&cumulative, rng);
         // Global phase is unobservable, so collapsing to amplitude exactly 1 is valid.
         self.collapse_to(outcome);
@@ -134,7 +141,7 @@ pub trait QuantumBackend {
     /// Returns `basis index -> number of times seen`. This is how real circuits
     /// are run: prepare once, sample many times. Costs `O(2^n + shots * n)`.
     fn sample(&self, shots: usize, rng: &mut dyn RngCore) -> HashMap<usize, usize> {
-        let cumulative = cumulative_probabilities(&self.probabilities());
+        let cumulative = cumulative_probabilities(self.probabilities());
         let mut counts = HashMap::new();
         for _ in 0..shots {
             *counts.entry(sample_index(&cumulative, rng)).or_insert(0) += 1;
@@ -165,15 +172,20 @@ pub fn control_mask(num_qubits: usize, controls: &[usize], target: usize) -> Res
     Ok(mask)
 }
 
-/// Running sum of `probs`: `out[i] = probs[0] + ... + probs[i]`.
-fn cumulative_probabilities(probs: &[f64]) -> Vec<f64> {
+/// Fail if any entry of `gate` is NaN or infinite, e.g. from `rx(q, float("nan"))`.
+/// Such a gate turns the whole state into NaN, which sampling would silently read as |0...0>.
+pub fn check_finite(gate: &Gate) -> Result<()> {
+    if gate.as_flattened().iter().all(|z| z.is_finite()) { Ok(()) } else { Err(QsError::NonFinite) }
+}
+
+/// Running sum of `probs`, in place (no second 2^n buffer): `out[i] = probs[0] + ... + probs[i]`.
+fn cumulative_probabilities(mut probs: Vec<f64>) -> Vec<f64> {
+    let mut acc = 0.0;
+    for p in &mut probs {
+        acc += *p;
+        *p = acc;
+    }
     probs
-        .iter()
-        .scan(0.0, |acc, p| {
-            *acc += p;
-            Some(*acc)
-        })
-        .collect()
 }
 
 /// Weighted random pick from a cumulative distribution using binary search.
@@ -288,5 +300,7 @@ pub(crate) mod conformance {
         assert_eq!(s.h(2), Err(QsError::QubitOutOfRange { qubit: 2, num_qubits: 2 }));
         assert_eq!(s.cx(1, 1), Err(QsError::DuplicateQubit(1)));
         assert_eq!(s.cx(5, 0), Err(QsError::QubitOutOfRange { qubit: 5, num_qubits: 2 }));
+        assert_eq!(s.rx(0, f64::NAN), Err(QsError::NonFinite));
+        assert_eq!(s.rz(0, f64::INFINITY), Err(QsError::NonFinite));
     }
 }

{qsengine-1.0.1 → qsengine-1.0.2}/src/circuit.rs

@@ -9,12 +9,13 @@
 //! instructions, and the whole simulation happens in Rust in one call, with the
 //! state vector never crossing into Python.
 
-use crate::backend::{QuantumBackend, control_mask};
+use crate::backend::{QuantumBackend, check_finite, control_mask};
 use crate::gates::{self, Gate};
 use crate::{BackendKind, MAX_QUBITS, QsError, Result};
 use num_complex::Complex64;
 use rand::RngCore;
 use std::collections::HashMap;
+use std::fmt;
 
 /// One recorded gate: apply `gate` to `target` where all `control_mask` bits are 1.
 /// These are the exact arguments of [`QuantumBackend::apply_gate_kernel`].
@@ -30,6 +31,22 @@ pub struct Instruction {
 pub struct QuantumCircuit {
     num_qubits: usize,
     instructions: Vec<Instruction>,
+    drawing: Vec<DrawOp>,
+}
+
+/// One gate as the user wrote it, kept only for drawing: `swap` is one entry
+/// here but three CNOTs in `instructions`.
+#[derive(Debug, Clone, PartialEq)]
+struct DrawOp {
+    label: String,
+    controls: Vec<usize>,
+    targets: Vec<usize>,
+}
+
+/// Drawing label for a gate with angle parameters, e.g. `RX(1.57)`.
+fn label(name: &str, angles: &[f64]) -> String {
+    let args: Vec<String> = angles.iter().map(|a| format!("{a:.2}")).collect();
+    format!("{name}({})", args.join(","))
 }
 
 impl QuantumCircuit {
@@ -38,7 +55,7 @@ impl QuantumCircuit {
         if num_qubits > MAX_QUBITS {
             return Err(QsError::TooManyQubits { requested: num_qubits, max: MAX_QUBITS });
         }
-        Ok(Self { num_qubits, instructions: Vec::new() })
+        Ok(Self { num_qubits, instructions: Vec::new(), drawing: Vec::new() })
     }
 
     pub fn num_qubits(&self) -> usize {
@@ -53,8 +70,15 @@ impl QuantumCircuit {
     /// Record `gate` on `target`, controlled on every qubit in `controls`
     /// (empty for a plain single-qubit gate). Every other gate method calls this.
     pub fn add_gate(&mut self, controls: &[usize], target: usize, gate: Gate) -> Result<()> {
+        self.push("U".into(), controls, target, gate)
+    }
+
+    /// Validate and record one gate, with the label [`Display`](fmt::Display) draws for it.
+    fn push(&mut self, label: String, controls: &[usize], target: usize, gate: Gate) -> Result<()> {
         let control_mask = control_mask(self.num_qubits, controls, target)?;
+        check_finite(&gate)?;
         self.instructions.push(Instruction { control_mask, target, gate });
+        self.drawing.push(DrawOp { label, controls: controls.to_vec(), targets: vec![target] });
         Ok(())
     }
 
@@ -68,44 +92,46 @@ impl QuantumCircuit {
     }
 
     // Named gates. The first eleven match `QuantumBackend`; the rest are circuit-only.
-    pub fn x(&mut self, q: usize) -> Result<()> { self.add_gate(&[], q, gates::X) }
-    pub fn y(&mut self, q: usize) -> Result<()> { self.add_gate(&[], q, gates::Y) }
-    pub fn z(&mut self, q: usize) -> Result<()> { self.add_gate(&[], q, gates::Z) }
-    pub fn h(&mut self, q: usize) -> Result<()> { self.add_gate(&[], q, gates::H) }
-    pub fn s(&mut self, q: usize) -> Result<()> { self.add_gate(&[], q, gates::S) }
-    pub fn t(&mut self, q: usize) -> Result<()> { self.add_gate(&[], q, gates::T) }
-    pub fn rx(&mut self, q: usize, theta: f64) -> Result<()> { self.add_gate(&[], q, gates::rx(theta)) }
-    pub fn ry(&mut self, q: usize, theta: f64) -> Result<()> { self.add_gate(&[], q, gates::ry(theta)) }
-    pub fn rz(&mut self, q: usize, theta: f64) -> Result<()> { self.add_gate(&[], q, gates::rz(theta)) }
+    pub fn x(&mut self, q: usize) -> Result<()> { self.push("X".into(), &[], q, gates::X) }
+    pub fn y(&mut self, q: usize) -> Result<()> { self.push("Y".into(), &[], q, gates::Y) }
+    pub fn z(&mut self, q: usize) -> Result<()> { self.push("Z".into(), &[], q, gates::Z) }
+    pub fn h(&mut self, q: usize) -> Result<()> { self.push("H".into(), &[], q, gates::H) }
+    pub fn s(&mut self, q: usize) -> Result<()> { self.push("S".into(), &[], q, gates::S) }
+    pub fn t(&mut self, q: usize) -> Result<()> { self.push("T".into(), &[], q, gates::T) }
+    pub fn rx(&mut self, q: usize, theta: f64) -> Result<()> { self.push(label("RX", &[theta]), &[], q, gates::rx(theta)) }
+    pub fn ry(&mut self, q: usize, theta: f64) -> Result<()> { self.push(label("RY", &[theta]), &[], q, gates::ry(theta)) }
+    pub fn rz(&mut self, q: usize, theta: f64) -> Result<()> { self.push(label("RZ", &[theta]), &[], q, gates::rz(theta)) }
     pub fn cx(&mut self, control: usize, target: usize) -> Result<()> {
-        self.add_gate(&[control], target, gates::X)
+        self.push("X".into(), &[control], target, gates::X)
     }
     pub fn cz(&mut self, control: usize, target: usize) -> Result<()> {
-        self.add_gate(&[control], target, gates::Z)
+        self.push("Z".into(), &[control], target, gates::Z)
     }
-    pub fn sdg(&mut self, q: usize) -> Result<()> { self.add_gate(&[], q, gates::SDG) }
-    pub fn tdg(&mut self, q: usize) -> Result<()> { self.add_gate(&[], q, gates::TDG) }
-    pub fn p(&mut self, q: usize, lambda: f64) -> Result<()> { self.add_gate(&[], q, gates::p(lambda)) }
+    pub fn sdg(&mut self, q: usize) -> Result<()> { self.push("S†".into(), &[], q, gates::SDG) }
+    pub fn tdg(&mut self, q: usize) -> Result<()> { self.push("T†".into(), &[], q, gates::TDG) }
+    pub fn p(&mut self, q: usize, lambda: f64) -> Result<()> { self.push(label("P", &[lambda]), &[], q, gates::p(lambda)) }
     pub fn u(&mut self, q: usize, theta: f64, phi: f64, lambda: f64) -> Result<()> {
-        self.add_gate(&[], q, gates::u(theta, phi, lambda))
+        self.push(label("U", &[theta, phi, lambda]), &[], q, gates::u(theta, phi, lambda))
     }
     pub fn cp(&mut self, control: usize, target: usize, lambda: f64) -> Result<()> {
-        self.add_gate(&[control], target, gates::p(lambda))
+        self.push(label("P", &[lambda]), &[control], target, gates::p(lambda))
     }
     pub fn crz(&mut self, control: usize, target: usize, theta: f64) -> Result<()> {
-        self.add_gate(&[control], target, gates::rz(theta))
+        self.push(label("RZ", &[theta]), &[control], target, gates::rz(theta))
     }
     /// Toffoli: flip `target` when both controls are |1>.
     pub fn ccx(&mut self, c1: usize, c2: usize, target: usize) -> Result<()> {
-        self.add_gate(&[c1, c2], target, gates::X)
+        self.push("X".into(), &[c1, c2], target, gates::X)
     }
     /// Swap two qubits, as three CNOTs (the kernel only knows controlled 2x2 gates).
     pub fn swap(&mut self, a: usize, b: usize) -> Result<()> {
         // Validate first so a bad swap records nothing, not one or two stray CNOTs.
         control_mask(self.num_qubits, &[a], b)?;
-        self.cx(a, b)?;
-        self.cx(b, a)?;
-        self.cx(a, b)
+        for (c, t) in [(a, b), (b, a), (a, b)] {
+            self.instructions.push(Instruction { control_mask: 1 << c, target: t, gate: gates::X });
+        }
+        self.drawing.push(DrawOp { label: "×".into(), controls: vec![], targets: vec![a, b] });
+        Ok(())
     }
 
     /// Apply every instruction to an existing backend, with single-qubit gate fusion.
@@ -165,7 +191,7 @@ impl QuantumCircuit {
 
     /// Final amplitudes after running the circuit.
     pub fn statevector(&self, kind: BackendKind) -> Result<Vec<Complex64>> {
-        Ok(self.simulate(kind)?.amplitudes())
+        Ok(self.simulate(kind)?.into_amplitudes())
     }
 
     /// Final basis-state probabilities after running the circuit.
@@ -180,6 +206,51 @@ impl QuantumCircuit {
     }
 }
 
+/// Text drawing, one wire per qubit (q0 on top), one column per gate:
+///
+/// ```text
+/// q0: ──H──●─
+///          │
+/// q1: ─────X─
+/// ```
+///
+/// `●` marks a control, `×` the two ends of a swap.
+///
+/// shortcut: columns are never packed or folded, so a long circuit draws as one very wide line; add folding if learners hit it.
+impl fmt::Display for QuantumCircuit {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let n = self.num_qubits;
+        let name_w = format!("q{}", n.saturating_sub(1)).len();
+        // Even rows are qubit wires, odd rows the gaps between them.
+        let mut rows: Vec<String> = (0..(2 * n).saturating_sub(1))
+            .map(|r| if r % 2 == 0 { format!("{:>name_w$}: ─", format!("q{}", r / 2)) } else { " ".repeat(name_w + 3) })
+            .collect();
+
+        for op in &self.drawing {
+            let w = op.label.chars().count() + 2;
+            let mid = w / 2;
+            // Rows from the gate's top qubit to its bottom one carry the vertical line.
+            let qubits = op.controls.iter().chain(&op.targets);
+            let (lo, hi) = (2 * qubits.clone().min().unwrap(), 2 * qubits.max().unwrap());
+            let mark = |c: char, fill: &str| format!("{}{c}{}", fill.repeat(mid), fill.repeat(w - mid - 1));
+            for (r, row) in rows.iter_mut().enumerate() {
+                let (q, wire, inside) = (r / 2, r % 2 == 0, lo <= r && r <= hi);
+                let cell = match (wire, inside) {
+                    (true, _) if op.targets.contains(&q) => format!("─{}─", op.label),
+                    (true, _) if op.controls.contains(&q) => mark('●', "─"),
+                    (true, true) => mark('┼', "─"),
+                    (true, false) => "─".repeat(w),
+                    (false, true) => mark('│', " "),
+                    (false, false) => " ".repeat(w),
+                };
+                row.push_str(&cell);
+            }
+        }
+        let lines: Vec<&str> = rows.iter().map(|r| r.trim_end()).collect();
+        f.write_str(&lines.join("\n"))
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -239,6 +310,32 @@ mod tests {
         assert!(counts.keys().all(|&k| k == 0 || k == 3));
     }
 
+    #[test]
+    fn non_finite_angles_are_rejected() {
+        let mut qc = QuantumCircuit::new(2).unwrap();
+        assert_eq!(qc.rx(0, f64::NAN), Err(QsError::NonFinite));
+        assert_eq!(qc.cp(0, 1, f64::INFINITY), Err(QsError::NonFinite));
+        assert!(qc.instructions().is_empty());
+    }
+
+    #[test]
+    fn draws_gates_controls_and_swaps() {
+        let mut qc = QuantumCircuit::new(3).unwrap();
+        qc.h(0).unwrap();
+        qc.cx(0, 2).unwrap();
+        qc.rz(1, 0.5).unwrap();
+        qc.swap(0, 1).unwrap();
+        let expect = "\
+q0: ──H──●────────────×─
+         │            │
+q1: ─────┼──RZ(0.50)──×─
+         │
+q2: ─────X──────────────";
+        assert_eq!(qc.to_string(), expect);
+        assert_eq!(qc.instructions().len(), 6); // the swap is still three CNOTs
+        assert_eq!(QuantumCircuit::new(1).unwrap().to_string(), "q0: ─");
+    }
+
     #[test]
     fn size_mismatch_is_an_error() {
         let qc = QuantumCircuit::new(2).unwrap();

{qsengine-1.0.1 → qsengine-1.0.2}/src/engine.rs

@@ -35,7 +35,13 @@ impl QuantumState {
         if num_qubits > MAX_QUBITS {
             return Err(QsError::TooManyQubits { requested: num_qubits, max: MAX_QUBITS });
         }
-        let mut amplitudes = vec![Complex64::new(0.0, 0.0); 1 << num_qubits];
+        // Reserve fallibly: a failed `vec!` aborts the process, which kills the Python interpreter.
+        let len = 1usize << num_qubits;
+        let mut amplitudes = Vec::new();
+        amplitudes
+            .try_reserve_exact(len)
+            .map_err(|_| QsError::OutOfMemory { bytes: len * size_of::<Complex64>() })?;
+        amplitudes.resize(len, Complex64::new(0.0, 0.0));
         amplitudes[0] = Complex64::new(1.0, 0.0);
         Ok(Self { num_qubits, amplitudes })
     }
@@ -113,6 +119,10 @@ impl QuantumBackend for QuantumState {
         self.amplitudes.clone()
     }
 
+    fn into_amplitudes(self: Box<Self>) -> Vec<Complex64> {
+        self.amplitudes
+    }
+
     fn probabilities(&self) -> Vec<f64> {
         // Override the default to skip the amplitude copy.
         self.amplitudes.par_iter().map(|a| a.norm_sqr()).collect()

{qsengine-1.0.1 → qsengine-1.0.2}/src/lib.rs

@@ -33,7 +33,7 @@
 //! ## Python
 //!
 //! The `python` module wraps [`QuantumCircuit`] as `qsengine.QuantumCircuit`.
-//! Errors map from [`QsError`] to `ValueError` / `RuntimeError`. Build it with
+//! Errors map from [`QsError`] to `ValueError` / `RuntimeError` / `MemoryError`. Build it with
 //! `maturin develop --release` (see the README).
 
 pub mod backend;
@@ -71,6 +71,10 @@ pub enum QsError {
     SizeMismatch { circuit: usize, backend: usize },
     /// A user-supplied gate matrix was not a 2x2 unitary.
     NotUnitary,
+    /// A gate angle (or matrix entry) was NaN or infinite.
+    NonFinite,
+    /// The state vector did not fit in memory.
+    OutOfMemory { bytes: usize },
     /// No usable GPU, or the GPU driver reported an error.
     Gpu(String),
 }
@@ -89,6 +93,10 @@ impl fmt::Display for QsError {
                 write!(f, "circuit has {circuit} qubits but backend has {backend}")
             }
             QsError::NotUnitary => write!(f, "gate matrix must be a 2x2 unitary"),
+            QsError::NonFinite => write!(f, "gate angles must be finite numbers, not NaN or infinity"),
+            QsError::OutOfMemory { bytes } => {
+                write!(f, "not enough memory for the state vector ({:.1} GiB)", *bytes as f64 / (1u64 << 30) as f64)
+            }
             QsError::Gpu(msg) => write!(f, "GPU error: {msg}"),
         }
     }

{qsengine-1.0.1 → qsengine-1.0.2}/src/python.rs

@@ -11,8 +11,8 @@
 
 use crate::{BackendKind, QsError, QuantumCircuit, format_bitstring};
 use num_complex::Complex64;
-use numpy::{PyArray1, ToPyArray};
-use pyo3::exceptions::{PyRuntimeError, PyValueError};
+use numpy::{IntoPyArray, PyArray1};
+use pyo3::exceptions::{PyMemoryError, PyRuntimeError, PyValueError};
 use pyo3::prelude::*;
 use rand::SeedableRng;
 use rand::rngs::StdRng;
@@ -23,6 +23,7 @@ impl From<QsError> for PyErr {
     fn from(e: QsError) -> PyErr {
         match e {
             QsError::Gpu(_) => PyRuntimeError::new_err(e.to_string()),
+            QsError::OutOfMemory { .. } => PyMemoryError::new_err(e.to_string()),
             _ => PyValueError::new_err(e.to_string()),
         }
     }
@@ -68,6 +69,11 @@ impl PyQuantumCircuit {
         self.inner.instructions().len()
     }
 
+    /// Text drawing of the circuit, one wire per qubit: `print(qc)`.
+    fn __str__(&self) -> String {
+        self.inner.to_string()
+    }
+
     fn __repr__(&self) -> String {
         format!("QuantumCircuit(num_qubits={}, gates={})", self.inner.num_qubits(), self.__len__())
     }
@@ -156,7 +162,8 @@ impl PyQuantumCircuit {
         let kind = parse_backend(backend)?;
         let circuit = self.inner.clone();
         let amps = py.detach(move || circuit.statevector(kind))?;
-        Ok(amps.to_pyarray(py))
+        // into_pyarray hands NumPy the Rust buffer itself, so no third copy of the state.
+        Ok(amps.into_pyarray(py))
     }
 
     /// Exact probability of each of the 2**n basis states after the circuit,
@@ -166,7 +173,7 @@ impl PyQuantumCircuit {
         let kind = parse_backend(backend)?;
         let circuit = self.inner.clone();
         let probs = py.detach(move || circuit.probabilities(kind))?;
-        Ok(probs.to_pyarray(py))
+        Ok(probs.into_pyarray(py))
     }
 }