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:
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¶
- Validates the inputs (above).
- Builds the stack and checks the port layer is a conductor.
- 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 = 0for ports on 0/180 degrees,margin_y = 0for 90/270); mixed orientations raise aValueError. - 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 defaultexcited=True; whether this yields the full S-matrix is not verified here. - Sets the sweep with
set_driven(fmin=..., fmax=..., num_points=num_freqs)and printsvalidate_config(). - Meshes with the preset, prints
print_mesh_stats()(tetrahedra and the field DOF estimate), callswrite_config()and printsvalidate_mesh(). - Prints
port_information.json, written next toconfig.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. - 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 asmesh_conductors_ports.pngandmesh_domain.pngnext 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.pybinds 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 inconfig.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 declaredgsimrequirement, and that only the Run cell calls.run(.run,upload,startandwait_for_resultsare 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.pyuses a synthetic matched through line: Touchstone round trip throughSParams.from_touchstone,to_skrfandwrite_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 toFAMILIESintest_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_stackthe right entry point, or shouldset_stacktake overrides? - Identity.
palace_driven/palace, folderdriven_sparams, readinessdraft,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.