Meep template development evidence and compatibility¶
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 generation seeds wavelength center/full span from project pyproject.toml
simulation defaults, not the earlier fixed 1.55/0.01 example window. The range
contract is in the full spec and Eve's handoff. Current review copies use the
project's 1.5–1.6 µm window (center 1.55, full span 0.1); historical solver/test
artifacts below retain their original windows. Generation reads the TOML; no
additional compatibility or runtime-loading block was added to user notebooks.
Technical reference, not app UI requirements. The product spec owns scope/release policy; Eve's handoff owns app implementation. These are recorded results, not newly rerun tests or current-environment guarantees. Latest targeted suite: 41 passed; earlier full suite: 130 passed / 140 optional skips. Preparation covered straight/coupler, custom-port GDS and XY/XZ/3D; direct 3D Python/GDS/accepted-layout configurations matched references. Latest cells and explicit GSCH rebuild were checked on October 12; details below.
Recorded project and solver evidence¶
October 14 compatibility update supersedes the failed run below: 66 passed
in 9.07 seconds against gsim source de1435b, correctly installed as editable
0.7.0. Updated zap origin notebook/binder to padding, regenerated its schema/pair, and
verified zero/asymmetric directional padding. The templates extra pins this
source revision; metadata records it. Shared PR/upload compatibility checks and
the update procedure are described in zapFDTD notes.
No cloud execution was performed. Existing material-dispersion fixture warnings
remain; preparation tests do not establish physical/numerical accuracy.
October 14 notebook binding/output correction: both origin notebooks now show named
input/project/preparation/results/PDK placeholders; zap cladding is also explicit.
The reference binders replace setup with resolved values and pin results_path
to the absolute generated bundle. Run passes that path explicitly; gsim's shared
downloader creates sim-data-<job_name>/ underneath. parent_dir=None instead
uses kernel cwd, so the old project-parent comment was incorrect. The app's new
default is project simulations/<design>/<template>-NNN/; callers of reference
binders still choose their destination.
Current solver-guarded Meep/zap/project/path suite: 59 passed, 4 failed on
October 14, not a green integration result. Both new cwd-independent Run checks
pass. Three zap preparation checks reject the origin notebook's padding_um argument
against the currently installed gsim Domain API; one zap schema/model equality
check differs. Paired notebook/Python source comparison passes. These unresolved
API/schema gaps are separate from the output-path correction. No cloud jobs,
dependency installs or editor execution were performed. Ruff was unavailable.
Command (project Python 3.12): python -m pytest tests/test_meep_template.py
tests/test_zapfdtd_template.py tests/test_project_wavelengths.py
tests/test_notebook_paths.py -q --tb=short -p no:cacheprovider.
October 9 environment: Python 3.12, gsim 0.6, photonics-full-init gpdk, GFP extension
SDK 2026.1009.0. scripts/verify_meep_3d_project.py uses existing SDK checks,
not a new geometry matcher, and does not edit user source files.
| Fixture | Recorded outcome |
|---|---|
gpdk.components.bends.bend_euler.bend_euler |
Python preparation/preview passes. |
| Same bend exported as GDS | Geometry, ports, full configuration match Python; stripped-metadata and embedded-port cases covered. |
meep_two_bends_both.gsch |
No conversion warnings/LVS findings; P1/P2 preparation/preview passes. |
meep_two_bends_schematic.gsch |
No physical placement; dropped X1.o2–X2.o2 and LVS.net.missing_in_layout; rejected. |
meep_two_bends_layout_busted.gsch |
Placement present, intended connection absent; rejected. |
Two authorized resolution-20 3D cloud smoke jobs completed. At 1.55 µm, GDS bend transmission/reflection were 94.3074% / 0.149994%; two-bend layout values were 96.1245% / 0.00352005%, insertion loss 0.171659 dB. These are integration results, not converged loss measurements. Lower two-bend loss needs mesh, termination and port-placement investigation. FDTD port indices were approximately 2.360 / 2.345, while a separate restricted core/oxide, staircase-sidewall mode diagnostic gave approximately 1.747. Its source-profile equivalence is unresolved. Cross-section preparation can fill absent mask layers with full-width material, producing inconsistent modes; this needs SDK/gsim investigation, not sidebar logic. Default diagnostics save geometry slices, late-time XY fields and modal indices/coefficients, not transverse mode-field arrays. The saved XY slice at z=0.470 µm was above the 0–0.220 µm core; use a core-plane/DFT field diagnostic.
Historical helper-based implementation (retired from current origin notebooks)¶
These deferred drafts retain the context/helper architecture; it does not describe
current 3D. template_meep is shared authoring/compatibility source,
sidebar_choice:false, not a fourth menu option. After source changes run
python -m scripts.build_meep_template. Legacy bundles include simulation.json,
assets/meep_template_runtime.py, schema and captured inputs; an absolute context
path must be rebound if moved. Their preparation writes fresh runs/job-<id>
configuration, provenance/runtime records and sampled response.json; solver
parent_dir=None defaults to cwd. Legacy execution rebuilds from declared context;
edits to the preview simulation object do not alter that job. Preparation never authenticates/uploads/solves
or queries cache. Clean 3D bundles instead use ordinary native calls.
Development-only compatibility and retired BAD code¶
Install isolated tools with pip install '.[templates]' pytest; the older tutorial
dev extra pins another gsim range. Historical gpdk pins may conflict with
pdk-schema 0.2; successful imports do not resolve dependencies. Keep GFP_API_KEY
in inherited environment, never notebooks/configuration/outputs.
Use project Python with the harness's --project-root, --sdk-path (outer folder
containing gdsfactoryplus/__init__.py), fresh --output, and optional --execute.
It selects the extension SDK and sibling nyancad, launches Python 3.12, blocks
solver/cloud/mode calls, omits Run/Results during preparation checks, then restores
those cells untouched. Test bootstrap and guards are removed before saved review
notebooks. Removing a guard cell does not undo monkeypatches; restart that kernel
before real execution. Legacy deferred sources retain their older SDK bootstrap;
normal project SDK installation should ultimately replace all such workarounds.
Windows zapFDTD upload line endings (temporary)¶
Eve reports that the October 12 cloud SIGSEGV was caused by CRLF rather than LF line endings in uploaded inputs. Inject this development-only patch in a fresh kernel before cloud execution; do not add it to shipped templates:
from gsim.fdtd.cloud import CloudWorkflowMixin as M
_orig = M._prepare_upload_dir
def _lf(self):
d = _orig(self)
for f in d.iterdir():
if f.suffix in (".msh", ".json"):
f.write_bytes(f.read_bytes().replace(b"\r\n", b"\n"))
return d
M._prepare_upload_dir = _lf
Run this patch once per fresh kernel: repeating it as written can wrap the patch
around itself and cause recursion. It normalizes the fresh temporary upload files
without changing notebook/source files. It covers sim.run()/sim.upload();
direct gcloud.upload(existing_directory, ...) bypasses this hook, so normalize
that directory's text inputs explicitly. Never apply byte replacement to binary
files. The upstream writer should eventually emit LF itself. This patch is
recorded, not executed or verified by this documentation update; a successful
patched run remains a qualification step. Restart to remove the monkeypatch.
For continuing work in separate chats, see the continuation handoff.
The following BAD user-facing loader is retained only as interim development reference until app generation merges. It couples notebooks to JSON/helper assets and a machine path. Never restore it to the true 3D template; if needed in a test, inject only in memory and remove before saving the preview.
import sys
from pathlib import Path
CONTEXT_PATH = 'C:\\Users\\eve\\Documents\\Codex\\2026-10-07\\https-github-com-doplaydo-simulation-templates\\outputs\\meep-3d-clean-preview\\simulation.json'
context_path = Path(CONTEXT_PATH).resolve()
bundle_dir = context_path.parent
import importlib.util
helper_path = bundle_dir / "assets" / "meep_template_runtime.py"
if not helper_path.is_file():
raise RuntimeError("Notebook bundle is missing assets/meep_template_runtime.py")
helper_spec = importlib.util.spec_from_file_location("bound_meep_runtime", helper_path)
runtime = importlib.util.module_from_spec(helper_spec)
sys.modules[helper_spec.name] = runtime
helper_spec.loader.exec_module(runtime)
context = runtime.load_context(context_path, PDK)
if context.template_id != 'meep_3d':
raise ValueError('This notebook requires template_id=meep_3d')
print("Design:", context.provenance.design_id)
available_ports = [port.name for port in runtime.load_design(context, bundle_dir).ports]
print('Available ports:', available_ports)
October 12: exact notebook preparation and rebuild verification¶
Ran scripts/verify_meep_notebook_inputs.py in project Python 3.12.14, gsim 0.6.0 and installed GFP SDK 2026.1012.0. Six fresh kernels covered the exact rebuild/import cell against all three GSCH fixtures, plus the current Python/direct-GDS/accepted-layout notebooks through preparation and interactive preview. A seventh fresh-kernel probe checked monitor selection. Run/Results were omitted from execution, solver/cloud methods guarded, and temporary cells removed from saved test notebooks. No solver calls were attempted or submitted; GSCH hashes were unchanged and user review copies were untouched.
| Case | Observed result |
|---|---|
_both.gsch |
Fresh GDS built/imported, P1/P2 restored, no warnings, existing SDK LVS passes. |
_schematic.gsch |
Build/import succeeds, but returns dropped X1.o2–X2.o2 warning; SDK LVS reports LVS.net.missing_in_layout. |
_layout_busted.gsch |
Same dropped connection warning and missing-layout-net LVS finding. |
| Python and direct GDS | PDK/stack validation and preparation pass; ports and complete configurations equal; prepared layout geometry XOR empty. |
| Accepted Layout Editor notebook | Build, PDK/stack validation, preparation and preview pass with P1 source and P2 requested monitor. |
| Monitor selection probe | Changing requested monitors to P1 still exports P2 and P1. Current gsim only validates the monitor-name field; its runner makes a monitor for each exported port. Selection is not honored. |
The latest .gsch fixture files all currently contain physical placements; the schematic-only case is rejected by warnings/LVS, not placement absence. Earlier October 9 placement findings remain historical. Stack validation also reports the configured energy-decay stopping policy; it is not a validation failure. Setup previews use the actual core plane z=0.11 µm, not solver fields or transverse source modes.
Calling the synchronous SDK LVS entry point directly inside Jupyter raised asyncio.run()/running-event-loop conflict. The harness uses await asyncio.to_thread(check_lvs, ...) so the existing checker runs outside the notebook loop; no monkeypatch or replacement comparison algorithm. This must be considered by any future notebook-callable build-and-validate facade.
Remaining blockers: build warnings/LVS must be enforced on notebook-driven rebuild, and the SDK must honor explicit monitor selection. The current short user geometry cell is intentionally unchanged. Numerical convergence/source-mode mismatch are still separate solver work. Targeted tests remain 41 passed; harness lint passes. Session artifacts: outputs/meep-notebook-verification-20261012-final/ (HTML report, JSON, clean executed copies, core-plane previews).
Current hidden-setup design¶
The current origin notebooks use one native setup cell containing bound path variables, all imports/PDK activation, and geometry loading. GSCH setup rejects build warnings and performs explicit thread-safe LVS through KLayout ReportDatabase before import. It is marked hidden and declared for one-time creation execution by the app; ordinary Jupyter does not auto-run it from metadata. Settings onward remain visible/manual. The earlier October 12 report tested the previous visible setup/geometry layout; Revised initialization was verified in fresh Python 3.12 kernels: Python/GDS/valid layout pass; both broken GSCH fixtures stop on dropped-connection warnings before import. No solver jobs, unchanged source hashes; artifacts are in outputs/meep-hidden-setup-verification-20261012/. The editor creation hook itself still needs app implementation. Temporary test bootstrap/guards remain in-memory only.