lightsmith 0.2.0__tar.gz → 0.3.0__tar.gz

{lightsmith-0.2.0 → lightsmith-0.3.0}/.gitignore

@@ -38,3 +38,5 @@ src-tauri/target/
 
 # outputs of examples
 examples/output/
+inverse_bend_out/
+inverse_3d_out/

{lightsmith-0.2.0 → lightsmith-0.3.0}/AGENTS.md

@@ -4,10 +4,10 @@ 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.
+1. Build a problem of one of the kinds in `lightsmith/problems.py` (scattering, emission, 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.
+4. `compare(problem, methods=[...])` cross-checks methods; Mie is the reference for single spheres, otherwise the first method listed (or, with no list, the one `auto` would pick).
 5. Results carry `provenance` (backend versions, device, precision, iterations, residuals) and `warnings`. Check `warnings` before trusting numbers.
 
 Component-to-circuit flow (`lightsmith.pdk`): `get_component(cell, **params)` builds layout + ports (port centres are the S-parameter reference planes; names o1, o2, ... as gdsfactory); `flow.simulate` solves its `DeviceProblem` via `solve` (2D effective-index plan view by default); `flow.component_model` fits and caches the S-parameters (key = cell, params, technology, band, solver, options); circuit netlists use `{"component": "pdk:<cell>", "settings": {<params>, <FlowSettings>}}`. Technologies are `Technology` JSON (`generic_soi()` uses only open data). Compare circuits with direct simulations only when both use the same solver and grid (`FlowSettings(method=..., waveguide_model="device")`): FDFD's numerical dispersion at the default grid is ~1e-2 in neff, and with the default 4x subpixel sampling the grid alignment of waveguide edges shifts neff by ~7e-3 between instances (use `subsamples: 16`).
@@ -15,10 +15,11 @@ Component-to-circuit flow (`lightsmith.pdk`): `get_component(cell, **params)` bu
 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.
+- CLI: `lightsmith {doctor,backends,schema,estimate,discretization,solve,compare}` — errors are JSON on stderr, exit code 1.
+  `discretization` (`ls.discretization`) shows what a backend will discretise (grid, mesh, dipoles, harmonics, cells) without solving.
 - MCP: `lightsmith-mcp` (stdio; `--http` for streamable HTTP). Tools:
   - discovery: `list_problem_kinds`, `get_schema(kind)`, `list_backends`, `check_environment`, `validate_problem`;
-  - solving: `estimate`, `solve`, `start_solve`, `compare`;
+  - solving: `estimate`, `get_discretization`, `solve`, `start_solve`, `compare`;
   - jobs: `get_job`, `list_jobs`, `cancel_job`, `get_result`;
   - materials: `search_materials`, `get_material`, `fit_drude_lorentz`.
 

lightsmith-0.3.0/CHANGELOG.md

@@ -0,0 +1,268 @@
+# 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.3.0] - 2026-11-08
+
+- `device="auto"` runs on the CPU, with a warning, when the problem will not fit in the GPU's free memory. Before,
+  `examples/pdk_mzi.py` took FDFD's block LU (12.9 GB) onto a 12 GB GPU, where Windows paged it for hours, although
+  SuperLU on the CPU needs 0.8 GB. `estimate` reports the same choice (`device`, `device_note`). Naming a device
+  still gets that device.
+- The MCP server's solver process reports progress through `lightsmith.progress`: every wavelength or iteration of a
+  solve, and each method of a `compare`. Inverse design goes through `solve`, so `device="auto"` treats it the same.
+- 2D FDFD rasterises the geometry once per solve, as 3D does, and tests each structure only inside its bounding box.
+  For the whole MZI of `examples/pdk_mzi.py` that took 690 of 846 s per wavelength, against 76 s for the factorisation.
+
+### Fixed
+
+- `method="auto"` passes over a 2D FDFD problem that exceeds `max_cells` and goes on to FDTD; the estimate now says
+  `fits: false` instead of raising, and only an explicit solve is refused.
+- FDFD accepts 2D ports with z size 0, as the `Port` schema documents, and refuses only a true z normal. The MCP server's
+  device example now leaves room for absorbing layers, so it runs on EME, BPM, FDFD and FDTD.
+- The MCP budget now covers 2D FDFD and 2D inverse design: their estimates report `memory_bytes` for the solver the device
+  will use.
+- FDTD devices apply the same dispersive time-step limit as every other FDTD problem kind.
+- The Mie refusal suggested `tmatrix` for non-spherical particles, which refuses them too; it now names `bem` and `dda`, as do
+  the MCP prompts.
+- CLI usage errors are JSON on stderr with exit status 1, like every other failure.
+- `discretization` no longer assumes a third-party backend has a built-in backend's internals; it reports no plan unless the
+  plugin overrides `Backend.discretization`.
+- Backends' `differentiable` flag now means "has a torch-differentiable entry point", and native Mie and PWE set it.
+
+### Added
+
+- **Progress callbacks and cancellation**: `solve(..., progress=callback)` and `compare(..., progress=callback)` call back with
+  `{"stage", "fraction", ...}` while solving: DDA per wavelength and incidence, BEM and FDFD per wavelength, FDTD per chunk of
+  steps, inverse design per iteration. A callback may raise `lightsmith.progress.Cancelled` to stop.
+- Backends declare `options_model`, so `list_backends` on the MCP server and `/v1/backends` on Cloud carry each backend's
+  options as a JSON Schema.
+- Every result records `provenance.versions` (library, NumPy, PyTorch when used). Under `method="auto"`, results and estimates
+  record `auto_skipped`: why the earlier backends were passed over. DDA results keep their BiCGStab residuals.
+- `tests/test_optics.py` validates `lightsmith.optics` against closed forms; tests for the DDA's `weighted` and
+  `extrapolate` modes, which also lose their "experimental" label in favour of what they do and where they fail.
+- The agent benchmark gained an emission task (44 tasks; every problem kind is now covered, and a test enforces it). Its gold
+  nanorod task now asks for the resonance wavelength, on which BEM and DDA agree.
+
+- **`lightsmith.discretization(problem, method)`**, `lightsmith discretization` and the MCP tool `get_discretization`: what a backend
+  will discretise, before any solve, with a common envelope (`layout_kind`, a labelled `summary`, a `payload`, the
+  estimate, warnings, and the library's refusal in `error`). FDTD: the Yee grid, TFSF and flux boxes, CPML,
+  refinement regions and mirror planes; unit cells of periodic structures and layer stacks; device grids and
+  ports. FDFD device grids and ports, inverse-design regions, the DDA dipole lattice, the BEM surface mesh, Mie
+  and T-matrix multipole orders, RCWA harmonics, FDE grids, EME and BPM cells, PWE k-paths and plane waves. Each
+  calls the backend's own planning code and never solves. `Backend.discretization` lets plugins answer too.
+  See `docs/discretization.md`.
+
+- **FDTD graded grids for device problems**: `mesh_override` boxes and `grid: "auto"` (each structure refined
+  to `cells_per_wavelength` in its own material) now work for `kind: "device"`, in 2D and 3D. Ports sit in
+  uniform cells along their normals; across their windows the cells may be graded, and the port modes come
+  from the FDE problem on the same non-uniform cross-section (the FDE grid gained per-cell widths), so they stay
+  exact for the grid: a straight guide still transmits |S21| = 1 with the grid's phase (1e-10 rad). A
+  500 → 900 nm 2D step graded from 25 to 10 nm is within 2e-5 of a uniform 10 nm run with 63 % of the cells,
+  and a 3D wire step graded from 40 to 15 nm within 8e-6 of a uniform 15 nm run with 45 % of the cells.
+- **FDTD graded grids** (scattering): `grid: "auto"` refines each particle's bounding box to the spacing its
+  material and size need, and `mesh_override: [{center_nm, size_nm, spacing_nm}]` adds refinement boxes. The
+  cells grade back to the base spacing at most `grading_ratio` (1.25) per cell. The grid is a tensor product
+  with independent per-axis widths. The Yee update uses primary and dual width arrays, so it conserves the
+  same discrete energy as the uniform one, on the CPU and on CUDA with CUDA graphs. The CPML, TFSF tables
+  (exact discrete background of the graded 1D problem, still leak-free), layered substrates, conformal
+  smoothing (metals' vertex tensor included), flux and far-field surfaces, near fields, particle absorption
+  and mirror planes all follow the widths. An n = 3.5, r = 20 nm sphere is within 0.11 % of a uniform 2 nm run, whose own error against Mie is
+  0.7 %, with 153 k cells instead of 242 k. A Drude sphere of r = 10 nm at 0.5 nm cells needs 488 k cells
+  instead of 1.74 M (2.1× faster in double precision). Its spectrum differs from the uniform run by at most
+  7e-4 of the peak, against a 13 % discretisation error. Particles on glass or on an absorbing substrate
+  agree within 0.34 %, and far fields within 0.1 % of the uniform run's. The coarsest cells must stay fine:
+  any change of cell size h reflects about (k h)²/16 of a wave, so `grid: "auto"` uses 60 cells per
+  background wavelength (`background_cells_per_wavelength`). A uniform grid gives today's run bit for bit.
+  Scattering only, with plane waves along an axis (or graded only along the axes the wave does not vary along).
+- **FDTD device problems** (`kind: "device"`, 3D and 2D): S-parameters between waveguide ports. Each port
+  mode is an exact eigenmode of the FDTD grid itself: the FDE cross-section problem solved with the
+  leapfrog frequency, the discrete propagation constant and each node's discrete material response, then
+  interpolated over the band from Chebyshev nodes. So the TFSF mode sources launch one way only, and the
+  monitors split the fields into forward and backward modes exactly. A straight silicon wire transmits with
+  |S21| = 1 to 1e-6 and the grid's own phase. A 2D width step matches FDFD to 3e-5 (TE) and 3.4e-4 (TM) at
+  dl = 10 nm, and a 3D one is converged to 1e-4 between dx = 25 and 15 nm. Device problems default to
+  `subpixel` smoothing (port modes need a diagonal permittivity). `polarization` selects TE or TM in 2D.
+- **FDTD mirror symmetries** (`symmetry: "auto"`, the default; `"off"` turns them off). A scattering run
+  whose particles are mirror-symmetric about their centre, lit by a plane wave that travels in the mirror
+  plane and is polarised in it (a PMC plane) or normal to it (a PEC plane), keeps half the grid per plane:
+  2× or 4× fewer cells. The conformal tensors, metals' vertex tensor included, are folded across the
+  planes, so cross sections, near fields and far fields match the full run to 1e-11 in double precision,
+  over substrates and absorbing substrates too. On the GPU, runs of 1–5 M cells are 1.55–2.3× faster (3.7×
+  in steady state at 15 M cells). The provenance and `estimate` report the planes used.
+- **FDTD conformal meshing.** `mesh_refinement` (`staircase`, `volume_average`, `subpixel`, `conformal`). The
+  new default, `conformal`, adds the off-diagonal terms of tensor subpixel smoothing, symmetrised for
+  stability. Dielectric sphere C_ext error at dx = 6 nm falls from 1.1 % to 0.04 %. At metal interfaces
+  the full dispersive tensor is applied at grid vertices as a sum of passive congruences, so it is stable
+  by construction. On a Drude sphere's plasmon band it cuts the C_ext error 2–4× compared with diagonal
+  smoothing (2.5 % against 6.6 % RMS at dx = 2 nm), and the error now falls as the grid is refined.
+- **FDTD far field** (`outputs.far_field`): near-to-far-field projection of the scattered fields, within
+  0.4 % of Mie.
+- **Dipole emission** (`kind: "emission"`): Purcell factor, radiative enhancement, efficiency and
+  radiation pattern of a point dipole near particles. Exact for one sphere in native Mie; any geometry in
+  FDTD (within 0.2 % of Mie next to a dielectric sphere).
+- **Gaussian beams** (`illumination: GaussianBeam`, FDTD): a focused beam as a sum of TFSF plane waves at
+  fixed angles (the waist scales with the wavelength, as for a lens of fixed NA); cross sections per unit
+  focal intensity. Within 0.13 % of Mie at the focus and 0.1 % of the beam profile off axis.
+- **FDTD substrates** (`Simulation.substrate`): particles on or above a non-absorbing half-space, lit from
+  above at any angle or through the substrate, including total internal reflection. The TFSF box takes
+  the background field (incident, reflected and transmitted waves) from an auxiliary column at normal
+  incidence. At oblique incidence it comes from tables of the exact discrete background (a 1D discrete
+  problem along z per frequency, then an inverse FFT). Either way it does not leak where it cuts the
+  interface. C_sca is within 0.2–0.5 % of a dipole reference for a sphere above glass (1.7 % for p
+  under total internal reflection, where the dipole model is least exact). Near fields are supported;
+  absorbing substrates and far fields are not yet.
+- **FDTD absorbing substrates and far fields over substrates.** Particles over metals or other absorbing
+  substrates. Over one, `c_abs` is the particles' own absorption, from the grid's exact discrete Poynting
+  balance on their nodes; it equals the inflow through a closed box around the particle to 1e-6. `c_sca` is
+  the power scattered upward, and `c_ext` the power taken from the reflected wave (the reflectance change).
+  `outputs.far_field` now works over any substrate, into both half-spaces, by reciprocity with the grid's
+  own layered background. Against a multipole reference, a sphere over an absorbing dielectric is within
+  0.1 %, and one over a Drude metal within 0.14 %. Over glass the new quantities reproduce the box fluxes
+  to 3e-4. `precision: "auto"` runs double over an absorbing substrate: in float32 a metal's long
+  ring-down left rounding noise of up to 1.2 % in C_sca.
+- **Leak-free plane waves and Gaussian beams at any angle** (FDTD scattering). Every plane wave, and every
+  component of a Gaussian beam, is fed from tables of the grid's exact discrete plane wave (the oblique
+  substrate method, with a uniform background), so the TFSF box does not leak at any direction. A sphere's
+  C_ext agrees between directions to 4e-5 (0.35 % before). A 20 nm sphere is within 0.1 % of Mie: with the
+  1D-fed source, the incident flux through the box did not cancel, giving errors up to 22 % at 800 nm. A beam
+  on a 40 nm sphere is within 0.04 % of Mie at the focus and off axis (0.13 % before). Gaussian beams now
+  support near-field output.
+- **Resonances** (`outputs.resonances`): wavelengths, Q factors and amplitudes from the FDTD ring-down,
+  through the new `lightsmith.resonance.harmonic_inversion` (multi-channel matrix pencil).
+
+### Changed
+
+- FDTD scattering stops when the scattered field has decayed, not the total field. The incident pulse
+  no longer sets the peak, so weak, sharp resonances are no longer cut off: a 15 nm Drude sphere's
+  spectrum rippled by ±10 %.
+- FDTD `pml_cells` defaults to 16 with a substrate (10 otherwise).
+- FDTD voxelisation evaluates the geometry once per point of the half-cell lattice, where it used to test each
+  field position's 26 neighbours separately for every component. The result is the same, and it is 4× faster
+  (45 s → 10 s for a 2.5 M-cell 3D MMI).
+- FDTD scattering: the default TFSF padding and PML gap are now at least 3 % of the longest wavelength
+  in the medium, so refining the grid no longer moves the monitors closer to the particle.
+- FDTD: the table-fed plane-wave source updates all face slabs of a kind in one gather and scatter, and
+  stops waiting once the pulse has passed (the wrapped edge of the table's inverse FFT had set it to the
+  whole table), so small scattering runs are 2.3–2.8× faster with the same results.
+- Documentation describes problems through the Python models first; saving and loading them as JSON
+  files for the CLI and MCP server is covered in the quick start.
+
+### Fixed
+
+- Inverse design: `estimate` now applies the optimisation-level solver options (`OptimizationProblem.options`),
+  merged over the device's key by key as the optimiser merges them (`inverse.backend.device_problem`); it used
+  the device's options alone.
+- FDTD options: the `pml_cells` description gives the device default (12), and the `mesh_override` description
+  no longer names another product.
+- FDTD: the time step is reduced where a dispersive (Drude–Lorentz) material would make the update unstable
+  on a coarse grid, checked from the update's eigenvalues over the grid's spatial frequencies. The
+  Johnson–Christy gold fit diverged at dx ≥ 20 nm, and lossy constants at dx near half a wavelength.
+- **3D devices with ports facing y** (FDE ports, EME, BPM): the cross-section's local x axis was global z,
+  so `"te"` selected the vertical-E mode and BPM's `bend_radius_nm` bent the guide out of the chip plane.
+  Local x is now the in-plane transverse axis for ports facing x or y, as it already was in 2D. Results for
+  ports facing x, and for all 2D devices, are unchanged.
+- **`compare`**: device, circuit, mode and band results now report differences (they came back empty);
+  without a method list the reference is the method `auto` would pick, not the alphabetically first
+  backend; relative cross-section differences are floored at 0.1 % of the reference extinction, so a
+  lossless particle's near-zero absorption no longer gives huge relative errors. Results that cannot be
+  compared are listed under `not_compared`.
+- **FDTD periodic and layer-stack transmission** into an absorbing substrate is referred to the interface,
+  as in TMM and RCWA. Before, T was taken a few cells inside the substrate (Si at 420 nm read 0.744 instead
+  of 0.815) and metal substrates reported T = 0.
+- **BEM** checks particle overlap on the volume-corrected meshes the solve uses, so particles about 0.1 nm
+  apart no longer produce interpenetrating meshes, and warns when a gap is smaller than the mesh size.
+- **`auto`** skips a backend whose estimate exceeds its own size limit (BEM `max_unknowns`, DDA
+  `max_dipoles`, T-matrix `max_modes`, ...) and falls through to the next method, instead of picking it and
+  failing at solve time.
+- **`Tabulated`** materials sort their data by wavelength (energy-ordered files are descending, which
+  interpolation silently got wrong) and refuse duplicate wavelengths or mismatched column lengths.
+
+
+## [0.2.0] - 2026-11-02
+
+### Added
+
+- **BEM** (`lightsmith-bem`): PMCHWT surface integral equations on RWG meshes for spheres, spheroids,
+  cylinders, layered spheres and disjoint clusters, with near and far fields, on CPU or GPU. `auto` tries
+  it after T-matrix for scattering.
+- **BPM** (`lightsmith-bpm`): wide-angle Padé beam propagation for devices, 2D and 3D (semi- and
+  full-vectorial), with bends, on CPU or GPU.
+- **FDTD oblique and conical incidence** on layer stacks and periodic structures, up to 85° from the
+  normal, with Bloch-periodic boundaries at fixed in-plane wavevector. Scattering accepts any incidence
+  direction.
+- **PDK flow** (`lightsmith.pdk`): technologies as JSON (`generic_soi` from open data), parametric cells
+  with GDS output, simulation at the port reference planes, fitted and cached compact models, and
+  `pdk:<cell>` instances in circuit netlists.
+- **MCP server rewrite** on MCP SDK 2.x: jobs, budgets, resources, prompts, materials tools, and remote
+  mode. The `mcp` extra is now `mcp>=2.3,<3`.
+- **3D inverse design** on a full-vector 3D FDFD solver (`lightsmith-fdfd` with `dimension=3` devices):
+  exact discrete port modes, TF/SF mode sources, batched BiCGStab on CPU or GPU, and adjoint gradients
+  with warm starts across iterations.
+- **Agent benchmark** (`benchmarks/agents/`): 43 graded tasks for agents using the MCP server.
+
+### Changed
+
+- The documentation moved to <https://docs.lightsmith.dev/>. The old GitHub Pages address redirects there.
+
+### Fixed
+
+- Multilayer Mie: avoid cancellation near zeros of ψₙ, which gave errors up to 12% for coated spheres
+  whose interface sits on such a zero.
+- RCWA: grazing diffraction orders (kz = 0) inside uniform layers no longer make the layer S-matrix
+  singular.
+- FDTD: runs whose fields grow without bound now raise, also on CPU in float64, where they used to stay
+  finite and return cross sections off by many orders of magnitude.
+- Topology optimisation: `OptimizationProblem.options` now merges into the device's options key by key
+  within each method, instead of replacing the method's whole dictionary (which dropped `dl_nm`,
+  `pml_cells` and the like).
+- `device="auto"` falls back to CPU when CUDA is available but no device is visible
+  (`CUDA_VISIBLE_DEVICES=""`), instead of failing with "Invalid device id".
+
+## [0.1.0] - 2026-11-01
+
+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.3.0...HEAD
+[0.3.0]: https://github.com/lightsmith-photonics/lightsmith/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/lightsmith-photonics/lightsmith/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/lightsmith-photonics/lightsmith/releases/tag/v0.1.0

{lightsmith-0.2.0 → lightsmith-0.3.0}/CITATION.cff

@@ -4,16 +4,16 @@ 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
+  with Mie, T-matrix, BEM, DDA, FDTD, TMM, RCWA, FDE, EME, BPM, 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.2.0
-date-released: "2026-11-02"
+version: 0.3.0
+date-released: "2026-11-08"
 license: MIT
 repository-code: "https://github.com/lightsmith-photonics/lightsmith"
 url: "https://docs.lightsmith.dev/"

{lightsmith-0.2.0 → lightsmith-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: lightsmith
-Version: 0.2.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.
+Version: 0.3.0
+Summary: Open photonics suite: one typed problem description solved by Mie, T-matrix, BEM, DDA, FDTD, TMM, RCWA, FDE, EME, BPM, FDFD, PWE and circuit solvers on CPU or GPU, with differentiable inverse design, built for humans and AI agents.
 Project-URL: Homepage, https://lightsmith.dev/
 Project-URL: Documentation, https://docs.lightsmith.dev/
 Project-URL: Repository, https://github.com/lightsmith-photonics/lightsmith
@@ -45,7 +45,7 @@ Description-Content-Type: text/markdown
 
 **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.
+Describe a photonics problem once and solve it with whichever method 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://docs.lightsmith.dev/>
 
@@ -85,7 +85,7 @@ 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:
+The same from the shell, with the problem saved to a file:
 
 ```bash
 uv run lightsmith solve examples/drude_sphere.json --method dda --device gpu
@@ -114,7 +114,7 @@ FDTD handles oblique and conical incidence on layer stacks and periodic structur
 
 ## From components to circuits (`lightsmith.pdk`)
 
-An open design kit: a technology as data (`generic_soi()`: 220 nm Si on 2 µm oxide, open material data only; define others as JSON), parametric cells (straight, circular/Euler bends, taper, MMI 1×2/2×2, directional coupler, ring/racetrack, Y-branch, crossing, grating coupler, MZI) with gdsfactory-style ports and GDS output, and a flow that simulates each component through `solve` (EME, FDFD or whatever `AUTO_ORDER` picks), fits a compact model, caches it by parameter hash and uses it in netlists as `pdk:<cell>`:
+An open design kit: a technology as data (`generic_soi()`: 220 nm Si on 2 µm oxide, open material data only; define your own in Python or load one from a file), parametric cells (straight, circular/Euler bends, taper, MMI 1×2/2×2, directional coupler, ring/racetrack, Y-branch, crossing, grating coupler, MZI) with gdsfactory-style ports and GDS output, and a flow that simulates each component through `solve` (EME, FDFD or whatever `AUTO_ORDER` picks), fits a compact model, caches it by parameter hash and uses it in netlists as `pdk:<cell>`:
 
 ```python
 from lightsmith.pdk import get_component

{lightsmith-0.2.0 → lightsmith-0.3.0}/README.md

@@ -2,7 +2,7 @@
 
 **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.
+Describe a photonics problem once and solve it with whichever method 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://docs.lightsmith.dev/>
 
@@ -42,7 +42,7 @@ 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:
+The same from the shell, with the problem saved to a file:
 
 ```bash
 uv run lightsmith solve examples/drude_sphere.json --method dda --device gpu
@@ -71,7 +71,7 @@ FDTD handles oblique and conical incidence on layer stacks and periodic structur
 
 ## From components to circuits (`lightsmith.pdk`)
 
-An open design kit: a technology as data (`generic_soi()`: 220 nm Si on 2 µm oxide, open material data only; define others as JSON), parametric cells (straight, circular/Euler bends, taper, MMI 1×2/2×2, directional coupler, ring/racetrack, Y-branch, crossing, grating coupler, MZI) with gdsfactory-style ports and GDS output, and a flow that simulates each component through `solve` (EME, FDFD or whatever `AUTO_ORDER` picks), fits a compact model, caches it by parameter hash and uses it in netlists as `pdk:<cell>`:
+An open design kit: a technology as data (`generic_soi()`: 220 nm Si on 2 µm oxide, open material data only; define your own in Python or load one from a file), parametric cells (straight, circular/Euler bends, taper, MMI 1×2/2×2, directional coupler, ring/racetrack, Y-branch, crossing, grating coupler, MZI) with gdsfactory-style ports and GDS output, and a flow that simulates each component through `solve` (EME, FDFD or whatever `AUTO_ORDER` picks), fits a compact model, caches it by parameter hash and uses it in netlists as `pdk:<cell>`:
 
 ```python
 from lightsmith.pdk import get_component

lightsmith-0.3.0/docs/api/core.md

@@ -0,0 +1,13 @@
+# Top level
+
+::: lightsmith.api
+    options:
+      members: [solve, estimate, discretization, compare, choose_method, AUTO_ORDER]
+
+::: lightsmith.progress
+    options:
+      members: [report, reporting, scaled, Cancelled]
+
+::: lightsmith.device
+    options:
+      members: [doctor, resolve_device, Device]

{lightsmith-0.2.0 → lightsmith-0.3.0}/docs/benchmarks/agents.md

@@ -13,11 +13,12 @@ agent pushed back on requests that cannot be answered as asked.
 
 ## Tasks
 
-43 tasks cover every problem kind:
+44 tasks cover every problem kind:
 
 | Kind | Tasks |
 |---|---:|
 | scattering | 12 |
+| emission | 1 |
 | layer_stack | 8 |
 | mode | 7 |
 | circuit | 5 |
@@ -31,8 +32,8 @@ They fall into four categories:
 - **Standard** (23): a well-posed question, such as the plasmon peak of a gold sphere in water, an
   antireflection coating, a Bragg mirror, grating efficiencies, waveguide modes, a 2D MMI, the TM gap of a
   photonic crystal, the FSR of an MZI or a ring, or a small topology optimisation.
-- **Trap** (15): answerable, but the obvious setup is wrong. Examples: a diameter given where the schema
-  wants a radius; a wavelength given in the medium; energies, wavenumbers, frequencies or µm instead of
+- **Trap** (16): answerable, but the obvious setup is wrong. Examples: a diameter given where the schema
+  wants a radius; an emitter's distance given from a particle's surface; a wavelength given in the medium; energies, wavenumbers, frequencies or µm instead of
   nm; a complex index in the e^{+jωt} convention; light incident from the substrate; a 1 mm slide that must
   be an incoherent layer; group index versus effective index; normalised frequency a/λ; a material
   dataset that does not cover the wavelength; cm versus nm in a link budget.
@@ -41,7 +42,7 @@ They fall into four categories:
   lossless 1×2 splitter with 70 % in each arm.
 - **Warning** (2): the tools warn about the answer and the agent must pass the warning on.
 
-11 tasks use grid-based solvers (DDA, RCWA, EME, PWE, inverse design) and are also graded on whether the
+11 tasks use grid-based solvers (BEM, RCWA, EME, PWE, inverse design) and are also graded on whether the
 agent estimated before solving.
 
 Each task file in `benchmarks/agents/tasks/` holds the prompt, the answer fields with units, a hidden
@@ -114,7 +115,7 @@ uv run --no-sync pytest benchmarks/agents/tests
 ```
 
 The tests check that the task files match `taskdefs.py`, that the graders work on hand-made transcripts,
-that the oracle passes all 43 tasks over stdio MCP with no failed tool call, and that the Claude adapter's
+that the oracle passes all 44 tasks over stdio MCP with no failed tool call, and that the Claude adapter's
 loop works against a scripted stand-in for the API (no key, no cost). They also check that deliberately
 wrong behaviour fails: numbers off by 25 %, skipped estimates, dropped concerns, no answer, the right
 numbers without a simulation, every naive problem, and answers to the unphysical requests.

{lightsmith-0.2.0 → lightsmith-0.3.0}/docs/cli.md

@@ -20,6 +20,7 @@ lightsmith compare  SPEC [--methods mie,dda] [--device auto] [-o comparison.json
 | `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 |
+| `discretization` | What the backend will discretise: grid, mesh, dipole lattice, harmonics, cells ([Discretisation](discretization.md)) |
 | `solve` | The result model as JSON |
 | `compare` | `reference`, `results` (one per method) and `relative_difference` |
 

lightsmith-0.3.0/docs/discretization.md

@@ -0,0 +1,56 @@
+# Discretisation: what a solver will discretise
+
+`lightsmith.discretization(problem, method="auto")` reports what a backend will discretise for a problem, before any
+solve: the FDTD Yee grid and its boxes, a device grid and its ports, the DDA dipole lattice, the BEM surface mesh,
+the Mie or T-matrix multipole order, the RCWA harmonics, an FDE cross-section grid, the EME or BPM cells along a
+device, the PWE k-path and plane waves. It calls each backend's own planning code (the code `estimate` and
+`solve` call) and never runs a solver, so it is as cheap as `estimate`. GUIs use it to draw the discretisation,
+and agents use it to check a set-up.
+
+```python
+import lightsmith as ls
+
+out = ls.discretization(problem, method="dda")
+out["summary"]        # {"dipoles": 2176, "spacing (nm)": 4.98, "dipoles per diameter": 16, ...}
+out["payload"]        # {"points_nm": [[x, y, z], ...], "spacing_nm": 4.98, ...}
+```
+
+```bash
+lightsmith discretization spec.json --method fdtd
+```
+
+The MCP server has the same call as the read-only tool `get_discretization(problem, method)`.
+
+## The envelope
+
+Every backend answers with the same keys:
+
+| Key | Meaning |
+|---|---|
+| `backend`, `method`, `problem_kind` | The backend that `method` resolves to (as for `solve`) and the problem kind |
+| `layout_kind` | Which payload follows (table below) |
+| `summary` | Labelled key figures, in display order |
+| `payload` | The geometry, in nm and world coordinates |
+| `estimate` | The backend's `estimate` for the same problem (on the CPU) |
+| `warnings` | The planning code's and the estimate's warnings |
+| `error` | The library's refusal of the problem, or `null`. The geometry is still returned where it can be computed, for example for a graded FDTD grid with a Gaussian beam. |
+
+A backend the problem does not suit raises, as `solve` would. Backends with nothing to discretise (TMM,
+quasistatic, circuits) return `layout_kind: "none"` and the estimate's figures in `summary`. Plugins can answer
+by overriding `Backend.discretization(problem, device)`.
+
+## Payloads
+
+| `layout_kind` | Backends | Payload |
+|---|---|---|
+| `yee_grid` | FDTD scattering, emission | `grid` (`kind`, `shape`, `cells`, `nodes_nm` per axis, min/max spacing, `max_ratio`), `domain_nm`, `pml`, `boxes` (TFSF, total- and scattered-field flux; emission: the radiated-power box), `regions` (from `grid: "auto"` and `mesh_override`), `symmetry` (mirror planes, `planes_nm`). The grid is whole; the run steps one mirror image of it (`estimate.cells`). |
+| `unit_cell` | FDTD periodic, layer stacks | Cell nodes `x_nm`, `y_nm`, `z_nm` (depth below the top of the stack), `planes_nm` (reflection monitor, source, stack top and bottom, transmission monitor), `pml_cells`, layer tops and thicknesses |
+| `device_grid` | FDTD and FDFD devices, inverse design | `nodes_nm` per axis, PML inner faces, `ports` (`axis`, `direction`, `source_nm`, FDTD `monitor_nm`, `window_nm`, `num_modes`), `two_d`; inverse design: `design_regions` (shape, extent, filter radius in cells) |
+| `dipole_lattice` | DDA | `points_nm` (occupied dipoles, subsampled by `stride` beyond 20 000), `material_slot`, `spacing_nm`, `dipoles_per_diameter`, `grid`, `n_dipoles`, `extrapolate` |
+| `surface_mesh` | BEM | `verts_nm`, `tris` (subsampled beyond 40 000), `tri_surface`, `mesh_size_nm`, `n_triangles`, `n_edges` |
+| `multipoles` | Mie (`lightsmith-mie`, `miepython`), T-matrix | Mie: `n_max` and `size_parameter` per wavelength and the rule used; T-matrix: `lmax` per particle, `modes`, `lmax_global` |
+| `harmonics` | RCWA | `harmonics` (m, n), `orders_max`, `layers` (each uniform in z: the problem's own layers) |
+| `cross_section_grid` | FDE | `x_nm`, `y_nm`, spacings, `pml_cells`, `symmetry`, `boundary`, `num_modes` |
+| `cells` | EME, BPM | `axis`, `lo_nm`, `hi_nm`, `cells` (`start_nm`, `stop_nm`; BPM: `steps`, `dz_nm`), the cross-section grid; EME: `modes_per_cell`; BPM: `step_nm` |
+| `plane_waves` | PWE | `k_reduced`, `k_distance`, `k_labels`, per polarisation the solver, plane-wave count, matrix size, FFT grid and (dense) G indices |
+| `none` | TMM, quasistatic, circuits | `note` |

{lightsmith-0.2.0 → lightsmith-0.3.0}/docs/index.md

@@ -2,9 +2,8 @@
 
 **The open photonics suite — GPU-native, differentiable, and built for AI agents.**
 
-Lightsmith lets you describe a photonics problem once, as typed JSON, and solve it with the method that
-fits. It covers nanoparticles, thin films, metasurfaces, waveguides, photonic crystals, devices and
-circuits. Every result uses the same units and conventions and records its provenance, so you can
+Lightsmith lets you describe a photonics problem once and solve it with whichever method fits. It covers
+nanoparticles, thin films, metasurfaces, waveguides, photonic crystals, devices and circuits. Every result uses the same units and conventions and records its provenance, so you can
 cross-check methods directly. Many solvers run on a GPU and can be differentiated, which is what powers
 inverse design.
 
@@ -21,7 +20,7 @@ cmp = ls.compare(sim, ["mie", "dda", "fdtd"])   # cross-check methods
 ```
 
 !!! warning "Pre-alpha"
-    Lightsmith 0.1 is pre-alpha, so the API may still change between minor versions. Each solver page
+    Lightsmith 0.2 is pre-alpha, so the API may still change between minor versions. Each solver page
     lists the validation behind it, with numbers taken from the test suite. Read the `warnings` on every
     result before you trust its numbers.
 
@@ -33,12 +32,15 @@ cmp = ls.compare(sim, ["mie", "dda", "fdtd"])   # cross-check methods
 | [`layer_stack`](problems/layer-stack.md): thin films | [TMM](solvers/tmm.md), [RCWA](solvers/rcwa.md), FDTD | ✅ | TMM, RCWA |
 | [`periodic`](problems/periodic.md): gratings, metasurfaces | [RCWA](solvers/rcwa.md), FDTD (rectangular lattices) | ✅ | RCWA |
 | [`mode`](problems/mode.md): waveguide cross-sections | [FDE](solvers/fde.md) | — | — |
-| [`device`](problems/device.md): S-parameters between ports | [EME](solvers/eme.md), [BPM](solvers/bpm.md), [FDFD](solvers/fdfd.md) (2D) | BPM, FDFD | FDFD (adjoint) |
+| [`device`](problems/device.md): S-parameters between ports | [EME](solvers/eme.md), [BPM](solvers/bpm.md), [FDFD](solvers/fdfd.md) | BPM, FDFD | FDFD (adjoint) |
 | [`bands`](problems/bands.md): photonic crystals | [PWE](solvers/pwe.md) | ✅ | dense path |
 | [`circuit`](problems/circuit.md): netlists of compact models | [S-matrix circuit solver](solvers/circuit.md) | ✅ | ✅ |
 | [`optimization`](problems/optimization.md): inverse design | [Topology optimisation on FDFD](solvers/inverse.md) | ✅ | — |
 
-## Three ways in, all JSON
+## Three ways in
+
+All three take the same problem description, so a problem you build in Python can be saved to a file,
+run from the shell, or handed to an agent unchanged.
 
 - **Python**: `import lightsmith as ls`, then `ls.solve`, `ls.estimate` and `ls.compare`. See the
   [quick start](quickstart.md).

{lightsmith-0.2.0 → lightsmith-0.3.0}/docs/install.md

@@ -83,7 +83,8 @@ lightsmith doctor
 ```
 
 The output should show the GPU under `"cuda_gpus"`, and `"auto_device"` should name `cuda:0`. With
-`device="auto"`, which is the default, solvers that support a GPU use it. Pass `device="cpu"` to force the
+`device="auto"`, which is the default, solvers that support a GPU use it, unless `estimate` says the problem
+will not fit in the GPU's free memory: then the solve runs on the CPU and says so in `warnings`. Pass `device="cpu"` to force the
 CPU, `device="cuda:1"` to pick a specific GPU, or `device="torch-cpu"` to run the PyTorch code path on
 the CPU, for example to get gradients without a GPU.
 

{lightsmith-0.2.0 → lightsmith-0.3.0}/docs/materials.md

@@ -1,16 +1,16 @@
 # Materials
 
-You can use a material anywhere a problem asks for one. Every material is a JSON object whose `kind` sets
-the model. Permittivities follow the `exp(-iωt)` convention, so loss means `Im(ε) > 0` and `Im(n) > 0`.
+You can use a material anywhere a problem asks for one: pass one of the models below. Permittivities
+follow the `exp(-iωt)` convention, so loss means `Im(ε) > 0` and `Im(n) > 0`.
 
-| `kind` | Model | Fields |
+| Model | Fields | Saved as `kind` |
 |---|---|---|
-| `constant_index` | `ConstantIndex` | `n_real`, `n_imag` (≥ 0) |
-| `constant_permittivity` | `ConstantPermittivity` | `eps_real`, `eps_imag` (≥ 0) |
-| `drude` | `Drude` | `eps_inf`, `wp_ev`, `gamma_ev`: ε(ω) = ε∞ − ωp² / (ω² + iγω), with energies in eV |
-| `drude_lorentz` | `DrudeLorentz` | `eps_inf`, `wp_ev`, `gamma_ev`, `poles: [{delta_eps, omega0_ev, gamma_ev}]` |
-| `tabulated` | `Tabulated` | `wavelength_nm`, `n_real`, `n_imag`, `source`: linear interpolation, no extrapolation |
-| `library` | `LibraryMaterial` | `name`, `dataset`: a bundled measured dataset (below) |
+| `ConstantIndex` | `n_real`, `n_imag` (≥ 0) | `constant_index` |
+| `ConstantPermittivity` | `eps_real`, `eps_imag` (≥ 0) | `constant_permittivity` |
+| `Drude` | `eps_inf`, `wp_ev`, `gamma_ev`: ε(ω) = ε∞ − ωp² / (ω² + iγω), with energies in eV | `drude` |
+| `DrudeLorentz` | `eps_inf`, `wp_ev`, `gamma_ev`, `poles: [{delta_eps, omega0_ev, gamma_ev}]` | `drude_lorentz` |
+| `Tabulated` | `wavelength_nm`, `n_real`, `n_imag`, `source`: linear interpolation, no extrapolation. Data in any order is sorted by wavelength; duplicate wavelengths are refused. | `tabulated` |
+| `LibraryMaterial` | `name`, `dataset`: a bundled measured dataset (below) | `library` |
 
 ## Bundled datasets
 
@@ -47,7 +47,7 @@ material's default is filled in, so a stored spec stays reproducible.
 ```python
 import lightsmith as ls
 
-ls.list_materials("Au")                      # datasets, ranges, references, ready-made JSON
+ls.list_materials("Au")                      # datasets, ranges and references
 gold = ls.LibraryMaterial(name="Au", dataset="McPeak")
 tab = ls.load_material("Au")                 # the default dataset as a Tabulated material
 ```