added ability to define a wave port using only a single voltage or current path

Author: dmarek-flex

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `eps_component` argument in `td.Simulation.plot_eps()` to optionally select a specific permittivity component to plot (eg. `"xx"`).
 - Monitor `AuxFieldTimeMonitor` for aux fields like the free carrier density in `TwoPhotonAbsorption`.
 - Broadband handling (`num_freqs` argument) to the TFSF source.
+- Ability to define a `WavePort` using only a voltage or current path integral, with the missing quantity inferred via power conservation.
 
 ### Fixed
 - Compatibility with `xarray>=2025.03`.

tests/test_plugins/smatrix/terminal_component_modeler_def.py

@@ -251,6 +251,8 @@ def make_coaxial_component_modeler(
         CoaxialLumpedPort,
         CoaxialLumpedPort,
     ),
+    use_current: bool = True,
+    use_voltage: bool = True,
     **kwargs,
 ):
     if not length:
@@ -279,27 +281,34 @@ def make_port(center, direction, type, name) -> Union[CoaxialLumpedPort, WavePor
             voltage_center[0] += mean_radius
             voltage_size = [Router - Rinner, 0, 0]
 
-            port = WavePort(
-                center=center,
-                size=[2 * Router, 2 * Router, 0],
-                direction=direction,
-                name=name,
-                mode_spec=td.ModeSpec(num_modes=1),
-                mode_index=0,
-                voltage_integral=microwave.VoltageIntegralAxisAligned(
+            voltage_integral = None
+            if use_voltage:
+                voltage_integral = microwave.VoltageIntegralAxisAligned(
                     center=voltage_center,
                     size=voltage_size,
                     extrapolate_to_endpoints=True,
                     snap_path_to_grid=True,
                     sign="+",
-                ),
-                current_integral=microwave.CustomCurrentIntegral2D.from_circular_path(
+                )
+            current_integral = None
+            if use_current:
+                current_integral = microwave.CustomCurrentIntegral2D.from_circular_path(
                     center=center,
                     radius=mean_radius,
                     num_points=41,
                     normal_axis=2,
                     clockwise=direction != "+",
-                ),
+                )
+
+            port = WavePort(
+                center=center,
+                size=[2 * Router, 2 * Router, 0],
+                direction=direction,
+                name=name,
+                mode_spec=td.ModeSpec(num_modes=1),
+                mode_index=0,
+                voltage_integral=voltage_integral,
+                current_integral=current_integral,
             )
         return port
 

tests/test_plugins/smatrix/test_terminal_component_modeler.py

@@ -253,7 +253,7 @@ def test_converting_port_to_simulation_objects(snap_center):
     port = LumpedPort(center=(0, 0, 0), size=(0, 1, 2), voltage_axis=2, impedance=50, name="Port1")
     freqs = np.linspace(1e9, 10e9, 11)
     source_time = td.GaussianPulse(freq0=5e9, fwidth=9e9)
-    _ = port.to_field_monitors(freqs=freqs, snap_center=snap_center)
+    _ = port.to_monitors(freqs=freqs, snap_center=snap_center)
     _ = port.to_source(source_time=source_time, snap_center=snap_center)
 
 
@@ -413,17 +413,38 @@ def test_make_coaxial_component_modeler_with_wave_ports(tmp_path):
     xy_grid = td.UniformGrid(dl=0.1 * 1e3)
     grid_spec = td.GridSpec(grid_x=xy_grid, grid_y=xy_grid, grid_z=z_grid)
     _ = make_coaxial_component_modeler(
-        path_dir=str(tmp_path), port_types=(WavePort, WavePort), grid_spec=grid_spec
+        path_dir=str(tmp_path),
+        port_types=(WavePort, WavePort),
+        grid_spec=grid_spec,
     )
 
 
-def test_run_coaxial_component_modeler_with_wave_ports(monkeypatch, tmp_path):
+@pytest.mark.parametrize("voltage_enabled", [False, True])
+@pytest.mark.parametrize("current_enabled", [False, True])
+def test_run_coaxial_component_modeler_with_wave_ports(
+    monkeypatch, tmp_path, voltage_enabled, current_enabled
+):
     """Checks that the terminal component modeler runs with wave ports."""
     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)
+    if not (voltage_enabled or current_enabled):
+        with pytest.raises(pd.ValidationError):
+            modeler = make_coaxial_component_modeler(
+                path_dir=str(tmp_path),
+                port_types=(WavePort, WavePort),
+                grid_spec=grid_spec,
+                use_voltage=voltage_enabled,
+                use_current=current_enabled,
+            )
+        return
+
     modeler = make_coaxial_component_modeler(
-        path_dir=str(tmp_path), port_types=(WavePort, WavePort), grid_spec=grid_spec
+        path_dir=str(tmp_path),
+        port_types=(WavePort, WavePort),
+        grid_spec=grid_spec,
+        use_voltage=voltage_enabled,
+        use_current=current_enabled,
     )
     s_matrix = run_component_modeler(monkeypatch, modeler)
 

tidy3d/plugins/microwave/impedance_calculator.py

@@ -72,15 +72,15 @@ def compute_impedance(self, em_field: MonitorDataTypes) -> IntegralResultTypes:
         if not self.voltage_integral:
             flux = em_field.flux
             if isinstance(em_field, FieldTimeData):
-                voltage = flux / current
+                voltage = flux.abs / current
             else:
-                voltage = 2 * flux / np.conj(current)
+                voltage = 2 * flux.abs / np.conj(current)
         if not self.current_integral:
             flux = em_field.flux
             if isinstance(em_field, FieldTimeData):
-                current = flux / voltage
+                current = flux.abs / voltage
             else:
-                current = np.conj(2 * flux / voltage)
+                current = np.conj(2 * flux.abs / voltage)
 
         impedance = voltage / current
         impedance = ImpedanceCalculator._set_data_array_attributes(impedance)

tidy3d/plugins/smatrix/component_modelers/terminal.py

@@ -113,7 +113,7 @@ def sim_dict(self) -> Dict[str, Simulation]:
         field_monitors = [
             mon
             for port in self.ports
-            for mon in port.to_field_monitors(
+            for mon in port.to_monitors(
                 self.freqs, snap_center=snap_centers.get(port.name), grid=sim_wo_source.grid
             )
         ]
@@ -149,15 +149,13 @@ def sim_dict(self) -> Dict[str, Simulation]:
 
         # Now, create simulations with wave port sources and mode solver monitors for computing port modes
         for wave_port in self._wave_ports:
-            mode_monitor = wave_port.to_mode_solver_monitor(freqs=self.freqs)
             # Source is placed just before the field monitor of the port
             mode_src_pos = wave_port.center[wave_port.injection_axis] + self._shift_value_signed(
                 wave_port
             )
             port_source = wave_port.to_source(self._source_time, snap_center=mode_src_pos)
 
-            new_mnts_for_wave = new_mnts + [mode_monitor]
-            update_dict = dict(monitors=new_mnts_for_wave, sources=[port_source])
+            update_dict = dict(sources=[port_source])
 
             task_name = self._task_name(port=wave_port)
             sim_dict[task_name] = sim_wo_source.copy(update=update_dict)

tidy3d/plugins/smatrix/ports/base_lumped.py

@@ -75,7 +75,7 @@ def to_voltage_monitor(self, freqs: FreqArray, snap_center: float = None) -> Fie
     def to_current_monitor(self, freqs: FreqArray, snap_center: float = None) -> FieldMonitor:
         """Field monitor to compute port current."""
 
-    def to_field_monitors(
+    def to_monitors(
         self, freqs: FreqArray, snap_center: float = None, grid: Grid = None
     ) -> list[FieldMonitor]:
         """Field monitors to compute port voltage and current."""

tidy3d/plugins/smatrix/ports/base_terminal.py

@@ -1,17 +1,19 @@
 """Class and custom data array for representing a scattering-matrix port, which is defined by a pair of terminals."""
 
 from abc import ABC, abstractmethod
+from typing import Union
 
 import pydantic.v1 as pd
 
 from ....components.base import Tidy3dBaseModel, cached_property
 from ....components.data.data_array import FreqDataArray
 from ....components.data.sim_data import SimulationData
 from ....components.grid.grid import Grid
-from ....components.monitor import FieldMonitor
+from ....components.monitor import FieldMonitor, ModeMonitor
 from ....components.source.base import Source
 from ....components.source.time import GaussianPulse
 from ....components.types import FreqArray
+from ....log import log
 
 
 class AbstractTerminalPort(Tidy3dBaseModel, ABC):
@@ -38,11 +40,21 @@ def to_source(
     ) -> Source:
         """Create a current source from a terminal-based port."""
 
-    @abstractmethod
     def to_field_monitors(
         self, freqs: FreqArray, snap_center: float = None, grid: Grid = None
-    ) -> list[FieldMonitor]:
-        """Field monitors to compute port voltage and current."""
+    ) -> Union[list[FieldMonitor], list[ModeMonitor]]:
+        """DEPRECATED: Monitors used to compute the port voltage and current."""
+        log.warning(
+            "'to_field_monitors' method name is deprecated and will be removed in the future. Please use "
+            "'to_monitors' for the same effect."
+        )
+        return self.to_monitors(freqs=freqs, snap_center=snap_center, grid=grid)
+
+    @abstractmethod
+    def to_monitors(
+        self, freqs: FreqArray, snap_center: float = None, grid: Grid = None
+    ) -> Union[list[FieldMonitor], list[ModeMonitor]]:
+        """Monitors used to compute the port voltage and current."""
 
     @abstractmethod
     def compute_voltage(self, sim_data: SimulationData) -> FreqDataArray:

tidy3d/plugins/smatrix/ports/wave.py

@@ -5,13 +5,13 @@
 import numpy as np
 import pydantic.v1 as pd
 
-from ....components.base import cached_property
+from ....components.base import cached_property, skip_if_fields_missing
 from ....components.data.data_array import FreqDataArray, FreqModeDataArray
-from ....components.data.monitor_data import ModeSolverData
+from ....components.data.monitor_data import ModeData
 from ....components.data.sim_data import SimulationData
 from ....components.geometry.base import Box
 from ....components.grid.grid import Grid
-from ....components.monitor import FieldMonitor, ModeSolverMonitor
+from ....components.monitor import ModeMonitor
 from ....components.simulation import Simulation
 from ....components.source.field import ModeSource, ModeSpec
 from ....components.source.time import GaussianPulse
@@ -62,16 +62,35 @@ class WavePort(AbstractTerminalPort, Box):
         description="Definition of current integral used to compute current and the characteristic impedance.",
     )
 
+    def _mode_voltage_coefficients(self, mode_data: ModeData) -> FreqModeDataArray:
+        """Calculates scaling coefficients to convert mode amplitudes
+        to the total port voltage.
+        """
+        mode_data = mode_data._isel(mode_index=[self.mode_index])
+        if self.voltage_integral is None:
+            current_coeffs = self.current_integral.compute_current(mode_data)
+            voltage_coeffs = 2 * np.abs(mode_data.flux) / np.conj(current_coeffs)
+        else:
+            voltage_coeffs = self.voltage_integral.compute_voltage(mode_data)
+        return voltage_coeffs.squeeze()
+
+    def _mode_current_coefficients(self, mode_data: ModeData) -> FreqModeDataArray:
+        """Calculates scaling coefficients to convert mode amplitudes
+        to the total port current.
+        """
+        mode_data = mode_data._isel(mode_index=[self.mode_index])
+        if self.current_integral is None:
+            voltage_coeffs = self.voltage_integral.compute_voltage(mode_data)
+            current_coeffs = (2 * np.abs(mode_data.flux) / voltage_coeffs).conj()
+        else:
+            current_coeffs = self.current_integral.compute_current(mode_data)
+        return current_coeffs.squeeze()
+
     @cached_property
     def injection_axis(self):
         """Injection axis of the port."""
         return self.size.index(0.0)
 
-    @cached_property
-    def _field_monitor_name(self) -> str:
-        """Return the name of the :class:`.FieldMonitor` associated with this port."""
-        return f"{self.name}_field"
-
     @cached_property
     def _mode_monitor_name(self) -> str:
         """Return the name of the :class:`.ModeMonitor` associated with this port."""
@@ -92,35 +111,24 @@ def to_source(self, source_time: GaussianPulse, snap_center: float = None) -> Mo
             name=self.name,
         )
 
