Metadata-Version: 2.4
Name: photonics-helper
Version: 0.1.11
Summary: A comprehensive helper library for photonics and optics calculations
Author-email: Hitaishi V <hitaishi2222@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/hitaishi2222/photonics_helper
Project-URL: Documentation, https://hitaishi2222.github.io/photonics_helper/
Keywords: photonics,optics,wavelength,frequency,conversion
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: matplotlib>=3.10.3
Requires-Dist: numpy>=2.2.6
Requires-Dist: pydantic>=2.12.5
Requires-Dist: rich>=14.3.3
Requires-Dist: scipy>=1.15.3
Provides-Extra: plotting
Requires-Dist: plotly>=5.0; extra == "plotting"
Provides-Extra: webapp
Requires-Dist: dash>=2.18.0; extra == "webapp"
Provides-Extra: examples
Requires-Dist: tqdm>=4.66; extra == "examples"
Provides-Extra: extras
Requires-Dist: imageio>=2.33; extra == "extras"
Provides-Extra: pinns
Requires-Dist: torch>=2.0; extra == "pinns"
Provides-Extra: fftw
Requires-Dist: pyfftw>=0.15.1; extra == "fftw"
Provides-Extra: mode-export
Requires-Dist: femwell>=0.1.12; extra == "mode-export"
Requires-Dist: tidy3d>=2.12; extra == "mode-export"
Provides-Extra: docs
Requires-Dist: zensical>=0.0.60; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.26; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=9.0.2; extra == "dev"
Requires-Dist: mypy>=1.15.0; extra == "dev"
Requires-Dist: ruff>=0.11.0; extra == "dev"
Requires-Dist: pre-commit>=3.8.0; extra == "dev"
Requires-Dist: coverage>=7.0; extra == "dev"
Requires-Dist: tqdm>=4.66; extra == "dev"
Requires-Dist: hypothesis>=6.0; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.8.0; extra == "dev"
Requires-Dist: mpmath>=1.3.0; extra == "dev"
Provides-Extra: all
Requires-Dist: plotly>=5.0; extra == "all"
Requires-Dist: dash>=2.18.0; extra == "all"
Requires-Dist: tqdm>=4.66; extra == "all"
Requires-Dist: pyfftw>=0.15.1; extra == "all"
Requires-Dist: imageio>=2.33; extra == "all"
Dynamic: license-file

![Photonics Helper banner](docs/img/banner.png)

# Photonics Helper

<p>
  <img src="https://github.com/hitaishi2222/photonics_helper/actions/workflows/ci.yml/badge.svg" alt="CI"/>
  <img src="https://github.com/hitaishi2222/photonics_helper/actions/workflows/docs.yml/badge.svg" alt="Docs"/>
  <img src="https://img.shields.io/pypi/v/photonics-helper.svg" alt="PyPI"/>
  <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square"/>
  <img src="https://img.shields.io/badge/python-3.12+-3776AB?style=flat-square&logo=python&logoColor=3776AB"/>
</p>

A comprehensive helper library for photonics and optics calculations.

**Documentation:** <https://hitaishi2222.github.io/photonics_helper/>

---

## Installation

```bash
pip install photonics-helper
```

Optional extras: `fftw`, `plotting`, `webapp`, `extras`, `mode-export`, `pinns`.

---

## Key Features

- **Type Safety**: Full inline type hints (PEP 561 `py.typed`)
- **Unit Conversions**: Wavelength, frequency, angular frequency
- **Pulse Visualization**: Interactive 2D/3D pulse envelope plots
- **DBR Simulation**: Transfer Matrix Method for multilayer stacks
- **FROG**: SHG-FROG trace generation and PCGPA pulse retrieval
- **Raman Modeling**: Full Raman response physics for 40+ materials
- **GNLSE Engine**: Split-step Fourier solver for nonlinear propagation
- **Vector GNLSE**: Coupled two-polarization solver
- **Multimode GNLSE**: N coupled modal envelopes with inter-modal FWM
- **Inverse Design**: `fit_two_wave`, `design_efficiency`, `fit_shg_autodiff`
- **Breathers**: Exact analytic breather solutions
- **Solitons**: Soliton solutions and analysis
- **Noise**: Stochastic noise sources (ASE, Raman)
- **Validation**: Convergence studies and analytical checks

---

## Quick Start

```python
from photonics_helper import Wavelength

# Unit conversions
wl = Wavelength(1550, "nm")
freq = wl.to_freq()
omega = freq.to_omega()

print(f"λ = {wl.as_nm} nm")
print(f"f = {freq.as_THz} THz")
print(f"ω = {omega.as_rad_s:.4e} rad/s")
```

### GNLSE Propagation

Animated version of `examples/13_gnlse_soliton_evolution.py`: an N = 3 soliton
breathing and fissioning over one dispersion length.

