more flexible terminal specs

Author: dmarek-flex

tests/test_components/test_microwave.py

@@ -1828,3 +1828,105 @@ def test_validate_conductor_voltage_configurations():
     ]
     with pytest.raises(ValueError, match="Duplicate voltage configuration"):
         analyzer._validate_conductor_voltage_configurations(error_polarity_reversed)
+
+
+def test_terminal_spec_valid_inputs():
+    """Test TerminalSpec validation with valid inputs for plus_terminals and minus_terminals."""
+    # Test Case 1.1: Coordinate2D tuples (single coordinate)
+    spec = td.TerminalSpec(plus_terminals=((1.0, 0.5),), minus_terminals=((-1.0, 0.5),))
+    assert spec is not None
+    assert len(spec.plus_terminals) == 1
+    assert spec.plus_terminals[0] == (1.0, 0.5)
+
+    # Test Case 1.2: Multiple Coordinate2D tuples
+    spec = td.TerminalSpec(plus_terminals=((1.0, 0.5), (2.0, 0.5)), minus_terminals=())
+    assert len(spec.plus_terminals) == 2
+
+    # Test Case 1.3: String identifiers
+    spec = td.TerminalSpec(
+        plus_terminals=("conductor_1", "conductor_2"), minus_terminals=("ground",)
+    )
+    assert spec.plus_terminals[0] == "conductor_1"
+    assert spec.minus_terminals[0] == "ground"
+
+    # Test Case 1.4: ArrayFloat2D with 2 points (linestring)
+    spec = td.TerminalSpec(plus_terminals=(np.array([[0.0, 0.0], [1.0, 1.0]]),), minus_terminals=())
+    assert isinstance(spec.plus_terminals[0], np.ndarray)
+    assert spec.plus_terminals[0].shape == (2, 2)
+
+    # Test Case 1.5: ArrayFloat2D with 3+ points (polygon)
+    spec = td.TerminalSpec(
+        plus_terminals=(np.array([[0, 0], [1, 0], [1, 1], [0, 1]]),), minus_terminals=()
+    )
+    assert isinstance(spec.plus_terminals[0], np.ndarray)
+    assert spec.plus_terminals[0].shape == (4, 2)
+
+    # Test Case 1.6: Lists converted to numpy by ArrayFloat2D
+    spec = td.TerminalSpec(plus_terminals=([[0.0, 0.0], [1.0, 1.0]],), minus_terminals=())
+    # List should be converted to numpy array
+    assert isinstance(spec.plus_terminals[0], np.ndarray)
+    assert spec.plus_terminals[0].shape == (2, 2)
+
+    # Test Case 1.7: Mixed types in same spec
+    spec = td.TerminalSpec(
+        plus_terminals=(
+            (1.0, 0.5),  # Coordinate2D
+            "conductor_2",  # str
+            np.array([[0, 0], [1, 1]]),  # ArrayFloat2D
+        ),
+        minus_terminals=(),
+    )
+    assert isinstance(spec.plus_terminals[0], tuple)
+    assert isinstance(spec.plus_terminals[1], str)
+    assert isinstance(spec.plus_terminals[2], np.ndarray)
+
+    # Test Case 1.8: Empty minus_terminals (valid for common mode)
+    spec = td.TerminalSpec(plus_terminals=((1.0, 0.5),), minus_terminals=())
+    assert len(spec.minus_terminals) == 0
+
+    # Test Case 1.9: Exactly 3 points (minimum for polygon - triangle)
+    spec = td.TerminalSpec(
+        plus_terminals=(np.array([[0, 0], [1, 0], [0.5, 1]]),), minus_terminals=()
+    )
+    assert spec.plus_terminals[0].shape == (3, 2)
+
+    # Test Case 1.10: Exactly 2 points
+    spec = td.TerminalSpec(plus_terminals=(np.array([[0.0, 0.0], [1.0, 0.0]]),), minus_terminals=())
+    assert spec.plus_terminals[0].shape == (2, 2)
+
+    # Test Case 1.11: 1 point but using ArrayLike
+    spec = td.TerminalSpec(plus_terminals=(np.array([[1.0, 0.0]]),), minus_terminals=())
+    assert spec.plus_terminals[0].shape == (1, 2)
+
+
+def test_terminal_spec_invalid_inputs():
+    """Test TerminalSpec validation rejects invalid inputs."""
+    # Test Case 2.1: Invalid array shape (not Nx2)
+    with pytest.raises(pd.ValidationError):
+        td.TerminalSpec(
+            plus_terminals=(np.array([[0, 0, 0], [1, 1, 1]]),),  # 3 columns instead of 2
+            minus_terminals=(),
+        )
+
+    # Test Case 2.2: Invalid polygon (self-intersecting bowtie)
+    with pytest.raises(pd.ValidationError, match="valid polygon"):
+        td.TerminalSpec(
+            plus_terminals=(
+                np.array([[0, 0], [1, 1], [1, 0], [0, 1]]),
+            ),  # Figure-8 self-intersection
+            minus_terminals=(),
+        )
+
+    # Test Case 2.3: 1D array instead of 2D
+    with pytest.raises(pd.ValidationError):
+        td.TerminalSpec(
+            plus_terminals=(np.array([0, 1, 2]),),  # 1D array
+            minus_terminals=(),
+        )
+
+    # Test Case 2.4: Wrong coordinate tuple length (3 elements instead of 2)
+    with pytest.raises(pd.ValidationError):
+        td.TerminalSpec(
+            plus_terminals=((1.0, 0.5, 2.0),),  # 3 elements
+            minus_terminals=(),
+        )

