qudenoise 0.1.0__tar.gz

qudenoise-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuDenoise contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qudenoise-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md LICENSE pyproject.toml
+recursive-include tests *.py
+recursive-include examples *.py *.json *.yaml
+recursive-include docs *.md

qudenoise-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.1
+Name: qudenoise
+Version: 0.1.0
+Summary: Pure-Python MPS quantum circuit simulator with Kraus-channel noise trajectories and a quantum-autoencoder denoiser
+Author: QuDenoise contributors
+License: MIT
+Keywords: quantum,simulator,matrix product state,tensor network,noise,autoencoder
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: autodiff
+Provides-Extra: gpu
+Provides-Extra: test
+Provides-Extra: viz
+License-File: LICENSE
+
+# QuDenoise
+
+A from-scratch, pure-Python **Matrix Product State (MPS) quantum circuit simulator** with
+**Kraus-channel noise (quantum trajectories)** and a **quantum-autoencoder (QAE) denoiser**.
+Runs on NumPy everywhere; optionally runs every tensor operation on a GPU through CuPy.
+
+## Install
+
+```bash
+pip install qudenoise            # NumPy/SciPy only (CPU)
+pip install "qudenoise[viz]"     # + matplotlib for plotting examples
+```
+
+### GPU (optional)
+
+CuPy publishes one wheel per CUDA version, so QuDenoise does **not** pin a CuPy variant. Install the one
+matching your toolkit yourself, e.g.
+
+```bash
+pip install cupy-cuda12x         # CUDA 12.x
+pip install cupy-cuda11x         # CUDA 11.x
+```
+
+(`pip install "qudenoise[gpu]"` pulls the generic `cupy` source package, which needs a local CUDA toolchain.)
+CuPy is imported lazily: without it QuDenoise imports and runs with no errors or warnings. With
+`device="auto"` (default) the GPU is used when available and this is logged once
+(`QuDenoise: running on GPU (CuPy)` / `running on CPU (NumPy)`); force a backend with
+`Simulator(device="cupy")` or `device="numpy"`.
+
+## Quick start
+
+```python
+from qudenoise import Circuit, Simulator
+
+c = Circuit(20).h(0)
+for i in range(19):
+    c.cnot(i, i + 1)
+
+sim = Simulator(bond_dim=8)              # chi cap; also truncation_threshold=...
+state = sim.run(c)                       # -> MPS
+print(state.bond_dimensions(), state.fidelity_estimate)
+samples, report = sim.sample(c, shots=1000, seed=1)
+```
+
+Non-adjacent two-qubit gates are routed with SWAP chains automatically; every insertion is logged
+(logger `qudenoise`, INFO) and recorded in `sim.last_report.routing_log`.
+
+### Noise
+
+```python
+c = Circuit(2).h(0).cnot(0, 1).depolarizing(0, 0.05).amplitude_damping(1, 0.1)
+res = Simulator().run_observable(c, lambda m: observables.expectation(m, {0: gates.Z(), 1: gates.Z()}).real,
+                                 n_trajectories=2000, seed=0)
+print(res.mean, "+/-", res.sem)
+```
+
+Channels: `depolarizing` (1q/2q), `amplitude_damping`, `phase_damping`, `bit_flip`, `phase_flip`, or any
+`KrausChannel`. Trajectories are seeded per index (`spawn_seeds`), so results are identical for any worker
+count. CPU runs with 8+ trajectories use a process pool; GPU runs are sequential in-process.
+
+### Quantum autoencoder
+
+```python
+from qudenoise import QAE
+qae = QAE(n_qubits=4, n_latent_qubits=2, ansatz_depth=2, seed=1)
+qae.fit(training_states, epochs=60, lr=0.1)      # MPS / Circuit / dense vectors
+clean_estimate = qae.denoise(noisy_state)
+```
+
+Cost = 1 - mean probability of the trash qubits being `|0..0>`, computed directly from the MPS. Gradients
+use the parameter-shift rule through `qudenoise.qae.compute_gradient`; pass `gradient_fn=` to plug in a JAX
+(`[autodiff]`) backend without changing the API.
+
+### CLI
+
+```bash
+qudenoise run circuit.json --qubits 20 --bond-dim 32 --shots 1000 [--device auto|numpy|cupy] [-o out.json]
+qudenoise train-qae config.yaml
+```
+
+Circuit JSON: `{"n_qubits": N, "ops": [{"gate": "h", "qubits": [0]}, {"gate": "rz", "qubits": [1], "params": [0.3]},
+{"noise": "depolarizing", "qubits": [0], "param": 0.01}]}`. A `.py` file defining `circuit` or
+`build_circuit(n)` also works (executed as ordinary Python - only run files you trust). See
+`examples/qae_config.yaml`.
+
+## Conventions and limits
+
+* Big-endian qubit order (`|q0 q1 ...>`); rotations are `exp(-i theta P / 2)`.
+* `MPS.to_dense()` refuses above 24 qubits unless forced. `qudenoise.reference` (dense/density-matrix
+  simulators) exists to validate the MPS code in tests; it is not a supported product feature.
+* With truncation, `state.truncation_error`, `state.fidelity_estimate` (product of `1 - eps_k`) and
+  `state.fidelity_lower_bound` track accuracy loss.
+
+## Development
+
+```bash
+pip install -e ".[test]" && pytest
+```
+
+Tests run on NumPy and, when CuPy + a GPU are present, are repeated on CuPy (backend-parity check).
+See `docs/design_notes.md`.
+
+MIT licensed.

