add test for sim validation and improved doc strings

Author: dmarek-flex

tests/test_components/test_simulation.py

@@ -3629,3 +3629,54 @@ def test_create_sim_multiphysics_with_incompatibilities():
                 ),
             ],
         )
+
+
+def test_validate_terminal_spec_generation():
+    """Test that auto generation of path specs is correctly validated for currently unsupported structures."""
+    freq0 = 10e9
+    mm = 1e3
+    run_time_spec = td.RunTimeSpec(quality_factor=3.0)
+    size = (10 * mm, 10 * mm, 10 * mm)
+    size_mon = (0, 8 * mm, 8 * mm)
+
+    # Currently limited to generation of axis aligned boxes around conductors,
+    # so the path may intersect other nearby conductors, like in this coaxial cable
+    coaxial = td.Structure(
+        geometry=td.GeometryGroup(
+            geometries=(
+                td.ClipOperation(
+                    operation="difference",
+                    geometry_a=td.Cylinder(
+                        axis=0, radius=2.5 * mm, center=(0, 0, 0), length=td.inf
+                    ),
+                    geometry_b=td.Cylinder(
+                        axis=0, radius=1.3 * mm, center=(0, 0, 0), length=td.inf
+                    ),
+                ),
+                td.Cylinder(axis=0, radius=1 * mm, center=(0, 0, 0), length=td.inf),
+            )
+        ),
+        medium=td.PEC,
+    )
+    mode_spec = td.ModeSpec(num_modes=2, target_neff=1.8, terminal_spec=td.TerminalSpec())
+
+    mode_mon = td.ModeMonitor(
+        center=(0, 0, 0),
+        size=size_mon,
+        freqs=[freq0],
+        name="mode_1",
+        colocate=False,
+        mode_spec=mode_spec,
+    )
+    sim = td.Simulation(
+        run_time=run_time_spec,
+        size=size,
+        sources=[],
+        structures=[coaxial],
+        grid_spec=td.GridSpec.uniform(dl=0.1 * mm),
+        monitors=[mode_mon],
+    )
+
+    # check that validation error is caught
+    with pytest.raises(SetupError):
+        sim._validate_terminal_specs()

tidy3d/components/geometry/utils.py

@@ -40,10 +40,10 @@
 
 
 def flatten_shapely_geometries(
-    geoms: Union[Shapely, Iterable[Shapely]], keep_types: tuple[type, ...] = (Polygon)
+    geoms: Union[Shapely, Iterable[Shapely]], keep_types: tuple[type, ...] = (Polygon,)
 ) -> list[Shapely]:
     """
-    Flatten nested geometries into a flat list of specified types.
+    Flatten nested geometries into a flat list, while only keeping the specified types.
 
     Recursively extracts and returns non-empty geometries of the given types from input geometries,
     expanding any GeometryCollections or Multi* types.

tidy3d/components/microwave/path_spec.py

@@ -1,4 +1,4 @@
-"""Specifications for defining path integrals."""
+"""Module containing specifications for voltage and current path integrals."""
 
 from __future__ import annotations
 
@@ -118,7 +118,7 @@ def _vertices_2D(self, axis: Axis) -> tuple[Coordinate2D, Coordinate2D]:
 
 
 class VoltageIntegralAxisAlignedSpec(AxisAlignedPathIntegralSpec):
-    """Class for computing the voltage between two points defined by an axis-aligned line."""
+    """Class for specifying the voltage calculation between two points defined by an axis-aligned line."""
 
     sign: Direction = pd.Field(
         ...,
@@ -152,13 +152,13 @@ def from_terminal_positions(
         z : float = None
             Position in z direction, only two of x,y,z can be specified to define line.
         extrapolate_to_endpoints: bool = True
-            Passed directly to :class:`VoltageIntegralAxisAligned`
+            Passed directly to :class:`VoltageIntegralAxisAlignedSpec`
         snap_path_to_grid: bool = True
-            Passed directly to :class:`VoltageIntegralAxisAligned`
+            Passed directly to :class:`VoltageIntegralAxisAlignedSpec`
 
         Returns
         -------
-        VoltageIntegralAxisAligned
+        VoltageIntegralAxisAlignedSpec
             The created path integral for computing voltage between the two terminals.
         """
         axis_positions = Geometry.parse_two_xyz_kwargs(x=x, y=y, z=z)
