Metadata-Version: 2.5
Name: lightsmith
Version: 0.1.0
Summary: Open photonics suite: one typed JSON problem spec solved by Mie, T-matrix, DDA, FDTD, TMM, RCWA, FDE, EME, FDFD, PWE and circuit solvers on CPU or GPU, with differentiable inverse design, built for humans and AI agents.
Project-URL: Homepage, https://lightsmith-photonics.github.io/lightsmith/
Project-URL: Documentation, https://lightsmith-photonics.github.io/lightsmith/
Project-URL: Repository, https://github.com/lightsmith-photonics/lightsmith
Project-URL: Issues, https://github.com/lightsmith-photonics/lightsmith/issues
Project-URL: Changelog, https://github.com/lightsmith-photonics/lightsmith/blob/main/CHANGELOG.md
Author-email: Alexander Feghali <alexander.al-feghali@mail.mcgill.ca>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,dda,electromagnetics,eme,fdfd,fdtd,gpu,inverse-design,mcp,mie,nanophotonics,photonic-circuit,photonic-crystal,photonics,plasmonics,rcwa,scattering,t-matrix,tmm,waveguide
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: array-api-compat>=1.11
Requires-Dist: miepython>=3.0
Requires-Dist: numpy>=2.0
Requires-Dist: pydantic>=2.6
Requires-Dist: scipy>=1.10
Provides-Extra: gpu
Requires-Dist: torch>=2.7; extra == 'gpu'
Provides-Extra: layout
Requires-Dist: gdsfactory>=9; (python_version >= '3.11') and extra == 'layout'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.2; extra == 'mcp'
Provides-Extra: tmatrix
Requires-Dist: treams<0.5,>=0.4.7; (python_version < '3.14') and extra == 'tmatrix'
Provides-Extra: xarray
Requires-Dist: xarray>=2024.1; extra == 'xarray'
Description-Content-Type: text/markdown

# Lightsmith

**The open photonics suite — GPU-native, differentiable, and built for AI agents.**

Describe a photonics problem once, as typed JSON, and solve it with the method that fits: from nanoparticles and thin films to metasurfaces, waveguides, photonic crystals, devices and circuits. Every result comes back in the same units and conventions, with provenance, so methods can be cross-checked directly. Many solvers run on GPU and can be differentiated, which is what powers inverse design.

Documentation: <https://lightsmith-photonics.github.io/lightsmith/>

> Status: pre-alpha (v0.1). Validation numbers for every solver are in `tests/` and in the technical report (`lightsmith-paper` repository).

## Install

```bash
uv add lightsmith                    # CPU
uv add "lightsmith[gpu]"             # + PyTorch for GPU solvers
uv add "lightsmith[mcp]"             # + MCP server for AI agents
uv add "lightsmith[tmatrix]"         # + treams T-matrix backend
uv add "lightsmith[layout]"          # + gdsfactory import (Python >= 3.11)
```

From a clone (pulls CUDA 12.8 PyTorch wheels on Windows/Linux):

```bash
uv sync --extra gpu --extra mcp
uv run lightsmith doctor
```

## Quick start

```python
import lightsmith as ls

sim = ls.Simulation(
    particles=[ls.Particle(shape=ls.Sphere(radius_nm=40),
                           material=ls.LibraryMaterial(name="Au"))],   # Johnson & Christy
    medium_index=1.33,
    wavelengths=ls.WavelengthRange(start_nm=400, stop_nm=800, num=81),
)

ls.estimate(sim, method="fdtd", device="gpu")   # grid, steps, memory; never solves
res = ls.solve(sim)                             # auto -> exact Mie for a sphere
cmp = ls.compare(sim, ["mie", "dda", "fdtd"])   # cross-check methods
```

The same from the shell, JSON in and out:

```bash
uv run lightsmith solve examples/drude_sphere.json --method dda --device gpu
```

## Problems and solvers

| Problem kind | Solvers (auto order first) | GPU | Gradients |
|---|---|---|---|
| `scattering` — particles, clusters | Mie (native, miepython), T-matrix (treams), DDA, FDTD, quasistatic | ✅ | Mie |
| `layer_stack` — thin films | TMM, RCWA, FDTD | ✅ | TMM, RCWA |
| `periodic` — gratings, metasurfaces | RCWA, FDTD (normal incidence) | ✅ | RCWA |
| `mode` — waveguide cross-sections | FDE (full vector, bends) | — | — |
| `device` — S-parameters between ports | EME, FDFD (2D) | FDFD | FDFD |
| `bands` — photonic crystals | PWE (2D TE/TM, 3D) | ✅ | dense path |
| `circuit` — netlists of compact models | S-matrix circuit solver | ✅ | ✅ |
| `optimization` — inverse design | topology optimisation on FDFD | ✅ | — |

`lightsmith backends` lists what is installed. Materials: bundled CC0 datasets (Au, Ag, Al, Cu, Si, SiO2, TiO2, water) from the refractiveindex.info database, online fetch of any entry, and passive Drude–Lorentz fitting for time-domain solvers.

GPL-licensed solvers live in separate plugin packages discovered through the `lightsmith.backends` entry point (`lightsmith-adda`, `lightsmith-scattnlay`), keeping this core MIT.

## Conventions

- Lengths in nm; wavelengths are vacuum wavelengths.
- Time dependence `exp(-iωt)`: absorbing materials have `Im(ε) > 0`.
- Scattering cross sections in nm²; efficiencies use the volume-equivalent radius, `Q = C / (π r_eq²)`.

## For AI agents

- `lightsmith schema` prints the JSON Schema of every problem kind.
- Every CLI command prints JSON; failures print `{"error", "message"}` to stderr with exit code 1.
- `lightsmith-mcp` serves `get_schema`, `list_backends`, `check_environment`, `estimate`, `solve` and `compare`.
- See [AGENTS.md](https://github.com/lightsmith-photonics/lightsmith/blob/main/AGENTS.md) and [llms.txt](https://github.com/lightsmith-photonics/lightsmith/blob/main/llms.txt).

## Licence

MIT. Backends keep their own licences; cite the ones you use (`Result.provenance`, `lightsmith backends`).

## Related repositories

Lightsmith is split across sibling repositories:

| Repository | Contents |
|---|---|
| `lightsmith` (this one) | Core library, solvers, benchmarks |
| `lightsmith-adda`, `lightsmith-scattnlay` | GPL solver plugins (separate licence) |
| `lightsmith-paper` | arXiv technical report |
| `lightsmith-studio`, `lightsmith-community`, `lightsmith-cloud`, `lightsmith-materials`, `lightsmith-deploy` | GUI, web platform, compute service, materials database, full-stack deployment |