tidy3d/__init__.py

@@ -24,9 +24,7 @@
     MicrowaveModeSolverData,
 )
 from tidy3d.components.microwave.impedance_calculator import ImpedanceCalculator
-from tidy3d.components.microwave.mode_spec import (
-    MicrowaveModeSpec,
-)
+from tidy3d.components.microwave.mode_spec import MicrowaveModeSpec, TerminalSpec
 from tidy3d.components.microwave.monitor import (
     MicrowaveModeMonitor,
     MicrowaveModeSolverMonitor,
@@ -799,6 +797,7 @@ def set_logging_level(level: str) -> None:
     "TemperatureBC",
     "TemperatureData",
     "TemperatureMonitor",
+    "TerminalSpec",
     "TetrahedralGridDataset",
     "Transformed",
     "TriangleMesh",

tidy3d/components/data/monitor_data.py

@@ -1819,31 +1819,6 @@ 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

@@ -6,6 +6,7 @@
 
 import numpy as np
 import pydantic.v1 as pd
+from shapely import Polygon
 
 from tidy3d.components.base import cached_property
 from tidy3d.components.geometry.base import Box
@@ -17,22 +18,103 @@
 )
 from tidy3d.components.mode_spec import AbstractModeSpec
 from tidy3d.components.types import Coordinate2D, annotate_type
+from tidy3d.components.types.base import ArrayFloat2D
 from tidy3d.constants import fp_eps
 from tidy3d.exceptions import SetupError
 
+ConductorIdentifierType = Union[Coordinate2D, str, ArrayFloat2D]
+
 
 class TerminalSpec(MicrowaveBaseModel):
