qsengine 1.0.0__tar.gz → 1.0.2__tar.gz

qsengine-1.0.2/.gitattributes

@@ -0,0 +1 @@
+site/** linguist-vendored

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

@@ -505,6 +505,16 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "matrixmultiply"
+version = "0.3.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f607c237553f086e7043417a51df26b2eb899d3caff94e6a67592ff992fedc7"
+dependencies = [
+ "autocfg",
+ "rawpointer",
+]
+
 [[package]]
 name = "metal"
 version = "0.31.0"
@@ -538,13 +548,28 @@ dependencies = [
  "log",
  "num-traits",
  "once_cell",
- "rustc-hash",
+ "rustc-hash 1.1.0",
  "spirv",
  "strum",
  "thiserror 2.0.21",
  "unicode-ident",
 ]
 
+[[package]]
+name = "ndarray"
+version = "0.17.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "520080814a7a6b4a6e9070823bb24b4531daac8c4627e08ba5de8c5ef2f2752d"
+dependencies = [
+ "matrixmultiply",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "portable-atomic",
+ "portable-atomic-util",
+ "rawpointer",
+]
+
 [[package]]
 name = "ndk-sys"
 version = "0.5.0+25.2.9519653"
@@ -563,6 +588,15 @@ dependencies = [
  "num-traits",
 ]
 
+[[package]]
+name = "num-integer"
+version = "0.1.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7ce2d95d4b3734dc35aa2f45e1aa22cd416814592a4f9d9205e11affd5b8e10b"
+dependencies = [
+ "num-traits",
+]
+
 [[package]]
 name = "num-traits"
 version = "0.2.19"
@@ -573,6 +607,22 @@ dependencies = [
  "libm",
 ]
 
+[[package]]
+name = "numpy"
+version = "0.30.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aa0b9111761885449e894981fa8051dcf69e0bd114aecbd4bcdd830b6be4ed92"
+dependencies = [
+ "libc",
+ "ndarray",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "pyo3",
+ "pyo3-build-config",
+ "rustc-hash 2.1.3",
+]
+
 [[package]]
 name = "objc"
 version = "0.2.7"
@@ -650,6 +700,15 @@ version = "1.13.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
 
+[[package]]
+name = "portable-atomic-util"
+version = "0.2.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10ab3eb7f3becc3a1cbc4f2c6f20267996cfc1a6467a873763411b136a122715"
+dependencies = [
+ "portable-atomic",
+]
+
 [[package]]
 name = "ppv-lite86"
 version = "0.2.21"
@@ -740,10 +799,11 @@ dependencies = [
 
 [[package]]
 name = "qsengine"
-version = "1.0.0"
+version = "1.0.2"
 dependencies = [
  "bytemuck",
  "num-complex",
+ "numpy",
  "pollster",
  "pyo3",
  "rand",
@@ -807,6 +867,12 @@ version = "0.6.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "20675572f6f24e9e76ef639bc5552774ed45f1c30e2951e1e99c59888861c539"
 
+[[package]]
+name = "rawpointer"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60a357793950651c4ed0f3f52338f53b2f809f32d83a07f72909fa13e4c6c1e3"
+
 [[package]]
 name = "rayon"
 version = "1.12.0"
@@ -848,6 +914,12 @@ version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "08d43f7aa6b08d49f382cde6a7982047c3426db949b1424bc4b7ec9ae12c6ce2"
 
+[[package]]
+name = "rustc-hash"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
+
 [[package]]
 name = "rustversion"
 version = "1.0.23"
@@ -1176,7 +1248,7 @@ dependencies = [
  "portable-atomic",
  "profiling",
  "raw-window-handle",
- "rustc-hash",
+ "rustc-hash 1.1.0",
  "smallvec",
  "thiserror 2.0.21",
  "wgpu-core-deps-apple",

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

@@ -1,6 +1,6 @@
 [package]
 name = "qsengine"
-version = "1.0.0"
+version = "1.0.2"
 edition = "2024"
 license = "MIT"
 description = "High-performance state-vector quantum simulator (CPU + portable GPU backends)"
@@ -23,7 +23,7 @@ default = ["gpu"]
 gpu = ["dep:wgpu", "dep:pollster", "dep:bytemuck"]
 # Python bindings. Off for plain `cargo build/test`; maturin turns it on
 # (see [tool.maturin] in pyproject.toml).
-python = ["dep:pyo3"]
+python = ["dep:pyo3", "dep:numpy"]
 
 [dependencies]
 num-complex = "0.4.6"
@@ -36,3 +36,5 @@ bytemuck = { version = "1", features = ["derive"], optional = true }
 # abi3-py39: one compiled wheel works on every CPython from 3.9 up.
 # num-complex: amplitudes convert straight to Python `complex`.
 pyo3 = { version = "0.30", features = ["abi3-py39", "num-complex"], optional = true }
+# statevector() / probabilities() return NumPy arrays without per-element Python objects.
+numpy = { version = "0.30", optional = true }

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qsengine
-Version: 1.0.0
+Version: 1.0.2
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Intended Audience :: Education
@@ -14,8 +14,8 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Scientific/Engineering :: Physics
 Classifier: Typing :: Typed
+Requires-Dist: numpy>=1.19
 Requires-Dist: pytest ; extra == 'test'
-Requires-Dist: numpy ; extra == 'test'
 Provides-Extra: test
 License-File: LICENSE
 Summary: A fast state-vector quantum simulator for Python, with a Rust core that runs on any CPU or GPU
@@ -58,7 +58,7 @@ print(qc.run(shots=1000, seed=1))   # {'00': 513, '11': 487}
 - **Fast where it counts.** Small circuits run on the CPU with almost no per-call overhead; from 14 qubits up, the GPU takes over. On a 22-qubit benchmark qsengine's GPU backend is about 5 times faster than Qiskit Aer.
 - **Any GPU, nothing to install.** The GPU backend uses [wgpu](https://wgpu.rs), so it runs on NVIDIA, AMD, Intel and Apple GPUs through Vulkan, DirectX 12 or Metal. No CUDA, no vendor toolkit.
 - **Works everywhere.** Without a usable GPU the same code runs on the CPU, in full 64-bit precision.
-- **Small, plain API.** One class, eleven gates, three ways to get a result. Mistakes raise a normal Python `ValueError` on the line that made them.
+- **Small, plain API.** One class, nineteen gates plus any 2x2 unitary, three ways to get a result. Mistakes raise a normal Python `ValueError` on the line that made them.
 - **Built to learn with.** The website walks from bra-ket notation to a complete Deutsch-Jozsa run, and every example on it is real qsengine output.
 
 ## Install
@@ -81,16 +81,19 @@ 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
-qc.statevector()            # exact complex amplitudes
+qc.probabilities()          # exact probabilities of all 8 basis states (NumPy array)
+qc.statevector()            # exact complex amplitudes (NumPy array)
 ```
 
 | Gates | Methods |
 | --- | --- |
-| Single qubit | `x`, `y`, `z`, `h`, `s`, `t` |
-| Rotations (radians) | `rx(q, theta)`, `ry(q, theta)`, `rz(q, theta)` |
-| Two qubit | `cx(control, target)`, `cz(control, target)` |
+| Single qubit | `x`, `y`, `z`, `h`, `s`, `sdg`, `t`, `tdg` |
+| Angles (radians) | `rx(q, theta)`, `ry(q, theta)`, `rz(q, theta)`, `p(q, lam)`, `u(q, theta, phi, lam)` |
+| Two qubit | `cx(control, target)`, `cz(control, target)`, `cp(control, target, lam)`, `crz(control, target, theta)`, `swap(q1, q2)` |
+| Three qubit | `ccx(control1, control2, target)` |
+| Any 2x2 unitary | `unitary(matrix, target, controls=[])` |
 
 Bitstrings put **qubit 0 on the right**, the same convention as Qiskit. Pass `seed` to `run()` for repeatable counts.
 
@@ -124,7 +127,7 @@ Below 14 qubits the CPU backend is 7 to 60 times faster than Aer; from 14 qubits
 
 ## Limitations
 
-Version 1.0 measures every qubit at the end of the circuit. There is no SWAP gate and no mid-circuit measurement yet, so algorithms such as teleportation that branch on a measurement are not possible. A register holds at most 30 qubits (16 GiB of memory).
+Version 1.0 measures every qubit at the end of the circuit. There is no mid-circuit measurement yet, so algorithms such as teleportation that branch on a measurement are not possible. A register holds at most 30 qubits (16 GiB of memory).
 
 ## Building from source
 
@@ -157,6 +160,8 @@ npm run dev                     # local preview
 npm run build                   # static site in site/out/
 ```
 
+Docs pages are Markdown (`site/app/docs/**/page.mdx`) with `$maths$`, tables and fenced code; `<Output printed="..." />` shows what a snippet prints. To add a page, create its `page.mdx` and list it in `DOCS` in `site/app/content.js`, which drives the sidebar and the previous/next links.
+
 ## Project layout
 
 ```text

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

