feat(rf): add voltage-based selection of modes to the ModeSolver

Author: dmarek-flex

tests/test_components/test_microwave.py

@@ -1794,3 +1794,37 @@ def test_RF_license_suppression():
     with AssertLogLevel(None):
         mode_spec = td.MicrowaveModeSpec._default_without_license_warning()
     td.config.microwave.suppress_rf_license_warning = original_setting
+
+
+def test_validate_conductor_voltage_configurations():
+    """Test validation of conductor voltage configurations in ModePlaneAnalyzer.
+
+    Tests common user errors:
+    1. Valid configuration
+    2. Conductor assigned to both positive and negative terminals
+    3. Polarity-reversed duplicates (most subtle user error)
+    """
+    analyzer = ModePlaneAnalyzer(size=(0, 2, 2), field_data_colocated=False)
+
+    # Valid: multiple terminal configurations with different conductors
+    valid_config = [
+        ({0}, {1}),  # Terminal 1: conductor 0 (+), conductor 1 (-)
+        ({2}, {3}),  # Terminal 2: conductor 2 (+), conductor 3 (-)
+    ]
+    analyzer._validate_conductor_voltage_configurations(valid_config)  # Should not raise
+
+    # ERROR: Conductor in both positive and negative sets
+    error_both_polarities = [
+        ({0, 1}, {1, 2})  # Conductor 1 is in BOTH positive and negative!
+    ]
+    with pytest.raises(ValueError, match="cannot be assigned to both a positive and negative"):
+        analyzer._validate_conductor_voltage_configurations(error_both_polarities)
+
+    # ERROR: Polarity-reversed duplicates (most common user error!)
+    # ({0}, {1}) and ({1}, {0}) represent the same terminal with reversed polarity
+    error_polarity_reversed = [
+        ({0}, {1}),  # Terminal 1: conductor 0 (+), conductor 1 (-)
+        ({1}, {0}),  # Terminal 2: conductor 1 (+), conductor 0 (-) <- SAME TERMINAL!
+    ]
+    with pytest.raises(ValueError, match="Duplicate voltage configuration"):
+        analyzer._validate_conductor_voltage_configurations(error_polarity_reversed)

tidy3d/components/data/monitor_data.py

@@ -1819,6 +1819,31 @@ def _isel(self, **isel_kwargs: Any):
         }
         return self.updated_copy(**update_dict, deep=False, validate=False)
 
+    def _select_mode_subset(self, mode_inds: list[int]) -> Self:
+        """Wraps ``xarray.DataArray.isel`` for all data fields that are defined over frequency and
+        mode index. Used in ``overlap_sort`` but not officially supported since for example
+        ``self.monitor.mode_spec`` and ``self.monitor.freqs`` will no longer be matching the
+        newly created data."""
+
+        num_modes = len(mode_inds)
+        modify_data = {}
+        for key, data in self.data_arrs.items():
+            if "mode_index" not in data.dims:
+                continue
+            # dims_orig = data.dims
+            # f_coord = data.coords["f"]
+            # slices = []
+            # for ifreq in range(num_freqs):
+            #     sl = data.isel(f=ifreq, mode_index=sort_inds_2d[ifreq])
+            #     slices.append(sl.assign_coords(mode_index=np.arange(num_modes)))
+            # # Concatenate along the 'f' dimension name and then restore original frequency coordinates
+            # data = xr.concat(slices, dim="f").assign_coords(f=f_coord).transpose(*dims_orig)
+            modify_data[key] = data.sel(mode_index=mode_inds).assign_coords(
+                mode_index=np.arange(num_modes)
+            )
+        subset_data = self.updated_copy(**modify_data)
+        return subset_data.updated_copy(path="monitor/mode_spec", num_modes=num_modes)
+
     def _assign_coords(self, **assign_coords_kwargs: Any):
         """Wraps ``xarray.DataArray.assign_coords`` for all data fields that are defined over frequency and
         mode index. Used in ``overlap_sort`` but not officially supported since for example

tidy3d/components/microwave/mode_spec.py

@@ -16,11 +16,24 @@
     ImpedanceSpecType,
 )
 from tidy3d.components.mode_spec import AbstractModeSpec
-from tidy3d.components.types import annotate_type
+from tidy3d.components.types import Coordinate2D, annotate_type
 from tidy3d.constants import fp_eps
 from tidy3d.exceptions import SetupError
 
 
+class TerminalSpec(MicrowaveBaseModel):
+    plus_terminals: tuple[Coordinate2D, ...] = pd.Field(
+        ...,
+        title="Impedance Specifications",
+        description="Field controls how the impedan",
+    )
+    minus_terminals: tuple[Coordinate2D, ...] = pd.Field(
+        ...,
+        title="Impedance Specifications",
+        description="Field controls how the impedan",
+    )
+
+
 class MicrowaveModeSpec(AbstractModeSpec, MicrowaveBaseModel):
     """
     The :class:`.MicrowaveModeSpec` class specifies how quantities related to transmission line
