Metadata-Version: 2.4
Name: microringlib
Version: 1.0.0
Summary: Physics-first photonic microring resonator simulation library with material-dispersion backends
Author-email: Elbek J Keskinoglu <ejkeskinoglu@connect.ust.hk>
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.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Requires-Dist: scipy>=1.9
Requires-Dist: matplotlib>=3.6
Provides-Extra: materials
Requires-Dist: refractiveindex>=0.0.7; extra == "materials"
Requires-Dist: PyOptik>=1.0.0; extra == "materials"
Dynamic: license-file

# microringlib

**microringlib** is a physics-first Python library for integrated-photonics waveguides and microring resonators. It includes linear ring/waveguide simulation, material-dispersion backends, resonance metrics, reduced nonlinear Kerr models, and reduced quantum/SFWM utilities.

Author: **Elbek J Keskinoglu**  
Email: **ejkeskinoglu@connect.ust.hk**  
License: MIT

## Features

- Straight waveguide transmission
- Single-bus microring resonators
- Add-drop microring resonators
- Cascaded / multi-ring add-drop filters
- Unitary coupler construction from power coupling `K`
- Passive power-budget checks for add-drop systems
- Resonance metrics: FWHM, FSR / peak spacing, loaded Q, finesse, extinction ratio
- Resonance-order tracking across sweeps such as thermal tuning
- Material backends: constant, tabulated, functional, optional refractiveindex.info adapter, optional PyOptik adapter
- Reduced Kerr bistability helpers in `microringlib.nonlinear`
- Reduced SFWM / photon-pair helpers in `microringlib.quantum`

## Installation

```bash
pip install microringlib
```

For local development:

```bash
pip install -e .
```

Optional material database adapters:

```bash
pip install -e ".[materials]"
```

The optional `refractiveindex` and `PyOptik` dependencies are imported lazily only when their material adapters are used.

## Quick start

```python
import numpy as np
import microringlib as mrl

wl = np.linspace(1520e-9, 1580e-9, 20001)

layers = [
    mrl.Layer(material="SiO2 lower", thickness=2e-6, n=1.444, alpha=0),
    mrl.Layer(material="Si core", thickness=220e-9, n=3.476,
              dn_dT=1.86e-4, alpha=mrl.Layer.dbcm_to_npm(2.0)),
    mrl.Layer(material="SiO2 upper", thickness=2e-6, n=1.444, alpha=0),
]

ring = mrl.RingGeometry(radius=10e-6)
c = mrl.Coupler.from_power_coupling(0.01)

res = mrl.single_mrr_thru(
    wavelengths=wl,
    resonator=ring,
    layers=layers,
    t=c.t,
    kappa=c.kappa,
    polarization="TE",
)

metrics = mrl.compute_resonance_metrics(wl, res.power, target_wavelength=1550e-9)
print(metrics["resonance_wavelength"] * 1e9, "nm")
print(metrics["loaded_Q"])
```

## Material backends

```python
si = mrl.ConstantMaterial("Si", n=3.476, k=0.0, dn_dT=1.86e-4)
sio2 = mrl.ConstantMaterial("SiO2", n=1.444, k=0.0, dn_dT=1.0e-5)

layers = [
    mrl.Layer("SiO2 lower", 2e-6, material_model=sio2),
    mrl.Layer("Si core", 220e-9, material_model=si, alpha=mrl.Layer.dbcm_to_npm(2.0)),
    mrl.Layer("SiO2 upper", 2e-6, material_model=sio2),
]
```

Material absorption can be represented with extinction coefficient `k`, using the power absorption convention `alpha = 4*pi*k/lambda`, plus any additional `Layer.alpha` loss.

## Reduced nonlinear and quantum models

`microringlib.nonlinear` contains reduced single-mode Kerr cavity helpers for qualitative bistability studies. These are **not** full Lugiato-Lefever equation or Maxwell solvers.

`microringlib.quantum` contains reduced SFWM / photon-pair scaling and toy JSA helpers. These are **not** calibrated full quantum coupled-mode simulations.

## Development

Run tests:

```bash
pytest -q
```

Build package:

```bash
python -m build
```

Upload to PyPI:

```bash
twine upload dist/*
```