@@ -25,7 +25,7 @@ print(qc.run(shots=1000, seed=1))   # {'00': 513, '11': 487}
 - **Fast where it counts.** Small circuits run on the CPU with almost no per-call overhead; from 14 qubits up, the GPU takes over. On a 22-qubit benchmark qsengine's GPU backend is about 5 times faster than Qiskit Aer.
 - **Any GPU, nothing to install.** The GPU backend uses [wgpu](https://wgpu.rs), so it runs on NVIDIA, AMD, Intel and Apple GPUs through Vulkan, DirectX 12 or Metal. No CUDA, no vendor toolkit.
 - **Works everywhere.** Without a usable GPU the same code runs on the CPU, in full 64-bit precision.
-- **Small, plain API.** One class, eleven gates, three ways to get a result. Mistakes raise a normal Python `ValueError` on the line that made them.
+- **Small, plain API.** One class, nineteen gates plus any 2x2 unitary, three ways to get a result. Mistakes raise a normal Python `ValueError` on the line that made them.
 - **Built to learn with.** The website walks from bra-ket notation to a complete Deutsch-Jozsa run, and every example on it is real qsengine output.
 
 ## Install
@@ -48,16 +48,19 @@ 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
-qc.statevector()            # exact complex amplitudes
+qc.probabilities()          # exact probabilities of all 8 basis states (NumPy array)
+qc.statevector()            # exact complex amplitudes (NumPy array)
 ```
 
 | Gates | Methods |
 | --- | --- |
-| Single qubit | `x`, `y`, `z`, `h`, `s`, `t` |
-| Rotations (radians) | `rx(q, theta)`, `ry(q, theta)`, `rz(q, theta)` |
-| Two qubit | `cx(control, target)`, `cz(control, target)` |
+| Single qubit | `x`, `y`, `z`, `h`, `s`, `sdg`, `t`, `tdg` |
+| Angles (radians) | `rx(q, theta)`, `ry(q, theta)`, `rz(q, theta)`, `p(q, lam)`, `u(q, theta, phi, lam)` |
+| Two qubit | `cx(control, target)`, `cz(control, target)`, `cp(control, target, lam)`, `crz(control, target, theta)`, `swap(q1, q2)` |
+| Three qubit | `ccx(control1, control2, target)` |
+| Any 2x2 unitary | `unitary(matrix, target, controls=[])` |
 
 Bitstrings put **qubit 0 on the right**, the same convention as Qiskit. Pass `seed` to `run()` for repeatable counts.
 
@@ -91,7 +94,7 @@ Below 14 qubits the CPU backend is 7 to 60 times faster than Aer; from 14 qubits
 
 ## Limitations
 
-Version 1.0 measures every qubit at the end of the circuit. There is no SWAP gate and no mid-circuit measurement yet, so algorithms such as teleportation that branch on a measurement are not possible. A register holds at most 30 qubits (16 GiB of memory).
+Version 1.0 measures every qubit at the end of the circuit. There is no mid-circuit measurement yet, so algorithms such as teleportation that branch on a measurement are not possible. A register holds at most 30 qubits (16 GiB of memory).
 
 ## Building from source
 
@@ -124,6 +127,8 @@ npm run dev                     # local preview
 npm run build                   # static site in site/out/
 ```
 
+Docs pages are Markdown (`site/app/docs/**/page.mdx`) with `$maths$`, tables and fenced code; `<Output printed="..." />` shows what a snippet prints. To add a page, create its `page.mdx` and list it in `DOCS` in `site/app/content.js`, which drives the sidebar and the previous/next links.
+
 ## Project layout
 
 ```text

{qsengine-1.0.0 → qsengine-1.0.2}/pyproject.toml

@@ -8,6 +8,7 @@ description = "A fast state-vector quantum simulator for Python, with a Rust cor
 readme = "README.md"
 requires-python = ">=3.9"
 license = "MIT"
+dependencies = ["numpy>=1.19"]
 license-files = ["LICENSE"]
 authors = [{ name = "kaiwave" }]
 keywords = ["quantum", "quantum computing", "simulator", "statevector", "qubit", "gpu", "rust"]
@@ -36,7 +37,7 @@ Issues = "https://github.com/kaiwave/qsengine/issues"
 "Release notes" = "https://qsengine.kaiwave.dev/docs/release-notes/"
 
 [project.optional-dependencies]
-test = ["pytest", "numpy"]
+test = ["pytest"]
 
 [tool.maturin]
 # Build the Rust crate with its Python bindings (and the default GPU backend).

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

@@ -4,7 +4,10 @@ Bit order: qubit 0 is the rightmost character of every bitstring and bit 0 of
 every basis index, the same convention as Qiskit.
 """
 
-from typing import Literal, Optional
+from typing import Literal, Optional, Sequence, Union
+
+import numpy as np
+import numpy.typing as npt
 
 __version__: str
 
@@ -18,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: ...
@@ -29,17 +34,36 @@ class QuantumCircuit:
     def rx(self, qubit: int, theta: float) -> None: ...
     def ry(self, qubit: int, theta: float) -> None: ...
     def rz(self, qubit: int, theta: float) -> None: ...
+    def sdg(self, qubit: int) -> None: ...
+    def tdg(self, qubit: int) -> None: ...
+    def p(self, qubit: int, lam: float) -> None: ...
+    def u(self, qubit: int, theta: float, phi: float, lam: float) -> None: ...
 
     # Two-qubit gates
     def cx(self, control: int, target: int) -> None: ...
     def cz(self, control: int, target: int) -> None: ...
+    def cp(self, control: int, target: int, lam: float) -> None: ...
+    def crz(self, control: int, target: int, theta: float) -> None: ...
+    def swap(self, qubit1: int, qubit2: int) -> None: ...
+
+    # Three-qubit gates
+    def ccx(self, control1: int, control2: int, target: int) -> None: ...
+
+    # Any 2x2 unitary, optionally controlled
+    def unitary(
+        self,
+        matrix: Union[Sequence[Sequence[complex]], npt.ArrayLike],
+        target: int,
+        controls: Sequence[int] = ...,
+    ) -> None:
+        """Apply a 2x2 unitary to `target`; raises ValueError if it is not unitary."""
 
     # Execution
     def run(
         self, shots: int = 1024, seed: Optional[int] = None, backend: Backend = "auto"
     ) -> dict[str, int]:
         """Measure all qubits `shots` times; returns {bitstring: count}."""
-    def statevector(self, backend: Backend = "auto") -> list[complex]:
+    def statevector(self, backend: Backend = "auto") -> npt.NDArray[np.complex128]:
         """Exact final amplitudes, length 2**num_qubits."""
-    def probabilities(self, backend: Backend = "auto") -> list[float]:
+    def probabilities(self, backend: Backend = "auto") -> npt.NDArray[np.float64]:
         """Exact final basis-state probabilities, length 2**num_qubits."""

{qsengine-1.0.0 → 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.0 → 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,26 +70,68 @@ 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(())
     }
 
-    // Named gates: same names and meaning as on `QuantumBackend`.
-    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)) }
+    /// Record a user-supplied 2x2 `gate`, after checking it is unitary.
+    /// [`add_gate`](Self::add_gate) trusts its matrix; this is the entry point for untrusted input.
+    pub fn unitary(&mut self, controls: &[usize], target: usize, gate: Gate) -> Result<()> {
+        if !gates::is_unitary(&gate, 1e-9) {
+            return Err(QsError::NotUnitary);
+        }
+        self.add_gate(controls, target, gate)
+    }
+
+    // Named gates. The first eleven match `QuantumBackend`; the rest are circuit-only.
+    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.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.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.push(label("P", &[lambda]), &[control], target, gates::p(lambda))
+    }
+    pub fn crz(&mut self, control: usize, target: usize, theta: f64) -> Result<()> {
+        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.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)?;
+        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.
@@ -132,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.
@@ -147,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::*;
@@ -190,6 +294,9 @@ mod tests {
         let mut qc = QuantumCircuit::new(2).unwrap();
         assert_eq!(qc.h(2), Err(QsError::QubitOutOfRange { qubit: 2, num_qubits: 2 }));
         assert_eq!(qc.cx(0, 0), Err(QsError::DuplicateQubit(0)));
+        assert_eq!(qc.swap(1, 1), Err(QsError::DuplicateQubit(1)));
+        assert_eq!(qc.swap(0, 5), Err(QsError::QubitOutOfRange { qubit: 5, num_qubits: 2 }));
+        assert_eq!(qc.unitary(&[], 0, [[gates::H[0][0]; 2]; 2]), Err(QsError::NotUnitary));
         assert!(qc.instructions().is_empty());
     }
 
@@ -203,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.0 → 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.0 → qsengine-1.0.2}/src/gates.rs

@@ -51,6 +51,37 @@ pub const S: Gate = [[I, O], [O, c(0.0, 1.0)]];
 /// T (fourth root of Z): |1> -> e^(i*pi/4)|1>.
 pub const T: Gate = [[I, O], [O, c(FRAC_1_SQRT_2, FRAC_1_SQRT_2)]];
 
+/// S-dagger, the inverse of S: |1> -> -i|1>.
+pub const SDG: Gate = [[I, O], [O, c(0.0, -1.0)]];
+
+/// T-dagger, the inverse of T: |1> -> e^(-i*pi/4)|1>.
+pub const TDG: Gate = [[I, O], [O, c(FRAC_1_SQRT_2, -FRAC_1_SQRT_2)]];
+
+/// Phase gate: |1> -> e^(i*lambda)|1>. `p(pi)` is Z, `p(pi/2)` is S.
+pub fn p(lambda: f64) -> Gate {
+    [[I, O], [O, Complex64::from_polar(1.0, lambda)]]
+}
+
+/// General single-qubit gate U(theta, phi, lambda), the same convention as Qiskit's `UGate`.
+pub fn u(theta: f64, phi: f64, lambda: f64) -> Gate {
+    let (s, co) = (theta / 2.0).sin_cos();
+    [
+        [c(co, 0.0), -Complex64::from_polar(s, lambda)],
+        [Complex64::from_polar(s, phi), Complex64::from_polar(co, phi + lambda)],
+    ]
+}
+
+/// True if `g` is unitary (`g * g^dagger = I`) to within `tol`.
+pub fn is_unitary(g: &Gate, tol: f64) -> bool {
+    (0..2).all(|r| {
+        (0..2).all(|col| {
+            let sum = g[r][0] * g[col][0].conj() + g[r][1] * g[col][1].conj();
+            let expect = if r == col { I } else { O };
+            (sum - expect).norm() < tol
+        })
+    })
+}
+
 /// Rotation about the X axis of the Bloch sphere by `theta` radians.
 pub fn rx(theta: f64) -> Gate {
     let (s, co) = (theta / 2.0).sin_cos();
@@ -85,21 +116,20 @@ pub fn matmul(a: &Gate, b: &Gate) -> Gate {
 mod tests {
     use super::*;
 
-    /// U * U^dagger should be the identity for every gate.
-    fn assert_unitary(g: &Gate) {
-        for r in 0..2 {
-            for col in 0..2 {
-                let sum = g[r][0] * g[col][0].conj() + g[r][1] * g[col][1].conj();
-                let expect = if r == col { 1.0 } else { 0.0 };
-                assert!((sum - c(expect, 0.0)).norm() < 1e-12, "not unitary: {g:?}");
-            }
+    #[test]
+    fn all_gates_are_unitary() {
+        for g in [ID, X, Y, Z, H, S, T, SDG, TDG, rx(0.3), ry(1.1), rz(-2.0), p(0.7), u(0.4, -1.3, 2.2)] {
+            assert!(is_unitary(&g, 1e-12), "not unitary: {g:?}");
         }
+        assert!(!is_unitary(&[[I, I], [O, I]], 1e-9));
     }
 
     #[test]
-    fn all_gates_are_unitary() {
-        for g in [ID, X, Y, Z, H, S, T, rx(0.3), ry(1.1), rz(-2.0)] {
-            assert_unitary(&g);
-        }
+    fn named_identities() {
+        let close = |a: &Gate, b: &Gate| (0..2).all(|r| (0..2).all(|k| (a[r][k] - b[r][k]).norm() < 1e-12));
+        assert!(close(&matmul(&S, &SDG), &ID));
+        assert!(close(&matmul(&T, &TDG), &ID));
+        assert!(close(&p(std::f64::consts::FRAC_PI_2), &S));
+        assert!(close(&u(std::f64::consts::FRAC_PI_2, 0.0, std::f64::consts::PI), &H));
     }
 }

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

@@ -10,7 +10,7 @@
 //!
 //! | Module      | Purpose                                                        |
 //! |-------------|----------------------------------------------------------------|
-//! | [`gates`]   | 2x2 gate matrices (X, Y, Z, H, S, T, rotations)                |
+//! | [`gates`]   | 2x2 gate matrices (Paulis, H, S, T, phase, U, rotations)       |
 //! | [`backend`] | The [`QuantumBackend`] trait: the one API every simulator obeys |
 //! | [`circuit`] | [`QuantumCircuit`]: record gates now, run them later           |
 //! | [`engine`]  | [`QuantumState`]: multithreaded CPU backend (f64 precision)    |
@@ -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;
@@ -69,6 +69,12 @@ pub enum QsError {
     DuplicateQubit(usize),
     /// A circuit was applied to a backend with a different number of qubits.
     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),
 }
@@ -86,6 +92,11 @@ impl fmt::Display for QsError {
             QsError::SizeMismatch { circuit, backend } => {
                 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.0 → qsengine-1.0.2}/src/python.rs

@@ -11,7 +11,8 @@
 
 use crate::{BackendKind, QsError, QuantumCircuit, format_bitstring};
 use num_complex::Complex64;
-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;
@@ -22,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()),
         }
     }
@@ -67,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__())
     }
@@ -93,6 +100,39 @@ impl PyQuantumCircuit {
     fn cx(&mut self, control: usize, target: usize) -> PyResult<()> { Ok(self.inner.cx(control, target)?) }
     /// Controlled-Z: flip the phase of |11> on `control`, `target`.
     fn cz(&mut self, control: usize, target: usize) -> PyResult<()> { Ok(self.inner.cz(control, target)?) }
+    /// S-dagger (inverse of S) on `qubit`.
+    fn sdg(&mut self, qubit: usize) -> PyResult<()> { Ok(self.inner.sdg(qubit)?) }
+    /// T-dagger (inverse of T) on `qubit`.
+    fn tdg(&mut self, qubit: usize) -> PyResult<()> { Ok(self.inner.tdg(qubit)?) }
+    /// Phase gate: multiply the |1> amplitude of `qubit` by e^(i*lam).
+    fn p(&mut self, qubit: usize, lam: f64) -> PyResult<()> { Ok(self.inner.p(qubit, lam)?) }
+    /// General single-qubit gate U(theta, phi, lam), the same convention as Qiskit.
+    fn u(&mut self, qubit: usize, theta: f64, phi: f64, lam: f64) -> PyResult<()> {
+        Ok(self.inner.u(qubit, theta, phi, lam)?)
+    }
+    /// Controlled phase: multiply the |11> amplitude of `control`, `target` by e^(i*lam).
+    fn cp(&mut self, control: usize, target: usize, lam: f64) -> PyResult<()> { Ok(self.inner.cp(control, target, lam)?) }
+    /// Controlled RZ: rotate `target` about Z by `theta` when `control` is |1>.
+    fn crz(&mut self, control: usize, target: usize, theta: f64) -> PyResult<()> {
+        Ok(self.inner.crz(control, target, theta)?)
+    }
+    /// Toffoli: flip `target` when `control1` and `control2` are both |1>.
+    fn ccx(&mut self, control1: usize, control2: usize, target: usize) -> PyResult<()> {
+        Ok(self.inner.ccx(control1, control2, target)?)
+    }
+    /// Swap the states of `qubit1` and `qubit2` (recorded as three CNOTs).
+    fn swap(&mut self, qubit1: usize, qubit2: usize) -> PyResult<()> { Ok(self.inner.swap(qubit1, qubit2)?) }
+
+    /// Apply any 2x2 unitary `matrix` (nested lists or a NumPy array) to `target`,
+    /// optionally only where every qubit in `controls` is |1>.
+    #[pyo3(signature = (matrix, target, controls = Vec::new()))]
+    fn unitary(&mut self, matrix: Vec<Vec<Complex64>>, target: usize, controls: Vec<usize>) -> PyResult<()> {
+        let gate = match matrix.as_slice() {
+            [r0, r1] if r0.len() == 2 && r1.len() == 2 => [[r0[0], r0[1]], [r1[0], r1[1]]],
+            _ => return Err(PyValueError::new_err("matrix must be 2x2")),
+        };
+        Ok(self.inner.unitary(&controls, target, gate)?)
+    }
 
     /// Simulate the circuit and measure every qubit `shots` times.
     ///
@@ -115,21 +155,25 @@ impl PyQuantumCircuit {
         Ok(counts.into_iter().map(|(i, c)| (format_bitstring(i, n), c)).collect())
     }
 
-    /// Exact final state as a list of 2**n complex amplitudes, indexed by basis
-    /// state (wrap with `numpy.array(...)` for vector maths).
+    /// Exact final state as a NumPy array of 2**n complex128 amplitudes,
+    /// indexed by basis state.
     #[pyo3(signature = (backend = "auto"))]
-    fn statevector(&self, py: Python<'_>, backend: &str) -> PyResult<Vec<Complex64>> {
+    fn statevector<'py>(&self, py: Python<'py>, backend: &str) -> PyResult<Bound<'py, PyArray1<Complex64>>> {
         let kind = parse_backend(backend)?;
         let circuit = self.inner.clone();
-        Ok(py.detach(move || circuit.statevector(kind))?)
+        let amps = py.detach(move || circuit.statevector(kind))?;
+        // 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.
+    /// Exact probability of each of the 2**n basis states after the circuit,
+    /// as a NumPy float64 array.
     #[pyo3(signature = (backend = "auto"))]
-    fn probabilities(&self, py: Python<'_>, backend: &str) -> PyResult<Vec<f64>> {
+    fn probabilities<'py>(&self, py: Python<'py>, backend: &str) -> PyResult<Bound<'py, PyArray1<f64>>> {
         let kind = parse_backend(backend)?;
         let circuit = self.inner.clone();
-        Ok(py.detach(move || circuit.probabilities(kind))?)
+        let probs = py.detach(move || circuit.probabilities(kind))?;
+        Ok(probs.into_pyarray(py))
     }
 }