@@ -64,6 +77,16 @@ class MicrowaveModeSpec(AbstractModeSpec, MicrowaveBaseModel):
         "ignored for the associated mode.",
     )
 
+    terminal_specs: Optional[tuple[TerminalSpec, ...]] = pd.Field(
+        None,
+        title="Terminal Specifications",
+        description="Field controls how the impedance is calculated for each mode calculated by the mode solver. "
+        "Can be a single impedance specification (which will be applied to all modes) or a tuple of specifications "
+        "(one per mode). The number of impedance specifications should match the number of modes field. "
+        "When an impedance specification of ``None`` is used, the impedance calculation will be "
+        "ignored for the associated mode.",
+    )
+
     @cached_property
     def _impedance_specs_as_tuple(self) -> tuple[Optional[ImpedanceSpecType]]:
         """Gets the impedance_specs field converted to a tuple."""

tidy3d/components/microwave/path_integrals/mode_plane_analyzer.py

@@ -7,7 +7,7 @@
 
 import pydantic.v1 as pd
 import shapely
-from shapely.geometry import LineString, Polygon
+from shapely.geometry import LineString, Point, Polygon
 
 from tidy3d.components.base import cached_property
 from tidy3d.components.geometry.base import Box, Geometry
@@ -21,11 +21,16 @@
 )
 from tidy3d.components.grid.grid import Grid
 from tidy3d.components.medium import LossyMetalMedium, Medium
+from tidy3d.components.microwave.mode_spec import TerminalSpec
 from tidy3d.components.structure import Structure
 from tidy3d.components.types import Axis, Bound, Coordinate, Shapely, Symmetry
 from tidy3d.components.validators import assert_plane
 from tidy3d.exceptions import SetupError
 
