tidy3d.plugins.smatrix.TerminalComponentModelerData

tidy3d.plugins.smatrix.TerminalComponentModelerData#

class TerminalComponentModelerData[source]#

Bases: AbstractComponentModelerData, MicrowaveBaseModel

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

Attributes

port_power_wave_matrices

Compute power-wave amplitude matrices for all port combinations.

port_pseudo_wave_matrices

Compute pseudo-wave amplitude matrices for all port combinations.

port_reference_impedances

Calculates the reference impedance for each port across all frequencies.

port_voltage_current_matrices

Compute voltage and current matrices for all port combinations.

data

attrs

Methods

ab_to_s(a_matrix, b_matrix)

Get the scattering matrix given the wave amplitude matrices.

change_port_reference_planes(smatrix[, ...])

Performs S-parameter de-embedding by shifting reference planes port_shifts um.

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_port_wave_amplitude_matrices([...])

Compute wave amplitude matrices for all port combinations.

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.

smatrix_deembedded([port_shifts])

Interface function returns de-embedded S-parameter matrix.

Inherited Common Usage

modeler#
smatrix(assume_ideal_excitation=None, s_param_def=None)[source]#

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

change_port_reference_planes(smatrix, port_shifts=None)[source]#

Performs S-parameter de-embedding by shifting reference planes port_shifts um.

Parameters:

  • smatrix (MicrowaveSMatrixData) – S-parameters before reference planes are shifted.

  • port_shifts (PortNameDataArray) – Data array of shifts of wave ports’ reference planes. The sign of a port shift reflects direction with respect to the axis normal to a WavePort plane: E.g.: PortNameDataArray(data=-a, coords={"port": "WP1"}) defines a shift in the first WavePort by a um in the direction opposite to the positive axis direction (the axis normal to the port plane).

Returns:

De-embedded S-parameters with respect to updated reference frames.

Return type:

MicrowaveSMatrixData

smatrix_deembedded(port_shifts=None)[source]#

Interface function returns de-embedded S-parameter matrix.

get_antenna_metrics_data(port_amplitudes=None, monitor_name=None)[source]#

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.

Note

The NetworkIndex identifies a single excitation in the modeled device, so it represents a LumpedPort or a single mode from a WavePort. Use the static method TerminalComponentModeler.network_index() to convert port and optional mode index into the appropriate NetworkIndex for use in the port_amplitudes dictionary.

Parameters:

  • port_amplitudes (dict[NetworkIndex, complex] = None) – Dictionary mapping a network index to their desired excitation amplitudes. For each network 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')[source]#

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)[source]#

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

Parameters:
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')[source]#

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.

property port_voltage_current_matrices#

Compute voltage and current matrices for all port combinations.

This method returns two matrices containing the voltage and current values computed across all frequency points and port combinations. The matrices represent the response at each output port when each input port is excited individually.

Returns:

A tuple containing the voltage matrix and current matrix. Each matrix has dimensions (f, port_out, port_in) representing the voltage/current response at each output port due to excitation at each input port.

Return type:

tuple[TerminalPortDataArray, TerminalPortDataArray]

compute_port_wave_amplitude_matrices(s_param_def='pseudo')[source]#

Compute wave amplitude matrices for all port combinations.

This method computes the incident (a) and reflected (b) wave amplitude matrices for all frequency points and port combinations using the specified wave definition. The matrices represent the forward and backward traveling wave amplitudes at each output port when each input port is excited individually.

Parameters:

s_param_def (SParamDef, optional) – The type of waves to compute, either “pseudo” waves (Equation 53-54 in [1]) or “power” waves (Equation 4.67 in [2]). Defaults to “pseudo”.

Returns:

A tuple containing the incident (a) and reflected (b) wave amplitude matrices. Each matrix has dimensions (f, port_out, port_in) representing the wave amplitudes at each output port due to excitation at each input port.

Return type:

tuple[TerminalPortDataArray, TerminalPortDataArray]

property port_pseudo_wave_matrices#

Compute pseudo-wave amplitude matrices for all port combinations.

This method returns the incident (a) and reflected (b) pseudo-wave amplitude matrices computed using the pseudo-wave definition from Marks and Williams [1]. The matrices represent the forward and backward traveling wave amplitudes at each output port when each input port is excited individually.

Returns:

A tuple containing the incident (a) and reflected (b) pseudo-wave amplitude matrices. Each matrix has dimensions (f, port_out, port_in) representing the pseudo-wave amplitudes at each output port due to excitation at each input port.

Return type:

tuple[TerminalPortDataArray, TerminalPortDataArray]

property port_power_wave_matrices#

Compute power-wave amplitude matrices for all port combinations.

This method returns the incident (a) and reflected (b) power-wave amplitude matrices computed using the power-wave definition from Pozar [2]. The matrices represent the forward and backward traveling wave amplitudes at each output port when each input port is excited individually.

Returns:

A tuple containing the incident (a) and reflected (b) power-wave amplitude matrices. Each matrix has dimensions (f, port_out, port_in) representing the power-wave amplitudes at each output port due to excitation at each input port.

Return type:

tuple[TerminalPortDataArray, TerminalPortDataArray]

static ab_to_s(a_matrix, b_matrix)#

Get the scattering matrix given the wave amplitude matrices.

Parameters:
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.