Architecture Overview

GDS in, S-parameters out, with every engine behind one contract.

layout (GDS / gdsfactory / SiEPIC)
    │  lyprocessor · layout.gdsfactory        ports auto-detected
    ▼
Component  ─────────  Technology (YAML, schema v2: named materials)
    │
    ▼
Solver ABC (solvers.base) ── registry + entry points
    │        validate() · build() · estimate()   [offline, free]
    │        run()                                [the only spending step]
    ▼
SMatrix ── checks (reciprocity/passivity) · .dat / Touchstone / HDF5 / npz
    │
    ▼
plotting · convergence.sweep · validation.validate_across · caching

Core modules

geometry

Component, Structure (flat, role-tagged: device / substrate / superstrate), Port (with port-extension stubs through the boundary), Region.

technology / materials.rii

Pydantic-validated technology files. Schema v2 defines named materials once (neutral nk/rii + per-engine hints) and layers reference them; gds-fdtd convert-tech migrates v1 files.

lyprocessor / simprocessor / layout.gdsfactory

GDS loading via KLayout (SiEPIC pin conventions), component assembly, and gdsfactory (>= 9) conversion.

spec

SimulationSpec — every numeric simulation setting, validated, in package-wide units (µm / degrees / Hz).

smatrix

The canonical SMatrix container plus the internal Lumerical-format .dat reader/writer (_sparams) it interoperates with.

Solver layer

solvers.base

The Solver ABC and registry. Constructors are cheap and pure; validate/build/estimate are offline; only run() spends. Third-party engines register via the gds_fdtd.solvers entry-point group (see Adding your own solver).

solvers.tidy3d / solvers.lumerical / solvers.beamz

The engine adapters. The tidy3d adapter drives an internal scene builder (solvers/_tidy3d_base + solvers/_tidy3d_engine); the Lumerical adapter generates .lsf directly; beamz builds a JAX FDTD grid. The pre-0.5 solver_tidy3d / solver_lumerical modules were removed in 0.6.0.

grid / modes / extraction

The kernel-engine pipeline: permittivity rasterization with sub-pixel averaging, local mode solving, and bidirectional mode-overlap extraction — for engines that only accept raw permittivity arrays.

Orchestration

convergence / caching / validation

Field sweeps with converged-value recommendation; job-hash result caching (repeat runs are free); cross-engine agreement reports.

execution / cli

Serializable JobSpec + local/subprocess backends and the gds-fdtd command-line interface — the remote-compute surface (see Running gds_fdtd jobs on remote compute).

errors / settings / logging_config

One exception hierarchy (GdsFdtdError), GDS_FDTD_* environment configuration, and package-scoped logging (text or JSON lines).