tidy3d.plugins.smatrix.TerminalComponentModeler

tidy3d.plugins.smatrix.TerminalComponentModeler#

class TerminalComponentModeler[source]#

Bases: AbstractComponentModeler, MicrowaveBaseModel

Tool for modeling two-terminal multiport devices and computing port parameters with lumped and wave ports.

Parameters:

  • name (str =)

  • simulation (Simulation) – Simulation describing the device without any sources present.

  • ports (tuple[Union[LumpedPort, CoaxialLumpedPort, WavePort, TerminalWavePort], …] = ()) – Collection of lumped and wave ports associated with the network. For each port, one simulation will be run with a source that is associated with the port.

  • freqs (ArrayLike[dtype=float, ndim=1]) – [units = Hz]. Array or list of frequencies at which to compute port parameters.

  • remove_dc_component (bool = True) – Whether to remove the DC component in the Gaussian pulse spectrum. If True, the Gaussian pulse is modified at low frequencies to zero out the DC component, which is usually desirable so that the fields will decay. However, for broadband simulations, it may be better to have non-vanishing source power near zero frequency. Setting this to False results in an unmodified Gaussian pulse spectrum which can have a nonzero DC component.

  • run_only (Optional[tuple[str, ...]] = None) – Set of matrix indices that define the simulations to run. If None, simulations will be run for all indices in the scattering matrix. If a tuple is given, simulations will be run only for the given matrix indices.

  • element_mappings (tuple[tuple[tuple[str, str], tuple[str, str], complex], ...] = ()) – Tuple of S matrix element mappings, each described by a tuple of (input_element, output_element, coefficient), where the coefficient is the element_mapping coefficient describing the relationship between the input and output matrix element. If all elements of a given column of the scattering matrix are defined by element_mappings, the simulation corresponding to this column is skipped automatically.

  • custom_source_time (Optional[Union[GaussianPulse, ContinuousWave, CustomSourceTime, BroadbandPulse, BasebandStep, BasebandGaussianPulse, BasebandRectangularPulse, BasebandCustomSourceTime]] = None) – If provided, this will be used as specification of the source time-dependence in simulations. Otherwise, a default source time will be constructed.

  • radiation_monitors (tuple[Union[DirectivityMonitor, DirectivityMonitorSpec], …] = ()) – Facilitates the calculation of figures-of-merit for antennas. These monitors will be included in every simulation and record the radiated fields. Users can specify a combination of DirectivityMonitor objects for manual placement and DirectivityMonitorSpec objects for automatic generation.

  • assume_ideal_excitation (bool = False) – If True, only the excited port is assumed to have a nonzero incident wave amplitude power. This choice simplifies the calculation of the scattering matrix. If False, every entry in the vector of incident wave amplitudes (a) is calculated explicitly. This choice requires a matrix inversion when calculating the scattering matrix, but may lead to more accurate scattering parameters when there are reflections from simulation boundaries.

  • s_param_def (Literal['pseudo', 'power', 'symmetric_pseudo'] = pseudo) – Wave definition: ‘pseudo’, ‘power’, or ‘symmetric_pseudo’. Default is ‘pseudo’.

  • low_freq_smoothing (Optional[ModelerLowFrequencySmoothingSpec] = None) – The low frequency smoothing parameters for the terminal component simulation.

  • structure_priority_mode (Optional[Literal['equal', 'conductor']] = conductor) – If not None, override the structure priority mode in the simulation. This field only affects structures of priority=None. If equal, the priority of those structures is set to 0; if conductor, the priority of structures made of LossyMetalMedium is set to 90, PECMedium to 100, and others to 0.

Notes

S-Parameter Definitions

The s_param_def parameter controls which wave definition is used to compute scattering parameters. Three definitions are supported:

  • "pseudo" (default): Pseudo-waves as defined by Marks and Williams [1]. Uses scaling factor \(F = \sqrt{\text{Re}(Z)} / (2|Z|)\). Wave amplitudes are \(a = F(V + ZI)\) and \(b = F(V - ZI)\).

  • "power": Power waves as defined by Kurokawa [3] and described in Pozar [2]. Uses scaling factor \(F = 1 / (2\sqrt{\text{Re}(Z)})\). Wave amplitudes are \(a = F(V + ZI)\) and \(b = F(V - Z^*I)\) where \(Z^*\) is the complex conjugate. Ensures \(|a|^2 - |b|^2\) represents actual power flow.

  • "symmetric_pseudo": Equivalent to pseudo-waves except for the scaling factor. Uses \(F = 1 / (2\sqrt{Z})\) where the square root is complex. This choice of scaling factor ensures the S-matrix will be symmetric when the simulated device is reciprocal.

References

Attributes

base_sim

The base simulation with all components added, including radiation monitors.

matrix_indices_monitor

Tuple of all the possible matrix indices.

matrix_indices_run_sim

Tuple of all the matrix indices that will be used to run simulations.

matrix_indices_source

Tuple of all the source matrix indices, which may be less than the total number of ports.

network_dict

Dictionary associating each unique NetworkIndex to a port and mode/terminal index.

sim_dict

Generate all the Simulation objects for the port parameter calculation.

ports

run_only

element_mappings

radiation_monitors

assume_ideal_excitation

s_param_def

low_freq_smoothing

structure_priority_mode

name

simulation

freqs