-    plus_terminals: tuple[Coordinate2D, ...] = pd.Field(
+    """Specifies the desired voltage pattern across conductors for a transmission line mode.
+
+    Identifies which conductors should be at positive versus negative voltage for mode selection
+    and ordering in coupled transmission line systems. Conductors can be identified using point
+    coordinates, structure names, or geometric regions for maximum flexibility.
+
+    Notes
+    -----
+    For most use cases, identifying conductors using a single (x, y) coordinate point or a
+    structure name string is recommended. If desired, users may specify geometric regions using
+    arrays of vertices, which are then converted to points, lines, or polygons to identify
+    conductors via intersections.
+
+    Example
+    -------
+    >>> # Recommended: Identify conductors using point coordinates
+    >>> # Differential mode: conductor 1 positive, conductor 2 negative
+    >>> diff_mode = TerminalSpec(
+    ...     plus_terminals=((1.0, 0.5),),  # Point inside positive conductor
+    ...     minus_terminals=((-1.0, 0.5),)  # Point inside negative conductor
+    ... )
+    >>>
+    >>> # Common mode: both conductors positive relative to ground
+    >>> common_mode = TerminalSpec(
+    ...     plus_terminals=((1.0, 0.5), (-1.0, 0.5)),  # Both conductors positive
+    ...     minus_terminals=()  # Ground plane is reference
+    ... )
+    >>>
+    >>> # Alternative: Identify conductors by structure name
+    >>> named_mode = TerminalSpec(
+    ...     plus_terminals=("trace1",),
+    ...     minus_terminals=("trace2",)
+    ... )
+    >>>
+    >>> # Advanced: Identify conductor using polygon region
+    >>> import numpy as np
+    >>> polygon_mode = TerminalSpec(
+    ...     plus_terminals=(np.array([[0, 0], [1, 0], [1, 1], [0, 1]]),),  # Square region
+    ...     minus_terminals=()
+    ... )
+    """
+
+    plus_terminals: tuple[ConductorIdentifierType, ...] = pd.Field(
         ...,
-        title="Impedance Specifications",
-        description="Field controls how the impedan",
+        title="Positive Terminals",
+        description="Identifies conductors that should be at positive voltage for this mode. "
+        "Each conductor can be specified as: (1) a (u, v) coordinate tuple locating a point inside "
+        "the conductor (recommended), (2) a string matching a structure name, or (3) an Nx2 array "
+        "of vertices defining a geometric region (point for N=1, line for N=2, polygon for N>2). "
+        "The coordinate or region should lie within the desired conductor in the mode plane.",
     )
-    minus_terminals: tuple[Coordinate2D, ...] = pd.Field(
+    minus_terminals: tuple[ConductorIdentifierType, ...] = pd.Field(
         ...,
-        title="Impedance Specifications",
-        description="Field controls how the impedan",
+        title="Negative Terminals",
+        description="Identifies conductors that should be at negative voltage for this mode. "
+        "Each conductor can be specified as: (1) a (u, v) coordinate tuple locating a point inside "
+        "the conductor (recommended), (2) a string matching a structure name, or (3) an Nx2 array "
+        "of vertices defining a geometric region (point for N=1, line for N=2, polygon for N>2). "
+        "The coordinate or region should lie within the desired conductor in the mode plane.",
     )
 
+    @pd.validator("plus_terminals", "minus_terminals", each_item=True)
+    def _validate_conductor_identifiers(cls, val):
+        """Validate conductor identification inputs."""
+
+        # If it's a string or tuple, pass through
+        if isinstance(val, (str, tuple)):
+            return val
+
+        # If it's a numpy array, validate shape and geometry
+        if isinstance(val, np.ndarray):
+            # Check that 2D arrays have exactly 2 columns (u, v coordinates)
+            if val.shape[1] != 2:
+                raise ValueError(
+                    f"Arrays must have exactly 2 columns for (u, v) coordinates, got shape {val.shape}"
+                )
+            # For 2D arrays, check number of points and polygon validity
+            num_points = val.shape[0]
+            if num_points <= 2:
+                return val
+            elif num_points > 2:
+                polygon = Polygon(val)
+                if not polygon.is_valid:
+                    raise ValueError(
+                        f"A supplied set of vertices {val} did not result in a valid "
+                        "polygon, make sure there are no self-intersections."
+                    )
+        return val
+
 
 class MicrowaveModeSpec(AbstractModeSpec, MicrowaveBaseModel):
     """
@@ -80,11 +162,11 @@ class MicrowaveModeSpec(AbstractModeSpec, MicrowaveBaseModel):
     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.",
+        description="Optional tuple of terminal specifications for mode selection and ordering in"
+        "transmission line systems. Each 'TerminalSpec' defines the desired voltage pattern (which conductors "
+        "should be positive vs. negative) for a mode. When provided, the mode solver automatically reorders "
+        "computed modes to match the terminal specification order and applies phase corrections to ensure "
+        "correct voltage polarity.",
     )
 
     @cached_property