tidy3d.rf.TerminalComponentModelerData

tidy3d.rf.TerminalComponentModelerData#

class TerminalComponentModelerData[source]#

Bases: AbstractComponentModelerData, MicrowaveBaseModel

Data associated with a TerminalComponentModeler simulation run.

Parameters:

  • 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.

  • renormalized_reference_impedance (Optional[Union[complex, TerminalPortDataArray, PortDataArray]] = None) – When set, overrides port_reference_impedances for all S-matrix computations. Accepts: complex (uniform), PortDataArray (per-port diagonal), or TerminalPortDataArray (full matrix).

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.

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

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 matrix for each port across all frequencies.

port_symmetric_pseudo_wave_matrices

Compute symmetric-pseudo wave amplitude matrices for all port combinations.

port_voltage_current_matrices

Compute voltage and current matrices for all port combinations.

modeler

renormalized_reference_impedance

data

log

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, compute_Finv])

Helper to convert port impedance matrix to F (and optionally its inverse), which are 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.

renormalize(reference_impedance)

Return a new instance whose S-matrix is renormalized to a different reference impedance.

s_to_z([assume_ideal_excitation, s_param_def])

Converts the S-matrix to the Z-matrix using the port reference impedances.

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.
modeler#
renormalized_reference_impedance#
renormalize(reference_impedance)[source]#

Return a new instance whose S-matrix is renormalized to a different reference impedance.

The returned object recomputes wave amplitudes from the cached voltage/current data using the new reference impedance, so all downstream methods (smatrix(), s_to_z(), compute_port_wave_amplitude_matrices(), etc.) automatically reflect the new impedance.

Parameters:

reference_impedance (RenormalizedReferenceImpedance) –

The new reference impedance. Accepts:

  • complex — uniform impedance applied to all ports (e.g. 50)

  • PortDataArray — per-port impedance with dims (f, port)

  • TerminalPortDataArray — full impedance matrix (f, port_out, port_in)

Returns:

A copy of this object with the new reference impedance applied.

Return type:

TerminalComponentModelerData

Examples

>>> s_50 = modeler_data.renormalize(50).smatrix()
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 (Wave definition: "pseudo", "power", or "symmetric_pseudo".) – If not provided, modeler.s_param_def is used. See TerminalComponentModeler for details.

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 matrix for each port across all frequencies.

This function determines the characteristic impedance for every port defined in the modeler. It returns a matrix with dimensions (f, port_out, port_in) to support coupled impedances from TerminalWavePort. For WavePort and LumpedPort, the impedance matrix is diagonal.

When renormalized_reference_impedance is set, returns the user-specified impedance instead of the simulation-derived one.

Returns:

A TerminalPortDataArray containing the complex impedance matrix with dimensions (f, port_out, port_in) for 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 (TerminalPortDataArray, optional) – Reference impedance matrix with dimensions (f, port_out, port_in). If not provided, it is computed from the cached property port_reference_impedances(). Defaults to None.

  • s_param_def (SParamDef) – Wave definition: “pseudo”, “power”, or “symmetric_pseudo”. See TerminalComponentModeler for details.

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(assume_ideal_excitation=None, s_param_def='pseudo')[source]#

Converts the S-matrix to the Z-matrix using the port reference impedances.

This method first computes the S-matrix of the device and then transforms it into the corresponding impedance matrix (Z-matrix), using the reference impedances from 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 (SParamDef, optional) – Wave definition: “pseudo”, “power”, or “symmetric_pseudo”. Default is “pseudo”. See TerminalComponentModeler for details.

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() 
>>> 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) – Wave definition: “pseudo”, “power”, or “symmetric_pseudo”. Default is “pseudo”. See TerminalComponentModeler for details.

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]

property port_symmetric_pseudo_wave_matrices#

Compute symmetric-pseudo wave amplitude matrices for all port combinations.

This method returns the incident (a) and reflected (b) symmetric-pseudo wave amplitude matrices. These are equivalent to pseudo-waves except for the scaling factor, which ensures the S-matrix will be symmetric when the simulated device is reciprocal.

Returns:

A tuple containing the incident (a) and reflected (b) symmetric-pseudo 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]

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', compute_Finv=False)#

Helper to convert port impedance matrix to F (and optionally its inverse), which are used for computing scattering parameters. F represents the scaling factor applied to forward and backward waves.

The matrix F is used when converting between S and Z parameters for circuits with differing port impedances. This function automatically detects whether Z is diagonal and uses optimized element-wise operations for diagonal matrices or full matrix operations for non-diagonal matrices.

Parameters:

  • Z_numpy (np.ndarray) – NumPy array of complex port impedance matrix with shape (f, port_out, port_in), where f is number of frequencies, port_out is number of output ports, and port_in is number of input ports. Z is assumed to be symmetric and positive semi-definite.

  • s_param_def (SParamDef, optional) – Wave definition: “pseudo”, “power”, or “symmetric_pseudo”. Default is “pseudo”. See TerminalComponentModeler for details.

  • compute_Finv (bool, optional) – If True, also compute and return F^{-1}. Default is False.

Returns:

F array with shape (f, port_out, port_in), or (F, Finv) tuple if compute_Finv is True.

Return type:

np.ndarray or tuple[np.ndarray, np.ndarray]

Notes

The F matrix definitions for each wave formulation are:

  • "power": \(F = 0.5 \cdot (\mathrm{Re}[Z])^{-1/2}\)

  • "pseudo": \(F = 0.5 \cdot (\mathrm{Re}(Z^{-1}))^{1/2}\)

  • "symmetric_pseudo": \(F = 0.5 \cdot Z^{-1/2}\)

where \(A^{1/2}\) denotes the matrix square root and \(A^{-1/2}\) denotes the matrix inverse square root.

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

data#
log#