feat(rf): Add symmetric_pseudo option for s_param_def

Author: dmarek-flex

CHANGELOG.md

@@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - `ModeSortSpec.sort_key` is now required with a default of `"n_eff"` (previously optional with `None` default). `ModeSortSpec.sort_order` is now optional with a default of `None`, which automatically selects the natural order based on `sort_key` and `sort_reference`: ascending when a reference is provided (closest first), otherwise descending for `n_eff` and polarization fractions (higher values first), ascending for `k_eff` and `mode_area` (lower values first).
+- Added `symmetric_pseudo` option for `s_param_def` in `TerminalComponentModeler` which applies a scaling factor that ensures the S-matrix is symmetric in reciprocal systems.
 
 ### Fixed
 - Fixed intermittent "API key not found" errors in parallel job launches by making configuration directory detection race-safe.

schemas/TerminalComponentModeler.json

@@ -18345,7 +18345,8 @@
       "default": "pseudo",
       "enum": [
         "power",
-        "pseudo"
+        "pseudo",
+        "symmetric_pseudo"
       ],
       "type": "string"
     },

tests/test_plugins/smatrix/test_terminal_component_modeler.py

@@ -121,7 +121,7 @@ def make_t_network_impedance_matrix(
     return np.array([[z11, z12], [z21, z22]])
 
 
-def calc_transmission_line_S_matrix_pseudo(Z0, Zref1, Zref2, gamma, length):
+def calc_transmission_line_S_matrix_pseudo(Z0, Zref1, Zref2, gamma, length, symmetric=False):
     """
     Calculate complete 2x2 S-parameter matrix for a transmission line
     using pseudo wave definition
@@ -141,6 +141,9 @@ def calc_transmission_line_S_matrix_pseudo(Z0, Zref1, Zref2, gamma, length):
         Propagation constant (can be frequency-dependent)
     length : float
         Length (scalar only)
+    symmetric : bool, optional
+        If True, use symmetric_pseudo scaling (F = 1/(2*sqrt(Z))) which ensures
+        S12 = S21 for reciprocal networks. Default is False.
 
     Returns:
     --------
@@ -163,17 +166,31 @@ def calc_transmission_line_S_matrix_pseudo(Z0, Zref1, Zref2, gamma, length):
     numerator_S22 = (Z0**2 - Zref1 * Zref2) * tanh_gamma_ell + Z0 * (Zref1 - Zref2)
     S22 = numerator_S22 / denom
 
-    # Calculate S21 (transmission from port 1 to port 2)
-    numerator_S21 = (
-        np.sqrt(np.real(Zref1) / np.real(Zref2)) * (np.abs(Zref2) / np.abs(Zref1)) * 2 * Z0 * Zref1
-    )
-    S21 = numerator_S21 / (denom * cosh_gamma_ell)
+    # Calculate S12 and S21 (off-diagonal transmission terms)
+    if symmetric:
+        # For symmetric_pseudo: F = 1/(2*sqrt(Z)), so F1/F2 = sqrt(Z2/Z1)
+        # This gives S12 = S21 for reciprocal networks
+        numerator_S12 = 2 * Z0 * np.sqrt(Zref1 * Zref2)
+        numerator_S21 = numerator_S12
+    else:
+        # For pseudo: F = sqrt(Re(Z))/(2|Z|)
+        numerator_S12 = (
+            np.sqrt(np.real(Zref1) / np.real(Zref2))
+            * (np.abs(Zref2) / np.abs(Zref1))
+            * 2
+            * Z0
+            * Zref1
+        )
+        numerator_S21 = (
+            np.sqrt(np.real(Zref2) / np.real(Zref1))
+            * (np.abs(Zref1) / np.abs(Zref2))
+            * 2
+            * Z0
+            * Zref2
+        )
 
-    # Calculate S12 (transmission from port 2 to port 1)
-    numerator_S12 = (
-        np.sqrt(np.real(Zref2) / np.real(Zref1)) * (np.abs(Zref1) / np.abs(Zref2)) * 2 * Z0 * Zref2
-    )
     S12 = numerator_S12 / (denom * cosh_gamma_ell)
+    S21 = numerator_S21 / (denom * cosh_gamma_ell)
 
     # Construct the S-parameter matrix (nfreq, 2, 2)
     nfreq = len(np.atleast_1d(S11))
@@ -434,6 +451,7 @@ def test_complex_reference_s_to_z_component_modeler():
     skrf_S_50ohm = skrf.Network.from_z(z=Z, f=freqs)
     skrf_S_power = skrf.Network.from_z(z=Z, f=freqs, s_def="power", z0=z0)
     skrf_S_pseudo = skrf.Network.from_z(z=Z, f=freqs, s_def="pseudo", z0=z0)
+    skrf_S_traveling = skrf.Network.from_z(z=Z, f=freqs, s_def="traveling", z0=z0)
 
     ports = ["port1", "port2"]
     smatrix = TerminalPortDataArray(
@@ -454,6 +472,14 @@ def test_complex_reference_s_to_z_component_modeler():
     smatrix.values = skrf_S_pseudo.s
     z_tidy3d = s_to_z(smatrix, reference=z0_tidy3d, s_param_def="pseudo")
     assert np.all(np.isclose(z_tidy3d.values, Z))
+    # Our symmetric_pseudo name is equivalent to "traveling" definition in scikit-rf
+    smatrix.values = skrf_S_traveling.s
+    z_tidy3d = s_to_z(smatrix, reference=z0_tidy3d, s_param_def="symmetric_pseudo")
+    assert np.all(np.isclose(z_tidy3d.values, Z))
+
+    # Check that invalid s_param_def raises ValueError
+    with pytest.raises(ValueError, match="Unsupported S-parameter definition"):
+        s_to_z(smatrix, reference=z0_tidy3d, s_param_def="invalid")
 
 
 def test_data_s_to_z(monkeypatch):
@@ -1450,24 +1476,42 @@ def test_internal_construct_smatrix_with_port_vi(monkeypatch):
         ]
     )
     Z0 = np.array(
+        [
+            12.843105732941 + 15.394208173652j,
+            28.567192048123 + 9.1023847562915j,
+            31.209457618234 + 3.8475102934671j,
+        ]
+    )
+    Z01 = np.array(
         [
             18.725191534567 + 12.672421364213j,
             34.038884625562 + 7.8654410284980j,
             35.725175635077 + 4.5490999181327j,
         ]
     )
+    Z02 = np.array(
+        [
+            24.156839210485 + 10.234195827361j,
+            41.892301567293 + 6.7812039451120j,
+            29.451276384019 + 5.1298475620183j,
+        ]
+    )
     # Break the reference impedance symmetry
-    Zref = np.column_stack((0.5 * Z0, 2 * Z0))
+    Zref = np.column_stack((Z01, Z02))
     # Calculate analytical S matrices for power and pseudo wave formulations
     S_pseudo = calc_transmission_line_S_matrix_pseudo(Z0, Zref[:, 0], Zref[:, 1], gamma, length)
+    S_symmetric_pseudo = calc_transmission_line_S_matrix_pseudo(
+        Z0, Zref[:, 0], Zref[:, 1], gamma, length, symmetric=True
+    )
     S_power = calc_transmission_line_S_matrix_power(Z0, Zref[:, 0], Zref[:, 1], gamma, length)
-
+    Zref3 = Zref[:, :, np.newaxis]
     # Calculate A and B matrices where A is diagonal and B = S @ A
+
     A = np.tile(np.eye(2), (len(freqs), 1, 1))  # Identity matrix for each frequency
     B = S_pseudo @ A
     # Now get Voltages and Currents at each port due to excitations from each port
-    Vscale = np.abs(Zref[:, :, np.newaxis]) / np.sqrt(np.real(Zref[:, :, np.newaxis]))
-    Iscale = Vscale / Zref[:, :, np.newaxis]
+    Vscale = np.abs(Zref3) / np.sqrt(np.real(Zref3))
+    Iscale = Vscale / Zref3
     voltages = Vscale * (A + B)  # (f x port_out x port_in)
     currents = Iscale * (A - B)  # (f x port_out x port_in)
 
@@ -1520,7 +1564,6 @@ def mock_port_impedances(modeler_data):
     )
 
     # Test the _internal_construct_smatrix method
-    S_computed = modeler_data.smatrix().data.values
 
     def check_S_matrix(S_computed, S_expected, tol=1e-12):
         # Check that S-matrix has correct shape
@@ -1542,12 +1585,21 @@ def check_S_matrix(S_computed, S_expected, tol=1e-12):
             )
 
     # Check pseudo wave S matrix
+    S_computed = modeler_data.smatrix().data.values
     check_S_matrix(S_computed, S_pseudo)
 
     # Check power wave S matrix
     S_computed = modeler_data.smatrix(s_param_def="power").data.values
     check_S_matrix(S_computed, S_power)
 
+    # Check symmetric_pseudo wave S matrix
+    S_computed = modeler_data.smatrix(s_param_def="symmetric_pseudo").data.values
+    check_S_matrix(S_computed, S_symmetric_pseudo)
+
+    # Check that invalid s_param_def raises ValueError
+    with pytest.raises(ValueError, match="Unsupported S-parameter definition"):
+        modeler_data.smatrix(s_param_def="invalid")
+
 
 def test_wave_port_to_absorber(tmp_path):
     """Test that wave port absorber can be specified as a boolean, ABCBoundary, or ModeABCBoundary."""

tidy3d/plugins/smatrix/analysis/terminal.py

@@ -58,8 +58,8 @@ def terminal_construct_smatrix(
         waves at other ports. This simplifies the S-matrix calculation and is
         required if not all ports are excited. Default is ``False``.
     s_param_def : SParamDef, optional
-        The definition of S-parameters to use depends whether "pseudo waves"
-        or "power waves" are calculated. Default is "pseudo".
+        Wave definition: "pseudo", "power", or "symmetric_pseudo". Default is "pseudo".
+        See :class:`.TerminalComponentModeler` for details.
 
     Returns
     -------
@@ -73,8 +73,15 @@ def terminal_construct_smatrix(
 
     if s_param_def == "pseudo":
         a_matrix, b_matrix = modeler_data.port_pseudo_wave_matrices
-    else:
+    elif s_param_def == "symmetric_pseudo":
+        a_matrix, b_matrix = modeler_data.port_symmetric_pseudo_wave_matrices
+    elif s_param_def == "power":
         a_matrix, b_matrix = modeler_data.port_power_wave_matrices
+    else:
+        raise ValueError(
+            f"Unsupported S-parameter definition '{s_param_def}'. "
+            "Supported values are 'pseudo', 'symmetric_pseudo', and 'power'."
+        )
 
     # If excitation is assumed ideal, a_matrix is assumed to be diagonal
     # and the explicit inverse can be avoided. When only a subset of excitations
@@ -225,10 +232,6 @@ def _compute_wave_amplitudes_from_VI(
     specified wave definition. The conversion handles impedance sign consistency and
     applies the appropriate normalization based on the chosen S-parameter definition.
 
-    The wave amplitudes are computed using:
-    - Pseudo waves: Equations 53-54 from Marks and Williams [1]
-    - Power waves: Equation 4.67 from Pozar [2]
-
     Parameters
     ----------
     port_reference_impedances : :class:`.PortDataArray`
@@ -238,8 +241,8 @@ def _compute_wave_amplitudes_from_VI(
     port_currents : :class:`.PortDataArray`
         Current values at each port with dimensions (f, port).
     s_param_def : SParamDef, optional
-        Wave definition type: "pseudo" for pseudo waves or "power" for power waves.
-        Defaults to "pseudo".
+        Wave definition: "pseudo", "power", or "symmetric_pseudo". Default is "pseudo".
+        See :class:`.TerminalComponentModeler` for details.
 
     Returns
     -------
@@ -295,8 +298,8 @@ def compute_wave_amplitudes_at_each_port(
     sim_data : :class:`.SimulationData`
         Results from a single simulation run.
     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].
+        Wave definition: "pseudo", "power", or "symmetric_pseudo".
+        See :class:`.TerminalComponentModeler` for details.
 
     Returns
     -------

tidy3d/plugins/smatrix/component_modelers/terminal.py

@@ -141,13 +141,35 @@ class TerminalComponentModeler(AbstractComponentModeler, MicrowaveBaseModel):
     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 :math:`F = \\sqrt{\\text{Re}(Z)} / (2|Z|)`. Wave amplitudes are :math:`a = F(V + ZI)`
+      and :math:`b = F(V - ZI)`.
+
+    - ``"power"``: Power waves as defined by Kurokawa [3] and described in Pozar [2]. Uses
+      scaling factor :math:`F = 1 / (2\\sqrt{\\text{Re}(Z)})`. Wave amplitudes are
+      :math:`a = F(V + ZI)` and :math:`b = F(V - Z^*I)` where :math:`Z^*` is the complex
+      conjugate. Ensures :math:`|a|^2 - |b|^2` represents actual power flow.
+
+    - ``"symmetric_pseudo"``: Equivalent to pseudo-waves except for the scaling factor. Uses
+      :math:`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**
 
     .. [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.
+
+    .. [3]  K. Kurokawa, "Power Waves and the Scattering Matrix," IEEE Trans.
+            Microwave Theory Tech., vol. 13, no. 2, pp. 194-202, March 1965.
     """
 
     ports: tuple[TerminalPortType, ...] = pd.Field(
@@ -200,7 +222,7 @@ class TerminalComponentModeler(AbstractComponentModeler, MicrowaveBaseModel):
     s_param_def: SParamDef = pd.Field(
         "pseudo",
         title="Scattering Parameter Definition",
-        description="Whether to compute scattering parameters using the 'pseudo' or 'power' wave definitions.",
+        description="Wave definition: 'pseudo', 'power', or 'symmetric_pseudo'. Default is 'pseudo'.",
     )
 
     low_freq_smoothing: Optional[ModelerLowFrequencySmoothingSpec] = pd.Field(