Metadata-Version: 2.4
Name: strelka-fdtd
Version: 0.1.0
Summary: Fastest open-source differentiable photonic optimizer. JAX-accelerated 2D FDTD with free adjoint gradients.
Author: Pushinka
License: Apache-2.0
Project-URL: Homepage, https://github.com/venticedcappuccino/strelka-fdtd
Project-URL: Documentation, https://github.com/venticedcappuccino/strelka-fdtd#readme
Project-URL: Issues, https://github.com/venticedcappuccino/strelka-fdtd/issues
Keywords: photonics,fdtd,inverse-design,jax,silicon-photonics,adjoint,optimization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jax>=0.4.0
Requires-Dist: jaxlib>=0.4.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.10.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"
Provides-Extra: full
Requires-Dist: gdstk; extra == "full"
Requires-Dist: scikit-learn; extra == "full"
Requires-Dist: optax; extra == "full"
Dynamic: license-file

# Strelka

**Fastest open-source differentiable photonic optimizer.**

JAX-accelerated 2D FDTD with free adjoint gradients. Designed for inverse design of photonic neural network chips.

## Key Numbers

| Metric | Value |
|--------|-------|
| Speed vs Meep | **85× faster** (single-threaded) |
| Gradient method | `jax.grad` — free adjoint, no separate sim |
| Largest demonstrated | **64×64 matrix** (240K DOF, 28 min on M2) |
| Platform | Apple Silicon, x86, any JAX backend |
| License | Apache 2.0 |

## Install

```bash
pip install strelka-fdtd
```

## Quick Start

### Python API

```python
from strelka import optimize, simulate

# Design an 8-port photonic matrix multiplier
result = optimize(n_ports=8, design_um=14.0, resolution=10)
# → Topology optimized in ~10 seconds

# Simulate a topology
sim = simulate(result['rho'], n_ports=8)
print(f"Output power: {sim['total_power']:.4f}")
```

### CLI

```bash
# Optimize
strelka optimize --ports 8 --res 10

# Full 64×64 (takes ~30 min on M2)
strelka optimize --ports 64 --res 5 --iters 50

# Benchmark your machine
strelka benchmark

# Decompose a weight matrix into photonic blocks
strelka decompose weights.npy --block-size 8
```

### Block Clements Cascade

Decompose any N×N matrix into 8×8 monolithic photonic blocks:

```python
from strelka.cascade import GivensBlockCascade
import numpy as np

W = np.random.randn(64, 64)  # your weight matrix
gbc = GivensBlockCascade(N=64, block_size=8)
result = gbc.inference(W)

print(f"Reconstruction error: {result['reconstruction_error']:.2e}")
print(f"Devices: {result['total_devices']} (vs {result['clements_mzis']} Clements MZIs)")
# → error: ~1e-15, 4× fewer devices
```

## How It Works

1. **FDTD Simulation**: Full-wave electromagnetic simulation of 2D photonic structures
2. **JAX Autodiff**: `jax.grad` computes the gradient of transmission w.r.t. every pixel — no separate adjoint simulation
3. **Adam Optimizer**: Gradient ascent with sigmoid binarization schedule
4. **Block Clements**: Exact decomposition of large matrices into small monolithic blocks

## Architecture

```
Your weight matrix (64×64)
    ↓ SVD
U (64×64 unitary) + Σ (diagonal) + V* (64×64 unitary)
    ↓ GivensBlockCascade
8×8 monolithic blocks + cross-block couplers
    ↓ strelka optimize
Foundry-ready GDS for each block
```

## Benchmarks

On Apple M2 (8-core, 16GB):

| Design | Grid | DOF | Time/iter | Full optimization |
|--------|------|-----|-----------|-------------------|
| 2-port | 124×124 | 3,600 | 0.6s | 6s |
| 8-port | 196×196 | 19,600 | 0.4s | 8s |
| 64-port | 538×538 | 240,100 | 0.9s | 28 min |

## Citing

If you use Strelka in your research, please cite:

```
Pushinka, "strelka-fdtd: Fastest open-source differentiable photonic optimizer," 2026.
https://github.com/venticedcappuccino/strelka-fdtd
```

## Contributing

We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

Founding contributors receive named credit and priority access to paid work.

## License

Apache 2.0
