Ports and excitation

A port is where the simulation feeds energy into the structure and measures the response. This page covers the four port types, the options every port carries, the excitation waveform, and what validate checks before a run.

What a port is

A port is a shape of kind port. Each port is both an excitation source and a measurement site. Its active flag decides which: an active port is driven, a passive port is a matched load that the run still measures.

A run produces one S-matrix column per driven port: driving port n yields S1n, S2n, and so on across every measured port. The two surfaces gate this differently. The desktop app requires exactly one active port per run and refuses to start with several, so a full matrix is built one driven port at a time. The CLI accepts several active ports in one rayrf run and emits a column for each. If no port is active the CLI warns and computes the port-1 column only.

Port types

Four port types cover vertical and in-plane feeds, straight from the geometry registry:

`point`

Single-cell vertical probe between two conductor layers.

Param	Type	Units	Default	Required	Meaning
`x_mm`	number	mm	`0`	yes	X of the feed point.
`y_mm`	number	mm	`0`	yes	Y of the feed point.
`port_number`	int		`1`	yes	Port index.
`impedance_ohm`	number	Ohm	`50`		Reference impedance.
`active`	bool		`false`		Drive (True) or load (False).
`top_layer`	string			yes	Positive-terminal conductor layer.
`bottom_layer`	string			yes	Negative-terminal conductor layer.
`deembed_mm`	number	mm	`0`		Reference-plane shift distance.
`deembed_dir`	string				Shift direction: one of x+, x-, y+, y-.

`rect`

Distributed rectangular (area) feed between two conductor layers.

Param	Type	Units	Default	Required	Meaning
`x_mm`	number	mm	`0`	yes	X of the footprint center.
`y_mm`	number	mm	`0`	yes	Y of the footprint center.
`w_mm`	number	mm	`none`	yes	Footprint width.
`h_mm`	number	mm	`none`	yes	Footprint height.
`port_type`	string		`rect`	yes	Must be 'rect'.
`port_number`	int		`1`	yes	Port index.
`impedance_ohm`	number	Ohm	`50`		Reference impedance.
`active`	bool		`false`		Drive (True) or load (False).
`direction`	string		`z`		Feed axis: z (transverse), x, or y.
`top_layer`	string			yes	Positive-terminal conductor layer.
`bottom_layer`	string			yes	Negative-terminal conductor layer.
`deembed_mm`	number	mm	`0`		Reference-plane shift distance.
`deembed_dir`	string				Shift direction: one of x+, x-, y+, y-.

`line`

In-plane line feed across a gap on a single conductor layer. The feed injects along the dominant X or Y component of p0 to p1; the drawn footprint is kept, and validate warns when the director is off-axis.

Param	Type	Units	Default	Required	Meaning
`p0_x_mm`	number	mm	`0`	yes	Endpoint 0 X (negative terminal).
`p0_y_mm`	number	mm	`0`	yes	Endpoint 0 Y (negative terminal).
`p1_x_mm`	number	mm	`none`	yes	Endpoint 1 X (positive terminal).
`p1_y_mm`	number	mm	`none`	yes	Endpoint 1 Y (positive terminal).
`width_mm`	number	mm	`0.1`		Strip width perpendicular to the line.
`port_type`	string		`line`	yes	Must be 'line'.
`port_number`	int		`1`	yes	Port index.
`impedance_ohm`	number	Ohm	`50`		Reference impedance.
`active`	bool		`false`		Drive (True) or load (False).
`bottom_layer`	string			yes	Conductor layer the feed sits on.
`top_layer`	string				Same layer as bottom_layer for a planar feed.
`excitation_mode`	string		`planar`		Must be 'planar'.

`bar`

In-plane bar feed on a single conductor layer. The feed injects along the dominant X or Y component of its director.

