Metadata-Version: 2.4
Name: qse-quantum
Version: 2.1.0
Summary: Analytical von Neumann entropy for CNOT-based quantum circuits via Walsh-Hadamard transforms
Author-email: Özgür Özer <ozgurozer@example.com>
Maintainer-email: Özgür Özer <ozgurozer@example.com>
License: MIT
Project-URL: Homepage, https://github.com/Ozgurooozer/qse
Project-URL: Documentation, https://github.com/Ozgurooozer/qse#readme
Project-URL: Repository, https://github.com/Ozgurooozer/qse.git
Project-URL: Issues, https://github.com/Ozgurooozer/qse/issues
Project-URL: Changelog, https://github.com/Ozgurooozer/qse/blob/main/CHANGELOG.md
Keywords: quantum,quantum-computing,von-neumann-entropy,entanglement,cnot,walsh-hadamard,quantum-information,quantum-circuits
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Quantum Computing
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: qiskit>=1.0.0; extra == "dev"
Requires-Dist: jupyter>=1.0.0; extra == "dev"
Requires-Dist: matplotlib>=3.7.0; extra == "dev"
Provides-Extra: qiskit
Requires-Dist: qiskit>=1.0.0; extra == "qiskit"
Provides-Extra: mitiq
Requires-Dist: mitiq>=0.30.0; extra == "mitiq"
Provides-Extra: all
Requires-Dist: qse-quantum[dev,mitiq,qiskit]; extra == "all"
Dynamic: license-file

# QSE — Quantum Stabilizer Entropy

