[yonghakim]

Stage 7 of the FDTD engine on the public wavebit.fdtd lifecycle, in one PR. It was first opened as five stacked pieces; #114 and #115 are folded in here and closed. Each piece keeps its own self-contained commits. Its acceptance criteria were committed before its first computation, and every amendment made before a run is a separate commit.

What lands

1. fdtd.solve_modes. Waveguide modes of the discrete Yee system, on the grid and the smoothed coefficients the time stepper uses. Power is normalized as a FluxMonitor measures it. Validation record: docs/validation/fdtd/fd-waveguide-modes.md.
2. fdtd.ModeMonitor. Forward and backward amplitudes and spectral energies per mode on a plane, from the run's Fourier fields. It uses the modes' exact unconjugated orthogonality.
3. A cell-snapped core continued through a PML. A SnappedBox may declare continuation=('z-', 'z+'), and a SnappedSlab may name the faces of the axes it runs along. Smoothed cores stay refused. Record: fd-waveguide-through-pml.md.
4. fdtd.ModeSource. A one-sided TFSF sheet whose incident field is a solved mode. It is exactly one-way at the centre wavelength. Off-centre, injection and leakage are predicted in closed form, and ModeMonitor(source=) reports them. Record: fd-mode-source.md.
5. fdtd.GaussianBeam. A focused beam on the same sheet, built from the grid's own discrete plane waves, so it is an exact grid solution at the centre wavelength. Record: fd-gaussian-beam.md.

Evidence

Registration commits: eb26ab9 52beba4 f9fb9e6, c09788f 54f6e3a 7c2f043 24ab6a5, eb2c43d, b6fe448, 9c383c2.

Piece	Oracle	Measured
Mode solver	uniform medium and hollow guide closed forms	≤ 1.1e-12
	exact slab TE/TM, 3 orders each	second order (2.003–2.027), Richardson ≤ 3.5e-6
	Hadley's published dielectric corners (rectangular guide)	finest 6.8e-5 to 5.9e-4, order ≈ 2
	solved mode advanced by the time stepper	stays itself to 6.4e-14
ModeMonitor	exact direction separation	≤ 4.7e-15
	modal sum vs flux, settled	1.7e-10
	backends	≤ 6.2e-16
	AD vs extrapolated central differences	1.3e-8
PML door	guided-mode reflection, slab, 12 → 24 cells	4.3e-8 → 3.5e-16
	guided-mode reflection, rectangular core, 12 → 24 cells	1.3e-6 → 3.5e-12
ModeSource	injection vs exact prediction	≤ 3.5e-11 (TE0, TM0, both directions)
	leakage vs exact prediction	≤ 1.5e-12; one-way at the centre to 1e-28
	absolute power	1.2e-13
	run index	converges to the exact slab index at order 2.02
	butt joint vs continuum mode matching	ΔT = 9.8e-5, ΔR = 1.5 %
	backends	≤ 1.3e-15
	AD vs extrapolated central differences (amplitude, phase, delay, scatterer; truncated run)	≤ 1.1e-9
GaussianBeam	waist	≤ 1.1e-8
	focal shift into a dielectric vs exact angular spectrum	0.003 µm at 0.025 µm
	power 2-D / 3-D	≤ 1.5e-12 / 3.6e-8
	back-radiation vs exact prediction	≤ 6.2e-12
	backends	≤ 1.2e-15
	AD vs extrapolated central differences (truncated run)	≤ 2.4e-10

Failures recorded, limits unchanged. Each is kept as a strict expected failure beside its registered replacement or its passing part:

• MM2: a broadband pulse in a closed metal guide never settles. Replaced by MM2b.
• MM4: difference step too coarse. Replaced by MM4b.
• G2, Gouy phase at 0.05 µm: 2.20e-3 rad against a limit of 2e-3. The error falls at second order (5.4e-4 at 0.025 µm).

Support decision for G2 (fce5d22), recorded separately from the verdict. GaussianBeam is supported, and its Gouy-phase accuracy is stated in three places: the guide (EN and KO), the class docstring and the validation record. The reasons:

• the difference is the grid's dispersion;
• it falls at second order and is inside the limit at 0.025 µm;
• it is of the size by which the paraxial formula departs from the exact beam.

No runtime warning is added: these grids are above the 8 to 12 cells per wavelength where CoarseMeshWarning already warns.

Amended before computing. S7 and G7 as registered need reverse mode to keep about 12k steps, more than 13 GB on JAX/CPU. checkpoint_steps is admitted only on Torch CUDA. As with MM4b, the derivatives and the central differences are both taken of the same truncated run in a smaller domain. The four derivatives and the 1e-6 limit are unchanged. The records list every amendment and its reason.

Comparison with Meep and FDTDX (59d6560), evidence, not acceptance

The same cases were run in Meep 1.35.0 and FDTDX 0.6.3. Each ran in its own process from inputs in physical units, using public APIs only. Meep's source was not read.

The values are frozen in tests/references/golden_stage7_cross_solver.json. Its wavebit.reference-values/1 record states each tool's build and settings, and what was and was not matched. fd-mode-source.md and fd-gaussian-beam.md (EN and KO) print the tables. test_stage7_cross_solver_golden.py holds the tables and each conclusion drawn from them to the golden.

What the comparison shows:

• One discrete system. FDTDX's run index equals Wavebit's to 7.3e-9.
• One-way launch. At the centre wavelength only the grid-mode launch is one-way: Wavebit 6.8e-29, FDTDX 4.3e-7, Meep 1.3e-3 at 0.05 µm.
• Butt joint. Every tool converges on the mode-matching transmission. FDTDX is closest on T; Wavebit is closest on the small R.
• Absorber. The external absorber values are a readout floor and cannot rank absorbers.
• Beam. Meep's beam is 0.86 % wide at every resolution. FDTDX's source focuses on its own plane. Wavebit's G2 difference is the smallest of the three at both spacings.

No verdict changes. main was merged in (f134bca, no conflicts) to bring the reference-record format.

Refused by name

• Lossy, dispersive, coupled-smoothed and leaky media on a mode plane.
• Bloch and mirror transverse faces.
• Traced structures on a mode or source plane, and a traced pulse wavelength, waist or focus.
• A monitor within a cell of a sheet.
• A beam the cross-section or transform grid cannot hold, and any beam off normal incidence.
• The engine placeholders now name the public classes.

Verification

• Every new rule and formula was deliberately broken and caught: 9 PML door rules, 16 ModeSource breaks, 13 beam breaks, plus the earlier solver and monitor ones. The new comparison test caught a changed EN cell, a changed KO cell and a changed golden value. Each time, the source was restored byte for byte.
• Locally:
  • quick verification profile: 17 passed
  • tests/api plus the comparison test: 1710 passed
  • ruff: clean
  • EN and KO docs build with -W: clean
• CI on 59d6560: all checks green.

Docs (EN/KO): the waveguide-modes and Gaussian-beam guide pages, the model page, the reference index, the source map, and the four validation records.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EsCWzkwvzVkG7JYdnKJnRk