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.