Skip to content

Palace driven S-parameters template (generic)

One generic origin for gsim's Palace path: it takes any component from Python, GDS or GSCH Layout, drives its electrical ports over a frequency sweep and returns S-parameters. This is a draft. It checks that the geometry meshes, that ports lie inside the meshed domain and that the configuration validates; it does not qualify numerical accuracy. For the shared binding contract see the template token author guide, the compact metadata and the origin packaging notes.

Files

The canonical origin is origin_simulation_templates/palace/driven_sparams/palace_driven_sparams.ipynb, with its paired .py. Config declares template ID palace_driven, engine palace, sources py, gds and gsch_layout, and requirements = {'gsim': '>=0.9.0'}. Readiness is left at the default draft.

The notebook cells are: introduction, Config, Settings, Prepare and preview, Run, Results. Only the Run cell sends a job to the cloud; Prepare is local and free.

Settings

Five questions are asked when the notebook is created; everything else is an editable literal in the Settings cell.

Setting Kind Default Notes
Port names list input [] Component port names. An empty list uses every electrical port.
Port type text input 'lumped' 'lumped' or 'wave'. One type for all ports.
Port conductor layer PDK layer none The layer the ports sit on. Must be a conductor.
Conductor layers PDK layers none Layers treated as conductors.
Mesh preset text input 'coarse' 'coarse', 'default' or 'fine'.

Fixed literals: simulation_type = 'driven' (the only supported type), num_freqs = 40, lumped_port_length_um = 5.0 and airbox_um = {'margin_x': 20.0, 'margin_y': 20.0, 'z_above': 20.0, 'z_below': 5.0}. Distances are in micrometers.

Invalid values raise a ValueError that lists the allowed values, before anything is meshed: an unknown or non-electrical port name, a port type or mesh preset outside the lists above, a layer that is not in the PDK layer stack, and a port layer that is not a conductor.

Frequency range from the project sweep

The frequency range is not a question. The binder only fills the wavelength center and span tokens, so the notebook reads the project's pyproject.toml sweep, as the optical templates do, and converts it back to Hz:

[tool.gdsfactoryplus.sim.x]
name = "f"
unit = "GHz"
min = 1
max = 20

The binder turns the GHz window into a wavelength window (scripts/project_wavelengths.py); the Settings cell computes fmin_hz = c / (center + span / 2) and fmax_hz = c / (center - span / 2). A test checks that 1–20 GHz comes back within a relative 1e-9 and that config.json stores MinFreq 1.0 and MaxFreq 20.0 (GHz).

If the project sweep is optical (a wavelength sweep, or a THz frequency sweep), the resulting fmax_hz is above 1 THz and Prepare prints a warning. It does not stop: whether an optical sweep should stop the template is an open question (see below).

Ports are asked by name

There is no electrical-port picker. The only port token, USER_OPTICAL_PORT, rejects candidates unless their port type is optical, and PDK RF ports are electrical. Ports are therefore a plain list input checked inside Prepare. The app cannot check membership while the notebook is created; Prepare does. Adding a USER_ELECTRICAL_PORT binding kind would need changes in the binder, the kind registry and the app.

CPW ports are not offered, because add_cpw_port needs signal and gap widths.

Conductor marking

Prepare copies the active PDK layer stack, sets info['layer_type'] = 'conductor' on each chosen layer of the copy, and passes the copy to palace.extract_layer_stack(...) and then to DrivenSim.set_stack(stack). The PDK's own stack is not modified. Layers the PDK already classifies as conductors stay conductors even when not chosen (on the gpdk stack: metal1, heater, metal2, plus the chosen metal3). Demoting unchosen conductors is an open question.

What Prepare does

  1. Validates the inputs (above).
  2. Builds the stack and checks the port layer is a conductor.
  3. Creates palace.DrivenSim, sets the output directory, geometry, stack and airbox (set_airbox). For wave ports the airbox margin along the port normal is zero (margin_x = 0 for ports on 0/180 degrees, margin_y = 0 for 90/270); mixed orientations raise a ValueError.
  4. Adds the ports: add_port(name, layer=port_layer, length=lumped_port_length_um) for lumped, add_wave_port(name, layer=port_layer, max_size=True, mode=1) for wave. All ports keep the default excited=True; whether this yields the full S-matrix is not verified here.
  5. Sets the sweep with set_driven(fmin=..., fmax=..., num_points=num_freqs) and prints validate_config().
  6. Meshes with the preset, prints print_mesh_stats() (tetrahedra and the field DOF estimate), calls write_config() and prints validate_mesh().
  7. Prints port_information.json, written next to config.json: port number, type and bounding box (lumped ports also carry their name; wave ports do not). On the gpdk straight, port numbers follow the order the ports were added.
  8. Plots the conductors and ports (plot_mesh(show_groups=[*conductor_layers, 'P'])), then a solid view of the whole domain with the outer boundary groups (<material>__None) transparent. Both are saved as mesh_conductors_ports.png and mesh_domain.png next to the configuration.

