qsengine 1.0.0__tar.gz → 1.0.1__tar.gz

qsengine-1.0.1/.gitattributes

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

{qsengine-1.0.0 → qsengine-1.0.1}/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.1"
 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.1}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "qsengine"
-version = "1.0.0"
+version = "1.0.1"
 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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qsengine
-Version: 1.0.0
+Version: 1.0.1
 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
@@ -82,15 +82,17 @@ qc.cx(0, 1)
 qc.cx(1, 2)
 
 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 +126,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 +159,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.1}/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
@@ -49,15 +49,17 @@ qc.cx(0, 1)
 qc.cx(1, 2)
 
 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 +93,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 +126,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.1}/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.1}/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
 
@@ -29,17 +32,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.1}/src/circuit.rs

@@ -58,7 +58,16 @@ impl QuantumCircuit {
         Ok(())
     }
 
-    // Named gates: same names and meaning as on `QuantumBackend`.
+    /// 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.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) }
@@ -74,6 +83,30 @@ impl QuantumCircuit {
     pub fn cz(&mut self, control: usize, target: usize) -> Result<()> {
         self.add_gate(&[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 u(&mut self, q: usize, theta: f64, phi: f64, lambda: f64) -> Result<()> {
+        self.add_gate(&[], 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))
+    }
+    pub fn crz(&mut self, control: usize, target: usize, theta: f64) -> Result<()> {
+        self.add_gate(&[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)
+    }
+    /// 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)
+    }
 
     /// Apply every instruction to an existing backend, with single-qubit gate fusion.
     ///
@@ -190,6 +223,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());
     }
 

{qsengine-1.0.0 → qsengine-1.0.1}/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.1}/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)    |
@@ -69,6 +69,8 @@ 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,
     /// No usable GPU, or the GPU driver reported an error.
     Gpu(String),
 }
@@ -86,6 +88,7 @@ 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::Gpu(msg) => write!(f, "GPU error: {msg}"),
         }
     }

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

@@ -11,6 +11,7 @@
 
 use crate::{BackendKind, QsError, QuantumCircuit, format_bitstring};
 use num_complex::Complex64;
+use numpy::{PyArray1, ToPyArray};
 use pyo3::exceptions::{PyRuntimeError, PyValueError};
 use pyo3::prelude::*;
 use rand::SeedableRng;
@@ -93,6 +94,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 +149,24 @@ 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))?;
+        Ok(amps.to_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.to_pyarray(py))
     }
 }