Skip to content

zapFDTD template implementation notes

Historical integration/qualification notes: source-specific origin exports and shared delivery sidecars described below are retired. For current authoring and delivery, use compact metadata and origin packaging.

Current AUTO/USER tokens, metadata defaults, migration status and app dependencies: template token author guide. This analysis uses one canonical notebook, app-owned source adapters and the generic auto_user_tokens binder.

One 3D guided-component analysis supports Python, GSCH layout and GDS targets. Use the shared UI/creation behavior in Eve's handoff. The full spec owns representation/PDK contracts and release gates. This is a draft, not a numerical qualification.

Files and source routes

The canonical origin is origin_simulation_templates/zapfdtd/generic_3d/zapfdtd_generic_3d.ipynb, with its paired .py. Config contains the embedded app declarations; stable template ID zapfdtd_3d and engine ID fdtd are preserved. It declares requirements = {'gsim': '>=0.8.0'}. See origin packaging for the nested authoring layout and flat notebook-only ZIP.

Source Config handling injected by the app
Python Import and call the selected factory.
GDS Import the selected cell with embedded port metadata.
GSCH Layout Editor Rebuild GDS, reject warnings, run SDK LVS, import the cell.
GSCH Schematic / direct kfnetlist Unavailable; physical geometry is required.

The same canonical analysis follows every source adapter. Preparation calls native sim.add_monitors() and Results displays driven heatmaps. Comments, cell order and analysis helpers survive binding. Target-specific notebooks are optional exports, not independently authored origins or archive inputs.

Source port, wavelength center/span, sample count and grid size remain <INSERT_...> placeholders in every origin, alongside paths/import bindings. They are filled from validated context and project defaults during generation; no origin contains a user path, source_port = None, or filled numerical values for those five settings. Active PDK import/activation remain required.

Generated notebooks have no runtime helper or JSON dependency, no cell tags, no compatibility bootstrap and no execution toggle. Only Config is marked hidden; the app still must enforce hiding/one-time setup execution. Settings, preparation, Run and Results are manual.

Native API and defaults

Config imports the selected module as pdk_provider, keeps the explicit PDK import/activation, and Prepare calls fdtd.Simulation(pdk=pdk_provider). The backend can then use module-owned MATERIAL_CARDS as well as PDK-attached cards for geometry, background and explicit overrides, retaining its native precedence. No get_stack() is needed. Module forwarding alone does not qualify material bands/numerics or prevent native built-in fallback; app qualification remains gated. Keep wavelengths in µm; cell_size_nm is the Yee-grid spacing in nm, not Meep's pixels-per-µm. Seed wavelength center/full span from the design project's pyproject.toml simulation range, exactly as defined in the full spec; keep 11 wavelengths and 60 nm cells as independent starting values. The app writes editable numbers, not a TOML-reading block. Compare finer grids before trusting numbers.

Settings exposes one source port, available optical ports, wavelength/span/count, grid spacing and background material from the selected PDK cladding layer. Config defines cladding_layer_name = "clad" for the test PDK and layers = PDK.layer_stack.layers; Settings reads background_material = layers[cladding_layer_name].material. The app must obtain the actual key from the solver/PDK integration, per Eve's handoff. Changing that one Config variable selects the layer; no second material-name literal. Missing layers/material cards fail rather than defaulting to oxide. Do not set a port-monitor selector: guided port measurements are implicit, including the source port for reflection. Additional plane monitors are a separate native API concern.

Preparation configures materials/source/geometry/domain/solver, calls sim.write(prepare_path) for the validated mesh.msh + config.json pair and sim.plot_3d() for the mesh-backed interactive preview. The default domain uses 1 µm padding; native PML and termination defaults apply. Transfer-mesh size and Yee-grid spacing are different controls; never present one as the other.

Run remains result = sim.run(parent_dir=None) with the same two directory comments as Meep. It uploads/starts a cloud job; one excitation yields one response column. Results prints result.convergence and calls result.plot_plotly(). No Meep-specific result methods. The template is excluded from automatic docs execution so a docs build cannot submit an unbound solver job.

