Metadata-Version: 2.4
Name: photokan
Version: 0.2.0
Summary: Photonic KAN: Bridging PyTorch, KAN, and Q.ANT photonic hardware
Author-email: Koneti <koneti@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://photokan.dev
Project-URL: Repository, https://github.com/koneti/photokan
Keywords: photonic,kan,kolmogorov-arnold,pytorch,neuromorphic,optical
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
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 :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.1.0
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: sympy>=1.12
Requires-Dist: matplotlib>=3.7
Provides-Extra: qpal
Requires-Dist: qpal; extra == "qpal"
Provides-Extra: llm
Requires-Dist: transformers>=4.40; extra == "llm"
Requires-Dist: peft; extra == "llm"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# PhotoKAN

**Photonic Kolmogorov-Arnold Networks** — bridging PyTorch · KAN · Q.ANT photonic hardware.

[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
[![PyTorch](https://img.shields.io/badge/pytorch-2.1%2B-orange)](https://pytorch.org)
[![Status](https://img.shields.io/badge/status-pre--alpha-red)](https://github.com)

> **Phase 1** (CPU simulation) is fully functional. Q.PAL/NPU integration ships in Phase 2.

---

## Why PhotoKAN?

Standard MLPs use fixed activations on *nodes* and linear weights on *edges*.  
KANs invert this: **learnable nonlinear functions sit on the edges**, summed at nodes.

Photonic hardware is physically structured around edge-level nonlinear transforms —
light through a waveguide produces exactly the kind of parametric nonlinear function
a KAN edge needs. This is not an analogy; it is a direct structural match.

Published benchmarks show:
- **43% fewer parameters** vs equivalent MLPs
- **46% fewer operations** vs equivalent MLPs
- **30× energy efficiency** gain on Q.ANT NPU vs CMOS

---

## Installation

```bash
pip install photokan          # CPU simulation (no hardware required)
pip install photokan[qpal]    # + Q.ANT NPU support
pip install photokan[llm]     # + HuggingFace integration (Phase 3)
pip install photokan[dev]     # + development tools
```

---

## Quick Start

```python
import torch
import photokan as pk

# Works on CPU sim if no NPU — no code changes needed
model = pk.PhotoKAN(
    layer_sizes=[4, 16, 16, 1],
    activation='sine',   # 'sine' | 'fourier' | 'spline' | 'relu'
    backend='auto',      # auto-detects NPU, falls back to CPU
)

x = torch.randn(32, 4)
y = model(x)

# Standard PyTorch training
optimizer = torch.optim.Adam(model.parameters(), lr=1e-3)
loss = torch.nn.MSELoss()(y, torch.randn(32, 1))
loss.backward()
optimizer.step()

# Check what hardware is available
print(pk.available_backends())
# → {'cpu': True, 'cuda': True, 'qpal': False}
```

---

## Activation Variants

| Name | Formula | Best for | Photonic native |
|------|---------|----------|-----------------|
| `sine` | `Σ w·sin(f·x + p)` | Periodic targets, photonic deployment | ✅ |
| `fourier` | `a₀ + Σ [a·cos + b·sin]` | Multi-frequency signals | ✅ |
| `spline` | B-spline basis | Non-periodic, high precision | Via LUT |
| `relu` | `Σ w·ReLU(a·x + b)` | Edge inference, speed | ✅ |

---

## Photonic Noise Simulation

Test accuracy against realistic hardware impairments before deploying to NPU:

```python
sim = pk.PhotonicSimulator()
sim.set_hardware_profile('npu2')   # SNR=16dB, 8-bit

results = sim.sweep_snr(model, x_test, y_test,
                         snr_range=[8, 10, 12, 14, 16, 20])
sim.plot_snr_accuracy(results)
```

---

## Architecture

```
User PyTorch model
    └── PhotoKAN / PhotoKANLayer   (nn.Module, drop-in)
            └── EdgeActivations    (sine / fourier / spline / relu)
                    └── QPALFunction (torch.autograd.Function)
                            ├── QPALBackend  → Q.ANT NPU via Q.PAL
                            └── SimBackend   → CPU physics simulation
```

---

## Project Status

| Phase | Features | Status |
|-------|----------|--------|
| **Phase 1** | Activations, SimBackend, Layers, Utils | ✅ Complete |
| **Phase 2** | Q.PAL integration, QPALBackend, gradient tests | 🔜 Months 4–6 |
| **Phase 3** | AOT compiler, LLM integration, arXiv paper | 🔜 Months 7–12 |

---

## Running Tests

```bash
pip install -e ".[dev]"
pytest                          # fast tests only
pytest -m slow                  # include convergence tests
pytest --cov=photokan           # with coverage
```

---

## References

- Liu et al. (2024) — KAN: Kolmogorov-Arnold Networks
- Peng et al. (2024) — Photonic KAN via RAMZI (98% MNIST, 65× energy-area reduction)
- Reinhardt et al. (2024) — SineKAN
- Q.ANT NPU — https://qant.com/photonic-computing/

---

*PhotoKAN v0.1 — Build the bridge. Light does the math.*
