Skip to content

Authoring canonical simulation templates

Reference binding contract auto_user_tokens. This coordinated local contract follows GDSFactory+ approved specs/simulation/notebook-bindings.md (Design 2267dbd82). Exact app/reference snapshot and compile-only conformance checks are separate from native or solver qualification; draft template readiness does not change.

Files authors maintain

Family Canonical notebook
Meep 3D origin_simulation_templates/meep/generic_3d/meep_generic_3d.ipynb
zapFDTD 3D origin_simulation_templates/zapfdtd/generic_3d/zapfdtd_generic_3d.ipynb
MEOW taper, vertical sidewall approximation origin_simulation_templates/meow/taper_vswa/meow_taper_vswa.ipynb
MEOW 1×2 MMI, vertical sidewall approximation origin_simulation_templates/meow/mmi1x2_vswa/meow_mmi1x2_vswa.ipynb
MEOW 2×2 MMI, vertical sidewall approximation origin_simulation_templates/meow/mmi2x2_vswa/meow_mmi2x2_vswa.ipynb
Femwell optical waveguide modes, vertical sidewall approximation origin_simulation_templates/femwell/waveguide_modes_vswa/femwell_waveguide_modes_vswa.ipynb
Femwell steady-state heater, vertical sidewall approximation origin_simulation_templates/femwell/heater_steady_state_vswa/femwell_heater_steady_state_vswa.ipynb
Palace driven S-parameters, generic (see Palace driven template) origin_simulation_templates/palace/driven_sparams/palace_driven_sparams.ipynb
SAX circuit wavelength sweep, schematic draft origin_simulation_templates/sax/circuit_wavelength_sweep/sax_circuit_wavelength_sweep.ipynb

The authoring authority is now the bounded literal declaration block inside Config. See compact metadata. Per-template .metadata.json sidecars are prohibited in the origin directory and are never generated by the builder. The matching app reader consumes these literals without executing Config.

Build/check with python -m scripts.build_templates and python -m scripts.check_origin_templates. The builder validates source compositions and refreshes Python companions. Route exports are optional and must use a separate output directory; no release manifests are written into the origin catalog. Shared schemas/registries are unversioned app-owned implementation assets. The authoring tree is nested; delivery is a flat notebook-only ZIP. See origin packaging. Tutorial packaging is independent.

Source adapters

The Config cell contains exactly one whole-line # <SIMULATION_TARGET_HANDLING> marker. The composer replaces it with one registered block from the app's bundled registry (reference tooling: scripts/contracts/source_adapters/registry.json). Every family receives the identical registered block for that source mode. The handler owns its loading imports and PDK activation; simulator and pdk_provider aliases belong only to analysis code that uses them, not to the shared input contract. The result is self-contained native Python; generated notebooks do not import this repository's helper scripts.

The compact sources list declares accepted representations, for example ['py', 'gds', 'gsch_layout']. The reference reader resolves the unique registered adapter for each route and its output contract. Conflicting or ambiguous adapters are errors. A schematic-only SAX draft is discoverable but unavailable until its adapter is implemented. Unsupported representations are not offered.

Python requires an exact importable module, its canonical source file, the retained index/runtime source.import_root, an exported callable/attribute chain, and literal positional/keyword arguments. The loader adds only that import root to sys.path; it never substitutes the bundle working directory or project root. It preserves partial aliases, checks module origin before invocation, verifies Component return type and detects active-PDK changes. It does not guess a factory from a short registry name. Normal Python import/factory caching applies: restart the kernel when edited code needs fresh imports; this is not a general dependency reloader.

GDS uses an explicit selected cell and the native importer. Embedded ports remain unless source.explicit_ports deliberately supplies a complete replacement list. null preserves ports; an explicit empty list removes them. This data must never be populated from an automatic port snapshot. Names must be unique.

GSCH Layout rebuilds fresh GDS, rejects reported build warnings/dropped connections, runs native SDK LVS, then imports the selected cell. The current SDK requires the source stem, generated GDS stem and selected top-cell name to match. Its owning project/model catalog and runtime dependencies must be available. Missing model metadata and LVS findings stop loading. Legacy captured GSCH port snapshots are ignored; deliberately supplied explicit port definitions remain supported.

In every composed Config, PDK.activate() immediately follows the active PDK import. The reader derives the Config cell identity from required cell 2; creation execution policy belongs to the app. Creation, opening, reopening and Prepare never execute Config. Users run it manually in the owning-project kernel. There is no component = None assignment, bootstrap, secret, or USER/AUTO cell classification.

Tokens and central authority

Use <INSERT_AUTO_NAME_HERE> or <INSERT_USER_NAME_HERE> independently of the Python variable or argument name. USER/AUTO mode, registered provider, value schema, provenance and review presentation are independent. A USER number is possible; automatically selected USER values remain editable USER choices.

Per-slot records are optional. A used reserved token resolves through the immutable binding_kinds.json alias table. An unknown AUTO name with an exact lowercase key in settings_defaults inherits AUTO_PARAMETER for arrays/objects or AUTO_TEMPLATE_DEFAULT otherwise. A known numerical default therefore needs no redundant kind/default/label record. Unknown USER names require an explicit registered kind. Metadata cannot add a provider or change fixed project/source/artifact semantics. No same-name project/template merge occurs.

The internal token_bindings projection has optional slots/relations and no version field. Each optional slot requires only name; supported fields are kind, default_key, label, units, schema, review, confirmation, selection_policy, boundary, fixed_fields and exclude_keys. Unknown/duplicate fields and conflicting fixed semantics fail. Schemas intersect the registered envelope and support only the bounded local-only vocabulary in the approved app spec. Units are display text; they do not convert data. Known aliases can display µm while valid units such as pF remain literal. Defaults, schemas and finite values are validated before use.

