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.