qudenoise-0.1.0/README.md

@@ -0,0 +1,103 @@
+# QuDenoise
+
+A from-scratch, pure-Python **Matrix Product State (MPS) quantum circuit simulator** with
+**Kraus-channel noise (quantum trajectories)** and a **quantum-autoencoder (QAE) denoiser**.
+Runs on NumPy everywhere; optionally runs every tensor operation on a GPU through CuPy.
+
+## Install
+
+```bash
+pip install qudenoise            # NumPy/SciPy only (CPU)
+pip install "qudenoise[viz]"     # + matplotlib for plotting examples
+```
+
+### GPU (optional)
+
+CuPy publishes one wheel per CUDA version, so QuDenoise does **not** pin a CuPy variant. Install the one
+matching your toolkit yourself, e.g.
+
+```bash
+pip install cupy-cuda12x         # CUDA 12.x
+pip install cupy-cuda11x         # CUDA 11.x
+```
+
+(`pip install "qudenoise[gpu]"` pulls the generic `cupy` source package, which needs a local CUDA toolchain.)
+CuPy is imported lazily: without it QuDenoise imports and runs with no errors or warnings. With
+`device="auto"` (default) the GPU is used when available and this is logged once
+(`QuDenoise: running on GPU (CuPy)` / `running on CPU (NumPy)`); force a backend with
+`Simulator(device="cupy")` or `device="numpy"`.
+
+## Quick start
+
+```python
+from qudenoise import Circuit, Simulator
+
+c = Circuit(20).h(0)
+for i in range(19):
+    c.cnot(i, i + 1)
+
+sim = Simulator(bond_dim=8)              # chi cap; also truncation_threshold=...
+state = sim.run(c)                       # -> MPS
+print(state.bond_dimensions(), state.fidelity_estimate)
+samples, report = sim.sample(c, shots=1000, seed=1)
+```
+
+Non-adjacent two-qubit gates are routed with SWAP chains automatically; every insertion is logged
+(logger `qudenoise`, INFO) and recorded in `sim.last_report.routing_log`.
+
+### Noise
+
+```python
+c = Circuit(2).h(0).cnot(0, 1).depolarizing(0, 0.05).amplitude_damping(1, 0.1)
+res = Simulator().run_observable(c, lambda m: observables.expectation(m, {0: gates.Z(), 1: gates.Z()}).real,
+                                 n_trajectories=2000, seed=0)
+print(res.mean, "+/-", res.sem)
+```
+
+Channels: `depolarizing` (1q/2q), `amplitude_damping`, `phase_damping`, `bit_flip`, `phase_flip`, or any
+`KrausChannel`. Trajectories are seeded per index (`spawn_seeds`), so results are identical for any worker
+count. CPU runs with 8+ trajectories use a process pool; GPU runs are sequential in-process.
+
+### Quantum autoencoder
+
+```python
+from qudenoise import QAE
+qae = QAE(n_qubits=4, n_latent_qubits=2, ansatz_depth=2, seed=1)
+qae.fit(training_states, epochs=60, lr=0.1)      # MPS / Circuit / dense vectors
+clean_estimate = qae.denoise(noisy_state)
+```
+
+Cost = 1 - mean probability of the trash qubits being `|0..0>`, computed directly from the MPS. Gradients
+use the parameter-shift rule through `qudenoise.qae.compute_gradient`; pass `gradient_fn=` to plug in a JAX
+(`[autodiff]`) backend without changing the API.
+
+### CLI
+
+```bash
+qudenoise run circuit.json --qubits 20 --bond-dim 32 --shots 1000 [--device auto|numpy|cupy] [-o out.json]
+qudenoise train-qae config.yaml
+```
+
+Circuit JSON: `{"n_qubits": N, "ops": [{"gate": "h", "qubits": [0]}, {"gate": "rz", "qubits": [1], "params": [0.3]},
+{"noise": "depolarizing", "qubits": [0], "param": 0.01}]}`. A `.py` file defining `circuit` or
+`build_circuit(n)` also works (executed as ordinary Python - only run files you trust). See
+`examples/qae_config.yaml`.
+
+## Conventions and limits
+
+* Big-endian qubit order (`|q0 q1 ...>`); rotations are `exp(-i theta P / 2)`.
+* `MPS.to_dense()` refuses above 24 qubits unless forced. `qudenoise.reference` (dense/density-matrix
+  simulators) exists to validate the MPS code in tests; it is not a supported product feature.
+* With truncation, `state.truncation_error`, `state.fidelity_estimate` (product of `1 - eps_k`) and
+  `state.fidelity_lower_bound` track accuracy loss.
+
+## Development
+
+```bash
+pip install -e ".[test]" && pytest
+```
+
+Tests run on NumPy and, when CuPy + a GPU are present, are repeated on CuPy (backend-parity check).
+See `docs/design_notes.md`.
+
+MIT licensed.

