tidy3d.plugins.smatrix.TerminalComponentModelerData

class TerminalComponentModelerData

Bases: AbstractComponentModelerData

Data associated with a TerminalComponentModeler simulation run.

Parameters:

• attrs (dict = {}) – Dictionary storing arbitrary metadata for a Tidy3D object. This dictionary can be freely used by the user for storing data without affecting the operation of Tidy3D as it is not used internally. Note that, unlike regular Tidy3D fields, attrs are mutable. For example, the following is allowed for setting an attr obj.attrs['foo'] = bar. Also note that Tidy3D` will raise a TypeError if attrs contain objects that can not be serialized. One can check if attrs are serializable by calling obj.json().

• modeler (TerminalComponentModeler) – The original TerminalComponentModeler object that defines the simulation setup and from which this data was generated.

• data (SimulationDataMap) – A mapping from task names to SimulationData objects, containing the results of each simulation run.

• log (Optional[str] = None) – A string containing the log information from the modeler post-processing run.

Notes

This class serves as a data container for the results of a component modeler simulation, with the original simulation definition, and port simulation data, and the solver log.

References

[1]

R. B. Marks and D. F. Williams, “A general waveguide circuit theory,” J. Res. Natl. Inst. Stand. Technol., vol. 97, pp. 533, 1992.

[2]

D. M. Pozar, Microwave Engineering, 4th ed. Hoboken, NJ, USA: John Wiley & Sons, 2012.

Attributes

port_reference_impedances	Calculates the reference impedance for each port across all frequencies.
data
attrs

Methods

ab_to_s(a_matrix, b_matrix)	Get the scattering matrix given the wave amplitude matrices.
check_port_impedance_sign(Z_numpy)	Sanity check for consistent sign of real part of Z for each port.
compute_F(Z_numpy[, s_param_def])	Helper to convert port impedance matrix to F, which is used for computing scattering parameters
compute_port_VI(port_out, sim_data)	Compute the port voltages and currents.
compute_power_delivered_by_port(port, sim_data)	Compute the power delivered to the network by a lumped port.
compute_power_wave_amplitudes(port, sim_data)	Calculates the unnormalized power wave amplitudes from port voltage (V), current (I), and impedance (Z0) using:
compute_power_wave_amplitudes_at_each_port(...)	Compute the incident and reflected power wave amplitudes at each port.
compute_wave_amplitudes_at_each_port(sim_data)	Compute the incident and reflected amplitudes at each port.
get_antenna_metrics_data([port_amplitudes, ...])	Calculate antenna parameters using superposition of fields from multiple port excitations.
s_to_z(reference[, assume_ideal_excitation, ...])	Converts the S-matrix to the Z-matrix using a specified reference impedance.
smatrix([assume_ideal_excitation, s_param_def])	Computes and returns the S-matrix and port reference impedances.

Inherited Common Usage

modeler

smatrix(assume_ideal_excitation=None, s_param_def=None)

Computes and returns the S-matrix and port reference impedances.

Parameters:

• assume_ideal_excitation (If True, assumes that exciting one port) – does not produce incident waves at other ports. This simplifies the S-matrix calculation and is required if not all ports are excited. If not provided, modeler.assume_ideal_excitation is used.

• s_param_def (The definition of S-parameters to use, determining whether) – “pseudo waves” or “power waves” are calculated. If not provided, modeler.s_param_def is used.

Returns:

Container with the computed S-parameters and the port reference impedances.

Return type:

MicrowaveSMatrixData

get_antenna_metrics_data(port_amplitudes=None, monitor_name=None)

Calculate antenna parameters using superposition of fields from multiple port excitations.

The method computes the radiated far fields and port excitation power wave amplitudes for a superposition of port excitations, which can be used to analyze antenna radiation characteristics.

Parameters:

• port_amplitudes (dict[str, complex]) – Dictionary mapping port names to their desired excitation amplitudes. For each port, \(\frac{1}{2}|a|^2\) represents the incident power from that port into the system. If None, uses only the first port without any scaling of the raw simulation data. When None is passed as a port amplitude, the raw simulation data is used for that port. Note that in this method a represents the incident wave amplitude using the power wave definition in [2].

• monitor_name (str) – Name of the DirectivityMonitor to use for calculating far fields. If None, uses the first monitor in radiation_monitors.

Returns:

Container with antenna parameters including directivity, gain, and radiation efficiency, computed from the superposition of fields from all excited ports.

Return type:

AntennaMetricsData

property port_reference_impedances

Calculates the reference impedance for each port across all frequencies.

This function determines the characteristic impedance for every port defined in the modeler. It handles two types of ports differently: for a WavePort, the impedance is frequency-dependent and computed from modal properties, while for other types like LumpedPort, the impedance is a user-defined constant value.

Returns:

A data array containing the complex impedance for each port at each frequency.

compute_wave_amplitudes_at_each_port(sim_data, port_reference_impedances=None, s_param_def='pseudo')

Compute the incident and reflected amplitudes at each port. The computed amplitudes have not been normalized.

Parameters:

• sim_data (SimulationData) – Results from the simulation.

• port_reference_impedances (PortDataArray, optional) – Reference impedance at each port. If not provided, it is computed from the cached property port_reference_impedances(). Defaults to None.

• s_param_def (SParamDef) – The type of waves computed, either pseudo waves defined by Equation 53 and Equation 54 in [1], or power waves defined by Equation 4.67 in [2].

Returns:

Incident (a) and reflected (b) wave amplitudes at each port.

Return type:

tuple[PortDataArray, PortDataArray]

compute_power_wave_amplitudes_at_each_port(sim_data, port_reference_impedances=None)

Compute the incident and reflected power wave amplitudes at each port. The computed amplitudes have not been normalized.

Parameters:

• sim_data (SimulationData) – Results from the simulation.

• port_reference_impedances (PortDataArray, optional) – Reference impedance at each port. If not provided, it is computed from the cached property port_reference_impedances(). Defaults to None.

Returns:

Incident (a) and reflected (b) power wave amplitudes at each port.

Return type:

tuple[PortDataArray, PortDataArray]

s_to_z(reference, assume_ideal_excitation=None, s_param_def='pseudo')

Converts the S-matrix to the Z-matrix using a specified reference impedance.

This method first computes the S-matrix of the device and then transforms it into the corresponding impedance matrix (Z-matrix). The conversion can be performed using either a single, uniform reference impedance for all ports or a more general set of per-port, frequency-dependent reference impedances.

This method TerminalComponentModelerData.s_to_z() is called on a TerminalComponentModelerData object, which contains the S-matrix and other simulation data internally.

Parameters:

• reference (Union[complex, PortDataArray]) – The reference impedance(s) to use for the conversion. If a single complex value is provided, it is assumed to be the reference impedance for all ports. If a PortDataArray is given, it should contain the specific reference impedance for each port.

• assume_ideal_excitation (If True, assumes that exciting one port) – does not produce incident waves at other ports. This simplifies the S-matrix calculation and is required if not all ports are excited. If not provided, modeler.assume_ideal_excitation is used.

• s_param_def (SParamDef, optional) – The definition of the scattering parameters used in the S-matrix calculation. This can be either “pseudo” for pseudo waves (see [1]) or “power” for power waves (see [2]). Defaults to “pseudo”.

Returns:

The computed impedance (Z) matrix, with dimensions corresponding to the ports of the device.

Return type:

DataArray

Examples

>>> z_matrix = component_modeler_data.s_to_z(reference=50) 
>>> z_11 = z_matrix.sel(port_out="port_1@0", port_in="port_1@0") 

See also

smatrix

Computes the scattering matrix.

static ab_to_s(a_matrix, b_matrix)

Get the scattering matrix given the wave amplitude matrices.

Parameters:

• a_matrix (TerminalPortDataArray) – Matrix of incident power wave amplitudes.

• b_matrix (TerminalPortDataArray) – Matrix of reflected power wave amplitudes.

Returns:

The computed scattering (S) matrix.

Return type:

TerminalPortDataArray

static compute_F(Z_numpy, s_param_def='pseudo')

Helper to convert port impedance matrix to F, which is used for computing scattering parameters

The matrix F is used when converting between S and Z parameters for circuits with differing port impedances. Its diagonal elements are defined as

\[F_{kk} = 1 / (2 * \sqrt{Re(Z_k)})\]

Parameters:

• Z_numpy (ArrayFloat1D) – NumPy array of complex port impedances.

• s_param_def (SParamDef, optional) – The type of wave amplitudes, by default “pseudo”.

Returns:

NumPy array containing the computed F values.

Return type:

ArrayFloat1D

static check_port_impedance_sign(Z_numpy)

Sanity check for consistent sign of real part of Z for each port.

This check iterates through each port and ensures that the sign of the real part of its impedance does not change across all frequencies. A sign change can indicate an unphysical result or numerical instability.

Parameters:

Z_numpy (np.ndarray) – NumPy array of impedance values with shape (num_freqs, num_ports).

Raises:

Tidy3dError – If an inconsistent sign of the real part of the impedance is detected for any port.

static compute_port_VI(port_out, sim_data)

Compute the port voltages and currents.

Parameters:

• port_out (TerminalPortType) – Port for computing voltage and current.

• sim_data (SimulationData) – Results from simulation containing field data.

Returns:

Voltage and current values at the port as frequency arrays.

Return type:

tuple[PortVoltageType, PortCurrentType]

static compute_power_wave_amplitudes(port, sim_data)

Calculates the unnormalized power wave amplitudes from port voltage (V), current (I), and impedance (Z0) using:

\[a = (V + Z0*I) / (2 * \sqrt(Re(Z0))) b = (V - Z0*I) / (2 * \sqrt(Re(Z0)))\]

Parameters:

• port (LumpedPortType) – Port for computing voltage and current.

• sim_data (SimulationData) – Results from the simulation.

Returns:

Incident (a) and reflected (b) power wave amplitude frequency arrays.

Return type:

tuple[FreqDataArray, FreqDataArray]

static compute_power_delivered_by_port(port, sim_data)

Compute the power delivered to the network by a lumped port. The power is calculated as the incident power minus the reflected power:

\[P = 0.5 * (|a|^2 - |b|^2)\]

Parameters:

• port (LumpedPortType) – Port for computing voltage and current.

• sim_data (SimulationData) – Results from the simulation.

Returns:

Power in units of Watts as a frequency array.

Return type:

FreqDataArray

__hash__()

Hash method.