App generation contract

python -m scripts.bind_zapfdtd_template --context simulation.json --output NEW_DIR validates zapfdtd_template.schema.json, stages captured inputs and refuses an existing destination. Rebuild the origin notebook/schema with python -m scripts.build_zapfdtd_template. This reference binder is not app UI.

Required creation fields are schema version, template/engine, PDK module, provenance, design and source. Geometry/paths use the same meanings as Meep's handoff. Native settings deliberately differ:

Field zapFDTD shape
source fdtd.PortSource: port, wavelength_um, wavelength_span_um, num_wavelengths, plus optional native source controls.
solver fdtd.Solver: cell_size_nm and optional termination controls. No Meep resolution or 2D mode.
cladding_layer_name Selected PDK layer-stack key; determines the uniform background material.
materials Explicit refractive-index overrides only. The background name is read from the PDK layer.
domain Native padding, PML-cell count and optional physical axis bounds.
wavelength_overrides Optional explicit wizard center/span in µm, overriding project defaults.

The starter notebook exposes no material-overrides, solver-settings or source-settings dictionaries or tokens. It uses the native defaults alongside the explicit background, source port, wavelength settings and cell size. Users can add advanced controls directly to their notebook later.

The binder reads project_root/pyproject.toml; sim.x takes precedence over sim.wls, matching GFP Settings. A 1.5–1.6 µm range yields center 1.55 µm and full span 0.1 µm. sim.wls.num does not replace FDTD's count of 11. Generation captures defaults once; later Config reruns never reset manually edited Settings.

PDK names must match actual layer-material keys. Project gpdk resolves Si and SiO2 without overrides. Bundled gdsfactory.gpdk uses lowercase si/sio2, which are absent from this gsim material registry: missing cards must fail with the existing material-resolution error, or the caller must provide an intentional override. Do not hard-code a silicon index or silently substitute a different material.

Choosing the PDK cladding material does not synthesize substrate/BOX/upper-cladding volumes. The current bend mesh contains silicon core plus a uniform background; that background touches the core. Layered environmental geometry is separate work.

Future source sweeps and field diagnostics

An explicit source_ports = ["o1", ...] is a sensible future batch input, initially one selected port. Each port must be excited separately; N selected port modes require N solver jobs to build the corresponding matrix columns. Do not launch multiple ports simultaneously and label the result a full S-matrix. Preserve port/mode labels, reference planes, wavelength arrays and valid/converged samples when combining columns. Prefer a native batch/result helper to lengthy notebook orchestration; it is not implemented in this draft.

Single-column runs still produce all-port response and can include field-plane heatmaps when requested through sim.monitors.add_plane(..., heatmap=fdtd.Heatmap(...)). These are driven-field cross sections, not standalone source eigenmode arrays. The current typed result does not provide Meep-style mode-profile diagnostics; solver-exported eigenmode arrays/plots need a separate solver/result contract.

Initial qualification covers planar axis-aligned optical ports. Native dipole, line-current, Gaussian/fiber sources, plane heatmaps, angled ports and full S-matrix orchestration are outside this draft's verified scope. Keep future hooks in native API settings rather than adding a wall of configuration to the notebook.

Verification

October 14 route-origin correction: Python, GSCH layout and GDS origins preserve the selected monitor-refined notebook set. Exact source comparisons retain the monitor behavior, GSCH build/LVS block and Results cell. October 15: replaced the local helper with native sim.add_monitors(). All five Settings values are declared placeholders. The binder preserves authored code/comments/metadata and fills only the selected origin's slots. The combined origin is retired. Current guarded regression result: 73 passed. This includes real Python/GDS preparation, three-route binding and pair/schema checks, authored-cell preservation and missing-binding failure. It does not establish new solver convergence or complete sidebar/editor integration.

Current API baseline and maintenance