remove_dc_component

custom_source_time

Methods

get_radiation_monitor_by_name(monitor_name)

Find and return a DirectivityMonitor monitor by its name.

mode_solver_for_port(port_name)

Get the mode solver object for a given port.

network_index(port[, mode_index, terminal_label])

Converts the port, and a mode_index when the port is a WavePort, or a terminal_label when the port is a TerminalWavePort, to a unique string specifier.

plot_port(port[, ax, label_font_size])

Plot a Simulation on the port plane.

plot_sim([x, y, z, ax])

Plot a Simulation with all sources and absorbers.

plot_sim_eps([x, y, z, ax])

Plot permittivity of the Simulation.

plot_sim_grid([x, y, z, ax])

Plot the cell boundaries as lines on a plane defined by one nonzero x,y,z coordinate.

task_name_from_index(source_index)

Compute task name for a given network index without constructing simulations.
ports#
run_only#
element_mappings#
radiation_monitors#
assume_ideal_excitation#
s_param_def#
low_freq_smoothing#
structure_priority_mode#
plot_sim(x=None, y=None, z=None, ax=None, **kwargs)[source]#

Plot a Simulation with all sources and absorbers.

This is a convenience method to visualize the simulation setup for troubleshooting. It shows all sources and absorbers for each port.

Parameters:

  • x (float, optional) – x-coordinate for the cross-section.

  • y (float, optional) – y-coordinate for the cross-section.

  • z (float, optional) – z-coordinate for the cross-section.

  • ax (matplotlib.axes.Axes, optional) – Axes to plot on.

  • **kwargs – Keyword arguments passed to Simulation.plot().

Returns:

The axes with the plot.

Return type:

matplotlib.axes.Axes

plot_sim_grid(x=None, y=None, z=None, ax=None, **kwargs)[source]#

Plot the cell boundaries as lines on a plane defined by one nonzero x,y,z coordinate.

This is a convenience method to visualize the simulation grid setup for troubleshooting.

Parameters:

  • x (float, optional) – x-coordinate for the cross-section.

  • y (float, optional) – y-coordinate for the cross-section.

  • z (float, optional) – z-coordinate for the cross-section.

  • ax (matplotlib.axes.Axes, optional) – Axes to plot on.

  • **kwargs – Keyword arguments passed to Simulation.plot_grid().

Returns:

The axes with the plot.

Return type:

matplotlib.axes.Axes

plot_sim_eps(x=None, y=None, z=None, ax=None, **kwargs)[source]#

Plot permittivity of the Simulation.

This method shows the permittivity distribution of the simulation with all sources and absorbers added for each port.

Parameters:

  • x (float, optional) – x-coordinate for the cross-section.

  • y (float, optional) – y-coordinate for the cross-section.

  • z (float, optional) – z-coordinate for the cross-section.

  • ax (matplotlib.axes.Axes, optional) – Axes to plot on.

  • **kwargs – Keyword arguments passed to Simulation.plot_eps().

Returns:

The axes with the plot.

Return type:

matplotlib.axes.Axes

plot_port(port, ax=None, label_font_size=None, **kwargs)[source]#

Plot a Simulation on the port plane.

This is a convenience method to visualize the port setup.

Parameters:

  • port (Union[str, TerminalPortType]) – The name or port object to plot.

  • ax (matplotlib.axes.Axes, optional) – Axes to plot on.

  • label_font_size (float, optional) – Font size for labels. If None, uses the default font size.

  • **kwargs – Keyword arguments passed to Simulation.plot().

Returns:

The axes with the plot.

Return type:

matplotlib.axes.Axes

mode_solver_for_port(port_name)[source]#

Get the mode solver object for a given port.

Parameters:

port_name (str) – Name of the port to get the mode solver for.

Returns:

The mode solver for the given port.

Return type:

ModeSolver

static network_index(port, mode_index=None, terminal_label=None)[source]#

Converts the port, and a mode_index when the port is a WavePort, or a terminal_label when the port is a TerminalWavePort, to a unique string specifier.

Parameters:

  • port (TerminalPortType) – The port to convert to an index.

  • mode_index (Optional[int]) – Selects a single mode from those supported by the port, which is only used when the port is a WavePort

  • terminal_label (Optional[str]) – Selects a single terminal from those supported by the port, which is only used when the port is a TerminalWavePort

Returns:

A unique string that is used to identify the row/column of the scattering matrix.

Return type:

NetworkIndex

property network_dict#

Dictionary associating each unique NetworkIndex to a port and mode/terminal index.

property matrix_indices_monitor#

Tuple of all the possible matrix indices.

property matrix_indices_source#

Tuple of all the source matrix indices, which may be less than the total number of ports.

property matrix_indices_run_sim#

Tuple of all the matrix indices that will be used to run simulations.

property sim_dict#

Generate all the Simulation objects for the port parameter calculation.

property base_sim#

The base simulation with all components added, including radiation monitors.

get_radiation_monitor_by_name(monitor_name)[source]#

Find and return a DirectivityMonitor monitor by its name.

Parameters:

monitor_name (str) – Name of the monitor to find.

Returns:

The monitor matching the given name.

Return type:

DirectivityMonitor

Raises:

Tidy3dKeyError – If no monitor with the given name exists.

task_name_from_index(source_index)[source]#

Compute task name for a given network index without constructing simulations.