Compact template declarations¶
The notebook Config cell is the sole authoring authority. Canonical origins live
under origin_simulation_templates/<simulator>/<template>/. Per-template metadata
sidecars are not delivered; the authoring builder rejects them.
A single block bounded by # <TEMPLATE_METADATA> and # </TEMPLATE_METADATA>
contains literal assignments. It remains in the collapsed Config cell; the binder
removes it from the generated simulation notebook. Reading it never executes
imports, functions, comprehensions, references, or arbitrary Python code.
template: stable id and engine.sources: supported representations. Adapter names and output contracts come from the shared registry.requirements: optional package names (including extras) mapped to PEP 440 version specifiers, for examplerequirements = {'gsim': '>=0.8.0'}. Omit it when there are no package constraints. This feeds the app's dependency review; reading metadata never installs packages. URLs and environment markers are not accepted here.
Current origins do not repeat defaults, input schemas, labels, units, or port relations in this block. The analysis identity is its stable ID and engine; notebook byte hashes provide freshness checks.
Inputs in notebook code¶
Layer pickers accept only a required literal name, kept verbatim as the prompt.
Neither default nor pdk_layer_role is supported, even with null/empty values.
Singular returns a nonempty string; plural returns a nonempty list of distinct
nonempty strings. Users may explicitly supply custom names absent from the PDK
stack. These are literal values, not instructions to create layers. Stack entries
are suggestions, not a closed membership restriction. The app owns search,
name-based ranking and explicit custom entry; see the
layer-input handoff.
An explicit input expression opts into setup, wherever it appears:
cell_size_nm = <INSERT_USER_INPUT_HERE>(name="Cell size (nm)", default=60.0)
configure(resolution=<INSERT_USER_INPUT_HERE>(name="Resolution", default=20))
source_port = <INSERT_USER_OPTICAL_PORT_HERE>(name="Source port")
cladding = <INSERT_USER_PDK_LAYER_HERE>(name="Cladding layer")
geometry_layers = <INSERT_USER_PDK_LAYERS_HERE>(name="Geometry layers")
name is the exact display label, independent of any surrounding variable or
keyword. Ordinary USER_INPUT and optical-port tokens accept optional finite
JSON-compatible literal default values; layer tokens do not. The app parses
these without evaluating code. An omitted generic default requires text; zero,
false, an empty string, and explicit None are actual generic defaults, not omission.
Literal defaults determine basic input types. Collections use the existing JSON
editor. Optical choices/defaults must belong to the eligible port domain; explicit
custom layer names do not need to occur in the stack suggestions.
Inputs with the same display name and identical declaration share an answer, including in the bounded commented portable alternative. Conflicting declarations with the same name fail. Names determine internal stable keys; authors do not write these keys. Renaming a label changes that input's identity.
Only optical pickers accept boundary="west" or boundary="east". The taper
also retains selection_policy="unique_boundary_or_user". Different inline
optical inputs must select distinct ports. Native notebook checks retain the
upper/lower role ordering and physics-specific constraints.
Ordinary values do not become setup questions:
num_wavelengths = 11
slice_length_um = 0.5
wavelength_um = <INSERT_AUTO_WAVELENGTH_UM_HERE>
wavelength_span_um = <INSERT_AUTO_WAVELENGTH_SPAN_UM_HERE>
Project wavelength center/full span remain app supplied; sample count remains template owned. AUTO bindings do not accept inline defaults. Optional captured Meep stack/overlay paths retain app-owned authorization and copying, with absence represented as null. Plain mesh, padding, threshold, and override dictionaries are editable notebook code, not inferred UI fields.
Origins may also use <INSERT_AUTO_WAVELENGTH_MIN_UM_HERE> and
<INSERT_AUTO_WAVELENGTH_MAX_UM_HERE>. These return the normalized project
wavelength endpoints in micrometers, from the same acquired window as center/span.
No additional metadata is needed. For frequency sweeps the bounds reverse during
conversion: minimum wavelength comes from maximum frequency. The shorter
WAVELENGTH_UM token remains an alias for WAVELENGTH_CENTER_UM. See the
app-side handoff before deploying an origin that
uses the new tokens.
The generic calls must be expressions, not strings. Marker calls in comments are accepted only in the existing bounded, lexically checked portable Config section, where declarations stay on one commented line. Input calls are bounded to 64 KiB and literal depth 32; integer literal magnitude is at most 2^63-1. The binder replaces the complete call with a literal and removes every remaining authoring marker before publishing the user's notebook. No runtime input helper or extra shared implementation file is delivered.
Inline declarations bind as grouped value expressions, preserving precedence:
<INSERT_USER_INPUT_HERE>(name="X", default=-2)**2 becomes (-2)**2.
Whitespace and newlines may surround a declaration, separate its marker from
the opening parenthesis, and separate its keyword arguments. Follow normal Python
line-continuation rules around the expression, for example:
Declarations work in function arguments and defaults, containers, slices,
comprehensions, arithmetic, and other value-expression positions. They do not
generate identifiers, function declarations, or fragments of string contents.
To choose a function, use a string input as the key in an explicit function
registry or an explicit attribute lookup; input values remain data, not code.
The shared five-program fixture at tests/fixtures/inline_input_edge_cases.json
checks the bound behavior, including Unicode and delimiter characters in data.
Cell 1 must contain nonempty Markdown; a title heading is optional. The catalog
uses a nonempty # Title heading of at most 512 characters when present, otherwise
the stable template ID. Filename, export stem, Config cell ID,
prepare folder and adapter details are derived. No template, binding-schema or
adapter revision numbers are authored or generated. Reserved
bindings inherit registry semantics. Physics validation remains in the notebook;
the app validates declared input types, project authority, and picker membership.
Qualification evidence stays in existing documents, not in the discovery payload.
The reader accepts one current structure; obsolete context fields fail validation.
Shared schemas and adapters belong to the app. The reference CLI uses its own
unversioned copies under scripts/contracts, never copies from a downloaded
notebook's directory. Notebook byte hashes are retained in memory and revalidated
before publication; no self-hash is authored in Config.
origin_simulation_templates.zip flattens canonical notebooks to the ZIP root.
Python companions, sidecars, shared adapters, registries, schemas, README files,
directory entries and generated target exports are excluded. A normal origin is
delivered as one .ipynb. This transport rejects nonempty assets declarations
rather than silently losing required files. App-captured project inputs remain a
separate mechanism. The tutorial archive retains its existing packaging behavior.
See origin packaging for the layout and rollout gate.
The simulation-templates PR may merge before
DataLab PR #4034. Upload stays
disabled until the origin endpoint is deployed.
App migration boundary¶
The reference composer/binder supports this format; matching app integration must
remove the old numbered fields and identifiers too. That
does not update an already installed app or establish production DataLab delivery.
The current app catalog provider still uses GFP_NOTEBOOK_CATALOG_DIR.
The app parses literal data without executing Config, uses its compiled adapter and binding policy, validates constraints, retains acquired notebook/asset bytes, and rejects changes before publication. A notebook cannot replace a fixed source provider. Unknown routes remain unavailable; no output contract is invented for them. Legacy sidecar catalogs retain their existing separate compatibility path.
The upload compatibility gate runs current compact/binding/native helper tests. Historical engine-specific context suites are no longer release gates: those obsolete structures are rejected by the current reference binder. Their historical files are retained; they are not evidence for current creation.
The unversioned binding handoff lists the exact app changes required for the removed fields and adapter identifiers.