qusim-np 1.0__tar.gz

qusim_np-1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Furkan Nar
+
+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.

qusim_np-1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: qusim-np
+Version: 1.0
+Summary: A minimal, readable quantum computing simulator: gates, state-vector algorithms, and VQE
+Author-email: Furkan Nar <furkan_nar4185@outlook.com>
+License: MIT
+Project-URL: Homepage, https://github.com/furkannar/qusim-np
+Project-URL: Repository, https://github.com/furkannar/qusim-np
+Keywords: quantum,quantum-computing,simulation,vqe,grover,qft
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: scipy>=1.11.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Dynamic: license-file
+
+# qusim-np
+
+**A minimal, readable quantum computing simulator in pure NumPy.**
+
+State-vector gates, textbook quantum algorithms, and a working
+Variational Quantum Eigensolver — in ~1,200 lines of well-documented,
+well-tested code. Built for learning, teaching, and prototyping.
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-178%20passing-brightgreen)](tests/)
+
+---
+
+## Features
+
+| Category | What you get |
+|---|---|
+| **Gates** | Pauli X/Y/Z, Hadamard, S, T, CNOT, SWAP, CZ, Toffoli, `rx`/`ry`/`rz` rotations |
+| **Algorithms** | Grover search, Deutsch–Jozsa, Quantum Fourier Transform |
+| **VQE** | Pauli-string Hamiltonians, hardware-efficient ansatz, `scipy` optimizer |
+| **Performance** | 1- and 2-qubit gates applied to state vectors in O(n·2ⁿ) — no dense 2ⁿ×2ⁿ matrices in the hot path |
+
+## Install
+
+```bash
+pip install qusim-np
+```
+
+From source:
+
+```bash
+git clone https://github.com/furkannar/qusim-np.git
+cd qusim-np
+pip install -e .
+```
+
+Requires Python ≥ 3.10, NumPy ≥ 2.0, SciPy ≥ 1.11.
+
+## Quick start
+
+```python
+import qusim_np
+
+# Grover's search — find state |101> among 8 possibilities
+state, k, p = qusim_np.grover_search(3, marked_states=[5])
+print(f"{k} iterations -> P(marked) = {p:.3f}")
+
+# Deutsch-Jozsa — constant or balanced with ONE query
+print(qusim_np.deutsch_jozsa_classify(3, lambda x: x % 2))   # 'balanced'
+
+# Quantum Fourier Transform
+F = qusim_np.qft_matrix(3)          # 8x8 unitary
+```
+
+### The math, briefly
+
+Grover's algorithm rotates the state vector in the plane spanned by the
+marked and unmarked subspaces. With $N = 2^n$ basis states and $M$ marked
+states, each iteration rotates by
+
+$$\theta = 2\arcsin\sqrt{\frac{M}{N}}, \qquad
+k_{\mathrm{opt}} \approx \frac{\pi}{4}\sqrt{\frac{N}{M}}$$
+
+so the marked states are amplified after $O(\sqrt{N/M})$ oracle queries.
+
+The Quantum Fourier Transform is the unitary
+
+$$F_{jk} = \frac{1}{\sqrt{N}}\,\omega^{jk}, \qquad
+\omega = e^{2\pi i / N}, \qquad j,k = 0,\dots,N-1$$
+
+## Variational Quantum Eigensolver
+
+The flagship feature: find the ground-state energy of a Hamiltonian
+written as a linear combination of Pauli strings,
+
+$$H = \sum_{i=0}^{m-1} \alpha_i P_i, \qquad
+P_i = \bigotimes_{k=0}^{n-1} \sigma_{i,k}, \qquad
+\sigma_{i,k} \in \{I, X, Y, Z\}$$
+
+by minimizing the variational energy
+
+$$E(\theta) = \langle \psi(\theta) \,|\, H \,|\, \psi(\theta) \rangle$$
+
+over the parameters of a hardware-efficient ansatz (HEA).
+
+```python
+import numpy as np
+import qusim_np
+
+# H = 0.3·II + 1.2·ZZ - 0.8·XI - 0.8·IX   (2 qubits)
+coeffs  = [0.3, 1.2, -0.8, -0.8]
+strings = ["II", "ZZ", "XI", "IX"]
+
+# Minimize <psi(theta)|H|psi(theta)> over a hardware-efficient ansatz
+res = qusim_np.vqe_optimize(2, layers=2,
+                         coefficients=coeffs, pauli_strings=strings)
+print(f"VQE energy:  {res.fun:.6f}")
+
+# Exact answer for comparison (dense diagonalization)
+H = qusim_np.hamiltonian(coeffs, strings)
+print(f"Exact:       {np.linalg.eigvalsh(H)[0]:.6f}")
+# -> VQE energy:  -1.700000   Exact:  -1.700000
+```
+
+### VQE building blocks
+
+```python
+# Pauli strings: "XZI", ("X","Z","I"), or index tuples (1,3,0) — all equivalent
+P = qusim_np.pauli_string_matrix("XZI")       # 8x8 matrix, 3 qubits
+
+# Expectation values WITHOUT building the 2^n x 2^n matrix
+qusim_np.pauli_string_expval(state, "ZZ")
+
+# Apply gates straight to state vectors (O(n·2^n), no big matrices)
+state = qusim_np.initialize_uniform_superposition(2)
+state = qusim_np.apply_single_qubit(state, qusim_np.gates.hadamard().matrix, 0)
+state = qusim_np.apply_two_qubit(state, qusim_np.gates.cnot().matrix, 0, 1)
+
+# Inspect the ansatz before optimizing
+theta = np.zeros(qusim_np.hea_param_count(2, layers=2))
+psi   = qusim_np.hea_state(2, theta, layers=2)
+```
+
+## Qubit convention
+
+Qubit 0 is the **most significant bit** of the basis-state index:
+
+$$|q_0 q_1 \dots q_{n-1}\rangle \;\longleftrightarrow\;
+\sum_{k=0}^{n-1} q_k\, 2^{\,n-1-k}$$
+
+A Pauli string `"XZI"` means X on qubit 0, Z on qubit 1, I on qubit 2 —
+same convention as Qiskit and most textbooks.
+
+## Project layout
+
+```
+qusim_np/
+├── config.py          # constants + Pauli matrices
+├── gates.py           # QuantumGate + gate constructors
+├── grover_search.py   # Hadamard transforms, oracle, diffusion, Grover
+├── deutsch_jozsa.py   # Deutsch-Jozsa algorithm
+├── qft.py             # QFT / inverse QFT
+└── vqe.py             # Pauli strings, Hamiltonians, HEA ansatz, VQE driver
+tests/                 # 178 tests
+```
+
+## Limitations
+
+Honest scope notes — this is a teaching/reference simulator:
+
+- **Dense state vectors**: memory is O(2ⁿ); practical limit ~15–20 qubits
+- **No noise model**: pure-state simulation only (no decoherence, no sampling noise)
+- **No circuit API**: you compose gates programmatically, not via a `QuantumCircuit` builder
+- **Classical only**: no real-device or cloud backend integration
+
+For production quantum computing, see [Qiskit](https://www.ibm.com/quantum/qiskit),
+[PennyLane](https://pennylane.ai/), or [Cirq](https://quantumai.google/cirq).
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest          # 178 tests, ~1s
+```
+
+Contributions welcome — see the test suite for conventions.
+
+## AI assistance
+
+Parts of this codebase were written with assistance from **SWE-2 by
+Cognition**, accessed through the **Devin** platform, for coding tasks
+such as implementing algorithms, tests, and documentation. All
+architectural and design decisions were made by the author.
+
+## License
+
+[MIT](LICENSE) © 2026 Furkan Nar

qusim_np-1.0/README.md

@@ -0,0 +1,178 @@
+# qusim-np
+
+**A minimal, readable quantum computing simulator in pure NumPy.**
+
+State-vector gates, textbook quantum algorithms, and a working
+Variational Quantum Eigensolver — in ~1,200 lines of well-documented,
+well-tested code. Built for learning, teaching, and prototyping.
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-178%20passing-brightgreen)](tests/)
+
+---
+
+## Features
+
+| Category | What you get |
+|---|---|
+| **Gates** | Pauli X/Y/Z, Hadamard, S, T, CNOT, SWAP, CZ, Toffoli, `rx`/`ry`/`rz` rotations |
+| **Algorithms** | Grover search, Deutsch–Jozsa, Quantum Fourier Transform |
+| **VQE** | Pauli-string Hamiltonians, hardware-efficient ansatz, `scipy` optimizer |
+| **Performance** | 1- and 2-qubit gates applied to state vectors in O(n·2ⁿ) — no dense 2ⁿ×2ⁿ matrices in the hot path |
+
+## Install
+
+```bash
+pip install qusim-np
+```
+
+From source:
+
+```bash
+git clone https://github.com/furkannar/qusim-np.git
+cd qusim-np
+pip install -e .
+```
+
+Requires Python ≥ 3.10, NumPy ≥ 2.0, SciPy ≥ 1.11.
+
+## Quick start
+
+```python
+import qusim_np
+
+# Grover's search — find state |101> among 8 possibilities
+state, k, p = qusim_np.grover_search(3, marked_states=[5])
+print(f"{k} iterations -> P(marked) = {p:.3f}")
+
+# Deutsch-Jozsa — constant or balanced with ONE query
+print(qusim_np.deutsch_jozsa_classify(3, lambda x: x % 2))   # 'balanced'
+
+# Quantum Fourier Transform
+F = qusim_np.qft_matrix(3)          # 8x8 unitary
+```
+
+### The math, briefly
+
+Grover's algorithm rotates the state vector in the plane spanned by the
+marked and unmarked subspaces. With $N = 2^n$ basis states and $M$ marked
+states, each iteration rotates by
+
+$$\theta = 2\arcsin\sqrt{\frac{M}{N}}, \qquad
+k_{\mathrm{opt}} \approx \frac{\pi}{4}\sqrt{\frac{N}{M}}$$
+
+so the marked states are amplified after $O(\sqrt{N/M})$ oracle queries.
+
+The Quantum Fourier Transform is the unitary
+
+$$F_{jk} = \frac{1}{\sqrt{N}}\,\omega^{jk}, \qquad
+\omega = e^{2\pi i / N}, \qquad j,k = 0,\dots,N-1$$
+
+## Variational Quantum Eigensolver
+
+The flagship feature: find the ground-state energy of a Hamiltonian
+written as a linear combination of Pauli strings,
+
+$$H = \sum_{i=0}^{m-1} \alpha_i P_i, \qquad
+P_i = \bigotimes_{k=0}^{n-1} \sigma_{i,k}, \qquad
+\sigma_{i,k} \in \{I, X, Y, Z\}$$
+
+by minimizing the variational energy
+
+$$E(\theta) = \langle \psi(\theta) \,|\, H \,|\, \psi(\theta) \rangle$$
+
+over the parameters of a hardware-efficient ansatz (HEA).
+
+```python
+import numpy as np
+import qusim_np
+
+# H = 0.3·II + 1.2·ZZ - 0.8·XI - 0.8·IX   (2 qubits)
+coeffs  = [0.3, 1.2, -0.8, -0.8]
+strings = ["II", "ZZ", "XI", "IX"]
+
+# Minimize <psi(theta)|H|psi(theta)> over a hardware-efficient ansatz
+res = qusim_np.vqe_optimize(2, layers=2,
+                         coefficients=coeffs, pauli_strings=strings)
+print(f"VQE energy:  {res.fun:.6f}")
+
+# Exact answer for comparison (dense diagonalization)
+H = qusim_np.hamiltonian(coeffs, strings)
+print(f"Exact:       {np.linalg.eigvalsh(H)[0]:.6f}")
+# -> VQE energy:  -1.700000   Exact:  -1.700000
+```
+
+### VQE building blocks
+
+```python
+# Pauli strings: "XZI", ("X","Z","I"), or index tuples (1,3,0) — all equivalent
+P = qusim_np.pauli_string_matrix("XZI")       # 8x8 matrix, 3 qubits
+
+# Expectation values WITHOUT building the 2^n x 2^n matrix
+qusim_np.pauli_string_expval(state, "ZZ")
+
+# Apply gates straight to state vectors (O(n·2^n), no big matrices)
+state = qusim_np.initialize_uniform_superposition(2)
+state = qusim_np.apply_single_qubit(state, qusim_np.gates.hadamard().matrix, 0)
+state = qusim_np.apply_two_qubit(state, qusim_np.gates.cnot().matrix, 0, 1)
+
+# Inspect the ansatz before optimizing
+theta = np.zeros(qusim_np.hea_param_count(2, layers=2))
+psi   = qusim_np.hea_state(2, theta, layers=2)
+```
+
+## Qubit convention
+
+Qubit 0 is the **most significant bit** of the basis-state index:
+
+$$|q_0 q_1 \dots q_{n-1}\rangle \;\longleftrightarrow\;
+\sum_{k=0}^{n-1} q_k\, 2^{\,n-1-k}$$
+
+A Pauli string `"XZI"` means X on qubit 0, Z on qubit 1, I on qubit 2 —
+same convention as Qiskit and most textbooks.
+
+## Project layout
+
+```
+qusim_np/
+├── config.py          # constants + Pauli matrices
+├── gates.py           # QuantumGate + gate constructors
+├── grover_search.py   # Hadamard transforms, oracle, diffusion, Grover
+├── deutsch_jozsa.py   # Deutsch-Jozsa algorithm
+├── qft.py             # QFT / inverse QFT
+└── vqe.py             # Pauli strings, Hamiltonians, HEA ansatz, VQE driver
+tests/                 # 178 tests
+```
+
+## Limitations
+
+Honest scope notes — this is a teaching/reference simulator:
+
+- **Dense state vectors**: memory is O(2ⁿ); practical limit ~15–20 qubits
+- **No noise model**: pure-state simulation only (no decoherence, no sampling noise)
+- **No circuit API**: you compose gates programmatically, not via a `QuantumCircuit` builder
+- **Classical only**: no real-device or cloud backend integration
+
+For production quantum computing, see [Qiskit](https://www.ibm.com/quantum/qiskit),
+[PennyLane](https://pennylane.ai/), or [Cirq](https://quantumai.google/cirq).
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest          # 178 tests, ~1s
+```
+
+Contributions welcome — see the test suite for conventions.
+
+## AI assistance
+
+Parts of this codebase were written with assistance from **SWE-2 by
+Cognition**, accessed through the **Devin** platform, for coding tasks
+such as implementing algorithms, tests, and documentation. All
+architectural and design decisions were made by the author.
+
+## License
+
+[MIT](LICENSE) © 2026 Furkan Nar

qusim_np-1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qusim-np"
+version = "1.0"
+description = "A minimal, readable quantum computing simulator: gates, state-vector algorithms, and VQE"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "Furkan Nar", email = "furkan_nar4185@outlook.com"},
+]
+keywords = ["quantum", "quantum-computing", "simulation", "vqe", "grover", "qft"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Education",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "numpy>=2.0.0",
+    "scipy>=1.11.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/furkannar/qusim-np"
+Repository = "https://github.com/furkannar/qusim-np"
+
+[tool.setuptools.packages.find]
+include = ["qusim_np*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

qusim_np-1.0/qusim_np/__init__.py

@@ -0,0 +1,40 @@
+"""Quantum computing engine: gates, state-vector simulation, and algorithms."""
+
+from qusim_np.config import QuantumConfig, config
+from qusim_np.gates import (
+    QuantumGate,
+    pauli_x, pauli_y, pauli_z, hadamard, phase_gate, t_gate,
+    identity, cnot, swap, controlled_phase, toffoli, rx, ry, rz,
+)
+from qusim_np.grover_search import (
+    hadamard_transform, hadamard_matrix_closed_form,
+    initialize_uniform_superposition, grover_oracle, diffusion_operator,
+    grover_iteration, calculate_theta, calculate_optimal_iterations,
+    grover_search,
+)
+from qusim_np.deutsch_jozsa import (
+    deutsch_jozsa_oracle, deutsch_jozsa, deutsch_jozsa_classify,
+)
+from qusim_np.qft import (
+    qft_matrix, inverse_qft_matrix, qft_state, inverse_qft_state,
+)
+from qusim_np.vqe import (
+    pauli_string_matrix, apply_single_qubit, apply_two_qubit,
+    apply_pauli_string, pauli_string_expval, hamiltonian, expectation_value,
+    hea_param_count, hea_state, vqe_energy, vqe_optimize,
+)
+
+__all__ = [
+    "QuantumConfig", "config", "QuantumGate",
+    "pauli_x", "pauli_y", "pauli_z", "hadamard", "phase_gate", "t_gate",
+    "identity", "cnot", "swap", "controlled_phase", "toffoli", "rx", "ry", "rz",
+    "hadamard_transform", "hadamard_matrix_closed_form",
+    "initialize_uniform_superposition", "grover_oracle", "diffusion_operator",
+    "grover_iteration", "calculate_theta", "calculate_optimal_iterations",
+    "grover_search",
+    "deutsch_jozsa_oracle", "deutsch_jozsa", "deutsch_jozsa_classify",
+    "qft_matrix", "inverse_qft_matrix", "qft_state", "inverse_qft_state",
+    "pauli_string_matrix", "apply_single_qubit", "apply_two_qubit",
+    "apply_pauli_string", "pauli_string_expval", "hamiltonian", "expectation_value",
+    "hea_param_count", "hea_state", "vqe_energy", "vqe_optimize",
+]

qusim_np-1.0/qusim_np/config.py

@@ -0,0 +1,46 @@
+r"""
+Quantum Computing Configuration
+
+This module contains constants and configuration values used across
+the quantum computing implementation.
+"""
+
+import numpy as np
+from dataclasses import dataclass
+
+
+@dataclass
+class QuantumConfig:
+    """Configuration constants for quantum computing implementation."""
+    
+    # Mathematical constants
+    SQRT_2: float = np.sqrt(2)
+    INV_SQRT_2: float = 1 / SQRT_2
+    
+    # Quantum gate constants
+    HADAMARD_SCALE: float = INV_SQRT_2
+    
+    # Grover's algorithm constants
+    # These will be computed dynamically based on n and M
+    # N = 2^n (total number of basis states)
+    # M = number of marked solutions
+    
+    # Rotation gate constants
+    # theta parameter for Rx, Ry, Rz gates
+    DEFAULT_ROTATION_ANGLE: float = np.pi / 4
+    
+    # SU(2) constraints
+    # Unitary: U^dagger * U = I
+    # Special Unitary: det(U) = 1
+    SU2_TOLERANCE: float = 1e-10
+
+
+# Global config instance
+config = QuantumConfig()
+
+
+# Single-qubit Pauli matrices (used by VQE Hamiltonians and Pauli strings)
+PAULI_I = np.array([[1, 0], [0, 1]], dtype=complex)
+PAULI_X = np.array([[0, 1], [1, 0]], dtype=complex)
+PAULI_Y = np.array([[0, -1j], [1j, 0]], dtype=complex)
+PAULI_Z = np.array([[1, 0], [0, -1]], dtype=complex)

qusim_np-1.0/qusim_np/deutsch_jozsa.py

@@ -0,0 +1,119 @@
+r"""
+qusim_np/deutsch_jozsa.py
+Deutsch-Jozsa Algorithm
+
+This module implements the Deutsch-Jozsa algorithm using the custom gates.
+
+Deutsch-Jozsa Algorithm:
+- Determines whether a function f: {0,1}^n -> {0,1} is constant or balanced
+  using a single quantum query (classically requires up to 2^{n-1} + 1 queries)
+- n-qubit Hadamard transform: H^{\otimes n}
+- Initial state: |s> = H^{\otimes n}|0>^{\otimes n} = (1/sqrt(N)) * sum_x |x>
+- Oracle O_f: O_f|x> = (-1)^{f(x)}|x> (phase kickback, no ancilla needed)
+- Final Hadamard transform: H^{\otimes n} again (H is self-inverse)
+- If f is constant: measurement yields |0^n> with probability 1
+- If f is balanced: amplitude of |0^n> is 0, so a nonzero outcome is certain
+- Amplitude of |y> after final transform:
+  A_y = (1/N) * sum_x (-1)^{f(x)} (-1)^{x \cdot y}  (Walsh-Hadamard transform)
+"""
+
+import numpy as np
+from qusim_np.grover_search import (
+    _validate_n, hadamard_transform, initialize_uniform_superposition
+)
+
+
+def _evaluate_f(f, N):
+    """
+    Evaluate f on all N basis states.
+
+    Args:
+        f: Callable f(x) -> bool/int, or a sequence of N bits
+        N: Number of basis states (2^n)
+
+    Returns:
+        list: f-values for x = 0..N-1 as 0/1 ints
+    """
+    if callable(f):
+        return [int(bool(f(x))) for x in range(N)]
+    values = list(f)
+    if len(values) != N:
+        raise ValueError(f"f sequence must have length {N}, got {len(values)}")
+    return [int(bool(v)) for v in values]
+
+
+def deutsch_jozsa_oracle(n, f):
+    r"""
+    Construct the Deutsch-Jozsa oracle O_f that encodes f as a phase.
+
+    O_f|x> = (-1)^{f(x)}|x>, where f(x) = 1 picks up a phase of -1.
+    This is a diagonal unitary: diag((-1)^{f(0)}, ..., (-1)^{f(N-1)}).
+
+    Args:
+        n: Number of qubits
+        f: Function to evaluate - either a callable f(x) -> bool/int
+           or a sequence of N = 2^n bits (f(0), f(1), ..., f(N-1))
+
+    Returns:
+        numpy.ndarray: The oracle matrix of shape (2^n, 2^n)
+    """
+    _validate_n(n)
+    N = 2 ** n
+    values = _evaluate_f(f, N)
+    phases = np.array([1 - 2 * v for v in values])  # +1 if f=0, -1 if f=1
+    return np.diag(phases).astype(complex)
+
+
+def deutsch_jozsa(n, f):
+    r"""
+    Run the Deutsch-Jozsa algorithm on function f.
+
+    Algorithm:
+    1. Initialize |s> = H^{\otimes n}|0^n>
+    2. Apply oracle: O_f|s>
+    3. Apply H^{\otimes n} again
+    4. Measure: |0^n> outcome implies f is constant
+
+    Args:
+        n: Number of qubits
+        f: Callable f(x) -> bool/int, or sequence of N = 2^n bits
+
+    Returns:
+        tuple: (final_state, zero_probability)
+            final_state: state vector of shape (2^n,)
+            zero_probability: probability of measuring |0^n>;
+                ~1.0 indicates constant, ~0.0 indicates balanced
+    """
+    _validate_n(n)
+
+    # Step 1: uniform superposition
+    state = initialize_uniform_superposition(n)
+
+    # Step 2: oracle phase kickback
+    O = deutsch_jozsa_oracle(n, f)
+    state = O @ state
+
+    # Step 3: Hadamard transform again (H^{\otimes n} is self-inverse)
+    H_n = hadamard_transform(n)
+    state = H_n @ state
+
+    # Step 4: probability of measuring |0...0>
+    zero_probability = abs(state[0]) ** 2
+
+    return state, zero_probability
+
+
+def deutsch_jozsa_classify(n, f, threshold=0.5):
+    r"""
+    Classify f as 'constant' or 'balanced' using the Deutsch-Jozsa algorithm.
+
+    Args:
+        n: Number of qubits
+        f: Callable f(x) -> bool/int, or sequence of N = 2^n bits
+        threshold: Decision boundary on P(|0^n>) (default 0.5)
+
+    Returns:
+        str: 'constant' if P(|0^n>) > threshold, else 'balanced'
+    """
+    _, p0 = deutsch_jozsa(n, f)
+    return "constant" if p0 > threshold else "balanced"