The generic Meep/zapFDTD templates use gsim 0.7.x source revision 9c9975b0a855c6988667a5147b045dfafec0517b. The templates extra pins that exact revision because PyPI 0.7.0 predates directional padding and native Simulation.add_monitors(). The same revision is recorded in each template's runtime metadata. The legacy walkthrough dev extra is a separate older environment; do not combine it with the generic templates extra.

Domain settings use padding, optional padding_x/padding_y/padding_z, physical axis bounds and pml_cells. Shared/axis padding accepts a scalar or a negative-side/positive-side pair, including zero. padding_um is rejected. The origin notebook and binder both use the same native names; changing only the notebook would let generation reintroduce the obsolete key.

When updating the dependency, check gsim's API changes, update the exact pin and both metadata revisions together, reconcile origin notebook/binder code, regenerate with python -m scripts.build_zapfdtd_template, and run:

python -m pytest tests/test_meep_template.py tests/test_zapfdtd_template.py tests/test_project_wavelengths.py tests/test_notebook_paths.py -q

The Generic template compatibility CI job runs the same solver-guarded checks on pull requests and before template upload. It compares generated schemas, checks notebook/Python pairs, prepares real geometry and tests directional padding and output paths. Updating the source pin is deliberate; CI does not silently update the dependency or run cloud jobs. A green preparation check does not qualify solver convergence.

tests/test_zapfdtd_template.py checks source binding, metadata, PDK dotted imports, port preservation, units, real mesh/config generation and failure handling with cloud calls blocked. scripts/verify_zapfdtd_notebook_inputs.py exercises the three source variants in fresh project Python 3.12 kernels and rejects the two existing broken GSCH fixtures. Temporary SDK bootstrap and guards are injected only into the harness and removed from saved notebooks. Successful numerical qualification is still pending; real cloud attempts are recorded below.

Verified October 12, 2026 with project Python 3.12.14, local gsim 0.6.0 revision 05c6c93, and extension SDK 2026.1012.0. Python bend/GDS/valid two-bend layout passed Config, Settings, mesh/config export and 3D preview in fresh kernels. Valid layout had no build warnings and zero LVS items. Both broken GSCH fixtures stopped in Config on dropped-connection warnings. Python/GDS configs matched exactly; original GSCH hashes were unchanged. No solver calls were attempted or submitted. Session artifacts: outputs/zapfdtd-3d-verification-20261012/ contains clean source-bound notebooks, executed copies, interactive previews and JSON reports. 48 automated Meep/zapFDTD/project checks passed; Run/Results compatibility was checked with synthetic typed data, not claimed as a real solver run.

Real cloud attempts, October 12

User authorized a bend solve with source o1 and input/output/core-plane intensity heatmaps. Job 01a13232-9a5a-77f2-a791-69f935f05dfb (fdtd-7fc98b3d) failed with exit 139 (SIGSEGV). The user then explicitly authorized a smaller 4 µm straight control, 60 nm grid, tighter Z bounds and 12,000-step cap; 01a1323b-e238-7f23-a7c1-c4b73a955fbe (fdtd-0a7cd1ad) also failed with exit 139. Both container logs show successful input download/extraction and Running zap_fdtd..., with no solver diagnostics or result artifacts returned. No real mode/field screenshots or numerical results can be claimed.

Inputs/logs are saved in session outputs zapfdtd-authorized-solve-20261012/ and zapfdtd-straight-control-20261012/. Current local FDTD revision a7b4175 requires grid.non_pml_bounds in its parser; current gsim revision 05c6c93 does not emit that field. This is a confirmed schema mismatch, not a proven explanation of the SIGSEGV: deployed binary revision/diagnostics are not known. Align writer and deployed schema and obtain a successful diagnostic solve before promoting readiness. Keep any test compatibility patches out of user notebooks. Current cladding binding/preparation regression suite: 65 passed.

Subsequent update from Eve: the SIGSEGV was traced to Windows CRLF input line endings. The temporary LF upload-hook patch is recorded in development workarounds. The grid-schema observation above remains independent; it was not the established crash cause. No patched solve has been run by this chat yet. Use a successful, version-recorded patched run to qualify the template, not the earlier failures.