write_config() validates the mesh and raises if a port lies outside the meshed domain. Without an airbox it fails with RuntimeError: Port ... lies outside the meshed domain; a test removes the set_airbox call and checks this. This is the placement gate to read before running a billable job. With wave ports the outer boundary is PEC (gsim's waveport_boundary='pec' default), not an absorbing boundary.

DrivenSim.plot_stack() is not called: on gsim 0.9.0 it raises AttributeError: 'Layer' object has no attribute 'layer' for any stack passed to set_stack, including get_stack().

Size of the dry path

Measured on a gpdk metal straight (gf.components.straight(length=40, cross_section="metal_routing"), ports e1 and e2 on metal3), gsim 0.9.0, gdsfactory 9.44.0, one machine, 1–20 GHz with 40 points. Mesh time is the mesh() call only.

Port type Preset Tetrahedra Estimated field DOFs (order 2) Mesh time
lumped coarse 458 3,130 0.13 s
lumped default 982 6,504 0.12 s
lumped fine 3,691 23,808 0.26 s
wave coarse 518 3,910 0.12 s
wave default 1,314 9,726 0.17 s
wave fine 4,643 33,550 0.34 s

These sizes are for a 40 µm strip and say nothing about a real design. The presets use literal mesh sizes (auto_size=False); gsim warns that a 10 µm conductor feature may be under-resolved even on this strip. For real designs edit the sim.mesh(...) call to pass refined_mesh_size, max_mesh_size or auto_size=True. There is no credit estimate API in the template; read the tetrahedra and DOF printout instead.

A single strip with in-plane lumped ports has no ground reference, so a run of this example checks the plumbing, not physics.

Tests

  • tests/test_palace_driven_template.py binds all three routes, executes Config, Settings and Prepare of the bound notebook for lumped and wave ports on the Python and GDS routes, and checks the written files, the GHz sweep in config.json, the boundaries, the tetrahedra count (at most 2,000), the placement table and both preview PNGs. It also checks the bad-input errors, the missing-airbox failure, the declared gsim requirement, and that only the Run cell calls .run(. run, upload, start and wait_for_results are replaced with failing stubs, so no cloud call is possible. The GSCH Layout route is bound only; executing it needs the native SDK and LVS.
  • tests/test_palace_driven_results.py uses a synthetic matched through line: Touchstone round trip through SParams.from_touchstone, to_skrf and write_touchstone, plus the GHz → wavelength → Hz round trip.
  • The existing origin tests (test_inline_origins.py, test_portable_origins.py, test_template_cell_layout.py, test_generic_pipeline.py, test_package_origin_templates.py, test_origin_publish_contract.py, test_compact_metadata.py) pick the new origin up without edits. It is not added to FAMILIES in test_generic_pipeline.py, which expects 11 samples, not 40.

Run the template tests and the origin checks from the repository root:

python -m pytest tests/test_palace_driven_template.py tests/test_palace_driven_results.py -q
python -m scripts.check_origin_templates
python -m scripts.package_origin_templates

Cloud checks (not run)

These are launched by a person after the local checks pass. Bind the template with python -m scripts.bind_template --context ctx.json --output NEW_DIR, run Config, Settings and Prepare, and read the tetrahedra count before running the Run cell.

Job Component / PDK Port type Preset Purpose
1 gpdk metal straight, 1–20 GHz, 40 points lumped coarse Plumbing: submit, results, Touchstone. Expect about 458 tetrahedra.
2 same wave coarse Wave-port path. Expect about 518 tetrahedra.
3 (optional) IHP open PDK CPW from the Palace walkthrough, port_layer = topmetal2 lumped coarse Compare with the walkthrough's S-parameters. Tetrahedra not measured.

Open questions

  • Electrical port picker. Keep the name list, or add USER_ELECTRICAL_PORT.
  • Frequency range. Keep the project sweep through the wavelength tokens, or allow a frequency question (it would need changes to two existing tests). Should an optical sweep warn or stop?
  • Conductor semantics. Should unchosen conductors become dielectrics? Is extract_layer_stack the right entry point, or should set_stack take overrides?
  • Identity. palace_driven / palace, folder driven_sparams, readiness draft, gsim>=0.9.0.
  • Inputs. One port type and one port layer for all ports; all ports excited.
  • Wave-port airbox. Assumes ports on opposite x or y faces.

Follow-ups

Not in this template: an eigenmode origin (palace.EigenmodeSim), an electrostatic origin (palace.ElectrostaticSim), a 2D boundary-mode origin (which must set mg_max_levels=1 because of awslabs/palace#1177, an issue not verified here), CPW ports, per-port type and layer, and a USER_ELECTRICAL_PORT binding kind.