```python
from photonics_helper import (
    Area,
    Length,
    Time,
    Wavelength,
    FiberProfile,
    GNLSESolver,
    Envelope,
    TemporalGrid,
    Wave,
)

import numpy as np
import matplotlib.pyplot as plt
from matplotlib import cm
from matplotlib.animation import FuncAnimation, PillowWriter

# Anomalous-dispersion fiber: β₂ = -2 ps²/km = -2e-3 ps²/m (engine units)
T0 = Time(200, "fs")
beta2 = -2.0e-3
n2, A_eff = 2.6e-20, Area(80, "um^2")
omega0 = Wavelength(1064, "nm").to_omega().as_rad_s
gamma = n2 * omega0 / (299792458.0 * A_eff.as_m2)

# N = 1 soliton power for these parameters; N = 3 needs 9x the power
P0_N1 = abs(beta2 * 1e-24) / (gamma * T0.as_s**2)
L_D = Length(T0.as_s**2 / abs(beta2 * 1e-24), "m")

grid = TemporalGrid(N=2**11, Tmax=Time(5 * T0.as_fs * 1e-15, "s"))
pulse = Wave(
    grid=grid,
    envelope=Envelope(shape="sech", peak_amplitude=np.sqrt(9 * P0_N1), pulse_width=T0),
    central_wavelength=Wavelength(1064, "nm"),
).with_effective_area(A_eff)

solver = GNLSESolver(
    pulse=pulse,
    fiber=Fiber(n2=n2, alpha=0.0, A_eff=A_eff, length=L_D),
    betas=np.array([beta2]),  # [β₂, β₃, ...] in psᵏ/m
    include_raman=False,
    include_self_steepening=False,
)
solver.propagate(num_steps=100, show_progress=True)  # tqdm bar over z

# Animate: temporal-envelope waterfall + peak-power trace growing with z
t_ps = grid.t * 1e12
z_m = solver.z_array
peak = np.array(
    [float(np.max(np.abs(w.envelope_field)) ** 2) for w in solver.evolution]
)
colors = cm.viridis(np.linspace(0, 1, len(solver.evolution)))

OFF = 0.22  # vertical spacing between waterfall traces
fig, (ax_t, ax_p) = plt.subplots(1, 2, figsize=(12, 4.5), constrained_layout=True)
ax_t.set(
    xlim=(-0.5, 0.5),
    ylim=(-0.1, OFF * len(solver.evolution) + 1.15),
    xlabel="Time (ps)",
    ylabel="Propagation distance (m)",
    title="Temporal envelope (waterfall)",
)
ax_p.set(
    xlim=(0, z_m[-1]),
    ylim=(0, peak.max() * 1.15),
    xlabel="Propagation distance (m)",
    ylabel="Peak power (W)",
    title="Peak power oscillates (N = 3 soliton)",
)
for ax in (ax_t, ax_p):
    ax.grid(alpha=0.3)

(z_line,) = ax_p.plot([], [], color="crimson", lw=2.2)
(marker,) = ax_p.plot([], [], "o", color="crimson", ms=7)
label = ax_p.text(
    0.03, 0.92, "", transform=ax_p.transAxes, fontsize=11, family="monospace", va="top"
)


def draw(k):
    for j in range(k + 1):
        a = np.abs(solver.evolution[j].envelope_field)
        base = j * OFF
        # Filled bands, not thin lines: each trace fills its own slot, so the
        # stack has no white gaps between traces.
        ax_t.fill_between(
            t_ps, base, a / a.max() * OFF * 0.98 + base, color=colors[j], lw=0
        )
    ticks = np.arange(0, len(solver.evolution) * OFF, 10 * OFF)
    ax_t.set_yticks(ticks)
    ax_t.set_yticklabels([f"{z_m[int(v / OFF)]:.0f}" for v in ticks])
    z_line.set_data(z_m[: k + 1], peak[: k + 1])
    marker.set_data([z_m[k]], [peak[k]])
    label.set_text(f"z = {z_m[k]:5.2f} / {z_m[-1]:.1f} m")
    return z_line, marker, label


anim = FuncAnimation(fig, draw, frames=len(solver.evolution), interval=100)
anim.save("soliton_fission.gif", writer=PillowWriter(fps=12), dpi=95)
```

Output:

![N = 3 soliton breathing and fission](docs/img/quickstart_gnlse.gif)

---

## Examples

See `examples/` for 45 runnable examples covering:

- Pulse visualization and FROG
- Raman response and material comparison
- GNLSE propagation (basic, soliton, Raman, steepening, TPA)
- Breather families and wave breaking
- Vector polarization and multimode GNLSE
- Noise, ASE, and Raman thermal floor
- Inverse design (QPM, FWM, autodiff)
- Material catalog query

---

## Reproductions

See `reproductions/` for literature reproductions (27 papers reproduced).

---

## Material Database

The SQLite material database (`materials.db`) ships with 45 materials,
41 Sellmeier equations, and 30 tabulated n/k datasets.
All 30 source keys are loadable through `RefractiveIndex.from_material_database`.

---

## Testing

```bash
python -m pytest tests/
```

---

## License

MIT
