Metadata-Version: 2.4
Name: microringlib
Version: 0.1.0
Summary: Lightweight photonic microring resonator simulation library
Author-email: Elbek J Keskinoglu <elbekjk@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/elbekjk/microringlib
Project-URL: Repository, https://github.com/elbekjk/microringlib
Keywords: photonics,microring,waveguide,optics,simulation
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.22
Requires-Dist: scipy>=1.9
Requires-Dist: matplotlib>=3.6

# microringlib

**microringlib** is a lightweight Python library for simulating photonic waveguides and microring resonators.
It provides fast mode solving, transmission modeling, and resonance analysis in a simple, NumPy-based workflow.

---

## ✨ Features

* 📐 Waveguide mode solver (TE / TM)
* 🔁 Microring resonator (MRR) simulation:

  * Through port
  * Add-drop configuration
* 📉 Transmission spectra computation
* 📊 Resonance metrics (FSR, extinction ratio, etc.)
* 🔬 Layer-based material modeling (temperature + loss)
* 📈 Built-in plotting utilities

---

## 📦 Installation

```bash
pip install microringlib
```

---

## 🚀 Quick Start

### Waveguide transmission

```python
import numpy as np
from microringlib import Layer, single_waveguide

# Define stack (cladding–core–cladding)
layers = [
    Layer("silica", 2e-6, 1.45),
    Layer("silicon", 220e-9, 3.48),
    Layer("silica", 2e-6, 1.45),
]

wl = np.linspace(1540e-9, 1560e-9, 200)

result = single_waveguide(
    wl,
    layers,
    T=25.0,
    polarization="TE",
    length=50e-6,
)

print(result.power)
```

---

### Microring resonator (through port)

```python
from microringlib import RingGeometry, single_mrr_thru

ring = RingGeometry(kind="circular", radius=10e-6)

out = single_mrr_thru(
    wl,
    ring,
    layers,
    T=25.0,
    polarization="TE",
    t=0.9,
)

print(out.power)
```

---

### Add-drop microring

```python
import numpy as np
from microringlib import single_mrr_add_drop

kappa = np.sqrt(1 - 0.9**2)

out = single_mrr_add_drop(
    wl,
    ring,
    layers,
    T=25.0,
    polarization="TE",
    t1=0.9,
    kappa1=kappa,
)

through, drop = out.power
```

---

### Plot transmission

```python
from microringlib import plot_transmission

plot_transmission(wl, out.power, labels=["Through"])
```

---

### Mode solving

```python
from microringlib import solve_waveguide_modes

mode = solve_waveguide_modes(
    1550e-9,
    layers,
    T=25.0,
    polarization="TE",
    num_modes=1,
)

print(mode.n_eff)
```

---

## 📊 Resonance metrics

```python
from microringlib import compute_resonance_metrics

metrics = compute_resonance_metrics(wl, out.power)

print(metrics["fsr"])
print(metrics["min_transmission"])
```

---

## 🧠 Core Concepts

### Layers

Each waveguide is defined as a stack of layers:

```python
Layer(name, thickness, refractive_index, dn_dT=0.0, alpha=0.0)
```

* `dn_dT`: thermo-optic coefficient
* `alpha`: propagation loss

---

### Ring Geometry

```python
RingGeometry(kind="circular", radius=10e-6)
```

Supported:

* `"circular"`
* `"racetrack"`
* `"elliptical"`

---

### Coupling

Microring coupling is defined by:

* `t`: transmission coefficient
* `kappa`: coupling coefficient

They must satisfy:

```
t² + κ² = 1
```

---

## ⚠️ Input Validation

The library checks for:

* Negative wavelengths ❌
* Invalid coupling coefficients ❌
* Negative waveguide lengths ❌
* Empty layer stacks ❌

---

## 🧪 Testing

Run the standalone validation:

```bash
python test_microringlib_standalone.py
```

---

## 📚 Use Cases

* Silicon photonics design
* Optical filter simulation
* Teaching integrated optics
* Rapid prototyping of resonator systems

---

## 🛠️ Development

Clone the repo:

```bash
git clone https://github.com/YOUR_USERNAME/microringlib.git
cd microringlib
pip install -e .
```

---

## 📄 License

MIT License

---

## 🤝 Contributing

Pull requests are welcome. For major changes, please open an issue first.

---

## ⭐ Citation

If you use this library in research, please consider citing or linking the repository.

---

## 🔗 Links

* GitHub: https://github.com/elbekjk/microringlib
* PyPI: https://pypi.org/project/microringlib/
