feat: add S-parameter de-embedding support to TerminalComponentModelerData

Author: George-Guryev-flxcmp

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- Added S-parameter de-embedding to `TerminalComponentModelerData`, enabling recalculation with shifted reference planes.  
 - New `MediumMonitor` that returns both permittivity and permeability profiles.
 - Task names are now optional when using `run(sim)` or `Job`. When running multiple jobs (via `run_async` or `Batch`), you can also provide simulations as a list without specifying task names. The previous dictionary-based format with explicit task names is still supported.
 - Added support for `tidy3d-extras`, an optional plugin that enables more accurate local mode solving via subpixel averaging.

tests/test_plugins/smatrix/test_terminal_component_modeler.py

@@ -1392,3 +1392,38 @@ def test_wave_port_to_absorber(tmp_path):
     sim = list(modeler.sim_dict.values())[0]
     absorber = sim.internal_absorbers[0]
     assert absorber.boundary_spec == custom_boundary_spec
+
+
+def test_S_parameter_deembedding(monkeypatch, tmp_path):
+    """Test S-parameter de-embedding."""
+
+    z_grid = td.UniformGrid(dl=1 * 1e3)
+    xy_grid = td.UniformGrid(dl=0.1 * 1e3)
+    grid_spec = td.GridSpec(grid_x=xy_grid, grid_y=xy_grid, grid_z=z_grid)
+    modeler = make_coaxial_component_modeler(port_types=(WavePort, WavePort), grid_spec=grid_spec)
+    port0_idx = modeler.network_index(modeler.ports[0])
+    port1_idx = modeler.network_index(modeler.ports[1])
+    modeler_run1 = modeler.updated_copy(run_only=(port0_idx,))
+
+    # Make sure the smatrix and impedance calculations work for reduced simulations
+    modeler_data = run_component_modeler(monkeypatch, modeler)
+    s_matrix = modeler_data.smatrix()
+
+    # test for invalid dimensions in port shifts
+    port_shifts = np.array([0])
+    with pytest.raises(ValueError):
+        S_dmb = modeler_data.change_port_reference_planes(smatrix=s_matrix, port_shifts=port_shifts)
+
+    port_shifts = np.zeros((3, 1))
+    with pytest.raises(ValueError):
+        S_dmb = modeler_data.change_port_reference_planes(smatrix=s_matrix, port_shifts=port_shifts)
+
+    # ensure matrices are identical if there is no shift in reference planes
+    port_shifts = np.array([0, 0])
+    S_dmb = modeler_data.change_port_reference_planes(smatrix=s_matrix, port_shifts=port_shifts)
+    assert np.allclose(S_dmb.data.values, s_matrix.data.values)
+
+    # make sure S-parameters are different if reference planes are moved
+    port_shifts = np.array([-2, 10])
+    S_dmb = modeler_data.change_port_reference_planes(smatrix=s_matrix, port_shifts=port_shifts)
+    assert not np.allclose(S_dmb.data.values, s_matrix.data.values)

tidy3d/plugins/smatrix/data/terminal.py

@@ -7,11 +7,13 @@
 import numpy as np
 import pydantic.v1 as pd
 
+from tidy3d import ModeData
 from tidy3d.components.base import Tidy3dBaseModel, cached_property
 from tidy3d.components.data.data_array import FreqDataArray
 from tidy3d.components.data.monitor_data import MonitorData
 from tidy3d.components.data.sim_data import SimulationData
 from tidy3d.components.microwave.data.monitor_data import AntennaMetricsData
+from tidy3d.constants import C_0
 from tidy3d.log import log
 from tidy3d.plugins.smatrix.component_modelers.terminal import TerminalComponentModeler
 from tidy3d.plugins.smatrix.data.base import AbstractComponentModelerData
@@ -117,6 +119,65 @@ def smatrix(
         )
         return smatrix_data
 
+    def change_port_reference_planes(
+        self, smatrix: MicrowaveSMatrixData, port_shifts: np.array
+    ) -> MicrowaveSMatrixData:
+        """
+        Performs S-parameter de-embedding by shifting reference planes `port_shifts` um.
+
+        Parameters
+        ----------
+        smatrix: :class:`.MicrowaveSMatrixData`
+            S-parameters before reference planes are shifted.
+        port_shifts: np.array
+            Numpy array of shifts of wave ports' reference planes.
+
+        Returns
+        -------
+        :class:`MicrowaveSMatrixData`
+            De-embedded S-parameters with respect to updated reference frames.
+        """
+
+        # get s-parameters with respect to current `WavePort` locations
+        S_matrix = smatrix.data.values
+        S_new = np.zeros_like(S_matrix, dtype=complex)
+        N_freq, N_ports, _ = S_matrix.shape
+
+        if len(port_shifts) != N_ports:
+            raise ValueError(
+                "A vector of WavePort reference plane shifts has to match a total number of Waveports in a simulation."
+                f"The expected length was {N_ports}, while a vector of {len(port_shifts)} was provided."
+            )
+
+        # extract `ModeSource` directions to ensure correct sign is used
+        port_shifts = np.ravel(port_shifts)
+        directions = np.array([1 if port.direction == "+" else -1 for port in self.modeler.ports])
+        directions = np.ravel(directions)
+
+        # pre-allocate memory for effective propagation constants
+        kvecs = np.zeros((N_ports, N_freq), dtype=complex)
+
+        # extract mode data
+        key = self.data.keys_tuple[0]
+        data = self.data[key].data
+        modes_data = tuple(mode_data for mode_data in data if isinstance(mode_data, ModeData))
+
+        # infer propagation constants from modal data
+        for i, mode_data in enumerate(modes_data):
+            n_complex = mode_data.n_complex
+            kvecs[i, :] = (2 * np.pi * n_complex.f * n_complex / C_0).squeeze()
+
+        # updated/de-embed S-parameters with respect to shifted reference planes
+        for i in range(N_freq):
+            phase = kvecs[:, i] * port_shifts * directions
+            P_inv = np.diag(np.exp(-1j * phase))
+            S_new[i, :, :] = P_inv @ S_matrix[i, :, :] @ P_inv
+
+        # create a new Port Data Array
+        smat_data = TerminalPortDataArray(S_new, coords=smatrix.data.coords)
+
+        return smatrix.updated_copy(data=smat_data)
+
     @pd.root_validator(pre=False)
     def _warn_rf_license(cls, values):
         log.warning(