Skip to content

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.