-    def to_field_monitors(
+    def to_monitors(
         self, freqs: FreqArray, snap_center: float = None, grid: Grid = None
-    ) -> list[FieldMonitor]:
-        """Field monitor to compute port voltage and current."""
+    ) -> list[ModeMonitor]:
+        """The wave port uses a :class:`.ModeMonitor` to compute the characteristic impedance
+        and the port voltages and currents."""
         center = list(self.center)
         if snap_center:
             center[self.injection_axis] = snap_center
-        field_mon = FieldMonitor(
-            center=center,
-            size=self.size,
-            freqs=freqs,
-            name=self._field_monitor_name,
-            colocate=False,
-        )
-        return [field_mon]
-
-    def to_mode_solver_monitor(self, freqs: FreqArray) -> ModeSolverMonitor:
-        """Mode solver monitor to compute modes that will be used to
-        compute characteristic impedances."""
-        mode_mon = ModeSolverMonitor(
+        mode_mon = ModeMonitor(
             center=self.center,
             size=self.size,
             freqs=freqs,
             name=self._mode_monitor_name,
             colocate=False,
             mode_spec=self.mode_spec,
-            direction=self.direction,
+            store_fields_direction=self.direction,
         )
-        return mode_mon
+        return [mode_mon]
 
     def to_mode_solver(self, simulation: Simulation, freqs: FreqArray) -> ModeSolver:
         """Helper to create a :class:`.ModeSolver` instance."""
@@ -136,30 +144,43 @@ def to_mode_solver(self, simulation: Simulation, freqs: FreqArray) -> ModeSolver
 
     def compute_voltage(self, sim_data: SimulationData) -> FreqDataArray:
         """Helper to compute voltage across the port."""
-        field_monitor = sim_data[self._field_monitor_name]
-        return self.voltage_integral.compute_voltage(field_monitor)
+        mode_data = sim_data[self._mode_monitor_name]
+        voltage_coeffs = self._mode_voltage_coefficients(mode_data)
+        amps = mode_data.amps
+        fwd_amps = amps.sel(direction="+").squeeze()
+        bwd_amps = amps.sel(direction="-").squeeze()
+        return voltage_coeffs * (fwd_amps + bwd_amps)
 
     def compute_current(self, sim_data: SimulationData) -> FreqDataArray:
         """Helper to compute current flowing through the port."""
-        field_monitor = sim_data[self._field_monitor_name]
-        return self.current_integral.compute_current(field_monitor)
+        mode_data = sim_data[self._mode_monitor_name]
+        current_coeffs = self._mode_current_coefficients(mode_data)
+        amps = mode_data.amps
+        fwd_amps = amps.sel(direction="+").squeeze()
+        bwd_amps = amps.sel(direction="-").squeeze()
+        # In ModeData, fwd_amps and bwd_amps are not relative to
+        # the direction fields are stored
+        sign = 1.0
+        if self.direction == "-":
+            sign = -1.0
+        return sign * current_coeffs * (fwd_amps - bwd_amps)
 
     def compute_port_impedance(
-        self, sim_mode_data: Union[SimulationData, ModeSolverData]
+        self, sim_mode_data: Union[SimulationData, ModeData]
     ) -> FreqModeDataArray:
         """Helper to compute impedance of port. The port impedance is computed from the
         transmission line mode, which should be TEM or at least quasi-TEM."""
         impedance_calc = ImpedanceCalculator(
             voltage_integral=self.voltage_integral, current_integral=self.current_integral
         )
         if isinstance(sim_mode_data, SimulationData):
-            mode_solver_data = sim_mode_data[self._mode_monitor_name]
+            mode_data = sim_mode_data[self._mode_monitor_name]
         else:
-            mode_solver_data = sim_mode_data
+            mode_data = sim_mode_data
 
         # Filter out unwanted modes to reduce impedance computation effort
-        mode_solver_data = mode_solver_data._isel(mode_index=[self.mode_index])
-        impedance_array = impedance_calc.compute_impedance(mode_solver_data)
+        mode_data = mode_data._isel(mode_index=[self.mode_index])
+        impedance_array = impedance_calc.compute_impedance(mode_data)
         return impedance_array
 
     @staticmethod
@@ -185,10 +206,11 @@ def _validate_path_integrals_within_port(cls, val, values):
         return val
 
     @pd.validator("current_integral", always=True)
+    @skip_if_fields_missing(["voltage_integral"])
     def _check_voltage_or_current(cls, val, values):
         """Raise validation error if both ``voltage_integral`` and ``current_integral``
         were not provided."""
-        if not values.get("voltage_integral") and not val:
+        if values.get("voltage_integral") is None and val is None:
             raise ValidationError(
                 "At least one of 'voltage_integral' or 'current_integral' must be provided."
             )