lightsmith 0.1.0__tar.gz

lightsmith-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Tooling caches and scratch output
+.pytest_cache/
+.ruff_cache/
+prof
+*.prof
+
+# Node / Next.js / Tauri
+node_modules/
+.next/
+out/
+src-tauri/target/
+*.tsbuildinfo
+
+# Local secrets and databases
+.env
+.env.*
+!.env.example
+*.db
+*.sqlite3
+
+# layout files written by ad-hoc runs at the repo root
+/*.gds
+/*.oas
+
+# MkDocs build output
+/site/

lightsmith-0.1.0/AGENTS.md

@@ -0,0 +1,30 @@
+# AGENTS.md
+
+Guidance for AI agents (and humans) using or developing lightsmith.
+
+## Using the library
+
+1. Build a problem of one of the kinds in `lightsmith/problems.py` (scattering, layer_stack, periodic, mode, device, bands, circuit, optimization); `lightsmith schema` prints the JSON Schema of all of them. Units are **nm**; wavelengths are **vacuum** wavelengths.
+2. Call `estimate` before `solve` for grid-based solvers (DDA, FDTD, FDFD, RCWA, PWE): it reports problem size, precision and memory without solving.
+3. `solve(problem, method="auto")` picks the preferred applicable method for the problem kind (see `AUTO_ORDER` in `api.py`). Errors explain why a backend was skipped and what to change.
+4. `compare(problem, methods=[...])` cross-checks methods; Mie is the reference for single spheres, otherwise the first method listed.
+5. Results carry `provenance` (backend versions, device, precision, iterations, residuals) and `warnings`. Check `warnings` before trusting numbers.
+
+Interfaces, all JSON in / JSON out:
+
+- Python: `import lightsmith as ls`
+- CLI: `lightsmith {doctor,backends,schema,estimate,solve,compare}` — errors are JSON on stderr, exit code 1.
+- MCP: `lightsmith-mcp` (stdio), tools `get_schema`, `list_backends`, `check_environment`, `estimate`, `solve`, `compare`.
+
+## Conventions (do not change without a schema version bump)
+
+- Time dependence `exp(-iωt)`: lossy materials have `Im(eps) > 0`, `Im(n) > 0`. Backends using `exp(+iωt)` conjugate at their boundary.
+- Cross sections in nm². Efficiencies are normalised by `π r_eq²`, with `r_eq` the volume-equivalent radius of all particles.
+- `Simulation.options[<method>]` holds method-specific options, validated by that backend's own options model.
+
+## Developing
+
+- `uv sync --extra gpu --extra mcp`, then `uv run pytest`. GPU tests are marked `gpu` and skip without CUDA.
+- New backends subclass `lightsmith.backends.Backend` and implement `supports`, `solve` (and ideally `estimate`, `available`). Register with `@register`, or from another package via the `lightsmith.backends` entry-point group. GPL-licensed solvers must live in separate plugin packages, never in this MIT core.
+- Native solvers use the array API (`device.namespace()`), never `numpy`/`torch` directly in hot loops, so one code path serves CPU and GPU.
+- Every new backend needs a test against Mie (or another reference) with a stated tolerance.

lightsmith-0.1.0/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to the `lightsmith` library are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[semantic versioning](https://semver.org/) (while the version is 0.x, minor releases may break the API).
+
+## [Unreleased]
+
+## [0.1.0] - unreleased
+
+First public release.
+
+### Added
+
+- **One problem spec for every method.** Pydantic models with a `kind` discriminator: `scattering`,
+  `layer_stack`, `periodic`, `mode`, `device`, `bands`, `circuit`, `optimization`. Any of them can be
+  passed as a model, dict or JSON string. `lightsmith schema` prints the JSON Schema. Lengths are in nm,
+  wavelengths are vacuum wavelengths, and the time convention is `exp(-iωt)`.
+- **Entry points** `solve`, `estimate`, `compare`, `choose_method` and `doctor`. `method="auto"` picks
+  the preferred applicable solver and explains why the others were skipped.
+- **Solvers.** All are MIT, and all are native unless noted.
+  - Scattering: Mie (native, homogeneous and layered spheres, GPU and autodiff), Mie through
+    `miepython`, T-matrix through `treams` (`tmatrix` extra), DDA, FDTD, and the quasistatic dipole
+    approximation.
+  - Thin films and periodic structures: TMM (coherent and incoherent layers, differentiable), RCWA
+    (1D/2D lattices, conical incidence, Li and normal-vector factorisation, differentiable), and
+    FDTD for periodic and layer-stack problems at normal incidence.
+  - Waveguides and devices: FDE (full-vector, bends, PML), EME, and 2D FDFD with adjoint gradients.
+  - Photonic crystals: PWE (2D TE/TM and 3D, dense and LOBPCG solvers).
+  - Circuits: S-matrix netlist solver with compact models and Touchstone I/O, differentiable.
+  - Inverse design: density-based topology optimisation on FDFD (filters, projection, minimum
+    feature size, MMA, Adam and L-BFGS-B), exported to polygons and GDS.
+- **Materials.** Bundled CC0 datasets from refractiveindex.info (Au, Ag, Al, Cu, Si, SiO2, TiO2,
+  water), online fetch of any database entry, and passive Drude–Lorentz fitting for time-domain solvers.
+- **Layout.** Built-in GDSII reader and writer, extrusion of GDS layers into device problems, and an
+  optional gdsfactory bridge (`layout` extra).
+- **Interfaces.** The `lightsmith` CLI (JSON on stdout, JSON errors on stderr) and the `lightsmith-mcp`
+  MCP server (`mcp` extra) for AI agents.
+- **Plugins.** The `lightsmith.backends` entry-point group, so GPL-licensed solvers can live in separate
+  packages (`lightsmith-adda`, `lightsmith-scattnlay`).
+- **Typing.** A `py.typed` marker; the public API is annotated.
+- **Documentation** site (MkDocs Material), `CITATION.cff` and `.zenodo.json`.
+
+### Notes
+
+- The `mcp` extra is pinned to `mcp>=1.2,<2`: the server uses the mcp 1.x `FastMCP` API, which mcp 2.x
+  renamed.
+
+[Unreleased]: https://github.com/lightsmith-photonics/lightsmith/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/lightsmith-photonics/lightsmith/releases/tag/v0.1.0

lightsmith-0.1.0/CITATION.cff

@@ -0,0 +1,29 @@
+cff-version: 1.2.0
+message: "If you use Lightsmith in your work, please cite it as below, and also cite the solver backends you used (see `lightsmith backends` and `Result.provenance`)."
+type: software
+title: "Lightsmith: an open, GPU-native photonics suite built for AI agents"
+abstract: >-
+  Lightsmith describes a photonics problem once, as typed JSON, and solves it
+  with Mie, T-matrix, DDA, FDTD, TMM, RCWA, FDE, EME, FDFD, PWE and S-matrix
+  circuit solvers on CPU or GPU, with differentiable inverse design. Every
+  result uses the same units and conventions and carries provenance, so methods
+  can be cross-checked directly. Python, CLI and MCP interfaces are JSON in,
+  JSON out.
+authors:
+  - family-names: Feghali
+    given-names: Alexander
+version: 0.1.0
+license: MIT
+repository-code: "https://github.com/lightsmith-photonics/lightsmith"
+url: "https://lightsmith-photonics.github.io/lightsmith/"
+keywords:
+  - photonics
+  - nanophotonics
+  - electromagnetics
+  - scattering
+  - Mie theory
+  - discrete dipole approximation
+  - FDTD
+  - RCWA
+  - inverse design
+  - GPU

lightsmith-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Feghali and the Lightsmith contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lightsmith-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+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 |

lightsmith-0.1.0/README.md

@@ -0,0 +1,94 @@
+# 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 |

lightsmith-0.1.0/docs/api/backends.md

@@ -0,0 +1,3 @@
+# Backends
+
+::: lightsmith.backends.base

lightsmith-0.1.0/docs/api/circuits.md

@@ -0,0 +1,3 @@
+# Circuits
+
+::: lightsmith.circuits

lightsmith-0.1.0/docs/api/core.md

@@ -0,0 +1,9 @@
+# Top level
+
+::: lightsmith.api
+    options:
+      members: [solve, estimate, compare, choose_method, AUTO_ORDER]
+
+::: lightsmith.device
+    options:
+      members: [doctor, resolve_device, Device]

lightsmith-0.1.0/docs/api/index.md

@@ -0,0 +1,14 @@
+# API reference
+
+Generated from the docstrings. The most-used names are re-exported from the top-level package
+(`import lightsmith as ls`):
+
+- [Top level](core.md): `solve`, `estimate`, `compare`, `choose_method`, `doctor`
+- [Problems](problems.md): every problem kind, plus `parse_problem` and `problem_json_schema`
+- [Scattering spec](spec.md): `Simulation`, shapes, illumination, output requests
+- [Materials](materials.md): material models, the bundled library, refractiveindex.info, Drude–Lorentz fits
+- [Results](results.md): result models for every problem kind
+- [Backends](backends.md): the `Backend` interface and registry
+- [Circuits](circuits.md): compact models, netlists, Touchstone files
+- [Inverse design](inverse.md): optimisation spec, driver, export
+- [Layout](layout.md): GDS import and export, the gdsfactory bridge

lightsmith-0.1.0/docs/api/inverse.md

@@ -0,0 +1,3 @@
+# Inverse design
+
+::: lightsmith.inverse

lightsmith-0.1.0/docs/api/layout.md

@@ -0,0 +1,3 @@
+# Layout
+
+::: lightsmith.layout

lightsmith-0.1.0/docs/api/materials.md

@@ -0,0 +1,7 @@
+# Materials
+
+::: lightsmith.materials
+
+::: lightsmith.materials_fit
+    options:
+      members: [fit_drude_lorentz, fit_quality]

lightsmith-0.1.0/docs/api/problems.md

@@ -0,0 +1,3 @@
+# Problems
+
+::: lightsmith.problems

lightsmith-0.1.0/docs/api/results.md

@@ -0,0 +1,3 @@
+# Results
+
+::: lightsmith.results

lightsmith-0.1.0/docs/api/spec.md

@@ -0,0 +1,3 @@
+# Scattering spec
+
+::: lightsmith.spec

lightsmith-0.1.0/docs/changelog.md

@@ -0,0 +1 @@
+--8<-- "CHANGELOG.md"

lightsmith-0.1.0/docs/cli.md

@@ -0,0 +1,43 @@
+# Command line
+
+The `lightsmith` command wraps the Python API. It is built for scripts and agents:
+
+- every command prints JSON to stdout;
+- every failure prints `{"error": "<ExceptionType>", "message": "..."}` to stderr and exits with code 1.
+
+```text
+lightsmith doctor
+lightsmith backends
+lightsmith schema
+lightsmith estimate SPEC [--method auto] [--device auto]
+lightsmith solve    SPEC [--method auto] [--device auto] [-o result.json]
+lightsmith compare  SPEC [--methods mie,dda] [--device auto] [-o comparison.json]
+```
+
+| Command | Output |
+|---|---|
+| `doctor` | NumPy, PyTorch and CuPy versions, the CUDA GPUs, and the device `auto` would pick |
+| `backends` | One entry per backend: `name`, `method`, `problem_kinds`, `license`, `gpu`, `differentiable`, `available`, `unavailable_reason`, `citation` |
+| `schema` | The JSON Schema of every problem kind |
+| `estimate` | Backend, device, problem size and memory, without solving |
+| `solve` | The result model as JSON |
+| `compare` | `reference`, `results` (one per method) and `relative_difference` |
+
+`SPEC` is a JSON file of any [problem kind](problems/index.md), or `-` to read from stdin.
+
+| Option | Values |
+|---|---|
+| `--device` | `auto`, `cpu`, `gpu`, `cuda:N` or `torch-cpu` |
+| `--method` | `auto`, a method such as `dda`, or a backend name such as `lightsmith-mie` (see [Solvers](solvers/index.md)) |
+| `--methods` | Comma-separated methods or backend names. Default: every backend that applies. |
+
+## Examples
+
+```bash
+lightsmith estimate examples/drude_sphere.json --method dda --device gpu
+lightsmith solve examples/drude_sphere.json -o result.json
+cat spec.json | lightsmith solve - --method rcwa
+lightsmith compare examples/drude_sphere.json --methods mie,dda,fdtd
+```
+
+The [MCP server](mcp-overview.md) exposes the same operations to AI agents.

lightsmith-0.1.0/docs/contributing.md

@@ -0,0 +1,112 @@
+# Contributing
+
+Contributions are welcome: solver backends, validation tests, materials and documentation. Lightsmith is
+MIT-licensed. By contributing, you agree that your contribution is released under the same licence.
+
+## Development setup
+
+```bash
+git clone https://github.com/lightsmith-photonics/lightsmith
+cd lightsmith
+uv sync --extra gpu --extra mcp
+uv run pytest                      # GPU tests are marked `gpu` and skip without CUDA
+uv run pytest -m slow              # long convergence checks
+uv run --group docs mkdocs serve   # documentation preview
+```
+
+## Ground rules
+
+- **Conventions are fixed.** Use nm, vacuum wavelengths and `exp(-iωt)`, and normalise efficiencies by
+  π r_eq². See [Conventions](conventions.md). Changing any of these needs a schema version bump.
+- **Every backend is validated.** A new backend needs a test against Mie or another reference, with a
+  stated tolerance. Add the numbers to the backend's page under [Solvers](solvers/index.md).
+- **One code path for CPU and GPU.** Native solvers use the array API (`device.namespace()`) and never
+  call `numpy` or `torch` directly in hot loops.
+- **The core stays MIT.** GPL-licensed solvers must live in separate plugin packages.
+- **Optional dependencies are imported lazily**, inside methods, so that a missing extra never breaks
+  `import lightsmith`.
+
+## Writing a backend
+
+A backend wraps one implementation of one method. Subclass `lightsmith.backends.Backend`:
+
+```python
+from typing import ClassVar
+
+from lightsmith.backends import Backend, register, unsupported_outputs
+from lightsmith.device import Device
+from lightsmith.results import Result
+from lightsmith.spec import Simulation
+
+
+@register
+class MySolver(Backend):
+    name: ClassVar[str] = "my-solver"            # unique implementation id
+    method: ClassVar[str] = "dda"                # the method family it implements
+    license: ClassVar[str] = "MIT"
+    citation: ClassVar[str] = "Author et al., Journal (year)"
+    gpu: ClassVar[bool] = False
+    differentiable: ClassVar[bool] = False
+    problem_kinds: ClassVar[tuple[str, ...]] = ("scattering",)
+
+    @classmethod
+    def available(cls) -> tuple[bool, str]:
+        try:
+            import my_dependency  # noqa: F401  (import optional dependencies lazily)
+        except ImportError:
+            return False, "my_dependency is not installed (pip install my_dependency)"
+        return True, ""
+
+    @classmethod
+    def supports(cls, sim: Simulation) -> tuple[bool, str]:
+        why = unsupported_outputs(sim, near_field=False, far_field=False)
+        return (not why), why
+
+    @classmethod
+    def estimate(cls, sim: Simulation, device: Device) -> dict:
+        return {"unknowns": 0, "memory_bytes": 0}     # cheap; never solves
+
+    @classmethod
+    def solve(cls, sim: Simulation, device: Device) -> Result:
+        ...
+```
+
+| Member | Role |
+|---|---|
+| `available()` | Whether the dependencies are installed, and if not, why. It is checked before `supports`. |
+| `supports(problem)` | Whether this backend can solve the problem, and if not, an actionable reason. The reason appears in `auto` selection errors. |
+| `estimate(problem, device)` | A cheap pre-flight report of size and memory. Optional, but expected for grid-based solvers. |
+| `solve(problem, device)` | Returns the result model for the problem kind: `Result`, `SpectrumResult`, `ModeResult`, `SParameterResult` or `BandResult`. Fill in `provenance` and `warnings`. |
+
+Options: read `options_for(problem, cls.name, cls.method)` from `lightsmith.problems` and validate it with a
+pydantic model that uses `extra="forbid"`.
+
+To make `method="auto"` consider a new method, add it to `AUTO_ORDER` in `lightsmith/api.py`. Methods
+not listed there are tried after the listed ones.
+
+## Plugin packages
+
+A backend can live in its own package. This is required for GPL-licensed solvers. Register it through
+the `lightsmith.backends` entry-point group in the plugin's `pyproject.toml`:
+
+```toml
+[project]
+name = "lightsmith-mysolver"
+dependencies = ["lightsmith>=0.1"]
+
+[project.entry-points."lightsmith.backends"]
+mysolver = "lightsmith_mysolver:MySolver"
+```
+
+Once the plugin is installed, `lightsmith backends` lists it, and `solve`, `compare` and the MCP server
+can use it. `lightsmith-adda` and `lightsmith-scattnlay` are working examples.
+
+## Documentation
+
+- The documentation lives in `docs/` and builds with MkDocs Material: `uv run --group docs mkdocs build --strict`.
+- The API reference is generated from docstrings by mkdocstrings.
+- New pages must be added to `nav` in `mkdocs.yml`; the strict build fails on pages missing from it.
+
+## Releases
+
+The maintainers' checklist is `RELEASING.md` in the repository root.