qudenoise-0.1.0/docs/design_notes.md

@@ -0,0 +1,27 @@
+# Design notes
+
+**Backend.** `backend.py` is the only place (besides `reference.py`) that imports NumPy directly. All modules
+call `get_backend()` at use time, never cache arrays across backends, and take RNGs explicitly
+(`get_rng(seed)`, `spawn_seeds`). CuPy is imported lazily; missing CuPy never warns.
+
+**MPS.** Site tensors `(D_left, 2, D_right)`, complex128, tracked orthogonality centre. Two-qubit gates act on
+adjacent sites via two-site tensor + SVD (`utils.svd_truncate`, fixed chi and/or discarded-weight threshold).
+Each truncation records `eps_k` (discarded weight); `fidelity_estimate = prod(1 - eps_k)` and the rigorous
+`1 - (sum sqrt(eps_k))^2` bound are exposed.
+
+**Routing.** Non-adjacent 2q gates are compiled into SWAP chains (out and back) and each insertion is logged,
+never silent.
+
+**Noise.** Quantum trajectories: per channel, branch probabilities come from the local norm after each Kraus
+operator; Pauli-type channels (scaled unitaries) take a state-independent fast path. Trajectory `i` uses seed
+`spawn_seeds(seed, n)[i]`, so parallel and serial runs agree exactly. GPU runs are sequential (CUDA contexts
+do not survive fork the way NumPy workers do).
+
+**QAE.** Ansatz of RY/RZ layers plus generic `RXX*RYY*RZZ` entanglers on a brick pattern (adjacent only).
+Every parameter feeds one `exp(-i t P/2)` gate, so the two-term parameter-shift rule is exact without
+truncation. Gradients live behind `qae.compute_gradient` / `gradient_fn`. Latent = leading qubits, trash =
+trailing qubits so projection and extension are cheap MPS boundary operations.
+
+**Known limitations.** Parameter-shift cost scales as 2 x n_params x n_states simulations per epoch (pure
+Python); the QAE targets small registers. Trajectories give unbiased averages but need many samples for
+small effects. Learning may hit local minima on entangled families; use `restarts=`.

qudenoise-0.1.0/examples/ghz_state.py

@@ -0,0 +1,15 @@
+"""60-qubit GHZ state with bond dimension 2 - far beyond dense simulation."""
+from qudenoise import Circuit, Simulator
+
+n = 60
+c = Circuit(n).h(0)
+for i in range(n - 1):
+    c.cnot(i, i + 1)
+
+sim = Simulator(bond_dim=4)
+state = sim.run(c)
+samples, _ = sim.sample(c, shots=8, seed=1)
+print("max bond dimension:", state.max_bond_dimension)
+print("samples (all-equal rows expected):")
+for row in samples:
+    print("".join(str(int(b)) for b in row))

qudenoise-0.1.0/examples/noisy_bell_pair.py

@@ -0,0 +1,9 @@
+"""Depolarizing noise on a Bell pair: trajectory average vs exact density matrix."""
+from qudenoise import Circuit, Simulator, gates, observables
+
+p = 0.1
+c = Circuit(2).h(0).cnot(0, 1).depolarizing(0, p).depolarizing(1, p)
+zz = lambda m: observables.expectation(m, {0: gates.Z(), 1: gates.Z()}).real
+res = Simulator(device="numpy").run_observable(c, zz, n_trajectories=2000, seed=0)
+print(f"<ZZ> trajectories: {res.mean:.4f} +/- {res.sem:.4f}")
+print(f"<ZZ> exact       : {(1 - 4 * p / 3) ** 2:.4f}")  # each qubit's Z shrinks by 1 - 4p/3

qudenoise-0.1.0/examples/qae_config.yaml