@@ -237,7 +237,7 @@ def plot(
 
 
 class CurrentIntegralAxisAlignedSpec(AbstractAxesRH, Box):
-    """Class for computing conduction current via Ampère's circuital law on an axis-aligned loop."""
+    """Class for specifying the computation of conduction current via Ampère's circuital law on an axis-aligned loop."""
 
     _plane_validator = assert_plane()
 
@@ -270,7 +270,7 @@ def main_axis(self) -> Axis:
     def _to_path_integral_specs(
         self, h_horizontal=None, h_vertical=None
     ) -> tuple[AxisAlignedPathIntegralSpec, ...]:
-        """Returns four ``AxisAlignedPathIntegral`` instances, which represent a contour
+        """Returns four ``AxisAlignedPathIntegralSpec`` instances, which represent a contour
         integral around the surface defined by ``self.size``."""
         ax1 = self.remaining_axes[0]
         ax2 = self.remaining_axes[1]
@@ -427,7 +427,7 @@ def plot(
 
 
 class CustomPathIntegral2DSpec(AbstractAxesRH):
-    """Class for defining a custom path integral defined as a curve on an axis-aligned plane.
+    """Class for specifying a custom path integral defined as a curve on an axis-aligned plane.
 
     Notes
     -----
@@ -486,7 +486,7 @@ def from_circular_path(
         radius : float
             The radius of the circle.
         num_points : int
-            THe number of equidistant points to use along the perimeter of the circle.
+            The number of equidistant points to use along the perimeter of the circle.
         normal_axis : Axis
             The axis normal to the defined circle.
         clockwise : bool
@@ -495,7 +495,7 @@ def from_circular_path(
 
         Returns
         -------
-        :class:`.CustomPathIntegral2D`
+        :class:`.CustomPathIntegral2DSpec`
             A path integral defined on a circular path.
         """
 
@@ -545,7 +545,7 @@ def _correct_shape(cls, val):
         # overall shape of vertices
         if val.shape[1] != 2:
             raise SetupError(
-                "'CustomPathIntegral2D.vertices' must be a 2 dimensional array shaped (N, 2). "
+                "'CustomPathIntegral2DSpec.vertices' must be a 2 dimensional array shaped (N, 2). "
                 f"Given array with shape of '{val.shape}'."
             )
         return val
@@ -574,13 +574,13 @@ def sign(self) -> Direction:
 
 
 class CustomVoltageIntegral2DSpec(CustomPathIntegral2DSpec):
-    """Class for computing the voltage between two points defined by a custom path.
+    """Class for specfying the computation of voltage between two points defined by a custom path.
     Computed voltage is :math:`V=V_b-V_a`, where position b is the final vertex in the supplied path.
 
     Notes
     -----
 
-    Use :class:`.VoltageIntegralAxisAligned` if possible, since interpolation
+    Use :class:`.VoltageIntegralAxisAlignedSpec` if possible, since interpolation
     near conductors will not be accurate.
 
     .. TODO Improve by including extrapolate_to_endpoints field, non-trivial extension."""
@@ -636,7 +636,7 @@ def plot(
 
 
 class CustomCurrentIntegral2DSpec(CustomPathIntegral2DSpec):
-    """Class for computing conduction current via Ampère's circuital law on a custom path.
+    """Class for specifying the computation of conduction current via Ampère's circuital law on a custom path.
     To compute the current flowing in the positive ``axis`` direction, the vertices should be
     ordered in a counterclockwise direction."""
 
@@ -720,9 +720,11 @@ class CompositeCurrentIntegralSpec(Box):
     sum_spec: Literal["sum", "split"] = pd.Field(
         ...,
         title="Sum Specification",
-        description="Determines the method used to combine the currents calculated by the different current integrals  defined by ``path_specs``."
-        "``sum`` simply adds all currents, while ``split`` keeps contributions with opposite phase separate, which allows for isolating "
-        "the current flowing in opposite directions. In ``split`` version, the current returned is the maximum of the two contributions.",
+        description="Determines the method used to combine the currents calculated by the different "
+        "current integrals defined by ``path_specs``. ``sum`` simply adds all currents, while ``split`` "
+        "keeps contributions with opposite phase separate, which allows for isolating the current "
+        "flowing in opposite directions. In ``split`` version, the current returned is the maximum "
+        "of the two contributions.",
     )
 
     @add_ax_if_none