Skip to content

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 example requirements = {'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:

cell_size_nm = (
    <INSERT_USER_INPUT_HERE>
    (
        name="Cell size (nm)",
        default=60.0,
    )
)

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.