@@ -0,0 +1,14 @@
+# qudenoise train-qae examples/qae_config.yaml
+n_qubits: 3
+n_latent_qubits: 2
+ansatz_depth: 1
+seed: 1
+output: qae_model.json
+fit: {epochs: 40, lr: 0.2, seed: 2}
+training_states:
+  - {n_qubits: 3, ops: [{gate: ry, qubits: [0], params: [0.3]}, {gate: ry, qubits: [1], params: [1.1]}, {gate: ry, qubits: [2], params: [0.9]}]}
+  - {n_qubits: 3, ops: [{gate: ry, qubits: [0], params: [1.5]}, {gate: ry, qubits: [1], params: [0.4]}, {gate: ry, qubits: [2], params: [0.9]}]}
+  - {n_qubits: 3, ops: [{gate: ry, qubits: [0], params: [2.2]}, {gate: ry, qubits: [1], params: [2.0]}, {gate: ry, qubits: [2], params: [0.9]}]}
+test_pairs:
+  - clean: {n_qubits: 3, ops: [{gate: ry, qubits: [0], params: [0.8]}, {gate: ry, qubits: [1], params: [1.7]}, {gate: ry, qubits: [2], params: [0.9]}]}
+    noisy: {n_qubits: 3, ops: [{gate: ry, qubits: [0], params: [0.8]}, {gate: ry, qubits: [1], params: [1.7]}, {gate: ry, qubits: [2], params: [0.9]}, {gate: rx, qubits: [2], params: [0.5]}]}

qudenoise-0.1.0/examples/train_qae_denoiser.py

@@ -0,0 +1,34 @@
+"""Train a QAE on a family of product states and use it to denoise perturbed states."""
+import math
+import random
+
+from qudenoise import Circuit, MPS, QAE
+from qudenoise.backend import get_rng
+from qudenoise.simulator import execute_ops
+
+
+def family(seed, n=4, k=2):
+    r = random.Random(seed)
+    c = Circuit(n)
+    for q in range(k):
+        c.ry(q, r.uniform(0, math.pi)).rz(q, r.uniform(0, 2 * math.pi))
+    for q in range(k, n):
+        c.ry(q, 0.9).rz(q, 0.4)
+    return c
+
+
+def state(c):
+    return execute_ops(c.compile(), MPS(c.n_qubits, device="numpy"), get_rng(0))
+
+
+qae = QAE(4, 2, ansatz_depth=2, seed=1)
+res = qae.fit([family(s) for s in range(6)], epochs=60, lr=0.1, seed=3)
+print(f"trash cost: {res.initial_cost:.3f} -> {res.final_cost:.5f}")
+
+for s in range(3):
+    clean = family(100 + s)
+    noisy = clean.copy()
+    for q in range(4):
+        noisy.rx(q, 0.25 * (-1) ** q)
+    r = qae.denoise_fidelity(state(noisy), state(clean))
+    print(f"fidelity {r['before']:.4f} -> {r['after']:.4f}")

qudenoise-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qudenoise"
+version = "0.1.0"  # keep in sync with src/qudenoise/__init__.py::__version__
+description = "Pure-Python MPS quantum circuit simulator with Kraus-channel noise trajectories and a quantum-autoencoder denoiser"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "QuDenoise contributors" }]
+keywords = ["quantum", "simulator", "matrix product state", "tensor network", "noise", "autoencoder"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "License :: OSI Approved :: MIT License",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "numpy>=1.22",
+    "scipy>=1.8",
+    "PyYAML>=5.4",  # train-qae config files
+]
+
+[project.optional-dependencies]
+# CuPy ships one wheel per CUDA version (cupy-cuda12x, cupy-cuda11x, ...), so `[gpu]` pulls the
+# generic source package name only as a convenience; on most machines install the matching wheel
+# yourself (see README) instead of using this extra.
+gpu = ["cupy"]
+autodiff = ["jax"]
+viz = ["matplotlib>=3.5"]
+test = ["pytest>=7"]
+
+[project.scripts]
+qudenoise = "qudenoise.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+qudenoise = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

qudenoise-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

qudenoise-0.1.0/src/qudenoise/__init__.py

@@ -0,0 +1,43 @@
+"""QuDenoise: pure-Python MPS quantum circuit simulator with noise and a QAE denoiser."""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from . import backend, gates, noise, observables
+from .backend import (
+    get_backend,
+    get_rng,
+    gpu_available,
+    set_backend,
+    to_backend,
+    to_numpy,
+    use_backend,
+)
+from .circuit import Circuit, Op
+from .mps import MPS
+from .noise import KrausChannel
+from .qae import QAE
+from .simulator import ObservableResult, SimulationReport, Simulator
+
+__all__ = [
+    "__version__",
+    "backend",
+    "gates",
+    "noise",
+    "observables",
+    "get_backend",
+    "get_rng",
+    "gpu_available",
+    "set_backend",
+    "to_backend",
+    "to_numpy",
+    "use_backend",
+    "Circuit",
+    "Op",
+    "MPS",
+    "KrausChannel",
+    "QAE",
+    "Simulator",
+    "SimulationReport",
+    "ObservableResult",
+]