Metadata-Version: 2.4
Name: qkan-sim-lib
Version: 0.2.0
Summary: From-scratch statevector qubit simulator with a Quantum Kolmogorov-Arnold Network (QKAN) layer on top, split into 5 layered packages.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"

# Qkan-Sim-Lib

A from-scratch qubit simulation stack, split into five layers, topped by a
small **Quantum Kolmogorov-Arnold Network (QKAN)**. No Qiskit/PennyLane/Cirq
dependency — just NumPy for the linear algebra.

```
5. analysis          regression metrics, reports, and entanglement diagnostics
                      of a trained network
        |
4. qkan               QKANEdge -> QKANLayer -> QKANNetwork, trained via
                      parameter-shift gradients; Trainer built to run
                      longer than 24 hours with checkpoint/resume
        |
3. gates               gate library (H, X, RX/RY/RZ, CNOT, ...) and the
                      QuantumCircuit DSL (Param/Input-driven gate sequences)
        |
2. entanglement         the interaction mechanism: apply_operator lets qubits
                      affect each other; diagnostics measure how entangled
                      the result is (reduced density matrix, purity, entropy)
        |
1. qubit_simulator       raw n-qubit statevector: init, storage, readout
```

Each layer only depends on the ones below it, is its own top-level Python
package, and has its own README with the details:

- [`qubit_simulator/`](qubit_simulator/README.md) — layer 1
- [`entanglement/`](entanglement/README.md) — layer 2
- [`gates/`](gates/README.md) — layer 3
- [`qkan/`](qkan/README.md) — layer 4
- [`analysis/`](analysis/README.md) — layer 5

## Install

Requires Python >= 3.10.

```bash
pip install -e ".[dev]"   # numpy + pytest
```

## Run it

```bash
python main.py
```

This builds a small dataset (`y = sin(pi*x)`), trains a `[1, 4, 1]` QKAN
(2 qubits per edge) with `qkan.training.Trainer`, then hands the trained
network to the `analysis` layer for a text report (loss curve, MSE/MAE/R²,
predictions vs. targets) and a quantum diagnostic (how entangled each edge's
circuit actually gets across the dataset).

For a longer, checkpointed/resumable run:

```bash
python examples/train_small_qkan.py --max-epochs 0 --checkpoint runs/sin.pkl
# trains indefinitely; Ctrl+C (or kill) any time, rerun the same command to resume.
```

## Testing

Each layer owns its own `tests/` directory:

```bash
pytest -q
```

## Why split it this way

The boundary between layers 2 and 3 is the one worth explaining: layer 2
(`entanglement`) owns the *only* function that mutates a `QuantumState`'s
amplitudes (`apply_operator`) plus the diagnostics for measuring entanglement
(reduced density matrix, purity, von Neumann entropy). Layer 3 (`gates`) owns
gate *names* and a circuit-building DSL, but always calls back down into
`apply_operator` to actually run anything — it never touches state directly.
That split means "how do qubits interact" and "what gates exist" are
independently testable and independently replaceable, and it's what lets
layer 5 reach directly into layer 2 to ask "is this trained QKAN edge
actually using entanglement, or just behaving like a classical function in a
quantum costume?" (see `analysis/quantum_diagnostics.py`).