Param	Type	Units	Default	Required	Meaning
`x_mm`	number	mm	`0`	yes	Bar center X.
`y_mm`	number	mm	`0`	yes	Bar center Y.
`length_mm`	number	mm	`1`	yes	Gap length along the feed director.
`width_mm`	number	mm	`4`	yes	Transverse bar width.
`angle_deg`	int	deg	`0`		Director angle from +X. The feed injects along the dominant axis, so use 0/90/180/270 to match the drawn bar exactly.
`port_type`	string		`bar`	yes	Must be 'bar'.
`port_number`	int		`1`	yes	Port index.
`impedance_ohm`	number	Ohm	`50`		Reference impedance.
`active`	bool		`false`		Drive (True) or load (False).
`bottom_layer`	string			yes	Conductor layer the feed sits on.
`top_layer`	string				Same layer as bottom_layer for a planar feed.
`excitation_mode`	string		`planar`		Must be 'planar'.

Placement the table does not carry:

A point port is a single-cell vertical probe. It drives the gap between a top_layer and a bottom_layer, so the two must be different conductor layers. Reach for it as the default lumped feed on a narrow trace.
A rect port spreads the same vertical feed across a footprint you drag out. Use it when a single cell is too coarse for the conductor, such as a wide trace or a patch edge. Its direction sets the feed axis: z feeds vertically between bottom_layer and top_layer, x or y feeds in-plane along that axis.
A line port is an in-plane feed across a gap on one layer, set by two endpoints: p0 is the negative terminal, p1 the positive, and current runs p0 to p1. Use it for a coplanar or edge feed where both terminals sit on the same layer. The endpoints come from the two-click placement, not a dialog, and snap to the nearest axis.
A bar port is a fixed in-plane bar on one layer, placed with a single click. Use it when you want a set-orientation in-plane gap rather than two picked endpoints. The bar is axis-aligned: its director angle is a multiple of 90 degrees, and the property panel rejects any other value.

The point and line dialogs set the electrical options and the layers:

Common options

Every port carries the same electrical options.

port_number names the S-matrix column, so keep it unique across the project. Two ports sharing a number leave the S-matrix mapping undefined, which validate warns about. A new port takes the lowest unused number.
impedance_ohm is the reference impedance the S-parameters normalize to, 50 by default. It must be positive: the wave math divides by its square root.
De-embedding shifts the measurement plane off the feed. Set deembed_mm to the distance and deembed_dir to the direction (x+, x-, y+, or y-) pointing from the feed toward the device. A shift of 0 measures right at the feed. Use it to subtract a feed line so the reported impedance and S-parameters refer to the device itself. The distance cannot be negative, as the direction control sets the sign.

Ports serialize into the solver input as lumped feeds: a point port becomes a lumped_point, the others a lumped_rect, with the impedance carried as R_ohm. An in-plane line or bar emits along its dominant axis, since the backend feeds only along X, Y, or Z.

Excitation

The source is a Gaussian pulse spanning the frequency band, from freq_min_hz to freq_max_hz. One broadband pulse excites the whole band in a single run, and the S-parameters come from the ratio of the transformed port voltages and currents.

Continuous-wave mode replaces the pulse with a steady sinusoid at one frequency. It never rings down and produces no meaningful S-parameters, so it is for field animations only. CW is an advanced-mode feature, and an auto-mode project with CW on is refused rather than run as a pulse. See FDTD tips.

What validate catches

Run validate before a run. For ports it reports:

A zero-height span, as an error. A point or rect port whose top and bottom conductors land on the same mesh layer collapses to no vertical extent and injects nothing. Setting top_layer equal to bottom_layer is the same mistake and is flagged as a warning.
No active port, as a warning. With nothing driven there is no excitation and no S-parameters, and a project with no ports at all warns the same way.
A port that maps to zero cells or lies outside the domain, as an error, and a non-positive impedance or a negative de-embed distance, as an error.
A duplicate port_number or an unrecognized deembed_dir, as a warning.
An off-axis in-plane feed, as a warning. The editor keeps placements on-axis, but a spec-built line or bar can carry any director. The exporter then drives the dominant X or Y component while the footprint stays as drawn, so an unintended off-axis feed injects along one axis only.