[![Tests](https://img.shields.io/badge/tests-7%2C000%2B%20passing-brightgreen)]()
[![Python](https://img.shields.io/badge/python-3.9%2B-blue)]()
[![License](https://img.shields.io/badge/license-MIT-green)]()
[![arXiv](https://img.shields.io/badge/arXiv-2026.xxxxx-red)]()

**Analytical von Neumann entropy for CNOT-based quantum circuits.**

QSE provides closed-form entropy formulas using Walsh-Hadamard transforms and F₂ linear algebra — **no state-vector simulation required**.

---

## Why QSE?

Computing von Neumann entropy typically requires exponential-cost simulation. QSE bypasses this with mathematical formulas:

| Approach | Complexity | Accuracy |
|----------|------------|----------|
| State-vector simulation | O(2^N) | Exact |
| **QSE (T14 formula)** | O(4^N_B · N_A) | **Exact** |

For large circuits where N_B is small, QSE is exponentially faster while remaining mathematically exact.

---

## Features

- **17 Proven Theorems** — Mathematically verified
- **7,000+ Tests** — All passing at machine precision (err < 10⁻¹³)
- **Hardware Validated** — IBM ibm_fez: η = 0.844 ± 0.003
- **Minimal Dependencies** — NumPy only
- **Open Source** — MIT License

---

## Installation

```bash
pip install qse
```

Or from source:

```bash
git clone https://github.com/Ozgurooozer/qse
cd qse
pip install -e .
```

---

## Quick Start

### Basic Usage

```python
import numpy as np
from qse import t14_formula, f2_rank

# Define circuit parameters
thetas = [np.pi/3, np.pi/4]  # Rotation angles on A qubits
M = np.array([[1, 0],         # CNOT connectivity matrix
              [0, 1]])

# Compute von Neumann entropy analytically
S = t14_formula(thetas, M)
print(f"S(B) = {S:.6f} bits")

# Get upper bound from F₂ rank
rank = f2_rank(M)
print(f"Upper bound: S(B) ≤ {rank} bits")
```

### Multi-Layer Circuits

```python
from qse import multilayer_vne

# Multiple CNOT layers
M1 = np.array([[1, 0, 1]])
M2 = np.array([[0, 1, 1]])
thetas = [0.5, 1.0, 1.5]

# XOR composition: M_eff = M1 ⊕ M2
S = multilayer_vne(thetas, M1, M2)
```

### Gate-Specific Entropy

```python
from qse import iswap_vne, fsim_vne

# iSWAP gate: B=|0⟩ always gives VNE=0 (separable output)
S_iswap = iswap_vne(alpha=np.pi/4, b_init="0")  # Returns 0.0

# fSim gate
S_fsim = fsim_vne(alpha=0.5, theta=0.3)
```

---

## Core Theorems

| Theorem | Statement | Status |
|---------|-----------|--------|
| **T14** | Walsh-Hadamard closed-form entropy formula | ✓ Proven |
| **T-RANK** | S(B) ≤ rank_F₂(M) for all θ | ✓ Proven |
| **T-OPT** | S(B) = rank_F₂(M) at θ = π/2 | ✓ Proven |
| **T15A** | Multi-layer: M_eff = M₁ ⊕ M₂ ⊕ ... ⊕ Mₖ | ✓ Proven |
| **T-NOISE** | Noise-decircuit separability | ✓ Proven |

See [Documentation](docs/01_QSE_Teorem_Ailesi.md) for complete theorem list.

---

## Mathematical Foundation

### T14: Main Formula

For a quantum circuit with:
- A subsystem: A = ⊗ᵢ Rₓ(θᵢ)|0⟩
- B subsystem: B = |0⟩^N_B
- CNOT connectivity: M ∈ F₂^(N_B × N_A)

The von Neumann entropy of B is:

```
S(B) = H({p_b})

p_b = (1/2^N_B) · Σ_s (-1)^(b·s) · Φ_M(s)

Φ_M(s) = ∏_{i : [M^T s]_i = 1} cos(θᵢ)
```

This is **exact** and requires no simulation.

---

## API Reference

### Core Functions

| Function | Description |
|----------|-------------|
| `t14_formula(thetas, M)` | Compute S(B) via T14 formula |
| `t14_statevector(thetas, M)` | Compute S(B) via simulation (reference) |
| `f2_rank(M)` | Compute rank over GF(2) |
| `shannon(p)` | Shannon entropy H(p) |

### Layer Functions

| Function | Description |
|----------|-------------|
| `effective_matrix(*matrices)` | XOR composition of M matrices |
| `multilayer_vne(thetas, *matrices)` | Entropy for multi-layer circuits |

### Gate Functions

| Function | Description |
|----------|-------------|
| `cz_vne(thetas, M)` | Entropy for CZ gates (Google native) |
| `iswap_vne(alpha, b_init)` | Entropy for iSWAP gate |
| `fsim_vne(alpha, theta, phi)` | Entropy for fSim gate |

---

## Verification

### Run Tests

```bash
# Quick verification (~10 seconds)
python quick_proofs.py

# Full test suite
pytest tests/ -v
```

### Expected Output

```
================================================================
  QSE Quick Proof Verification
================================================================

[T14]  Walsh-Hadamard formula
  ✓ PASS  T14 formula vs state-vector             max_err=1.02e-13

[T-RANK]  S(B) ≤ rank_F₂(M)
  ✓ PASS  VNE ≤ rank_F₂(M)                        violations=0/200

...

  12/12 proof tests passed
  All algebraic and numerical proofs verified.
```

---

## Integration

### Qiskit

```python
from qiskit import QuantumCircuit
import numpy as np
from qse import t14_formula

# Build circuit
qc = QuantumCircuit(4)
qc.rx(np.pi/3, 0)
qc.rx(np.pi/4, 1)
qc.cnot(0, 2)
qc.cnot(1, 3)

# Extract M matrix from circuit
M = np.array([[1, 0], [0, 1]])
thetas = [np.pi/3, np.pi/4]

# Compute entropy
S = t14_formula(thetas, M)
```

### Mitiq (Planned)

```python
from mitiq import QPROGRAM
from qse.mitiq import qse_error_estimate

# Estimate error using QSE entropy formulas
error_bound = qse_error_estimate(circuit, noise_level=0.01)
```

---

## Citation

If you use QSE in your research, please cite:

```bibtex
@article{qse2026,
  title={Quantum Stabilizer Entropy: Analytic von Neumann Entropy 
         for CNOT-Based Circuits via Walsh-Hadamard Transforms 
         and F₂ Linear Algebra},
  author={Özer, Özgür},
  journal={arXiv preprint arXiv:2026.xxxxx},
  year={2026}
}
```

---

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Development Setup

```bash
git clone https://github.com/Ozgurooozer/qse
cd qse
pip install -e ".[dev]"
pytest tests/ -v
```

---

## License

MIT License — see [LICENSE](LICENSE) for details.

---

## Acknowledgments

- IBM Quantum for hardware access (ibm_fez)
- Unitary Foundation for open-source quantum ecosystem support

---

## Contact

- **GitHub**: [https://github.com/Ozgurooozer/qse](https://github.com/Ozgurooozer/qse)
- **Issues**: [https://github.com/Ozgurooozer/qse/issues](https://github.com/Ozgurooozer/qse/issues)

---

*QSE — Making quantum entropy computation fast and exact.*
