witwin-maxwell 0.0.1__tar.gz → 0.2.0__tar.gz

witwin_maxwell-0.2.0/.github/workflows/publish-witwin-maxwell.yml

@@ -0,0 +1,285 @@
+name: Build and publish witwin-maxwell
+
+on:
+  push:
+    branches:
+      - master
+      - "codex/**"
+  pull_request:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  validate_release:
+    if: github.event_name != 'release' || (startsWith(github.event.release.tag_name, 'witwin-maxwell-v') && !github.event.release.prerelease)
+    name: Validate release
+    runs-on: ubuntu-latest
+    outputs:
+      package_dir: ${{ steps.package_dir.outputs.path }}
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Resolve package directory
+        id: package_dir
+        shell: bash
+        run: |
+          if [ -f pyproject.toml ]; then
+            echo "path=." >> "$GITHUB_OUTPUT"
+          elif [ -f maxwell/pyproject.toml ]; then
+            echo "path=maxwell" >> "$GITHUB_OUTPUT"
+          else
+            echo "Unable to find pyproject.toml for the witwin-maxwell package." >&2
+            exit 1
+          fi
+
+      - name: Validate release tag and package version
+        if: github.event_name == 'release'
+        shell: bash
+        env:
+          PACKAGE_DIR: ${{ steps.package_dir.outputs.path }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          python - <<'PY'
+          import os
+          import re
+          import sys
+          import tomllib
+          from pathlib import Path
+
+          tag = os.environ["RELEASE_TAG"]
+          match = re.fullmatch(r"witwin-maxwell-v(?P<version>[0-9A-Za-z.+_-]+)", tag)
+          if match is None:
+              print(f"Release tag '{tag}' must match 'witwin-maxwell-v<version>'.", file=sys.stderr)
+              raise SystemExit(1)
+
+          expected_version = match.group("version")
+          pyproject_path = Path(os.environ["PACKAGE_DIR"]) / "pyproject.toml"
+          data = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+
+          project = data["project"]
+          package_name = project["name"]
+          package_version = project["version"]
+
+          if package_name != "witwin-maxwell":
+              print(f"Expected package name 'witwin-maxwell', found '{package_name}'.", file=sys.stderr)
+              raise SystemExit(1)
+
+          if package_version != expected_version:
+              print(
+                  f"Release tag version '{expected_version}' does not match pyproject version '{package_version}'.",
+                  file=sys.stderr,
+              )
+              raise SystemExit(1)
+
+          print(f"Validated {package_name} {package_version} from {pyproject_path}.")
+          PY
+
+  build_cuda_wheels:
+    name: Build CUDA wheel / ${{ matrix.os }} / py${{ matrix.python_version }}
+    needs: validate_release
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04, windows-2022]
+        python_version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python_version }}
+
+      - name: Free disk space (Linux)
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          echo "Disk before cleanup:"; df -h /
+          sudo rm -rf /usr/share/dotnet /opt/ghc /usr/local/lib/android \
+            /usr/local/share/boost /opt/hostedtoolcache/CodeQL \
+            /usr/local/share/powershell /usr/share/swift || true
+          sudo docker image prune --all --force || true
+          echo "Disk after cleanup:"; df -h /
+
+      - name: Install CUDA Toolkit
+        uses: Jimver/cuda-toolkit@v0.2.29
+        with:
+          cuda: "12.5.0"
+          method: local
+          log-file-suffix: "${{ runner.os }}-py${{ matrix.python_version }}"
+
+      - name: Set up MSVC
+        if: runner.os == 'Windows'
+        uses: ilammy/msvc-dev-cmd@v1
+        with:
+          arch: x64
+
+      - name: Export Windows CUDA_HOME
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $cudaRoot = $env:CUDA_PATH
+          if (-not $cudaRoot) {
+            $nvcc = (Get-Command nvcc -ErrorAction Stop).Source
+            $cudaRoot = Split-Path (Split-Path $nvcc -Parent) -Parent
+          }
+          "CUDA_HOME=$cudaRoot" >> $env:GITHUB_ENV
+          "CUDA_PATH=$cudaRoot" >> $env:GITHUB_ENV
+          "CUDA_ROOT=$cudaRoot" >> $env:GITHUB_ENV
+          "CUDA_BIN_PATH=$cudaRoot" >> $env:GITHUB_ENV
+
+      - name: Show toolchain
+        shell: bash
+        run: |
+          python --version
+          nvcc --version
+          command -v cl || true
+
+      - name: Install CUDA extension build dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools wheel ninja numpy
+          python -m pip install torch==2.6.0 --index-url https://download.pytorch.org/whl/cu124
+          python -m pip install build
+
+      - name: Build packaged FDTD CUDA extension
+        env:
+          MAX_JOBS: "2"
+          TORCH_CUDA_ARCH_LIST: "7.0;8.0;8.6;8.9;9.0+PTX"
+          WITWIN_MAXWELL_FDTD_CUDA_BUILD_DIR: ${{ runner.temp }}/witwin_maxwell_fdtd_cuda
+        run: |
+          python scripts/build_fdtd_cuda_prebuilt.py --verbose
+
+      - name: Build platform wheel
+        shell: bash
+        env:
+          PACKAGE_DIR: ${{ needs.validate_release.outputs.package_dir }}
+        run: |
+          python -m build --wheel "$PACKAGE_DIR"
+
+      - name: Normalize Linux wheel platform tag
+        if: runner.os == 'Linux'
+        shell: bash
+        env:
+          PACKAGE_DIR: ${{ needs.validate_release.outputs.package_dir }}
+        run: |
+          # PyPI rejects the raw linux_x86_64 tag; the extension is built on the
+          # ubuntu-22.04 runner (glibc 2.35), so retag to the matching manylinux
+          # tag. torch/CUDA runtime libraries are runtime dependencies and stay
+          # unbundled, so no auditwheel repair is required.
+          shopt -s nullglob
+          for whl in "$PACKAGE_DIR"/dist/*-linux_x86_64.whl; do
+            echo "Retagging $whl"
+            python -m wheel tags --platform-tag manylinux_2_35_x86_64 --remove "$whl"
+          done
+          ls -l "$PACKAGE_DIR"/dist
+
+      - name: Smoke install prebuilt wheel
+        shell: bash
+        env:
+          PACKAGE_DIR: ${{ needs.validate_release.outputs.package_dir }}
+          WITWIN_MAXWELL_FDTD_CUDA_PREBUILT: "1"
+          WITWIN_MAXWELL_FDTD_CUDA_BUILD_DIR: ${{ runner.temp }}/missing_prebuilt_build_dir
+        run: |
+          python -m pip uninstall -y witwin-maxwell || true
+          python -m pip install --no-deps "$PACKAGE_DIR"/dist/*.whl
+          python - <<'PY'
+          import importlib.util
+          import site
+          from pathlib import Path
+
+          candidates = []
+          for root in site.getsitepackages() + [site.getusersitepackages()]:
+              candidates.append(Path(root) / "witwin" / "maxwell" / "fdtd" / "cuda" / "build.py")
+          build_path = next((path for path in candidates if path.exists()), None)
+          assert build_path is not None, f"installed build.py not found in {candidates}"
+
+          spec = importlib.util.spec_from_file_location("witwin_maxwell_fdtd_cuda_build", build_path)
+          module = importlib.util.module_from_spec(spec)
+          spec.loader.exec_module(module)
+
+          path = module.prebuilt_extension_path()
+          assert path.exists(), f"missing packaged prebuilt extension: {path}"
+          extension = module.build_extension()
+          print(f"Loaded packaged FDTD CUDA extension from {extension.__file__}")
+          PY
+
+      - name: Upload wheel artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheel-${{ matrix.os }}-py${{ matrix.python_version }}
+          path: ${{ needs.validate_release.outputs.package_dir }}/dist/*.whl
+          if-no-files-found: error
+
+  build_sdist:
+    name: Build source distribution
+    needs: validate_release
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build distributions
+        shell: bash
+        env:
+          PACKAGE_DIR: ${{ needs.validate_release.outputs.package_dir }}
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build --sdist "$PACKAGE_DIR"
+
+      - name: Upload source distribution artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: ${{ needs.validate_release.outputs.package_dir }}/dist/*.tar.gz
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    if: github.event_name == 'release'
+    needs:
+      - build_cuda_wheels
+      - build_sdist
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/project/witwin-maxwell/
+
+    steps:
+      - name: Download wheel artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: wheel-*
+          path: dist
+          merge-multiple: true
+
+      - name: Download source distribution artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          skip-existing: true

{witwin_maxwell-0.0.1 → witwin_maxwell-0.2.0}/.gitignore

@@ -172,6 +172,9 @@ venv.bak/
 # mkdocs documentation
 /site
 .slangtorch_cache/
+.*_runtime_*.slang
+witwin/maxwell/fdtd/cuda/prebuilt/*.pyd
+witwin/maxwell/fdtd/cuda/prebuilt/*.so
 .fdtd_runtime_*.slang
 .adjoint_kernels_runtime_*.slang
 *.png
@@ -179,6 +182,7 @@ venv.bak/
 *.npz
 
 settings.local.json
+.claude/
 
 # mypy
 .mypy_cache/

{witwin_maxwell-0.0.1 → witwin_maxwell-0.2.0}/FEATURE_LIST.md

@@ -21,10 +21,16 @@ This document tracks the current user-visible capabilities of the `maxwell` pack
 
 - `Domain` with explicit 3D bounds and `from_domain_range(...)`
 - `GridSpec.uniform(...)` for isotropic grids
-- `GridSpec.anisotropic(...)` for nonuniform `dx`, `dy`, `dz`
-- `GridSpec.spacing` always returns `(dx, dy, dz)`, with `GridSpec.is_uniform` for uniform-grid checks
+- `GridSpec.anisotropic(...)` for per-axis constant `dx`, `dy`, `dz`
+- `GridSpec.custom(x_coords, y_coords, z_coords)` for nonuniform (graded) Yee grids from explicit node coordinates: any 1D float array-likes (list / NumPy / torch), validated per axis (strictly increasing, finite, at least two nodes) and stored as read-only float64 masters; a uniform axis is expressed by uniformly spaced coords, and the `Domain` bounds must equal the coordinate extents
+- `GridSpec.auto(min_steps_per_wavelength=..., wavelength=None, max_ratio=..., override_structures=..., layer_refinement=...)` for adaptive (AutoGrid) meshing: at prepare time every structure and `MaterialRegion` AABB face snaps to a cell boundary, each face-bounded interval is stepped at `wavelength / (n_max * min_steps_per_wavelength)` using the maximum overlapping refractive index at the meshing wavelength (material regions contribute `sqrt(max(eps_bounds) * max(mu_bounds))`), intervals are filled with uniform or geometrically graded cells with a global adjacent-cell ratio bound of `max_ratio`, and the result materializes through the same nonuniform-grid path as `GridSpec.custom` (single downstream representation); the meshing wavelength defaults to the highest source frequency in the scene, or an explicit `wavelength=`
+- `MeshOverrideStructure(geometry, dl)` mesh overrides for `GridSpec.auto`: a scalar or per-axis `(dx, dy, dz)` maximum step enforced inside the geometry's axis-aligned bounding box
+- `LayerRefinementSpec(min_cells=..., axes=None)` for `GridSpec.auto`: any structure-bounded interval thinner than `min_cells` local target steps receives at least `min_cells` cells along the covered axes
+- `GridSpec.is_custom`, `GridSpec.is_auto`, `GridSpec.min_spacing`, and `GridSpec.axis_coords(...)` for nonuniform-grid introspection
+- `GridSpec.spacing` returns `(dx, dy, dz)` for uniform specs, with `GridSpec.is_uniform` for uniform-grid checks; both raise on `GridSpec.custom` and `GridSpec.auto`, as do the scalar `Scene.dx/dy/dz` / `Scene.grid_spacing` properties (use `scene.x/y/z`, the half-grid coordinates, or `grid.min_spacing` instead)
 - `BoundarySpec.none()`, `BoundarySpec.pml(...)`, `BoundarySpec.periodic()`, `BoundarySpec.bloch(...)`, `BoundarySpec.pec()`, and `BoundarySpec.pmc()`
 - Per-face boundary configuration through `BoundarySpec.faces(...)` and direct `BoundarySpec(kind=..., x=..., x_low=..., ...)` overrides, including global defaults plus per-axis or per-face specialization
+- `BoundarySpec.bloch_wavevector="auto"` marker for solver-resolved Bloch phase workflows during FDTD preparation
 - Public `BoundaryKind` literal type for boundary-mode selection across declarative scene APIs
 - Shared `witwin.core.Structure` records pairing geometry and material, with `priority`, `enabled`, and `tags`
 - `Geometry.with_material(...)` convenience path returns a shared `Structure`
@@ -33,14 +39,17 @@ This document tracks the current user-visible capabilities of the `maxwell` pack
 - Scene-level modal port assembly with `Scene.add_port(...)`, plus `Scene.resolved_sources()` / `Scene.resolved_monitors()` to materialize first-class `ModePort` objects into the standard `Scene -> Simulation -> Result` workflow
 - `Scene.clone(...)` for scene-preserving validation, benchmarking, and device-transfer workflows
 - `Scene(...)` defaults to `device="cuda"` and requires an explicit `device="cpu"` override for scene-only CPU workflows
-- Optional low-face symmetry specification on `Scene(symmetry=(..., ..., ...))` with per-axis `None` / `"PEC"` / `"PMC"`
-- Optional subpixel material averaging via `Scene(subpixel_samples=...)`, accepting only `int` or `(sx, sy, sz)`
+- Optional domain symmetry on `Scene(symmetry=(..., ..., ...))` with per-axis `None` / `"PEC"` / `"PMC"` on either domain face, via bare mode strings (low face by default) or explicit `(mode, face)` pairs such as `("PEC", "high")`, folding the domain about any axis at either face with matching result-side expansion
+- Optional subpixel material averaging via `Scene(subpixel_samples=...)`, accepting `int`, `(sx, sy, sz)`, or a `SubpixelSpec(samples=..., averaging=..., pec=...)` policy object; the bare `int` / tuple form keeps the legacy arithmetic / staircase behavior bitwise unchanged
+- `SubpixelSpec(averaging="polarized")` enables Kottke normal-projection subpixel averaging (harmonic permittivity/permeability along the SDF interface normal, arithmetic tangentially) for `eps` and `mu` components, flowing through both FDFD and FDTD from the shared material compiler
+- `SubpixelSpec(pec="conformal")` enables stable partial-fill conformal PEC edge treatment for in-domain `Material.pec()` structures in FDTD
 - Solver-side compiled scene inspection via `Simulation.prepare()`, where `prepared.solver.scene` materializes Yee-grid dimensions, lazy meshgrid allocation, material compilation, and orthogonal material cross sections without storing that state on the public `Scene`
 
 ## Geometry
 
 - Analytic geometry primitives:
   `Box`, `Sphere`, `Cylinder`, `Ellipsoid`, `Cone`, `Pyramid`, `Prism`, `Torus`, `HollowBox`
+- Extruded polygon geometry via `PolySlab(vertices, bounds, axis, sidewall_angle, reference_plane)` with Tidy3D-style linear sidewall taper and even-odd interior rule for non-convex cross-sections, plus `ComplexPolySlab(loops, ...)` for self-intersecting and multi-loop (hole-carving) cross-sections
 - Shared core geometry constructors use `position=...` consistently across analytic primitives, `Mesh`, and `SMPLBody`
 - Shared core geometry constructors default to `device=None`, while `Scene(...)` owns device placement and defaults to CUDA
 - Rotation support for applicable analytic geometries
@@ -70,12 +79,16 @@ This document tracks the current user-visible capabilities of the `maxwell` pack
 - Structure overlap resolution uses `Structure.priority` first, then append order among equal-priority structures
 - Occupancy-based material blending on the scene grid, with SDF-driven soft occupancy for shared `Box`, `Sphere`, `Cylinder`, `Torus`, and `HollowBox`
 - Phase-1.5 primitive SDF coverage for shared `Ellipsoid`, `Cone`, `Pyramid`, and `Prism`
+- Differentiable SDF occupancy for `PolySlab` and `ComplexPolySlab`, with gradients through polygon vertices, axis bounds, and sidewall angle
 - Differentiable mesh occupancy compilation through shared mesh signed-distance evaluation, including Slang-accelerated CUDA forward/backward distance-sign queries for watertight solid fill, geometry-state-aware static mesh SDF caching, cached BVH acceleration for larger static CUDA meshes, and shared surface-band modes
 - Supersampled voxel averaging for smoother material interfaces on partial cells
+- Polarized (Kottke normal-projection) subpixel averaging for `eps` and `mu`, using SDF-gradient interface normals estimated by central finite differences on the node grid (differentiable in geometry parameters), reducing normal-field error at high-contrast interfaces
+- In-domain perfect-electric-conductor material via `Material.pec(name=None)` / `Material.is_pec`, compiled to a differentiable union PEC occupancy grid and enforced in FDTD through per-edge open-fraction coefficient scaling (`staircase` hard edge or `conformal` stable partial fill)
 
 ## Sources
 
 - `CW`, `GaussianPulse`, and `RickerWavelet` source-time definitions
+- `CustomSourceTime` arbitrary temporal waveform from a sampled `(times, amplitudes)` table or a callable `fn`, evaluated on the solver time grid through the Python scalar injection path (no CUDA kernel change)
 - `PointDipole` source definition with `source_time` and selectable `profile="gaussian"|"ideal"`
 - `PointDipole`, `ModeSource`, `ModeMonitor`, and `ModePort` use `position=...` as the public spatial-location argument
 - `PointDipole` width compensation keeps narrow-source injected strength consistent with the default regularization width in FDTD/FDFD workflows
@@ -83,15 +96,53 @@ This document tracks the current user-visible capabilities of the `maxwell` pack
 - `PlaneWave` soft source for analytical plane-wave injection on an auto-placed source plane
 - `PlaneWave` soft source uses a single-plane directional `E/H` equivalent-current injector with calibrated Tidy3D-style incident-power scaling
 - `GaussianBeam` soft source for analytical Gaussian-beam injection with configurable waist and focus
+- `AstigmaticGaussianBeam` soft source for elliptical Gaussian-beam injection with independent per-axis waist `(w0_u, w0_v)` and per-axis focal offsets `focus_u`/`focus_v`, reducing exactly to `GaussianBeam` for isotropic inputs and reusing the same soft and TFSF injection paths
+- `UniformCurrentSource(size, polarization, source_time, center=...)` for a uniform additive electric current filling an axis-aligned box region; radiated power scales as the square of the drive amplitude
+- `CustomCurrentSource(current_dataset, source_time)` injects an arbitrary volume electric-current (`Jx/Jy/Jz`) and magnetic-current (`Mx/My/Mz`) distribution from a `CurrentDataset` (rectilinear coordinate arrays plus per-component tensors), trilinearly interpolated onto the Yee grid
+- `CustomFieldSource(field_dataset, source_time)` replays a tangential `E/H` distribution on a plane by converting it into equivalent surface currents `J = n x H`, `M = -n x E` (normal along the single-sample `FieldDataset` axis), reproducing the corresponding directional plane wave
 - Experimental `ModeSource` soft source for axis-aligned FDTD waveguide launching, using a full-vector generalized 2D eigenmode solve for forward source-plane assembly on real isotropic apertures, dense and sparse forward backends for that generalized solve, and a retained experimental torch-differentiable scalar eigensolve path for current trainable FDTD scenes
-- Experimental `TFSF(bounds=...)` injection descriptor for `PlaneWave` and `GaussianBeam`, with validated axis-aligned `PlaneWave` support for `CW` and `GaussianPulse`, and validated CW oblique `PlaneWave` support
-- CUDA `PlaneWave` TFSF forward stepping uses Slang auxiliary-line updates and fused patch-application kernels to reduce per-step launch overhead
+- Experimental `TFSF(bounds=...)` injection descriptor for `PlaneWave`, `GaussianBeam`, and `AstigmaticGaussianBeam`, with validated axis-aligned `PlaneWave` support for `CW` and `GaussianPulse`, and validated CW oblique `PlaneWave` support
+- Experimental `TFSF.slab(axis="z", bounds=...)` injection descriptor for grating-oriented CW `PlaneWave` workflows, spanning the transverse Bloch unit cell during solver preparation for periodic grating illumination
+- CUDA `PlaneWave` TFSF forward stepping uses native CUDA auxiliary-line updates and fused patch-application kernels to reduce per-step launch overhead
 - `GaussianBeam` `TFSF` remains experimental and currently uses the analytical profile provider rather than the future angular-spectrum / discrete-face engine
 - Polarization specified by field name (`"Ex"`, `"Ey"`, `"Ez"`) or explicit 3-vector
 - Source amplitude and phase carried by `source_time`; spatial sources keep width / beam parameters and optional name
 - Multiple sources per scene
 - Source compilation uses `compile_fdfd_sources(...)` / `compile_fdtd_sources(...)` list-based interfaces across both solvers
 
+## Grating TFSF Example
+
+```python
+import witwin.maxwell as mw
+
+scene = mw.Scene(
+    domain=mw.Domain(bounds=((-0.5, 0.5), (-0.5, 0.5), (-1.0, 1.0))),
+    grid=mw.GridSpec.uniform(0.05),
+    boundary=mw.BoundarySpec.faces(
+        default="pml",
+        num_layers=12,
+        strength=1.0,
+        x="bloch",
+        y="bloch",
+        z="pml",
+        bloch_wavevector="auto",
+    ),
+)
+
+scene.add_source(
+    mw.PlaneWave(
+        direction=(0.25, 0.0, 0.9682458366),
+        polarization=(1.0, 0.0, -0.2581988897),
+        source_time=mw.CW(frequency=200e12),
+        injection=mw.TFSF.slab(axis="z", bounds=(-0.4, 0.4)),
+    )
+)
+
+scene.add_monitor(mw.FluxMonitor("transmission", axis="z", position=0.7))
+
+result = mw.Simulation.fdtd(scene, frequencies=[200e12]).run()
+```
+
 ## Monitors
 
 - `PointMonitor` for point sampling of selected electric or magnetic field components
@@ -99,7 +150,12 @@ This document tracks the current user-visible capabilities of the `maxwell` pack
 - `FinitePlaneMonitor` for first-class finite rectangular plane sampling with explicit `position=(x, y, z)` and `size=(sx, sy, sz)` on a zero-thickness axis
 - `ClosedSurfaceMonitor` for first-class finite closed Huygens-surface workflows, including `ClosedSurfaceMonitor.box(...)` and custom multi-face axis-aligned surfaces built from `FinitePlaneMonitor` faces
 - `FluxMonitor` for plane-integrated power / flux extraction from tangential `E/H` fields
+- `FieldTimeMonitor` for raw time-domain FDTD field recording (point, plane, or volume region) with `start` / `stop` / `interval` sampling controls, returning the sample-time tensor `t` and per-component GPU buffers through `Result.monitor(...)`
+- `FluxTimeMonitor` for instantaneous time-domain Poynting flux (`E x H`) recorded on an axis-aligned plane with `start` / `stop` / `interval` sampling controls, returning the sample-time tensor `t` and the flux time series through `Result.monitor(...)`
 - Experimental `ModeMonitor` for first-class modal decomposition on an axis-aligned port plane, reusing the current `ModeSource` mode specification and returning forward / backward modal amplitudes and power through `Result.monitor(...)`
+- Experimental `DiffractionMonitor` for grating diffraction-order decomposition on an axis-aligned periodic unit-cell plane, returning per-order `(m, n)` complex tangential amplitudes, per-order Poynting power, propagating / evanescent flags, and diffraction angles through `Result.monitor(...)`, with reciprocal lattice and light-cone cutoff derived from the transverse periods and the resolved Bloch wavevector
+- `PermittivityMonitor` and `MediumMonitor` for first-class point / plane / volume sampling of the compiled material properties (`eps`, plus `mu` and `sigma_e` for `MediumMonitor`), resolved from the compiled material tensors at result time through `Result.monitor(...)` without requesting any time stepping or extra DFT frequencies
+- Experimental `DipoleEmissionMonitor` for the power a named `PointDipole` delivers to the field (`P = -(1/2) Re(conj(J) . E)`), formed from the co-located electric-field DFT at the dipole cell and the injected source current spectrum, returning per-frequency `power_delivered` through `Result.monitor(...)`; combine a structured run with a vacuum run through `maxwell.postprocess.purcell_factor(...)` to obtain the Purcell factor / local density of states
 - Optional per-monitor `frequencies=` on plane and modal monitors / ports
 - Named monitor results returned through the unified `Result` object
 - Multi-component plane monitors with aggregated `Result.monitor(...)` payloads and collocated tangential grids for postprocessing workflows
@@ -124,9 +180,18 @@ This document tracks the current user-visible capabilities of the `maxwell` pack
 - Axis-aligned diagonal electric anisotropy and diagonal `sigma_e_tensor` support in the Yee-grid operator
 - Per-face `none` / `pml` boundary selection, including one-sided and mixed-axis PML layouts
 - Explicit fast-fail validation for unsupported magnetic response and Kerr media
-- Configurable GMRES settings via `GMRES(max_iter, tol, restart, solver_type)`
+- Configurable GMRES settings via `GMRES(max_iter, tol, restart, solver_type, preconditioner)`
+- GPU-native preconditioners for the iterative solvers: `none`, `jacobi` (default), `ssor` (relaxation via `GMRES(ssor_omega=...)`, default 0.8), `ilu` (ILU(0); unstable on the indefinite curl-curl operator — see `benchmark/FDFD_PERFORMANCE.md`), and `ams` (experimental in-repo Hiptmair–Xu auxiliary-space preconditioner with geometric multigrid; measured non-contractive on the indefinite time-harmonic operator — see the module docstring for its scope)
+- Double-precision iterative solves via `GMRES(precision="double")`: the Krylov recurrences and preconditioner run in complex128 while assembly and returned fields stay complex64; removes the float32 round-off stagnation (measured: `sqmr`+`ssor` converges to 1e-7 at 48³ where single precision stalls at ~2e-2)
+- Supported `solver_type` values: `gmres`, `cg`, `direct`, plus in-repo GPU Krylov engines `bicgstab`, `tfqmr`, `idr` (IDR(s)), and `sqmr` (simplified QMR; exploits the complex-symmetric system)
+- The FDFD system is assembled in a symmetrized UPML formulation (exactly complex-symmetric via a diagonal similarity), which also measures far lower PML reflection than the previous discretization; the adjoint solve reuses the forward factorization/preconditioner as a consequence
+- `direct` solver backed by NVIDIA cuDSS (`pip install witwin-maxwell[direct]`): factorize-once / solve-many with the factorization cached on the prepared solver and reused across source changes; complex64 LU plus iterative refinement
+- Direct-solve reuse composes with `solver.set_frequency(...)`, which releases the stale factorization automatically
 - Typed FDFD solver configuration through `FDFDConfig(solver=..., enable_plot=..., verbose=...)`
 - Prepared execution via `Simulation.prepare()` before running
+- Differentiable FDFD: scenes with trainable parameters (SceneModule parameters, `MaterialRegion` densities, trainable geometry tensors) route through an adjoint gradient bridge, so `loss.backward()` on `Result` fields propagates to material and geometry inputs; the adjoint solve reuses the cached system state (with the direct backend, a cached transpose factorization)
+- System-matrix caching on the prepared solver: repeated `solve()` calls reuse the assembled matrix across source changes
+- Frequency switching on the prepared solver via `solver.set_frequency(...)`, reusing compiled material components when all materials are non-dispersive
 - Unified `Result` output containing `Ex`, `Ey`, and `Ez`
 - Solver stats including convergence flag, solver info, residual, and solver configuration
 
@@ -134,19 +199,27 @@ This document tracks the current user-visible capabilities of the `maxwell` pack
 
 - Time-domain simulation through `Simulation.fdtd(...)`
 - CUDA-only solver execution; `Simulation.fdtd(...)` requires `Scene(device="cuda")`
+- Compiled native CUDA kernels are the only FDTD runtime backend; the Torch reference path has been retired from the runtime and relocated to the CUDA parity tests
 - Single- or multi-frequency DFT extraction through `frequency=` or `frequencies=[...]`
 - Source temporal frequency (`source_time.frequency`) remains distinct from simulation / monitor extraction frequencies; Maxwell does not infer extraction frequencies implicitly
 - ADE-based electric and magnetic dispersive-material updates for Debye, Drude, and Lorentz media
+- Static isotropic or diagonal electric conductivity (`sigma_e`) in the time-domain update, folded into the per-component lossy-dielectric `Ca`/`Cb` coefficients via the standard semi-implicit trapezoidal scheme so simple lossy dielectrics no longer require a fitted Drude pole
 - Axis-aligned diagonal anisotropy support for electric and magnetic material tensors on the Yee grid
+- Nonuniform (`GridSpec.custom`) Yee grids run on the single native CUDA kernel path through per-axis primal/dual spacing arrays, so a uniform grid is just the constant-array special case (a `GridSpec.custom` built from a uniform scene's node masters reproduces the `GridSpec.uniform` run bitwise); covers all field-update variants (standard, CPML dense/compressed, Bloch, mixed Bloch+PML), physical-depth-graded CPML profiles with per-side layer thicknesses, per-face local-cell Mur deltas, physically placed sources and monitors via the float64 coordinate masters, and `dt` from the per-axis minimum spacing
+- The reverse-time FDTD adjoint is the exact transpose of the nonuniform forward stencils (each reverse term reuses the same per-axis spacing element as its forward counterpart), so design-region gradients work unchanged on graded meshes
 - Instantaneous isotropic electric Kerr nonlinearity with GPU-resident dynamic update coefficients
 - Automatic run length estimation with `TimeConfig.auto(...)`
 - Explicit run-step control with `TimeConfig(time_steps=...)`
+- Opt-in auto-shutoff early termination stops the forward loop once relative electric-field energy decays below `Simulation.fdtd(..., shutoff=..., shutoff_check_interval=100)` (default `shutoff=0.0` disables it), with a settling/DFT/observer-aware floor so continuously driven CW and spectral runs are never truncated, plus a planned-window normalization restore so an early-stopped run's DFT/monitor spectra match the full-length run; `Result.stats()` reports `shutoff`, `shutoff_triggered`, `shutoff_step`, and `steps_run`
 - Automatic `dt` tightening for broadband source-time objects such as `GaussianPulse` and `RickerWavelet`, and for electric or magnetic dispersive material poles such as `Drude`, `Debye`, and `Lorentz` media
 - CPML absorber configuration through `BoundarySpec.pml(...)` plus typed `Simulation.fdtd(...)` config (`absorber=...`, `cpml_config=...`)
 - CPML auxiliary `psi` storage auto-selects between a dense fast path and slab-allocated low-memory storage, with `cpml_config={"memory_mode": "auto"|"dense"|"slab"}` and optional `dense_memory_limit_mib` tuning
+- Additional PML-face absorber variants selectable through `Simulation.fdtd(..., absorber=...)`: `"absorber"` (adiabatic graded-conductivity layer with no auxiliary `psi` memory) and `"stablepml"` (a CPML profile tuned for late-time stability with a higher grading order and larger complex-frequency shift), alongside the existing `"cpml"` and `"pml"` options
+- First-order Mur absorbing boundary as a per-face `BoundarySpec.mur()` kind, applied by a native CUDA kernel after the electric update that updates persistent per-face boundary buffers in place (no per-step host arithmetic or allocation, so it is captured into the tail CUDA graph)
 - Non-absorbing FDTD boundary conditions: periodic, Bloch phase-shifted periodic, PEC, and PMC
 - Per-face FDTD boundary selection across `pml`, `periodic`, `pec`, `pmc`, and `none`, including mixed-axis combinations such as periodic-in-`y` plus PML-in-`x/z`
-- Mixed low-face symmetry plus high-face absorber workflows through `Scene(symmetry=...)` with `BoundarySpec.pml(...)`
+- Mixed x/y Bloch + z PML FDTD forward stepping for grating-oriented CW `PlaneWave` TFSF slabs, including explicit Bloch wavevectors and solver-resolved automatic Bloch phase from the incident CW plane wave
+- Any-axis / either-face domain symmetry (PEC/PMC image plane on the chosen `low` or `high` face) combined with absorbing boundaries through `Scene(symmetry=...)` with `BoundarySpec.pml(...)`; point-like sources in the folded-away half are rejected with a clear error
 - Spectral window and normalization configuration through `SpectralSampler(window=..., normalize_source=...)`
 - Pulse-driven spectral extraction starts at the transient without steady-state apodization for `GaussianPulse` and `RickerWavelet`, while CW extraction still skips startup transients
 - Optional prepared execution via `Simulation.prepare()`
@@ -162,6 +235,12 @@ This document tracks the current user-visible capabilities of the `maxwell` pack
 - Internal checkpoint/replay support for adjoint-enabled FDTD runs, including CPML auxiliary state replay, TFSF auxiliary-line replay, and Bloch real/imag field checkpoints
 - Adjoint gradient pullback from Yee-grid electric permittivity coefficients back through `Scene.compile_material_tensors()` into trainable material-graph inputs
 - Solver stats including time steps, `dt`, absorber, requested frequencies, per-frequency DFT sample counts, elapsed time, milliseconds per step, and steps per second
+- Native CUDA extension builds on Windows can discover and load the Visual Studio x64 build environment automatically for accelerated FDTD kernels
+- Native CUDA extension platform wheels include the packaged FDTD CUDA extension, so ordinary `pip install witwin-maxwell` users can load the accelerated FDTD runtime without compiling locally
+- Native CUDA extension builds resolve conda-distributed torch import libraries automatically, and `WITWIN_MAXWELL_FDTD_CUDA_PREBUILT=1` loads an already-built extension from the configured build directory without invoking the build toolchain (required under profilers such as Nsight Systems)
+- Native CUDA CPML field updates skip full-volume coefficient reads when the decay/curl coefficient tensors are spatially uniform, detected automatically once per solve (about 1.4x faster forward stepping on homogeneous scenes)
+- Optional CUDA-graph capture of the per-step FDTD work via `Simulation.fdtd(..., cuda_graph=True)`: the magnetic/electric Yee updates (with CPML) are captured as one graph, and the post-source tail (PEC clamp, Mur ABC, and a GPU-driven running DFT) as a second graph, collapsing per-step kernel-launch and host overhead. The running DFT is driven from a precomputed device weight table indexed by a device step counter (no per-step host arithmetic or host->device transfer), so it captures cleanly and stays bit-identical to the host path (single- and multi-frequency). Bit-exact against the non-graph path, opt-in, and automatically declined for TFSF / magnetic-source / complex-field / Kerr / dispersive scenes whose per-step work carries host input. Most effective in the launch-bound small/adaptive-grid regime (measured ~3.7x/step on a ~1.25e5-cell AutoGrid scene, bringing AutoGrid to ~10.9x faster than the fine-uniform reference -- its full cell-count ratio -- and negligible on large compute-bound uniform grids); `Result.stats()["cuda_graph_active"]` / `["tail_graph_active"]` report whether capture engaged
+- The native CUDA module surface accepts strided tensor views, so reverse-time adjoint checks run on native CUDA reverse kernels for standard, CPML, Bloch, and dispersive scenes, validated against the relocated Torch reference; TFSF adjoint uses the native reference composition
 - FDTD result stats include CPML auxiliary-memory mode and allocated-versus-dense `psi` byte counts
 - Support for odd grid sizes in Yee-component field outputs
 
@@ -195,6 +274,8 @@ This document tracks the current user-visible capabilities of the `maxwell` pack
 - `maxwell.postprocess.compute_directivity(...)` for radiation intensity, total radiated power, directivity, gain, radiation efficiency, and 3 dB beamwidth extraction from NFFT far fields
 - `maxwell.postprocess.compute_s_parameters(...)` for broadband `S11` / `S21` extraction from flux-monitor results using reference-run or explicit incident-power normalization
 - Experimental `maxwell.postprocess.compute_mode_overlap(...)` for plane-monitor or first-class `ModeMonitor` / `ModePort` modal decomposition against an axis-aligned scalar `ModeSource` reference, returning forward/backward modal amplitudes and power fractions
+- Experimental `maxwell.postprocess.purcell_factor(structured, vacuum, name)` for the vacuum-normalized Purcell factor / local density of states of a `DipoleEmissionMonitor`, validated under `tests/monitors/emission/test_dipole_emission_monitor.py` against the analytic dipole-near-PEC-mirror curve (perpendicular orientation) and unity vacuum emission
+- Experimental `maxwell.postprocess.compute_diffraction_orders(...)` and `enumerate_diffraction_orders(...)` for grating diffraction-order decomposition on a periodic unit-cell plane; regression-tested under `tests/monitors/diffraction/test_diffraction_monitor.py` for order-cutoff / light-cone physics, Parseval consistency between the summed order powers and the direct plane-flux integral, specular dominance at normal incidence, grating-driven redistribution of transmitted power into the `+/-1` orders, and cross-validation of the transmission/reflection coefficients against the independent Yee-grid `FluxMonitor` primitive (with an `xfail` tripwire documenting that absolute `T + R = 1` energy conservation is not recoverable under the FDTD spectral-monitor CW normalization)
 - End-to-end validation coverage for first-class finite closed-surface Huygens workflows in homogeneous free space: rectangular-box dipole near-field reconstruction/directivity, non-rectangular orthogonal-surface dipole directivity, and TFSF Rayleigh-sphere bistatic RCS are regression-tested against analytic or direct-FDTD references under `tests/validation/physics/test_postprocess_end_to_end_validation.py`
 - First-class closed-surface postprocessing now rejects layered or otherwise inhomogeneous exterior media explicitly instead of silently applying a free-space Green's function outside its validity range
 
@@ -206,6 +287,12 @@ This document tracks the current user-visible capabilities of the `maxwell` pack
 - `PlaneWave` export places the source inside the physical interior and uses Tidy3D's infinite-plane aperture convention instead of a finite rectangular source patch
 - Supported mappings: Domain, GridSpec, BoundarySpec (uniform or per-face PML/periodic/PEC/PMC/Bloch export), Structure (Box/Sphere/Cylinder/Cone), Material (simple conductive / Drude / Lorentz / Debye / mixed PoleResidue with `mu_r = 1`), PointDipole, PlaneWave, GaussianBeam, PointMonitor, PlaneMonitor, FinitePlaneMonitor, FluxMonitor, symmetry
 
+## GDS Adapter
+
+- `maxwell.adapters.gds.from_gds(path, layer=..., bounds=..., ...)` imports GDS layout polygons as `PolySlab` geometries with cell selection (explicit name or unique top-level cell), layer/datatype filtering, recursive reference flattening, extrusion parameters (`axis`, `bounds`, `sidewall_angle`, `reference_plane`), and unit conversion from the file's user unit to metres (overridable via `length_scale`)
+- `maxwell.adapters.gds.to_gds_file(geometries, path, ...)` writes `PolySlab` / `ComplexPolySlab` cross-sections as GDS polygons on a chosen layer/datatype (multi-loop geometry is even-odd merged so holes survive as keyhole cuts), with the library unit derived from `length_scale` (micrometre user units by default)
+- Adapter module at `maxwell/adapters/gds.py` with optional `gdstk` import
+
 ## Tidy3D Benchmarking
 
 - `benchmark/` package as the unified Maxwell-vs-Tidy3D benchmarking entrypoint
@@ -223,6 +310,12 @@ This document tracks the current user-visible capabilities of the `maxwell` pack
 - Auto-updated benchmark summary in `benchmark/RESULTS.md`, grouped by benchmark scene folder with per-metric better-direction and target-range guidance
 - Plane-wave benchmark runs enable source-spectrum normalization on the Maxwell side so pulsed `PlaneWave` scenarios compare against the same frequency-domain reference convention as the Tidy3D export
 
+## Performance Benchmarking
+
+- FDFD solver performance benchmark via `python -m benchmark.fdfd_performance`, sweeping cubic grid sizes (default 32³ through 128³) on a canonical dipole + dielectric-cube scene, with `--solver`/`--precond`/`--precision` axes
+- Per-size metrics: matrix assembly time, solve time, operator matvec count, convergence flag, explicit relative residual, and CuPy peak-GPU-memory high-water mark
+- Results written to `benchmark/FDFD_PERFORMANCE.md` with raw JSON runs archived under `benchmark/cache/fdfd_performance/`
+
 ## Validation and Reference Utilities
 
 - Shared material compiler used by scene construction and backend preparation
@@ -234,15 +327,26 @@ This document tracks the current user-visible capabilities of the `maxwell` pack
 
 ## Known Limitations
 
-- Current subpixel material smoothing uses scalar arithmetic averaging on the scene grid
-- Yee-edge tangential versus normal permittivity averaging is not yet implemented
-- High-contrast interfaces can therefore show larger normal-field error than a true edge-aware subpixel scheme
+- Nonuniform (`GridSpec.custom`) grids are FDTD-only in v1: FDFD and Tidy3D export both raise `NotImplementedError` for custom grids; `GridSpec.auto` resolves to a nonuniform grid at prepare time and inherits the same restrictions (FDFD unsupported, TFSF/mode-plane locally-uniform rules apply)
+- On nonuniform grids, TFSF-kind injections (`PlaneWave` TFSF box, grating TFSF slab) require locally uniform spacing along all three axes over the injection region expanded by one cell, and `ModeSource` / `ModeMonitor` / `ModePort` require locally uniform transverse spacing across the mode plane; both are validated with explicit errors. Soft (non-TFSF) surface sources and `PointDipole` are fully generalized, but the soft `PlaneWave` numerical-dispersion phase correction uses the per-axis minimum spacing (exact on uniform grids, an approximation on graded ones)
+- Subpixel material averaging (`Scene(subpixel_samples=...)` with more than one sample) is not yet generalized to nonuniform grids and fails through the scalar `Scene.dx` accessor
+- Polarized subpixel averaging is applied to `eps` and `mu` only; `sigma_e`, Kerr `chi3`, and dispersive-pole weights stay arithmetic (the normal-projection rule is not well defined for conductivity/nonlinearity, and only the static base permittivity/permeability becomes normal-aware for dispersive media)
+- The polarized rule is baked at grid nodes and both runtimes keep their existing arithmetic node-to-Yee-edge averaging, so a residual O(dx) half-cell smoothing of the normal-aware correction remains versus evaluating the rule exactly at each Yee-edge location; this residual is far below the arithmetic/staircase error it replaces
+- Conformal PEC (`SubpixelSpec(pec="conformal")`) is FDTD-only: FDFD raises `NotImplementedError` for in-domain PEC materials, and the FDTD scheme is the stable partial-fill (edge-fraction E-suppression) variant of the Dey-Mittra family; classical area-scaled Dey-Mittra (H-side `1/A_open` with an area floor), contour-path H-loop averaging, and surface-impedance boundaries remain future work
+- Subpixel averaging normals and PEC fill fractions reuse per-structure signed-distance fields, so accuracy is bounded by SDF quality for primitives with kinked distance fields (faces/edges/corners)
 - Maxwell supports axis-aligned diagonal anisotropy through `DiagonalTensor3`, but `Material.orientation` and full `Tensor3x3` rotation / off-diagonal tensors remain unsupported
 - Kerr media cannot be combined with dispersive or anisotropic materials in the same scene in v1
+- Experimental `DiffractionMonitor` is v1-limited: it assumes the monitor plane spans one full transverse unit cell (periods taken from the transverse domain lengths), targets FDTD `CW` grating scenes with transverse Bloch/periodic boundaries, and reports per-order power as a share of the transmitted plane flux. Absolute per-order diffraction efficiency normalized against a separately measured incident power is not asserted, because the FDTD spectral-monitor CW normalization is steady-state/ratio-based rather than an absolute cross-run power balance
+- Experimental `DipoleEmissionMonitor` is v1-limited: it reports `power_delivered` from the single co-located dipole cell (a point approximation of the profile-weighted current integral) and requires FDTD `PointDipole` sources; the Purcell factor is only obtained by explicitly normalizing against a separate vacuum run through `maxwell.postprocess.purcell_factor(...)`, because the discrete effective source volume that sets the absolute power scale has no reliable closed form, so a lone run returns `purcell_factor=None`
 - FDFD supports electric anisotropy only; static magnetic media and magnetic dispersion still fail explicitly
-- FDTD rejects static conductive `sigma_e` materials explicitly; use FDFD for frequency-domain conductivity or Maxwell dispersive poles for time-domain media
-- Mixed Bloch boundary configurations currently fail explicitly in FDTD; use homogeneous `BoundarySpec.bloch(...)` or avoid Bloch on mixed boundary layouts
+- FDTD supports static electric conductivity (`sigma_e`) in the forward update but still lacks static magnetic conductivity (`sigma_m`), and the FDTD adjoint bridge rejects `sigma_e` media because the reverse-time kernels do not model the conduction-loss decay
+- Mixed Bloch boundary configurations outside the supported x/y Bloch + z PML grating FDTD path still fail explicitly
+- TFSF slab runtime support is currently limited to CW `PlaneWave` grating slabs with `axis="z"`; non-Bloch slabs, non-`PlaneWave` slab sources, and broadband automatic fixed-angle Bloch workflows fail explicitly because automatic Bloch phase is single-frequency metadata
+- Automatic Bloch wavevectors are solver-preparation metadata and are rejected by unresolved Tidy3D export
 - FDFD currently supports per-face boundary mixing only for `none` and `pml`
+- Domain symmetry (`Scene(symmetry=...)`) is FDTD-only (FDFD rejects it), applies a single image plane per axis at the chosen `low`/`high` face, and requires the user to supply the pre-folded half/quarter domain with a physically symmetric source layout; the symmetry-plane face must be `none` or `pml`. Tidy3D export encodes symmetry about the domain center only and drops the per-face (`low`/`high`) selection
+- The first-order `BoundarySpec.mur()` absorbing boundary leaves a higher reflected residual than a PML absorber (single-snapshot residual energy roughly an order of magnitude above a reflecting PEC box, versus about two orders for PML), applies only to the real electric field so it cannot be combined with Bloch complex-field runs, and has no second-order variant in v1
+- The `"absorber"` and `"stablepml"` variants share the existing PML face plumbing (`BoundarySpec.pml(...)`); `"stablepml"` overrides the CPML grading/alpha profile, so a user-supplied `cpml_config` does not override the stable-profile grading keys
 - Tidy3D export and the FDTD adjoint bridge reject anisotropy, magnetic dispersion, and Kerr media explicitly in v1
 - Experimental `ModeSource`, `ModeMonitor`, and `ModePort` are currently limited to FDTD `CW` soft injection / monitoring on an axis-aligned plane and no Tidy3D mode-source export support; forward mode solving now uses a full-vector generalized eigenproblem on real isotropic source apertures and can handle non-unit `mu_r`, but the differentiable path still inherits the older scalar restrictions, and the broader modal stack is still missing complex/lossy, anisotropic, bent, angled, and RF-style wave-port coverage
 - Experimental `compute_mode_overlap(...)` currently expects aligned tangential `E/H` fields on the target port plane and inherits the same axis-aligned modal-source assumptions as the current `ModeSource` implementation
@@ -250,3 +354,5 @@ This document tracks the current user-visible capabilities of the `maxwell` pack
 - First-class closed-surface postprocessing currently requires a homogeneous exterior medium immediately outside every face; layered or otherwise inhomogeneous exteriors are rejected explicitly
 - Closed-surface validation currently covers axis-aligned planar faces, including rectangular Huygens boxes and non-rectangular orthogonal polyhedra; curved/non-planar closed surfaces still need a separate workflow and validation path
 - Benchmark soft-plane-wave absolute calibration still needs separate validation/debugging and remains a known open correctness issue
+- `UniformCurrentSource`, `CustomCurrentSource`, and `CustomFieldSource` are v1 forward-only: the FDTD adjoint bridge rejects them (no source pullback is implemented). `CustomFieldSource` additionally requires a planar (single-sample-axis) `FieldDataset`, injects toward `+normal` only, and reproduces the plane wave to discretization-limited tolerance (finite-aperture edge diffraction and half-cell E/H staggering leave a small backward and cross-polarized residual)
+- `CustomSourceTime` v1 is limited to the Python scalar soft/uniform injection path: it is supported on `PointDipole` but rejected on `PlaneWave`, `GaussianBeam`, `AstigmaticGaussianBeam` (which require the native time-shifted kernel), and on `ModeSource` (CW-only); callable `fn` waveforms need an explicit `characteristic_frequency` and are not supported in the FDTD adjoint (only sampled `(times, amplitudes)` tables are), and custom-waveform samples are not differentiable