Provider Binding authority
project_root / pdk_module / pdk_qualified_name Retained owning-project/PDK context
source_field Exact module/file/import root, args/kwargs, selected cell/original source/deliberate ports
artifact_path App-owned route-specific GDS/LVS/dschematic/prepare/results/export roles
wavelength Required owning-project sim.x, then legacy sim.wls; no creation overrides
template_default / parameter Retained template settings_defaults; no creation overrides
captured_parameter Authorized declared template asset copied into inputs/, with byte revalidation
optical_port / USER parameter kinds Confirmed eligible optical port, or explicit layer name(s), including custom literal keys

All payloads are finite JSON data serialized as Python literals. Only the PDK import uses validated dotted-identifier serialization. There are no AUTO_CODE, AUTO_ARGUMENTS or generated factory-call bindings. Settings dictionaries are consumed by ordinary authored Python, such as sim.domain(**domain_settings). Solver/material-specific handling belongs in the canonical analysis notebook. Declarations can constrain supplied settings with fixed_fields before filtering reserved keys. Meep's 3D template requires mode: "3d" and null x/y/z cuts; contradictory settings fail instead of being silently discarded.

For example:

{"name":"CELL_SIZE_NM", "label":"grid spacing", "units":"nm",
 "schema":{"type":"number","exclusiveMinimum":0}}

AUTO means no creation prompt or editable creation value. Generated notebooks remain manually editable. Every optical port requires explicit confirmation, including a unique boundary suggestion. Layer questions always require an explicit answer, never a default or an automatic answer from a unique suggestion. Candidate inspection is grouped by used domains, and unused route declarations cause no factory or port construction. Distinct USER port pairs use only the registered {kind: "distinct", slots: [...]} relation. The app owns inspection and choice UI.

USER_PDK_LAYER and USER_PDK_LAYERS accept only the required literal name, preserved as the prompt and input identity. default and pdk_layer_role are rejected whenever present. Singular returns a nonempty string; plural returns a nonempty list of distinct nonempty strings. Explicit custom names remain literal values and do not create PDK layers. The stack supplies searchable suggestions, not a closed allowed-value list. See the layer-input handoff.

Defaults and context

Project sim.x takes precedence over legacy sim.wls, including invalid sim.x. Require authored finite positive min/max with min <= max. Convert GHz/THz frequency ranges into reversed wavelength bounds. Resolve min/max and center/full span in micrometers at creation; never put a TOML reader or duplicate wavelength defaults in notebooks. Binding rejects wavelength_overrides and any AUTO parameter answer. Missing or invalid project sweep settings block creation. The window must stay above zero.

The reserved <INSERT_AUTO_WAVELENGTH_MIN_UM_HERE> and <INSERT_AUTO_WAVELENGTH_MAX_UM_HERE> tokens expose the normalized endpoints directly. Center (WAVELENGTH_CENTER_UM, also aliased as WAVELENGTH_UM) and full span (WAVELENGTH_SPAN_UM) remain supported. All four values come from one project read per binding plan. Preserve endpoint precision instead of reconstructing bounds from rounded center/span; equal endpoints are valid and give zero span. No origin metadata declarations or USER questions are added for these AUTO tokens.

Counts always come from template metadata: Meep 11, zapFDTD 11, MEOW 3. Project num and historical context counts do not replace them. Other numeric settings retain their template-owned defaults and declared constraints. These are starting values, not new convergence evidence.

The creation API is python -m scripts.bind_template --context context.json --output NEW_DIRECTORY. Its common context is documented by scripts/contracts/binding_context.schema.json. Supply template_id, pdk_module, source, required project context for project-owned values, and parameters containing only used USER answers. binding_candidates carries retained optical_ports, layer_names, layer_names_available, and optional physical optical_evidence. This reference context is a caller-provided capture; it is not a way to override the server's retained AUTO authority. Destination suggestion/editing stays app-owned, then supplies AUTO artifact paths. Creation does not import the selected design or simulator packages.

There is one current binding structure, with no numbered compatibility dispatch. Old engine-specific creation contexts and precomposed route exports are not current app creation inputs. Unknown fields and unsupported adapters fail clearly.

Extend and verify

Copy a canonical notebook, change its identity/title/engine/file names and analysis, select compatible adapters, and declare consumed tokens/defaults. An unknown engine name needs no binding/composition code change. A genuinely new input representation needs a new shared adapter, its output contract and tests.

Keep all analysis cells, comments and unrelated metadata. After substitution the binder compiles code, clears outputs/counts and scans the whole notebook—including Markdown, metadata keys, attachments and joined source fragments—for unresolved tokens. Any remaining token blocks publication. Files are staged in a fresh bundle; existing destinations are rejected. Token-looking data is rejected, not recursively interpreted. Shapes/ports/materials and solver qualification remain native analysis responsibilities. Update app-owned adapters and their tests together when behavior changes; do not promise compatibility with arbitrary scripts or all future package APIs.

Portable Python alternatives

Config includes an explicitly delimited, commented direct-factory alternative. The Python reference binder fills its tokens, including dotted import/attribute positions, without executing the alternative. Users uncomment that section and delete the rest of Config. Solver helpers are retained in the alternative. Non-Python route exports omit it so factory inputs are never requested for GDS. The schematic-only SAX draft instead retains its explicit schematic loading.

The app-side binder needs the same bounded-comment and route filtering support before it can consume these origins. This repository update does not implement that separate backend change. Arbitrary comments still cannot contain tokens.