+# Type for holding sets of indices associated with conductors,
+# where the first set contains positive terminals and the second set contains negative terminals.
+VoltageSets = tuple[set[int], set[int]]
+
 
 class ModePlaneAnalyzer(Box):
     """Analyzes conductor geometry intersecting a mode plane.
@@ -246,6 +251,61 @@ def bounding_box_from_shapely(geom: Shapely) -> Box:
                 )
         return bounding_boxes, conductor_shapely
 
+    def _find_conductor_terminals(
+        self, conductor_shapely: list[Shapely], terminal_specs: list[TerminalSpec]
+    ) -> list[VoltageSets]:
+        """Given a list of terminal specs and the isolated conductors in the mode plane,
+        returns the indices of conductors that make up the terminal specifications."""
+        terminals = []
+        for term_spec in terminal_specs:
+            all_plus_indices = set()
+            all_minus_indices = set()
+            for plus_terminal in term_spec.plus_terminals:
+                plus = Point(*plus_terminal)
+                plus_indices = [
+                    i for i, geom in enumerate(conductor_shapely) if geom.contains(plus)
+                ]
+                assert len(plus_indices) == 1
+                all_plus_indices.update(plus_indices)
+            for minus_terminal in term_spec.minus_terminals:
+                minus = Point(*minus_terminal)
+                minus_indices = [
+                    i for i, geom in enumerate(conductor_shapely) if geom.contains(minus)
+                ]
+                assert len(minus_indices) == 1
+                all_minus_indices.update(minus_indices)
+            terminals.append((all_plus_indices, all_minus_indices))
+        return terminals
+
+    def _validate_conductor_voltage_configurations(
+        self, conductor_voltage_sets: list[VoltageSets]
+    ) -> None:
+        # Check that a conductor index only belongs in either plus or minus sets
+        for voltage_set in conductor_voltage_sets:
+            if not voltage_set[0].isdisjoint(voltage_set[1]):
+                raise ValueError(
+                    "A conductor cannot be assigned to both a positive and negative voltage."
+                )
+
+        # Check that only unique polarity configurations exist
+        # Two configurations are considered the same if one is the polarity-reversed version of the other
+        unique_terminal_configuration = set()
+
+        for voltage_set in conductor_voltage_sets:
+            pos, neg = voltage_set
+
+            # Create a normalized representation that treats (pos, neg) and (neg, pos) as equivalent
+            # Using frozenset of frozensets ensures order-independence
+            terminal_configuration = frozenset([frozenset(pos), frozenset(neg)])
+
+            if terminal_configuration in unique_terminal_configuration:
+                raise ValueError(
+                    "Duplicate voltage configuration detected. "
+                    "Each unique pair of conductor sets (including polarity-reversed pairs) can only appear once."
+                )
+
+            unique_terminal_configuration.add(terminal_configuration)
+
     def _check_box_intersects_with_conductors(
         self, shapely_list: list[Shapely], bounding_box: Box
     ) -> bool:

tidy3d/components/mode/mode_solver.py

@@ -1407,10 +1407,22 @@ def _make_path_integrals(
             )
         return make_path_integrals(self.mode_spec)
 
+    def _post_process_modes_with_terminal_specs(
+        self,
+        mode_solver_data: MicrowaveModeSolverData,
+    ) -> MicrowaveModeSolverData:
+        """Select, sort and post process modes to match terminal specifications."""
+        raise SetupError("Terminal-based mode setup is not available for the local mode solver.")
+
     def _add_microwave_data(
         self, mode_solver_data: MicrowaveModeSolverData
     ) -> MicrowaveModeSolverData:
         """Calculate and add microwave data to ``mode_solver_data`` which uses the path specifications."""
+
+        # Check if terminal specifications are present and will be used to drive the mode ordering and selection
+        if self.mode_spec.terminal_specs is not None:
+            mode_solver_data = self._post_process_modes_with_terminal_specs(mode_solver_data)
+
         voltage_integrals, current_integrals = self._make_path_integrals()
         # Need to operate on the full symmetry expanded fields
         mode_solver_data_expanded = mode_solver_data.symmetry_expanded_copy
@@ -1848,7 +1860,7 @@ def _grid_correction(
         mode_spec: ModeSpec,
         n_complex: ModeIndexDataArray,
         direction: Direction,
-    ) -> [FreqModeDataArray, FreqModeDataArray]:
+    ) -> tuple[FreqModeDataArray, FreqModeDataArray]:
         """Correct the fields due to propagation on the grid.
 
         Return a copy of the :class:`.ModeSolverData` with the fields renormalized to account
@@ -1864,7 +1876,7 @@ def _grid_correction(
 
         Returns
         -------
-        :class:`.ModeSolverData`
+        tuple[:class:`.FreqModeDataArray`, :class:`.FreqModeDataArray`]
             Copy of the data with renormalized fields.
         """
         normal_axis = plane.size.index(0.0)