pecframe class

Author: dbochkov-flexcompute

tests/test_components/test_absorbers.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import matplotlib.pyplot as plt
 import pydantic.v1 as pydantic
 import pytest
 
@@ -391,7 +390,9 @@ def test_abc_boundaries_simulations():
             ),
             sources=[],
             medium=td.CustomMedium(
-                permittivity=td.SpatialDataArray([[[2, 3]]], coords=dict(x=[0], y=[0], z=[0, 1]))
+                permittivity=td.SpatialDataArray(
+                    [[[2, 3]]], coords={"x": [0], "y": [0], "z": [0, 1]}
+                )
             ),
             run_time=1e-20,
             boundary_spec=td.BoundarySpec.all_sides(td.ABCBoundary()),

tests/test_components/test_source.py

@@ -597,3 +597,17 @@ def test_broadband_angled_gaussian_warning():
             sources=[s],
             normalize_index=None,
         )
+
+
+def test_source_frame():
+    _ = td.PECFrame()
+    _ = td.PECFrame(length=4)
+    with pytest.raises(pydantic.ValidationError):
+        _ = td.PECFrame(length=0)
+
+    _ = td.ModeSource(
+        source_time=td.GaussianPulse(freq0=td.C_0, fwidth=0.2 * td.C_0),
+        direction="+",
+        size=(1, 1, 0),
+        frame=td.PECFrame(),
+    )

tests/test_components/test_source_frames.py

@@ -0,0 +1,72 @@
+"""Tests frames around sources and absorbers."""
+
+from __future__ import annotations
+
+import pydantic.v1 as pydantic
+import pytest
+
+import tidy3d as td
+
+
+def test_source_absorber_frames():
+    _ = td.PECFrame()
+    with pytest.raises(pydantic.ValidationError):
+        _ = td.PECFrame(length=0)
+
+    wvl_um = 1
+    freq0 = td.C_0 / wvl_um
+    mode_source = td.ModeSource(
+        size=(1, 1, 0),
+        source_time=td.GaussianPulse(freq0=freq0, fwidth=0.2 * freq0),
+        mode_spec=td.ModeSpec(num_modes=2),
+        mode_index=1,
+        frame=td.PECFrame(length=3),
+        direction="+",
+    )
+    sim = td.Simulation(
+        center=[0, 0, 0],
+        size=[1, 1, 1],
+        grid_spec=td.GridSpec.auto(
+            min_steps_per_wvl=10,
+            wavelength=wvl_um,
+        ),
+        sources=[mode_source],
+        run_time=1e-20,
+        absorbers=[
+            td.PortAbsorber(
+                size=(0.4, 0.5, 0), direction="-", boundary_spec=td.ABCBoundary(permittivity=1)
+            )
+        ],
+    )
+
+    _ = sim.with_port_frames
+
+    # added frame will collide with projection monitor which requires uniform medium
+    bad_sim = td.Simulation(
+        center=[0, 0, 0],
+        size=[1, 1, 1],
+        grid_spec=td.GridSpec.auto(
+            min_steps_per_wvl=10,
+            wavelength=wvl_um,
+        ),
+        monitors=[
+            td.FieldProjectionAngleMonitor(
+                center=[0, 0.25, 0],
+                size=[1, 0, 1],
+                freqs=[freq0],
+                name="n2f_angle",
+                phi=[0],
+                theta=[0],
+                normal_dir="+",
+            )
+        ],
+        sources=[mode_source],
+        run_time=1e-20,
+        absorbers=[
+            td.PortAbsorber(
+                size=(0.4, 0.5, 0), direction="-", boundary_spec=td.ABCBoundary(permittivity=1)
+            )
+        ],
+    )
+    with pytest.raises(pydantic.ValidationError):
+        _ = bad_sim.with_port_frames

tidy3d/__init__.py

@@ -342,6 +342,9 @@
     ModeSource,
     PlaneWave,
 )
+from .components.source.frame import (
+    PECFrame,
+)
 
 # sources
 from .components.source.time import (
@@ -615,6 +618,7 @@ def set_logging_level(level: str) -> None:
     "NonlinearSusceptibility",
     "PECBoundary",
     "PECConformal",
+    "PECFrame",
     "PECMedium",
     "PMCBoundary",
     "PMCMedium",

tidy3d/components/boundary.py

@@ -232,7 +232,7 @@ def from_monitor(
 
 
 class PortAbsorber(Box):
-    """One-way wave equation absorbing boundary conditions for absorbing a waveguide mode."""
+    """Internally placed plane with one-way wave equation boundary conditions for absorption of electromagnetic waves."""
 
     direction: Direction = pd.Field(
         ...,
@@ -249,7 +249,7 @@ class PortAbsorber(Box):
     boundary_spec: Union[ModeABCBoundary, ABCBoundary] = pd.Field(
         ...,
         title="Boundary Specification",
-        description="Boundary specification.",
+        description="Boundary specification for defining effective propagation index in the one-way wave equation.",
         discriminator=TYPE_TAG_STR,
     )
 

tidy3d/components/eme/simulation.py

@@ -211,8 +211,8 @@ class EMESimulation(AbstractYeeGridSimulation):
 
     absorbers: tuple[()] = pd.Field(
         (),
-        title="Inner Absorbers",
-        description="Inner absorbers.",
+        title="Port Absorbers",
+        description="Absorbers based on the first order boundary conditions placed inside the computational domain.",
     )
 
     grid_spec: GridSpec = pd.Field(

tidy3d/components/mode/simulation.py

@@ -170,8 +170,8 @@ class ModeSimulation(AbstractYeeGridSimulation):
 
     absorbers: tuple[()] = pd.Field(
         (),
-        title="Inner Absorbers",
-        description="Inner absorbers.",
+        title="Port Absorbers",
+        description="Absorbers based on the first order boundary conditions placed inside the computational domain.",
     )
 
     grid_spec: GridSpec = pd.Field(

tidy3d/components/simulation.py

@@ -103,6 +103,7 @@
     ModeSource,
     PlaneWave,
 )
+from .source.frame import PECFrame
 from .source.time import ContinuousWave, CustomSourceTime
 from .source.utils import SourceType
 from .structure import MeshOverrideStructure, Structure
@@ -178,10 +179,6 @@
 # RF frequency warning
 RF_FREQ_WARNING = 300e9
 
-# length and thickness of optional PEC frames around mode sources (in cells)
-MODE_PEC_FRAME_LENGTH = 2
-MODE_PEC_FRAME_THICKNESS = 1e-5
-
 
 def validate_boundaries_for_zero_dims(warn_on_change: bool = True):
     """Error if absorbing boundaries, bloch boundaries, unmatching pec/pmc, or symmetry is used along a zero dimension."""
@@ -370,8 +367,8 @@ class AbstractYeeGridSimulation(AbstractSimulation, ABC):
 
     absorbers: tuple[PortAbsorber, ...] = pydantic.Field(
         (),
-        title="Inner Absorbers",
-        description="Inner absorbers.",
+        title="Port Absorbers",
+        description="Absorbers based on the first order boundary conditions placed inside the computational domain.",
     )
 
     @pydantic.validator("simulation_type", always=True)
@@ -480,7 +477,7 @@ def plot_absorbers(
         ax: Ax = None,
         shifted: bool = False,
     ) -> Ax:
-        """Plot each of simulation's inner absorbers on a plane defined by one nonzero x,y,z coordinate.
+        """Plot each of simulation's port absorbers on a plane defined by one nonzero x,y,z coordinate.
 
         Parameters
         ----------
@@ -5174,7 +5171,7 @@ def dt(self) -> float:
             Time step (seconds).
         """
 
-        return self.with_pec_frames._dt
+        return self.with_port_frames._dt
 
     @cached_property
     def _dt(self) -> float:
@@ -5668,7 +5665,7 @@ def _make_pec_frame(self, obj) -> Structure:
         direction = obj.direction
         if isinstance(obj, ModeSource):
             axis = obj.injection_axis
-            length = obj.pec_frame
+            length = obj.frame.length
         else:
             axis = obj.size.index(0.0)
             length = 1
@@ -5709,13 +5706,13 @@ def _make_pec_frame(self, obj) -> Structure:
         return structure
 
     @cached_property
-    def with_pec_frames(self) -> Simulation:
+    def with_port_frames(self) -> Simulation:
         """Return an instance with added pec frames around mode sources."""
 
         pec_frames = [
             self._make_pec_frame(src)
             for src in self.sources
-            if isinstance(src, ModeSource) and src.pec_frame > 0
+            if isinstance(src, ModeSource) and isinstance(src.frame, PECFrame)
         ]
 
         pec_frames = pec_frames + [
@@ -5732,13 +5729,13 @@ def with_pec_frames(self) -> Simulation:
             grid_spec=GridSpec.from_grid(self.grid), structures=list(self.structures) + pec_frames
         )
 
-    def _validate_with_pec_frames(self):
+    def _validate_with_port_frames(self):
         """Validate that after adding pec frames simulation setup is still valid."""
 
         try:
-            _ = self.with_pec_frames
+            _ = self.with_port_frames
         except Exception:
             log.error(
                 "Simulation fails after requested mode source PEC frames are added. "
-                "Please inspect '.with_pec_frames'."
+                "Please inspect '.with_port_frames'."
             )

tidy3d/components/source/field.py

@@ -12,6 +12,7 @@
 from tidy3d.components.data.dataset import FieldDataset
 from tidy3d.components.data.validators import validate_can_interpolate, validate_no_nans
 from tidy3d.components.mode_spec import ModeSpec
+from tidy3d.components.source.frame import PECFrame
 from tidy3d.components.types import TYPE_TAG_STR, Ax, Axis, Coordinate, Direction
 from tidy3d.components.validators import (
     assert_plane,
@@ -403,10 +404,10 @@ class ModeSource(DirectionalSource, PlanarSource, BroadbandSource):
         "``num_modes`` in the solver will be set to ``mode_index + 1``.",
     )
 
-    pec_frame: pydantic.NonNegativeInt = pydantic.Field(
-        0,
-        title="PEC Frame.",
-        description="Add a thin pec frame around the source during FDTD run.",
+    frame: Optional[PECFrame] = pydantic.Field(
+        None,
+        title="Source Frame.",
+        description="Add a thin frame around the source during FDTD run for an improved injection.",
     )
 
     @cached_property

tidy3d/components/source/frame.py

@@ -0,0 +1,24 @@
+"""Defines specifications for source frames."""
+
+from __future__ import annotations
+
+from abc import ABC
+
+import pydantic.v1 as pydantic
+
+from tidy3d.components.base import Tidy3dBaseModel
+
+
+class AbstractSourceFrame(Tidy3dBaseModel, ABC):
+    """Abstract base class for all source frames."""
+
+    length: int = pydantic.Field(
+        2,
+        title="Length",
+        description="Length of the frame in number of cells.",
+        gt=0,
+    )
+
+
+class PECFrame(AbstractSourceFrame):
+    """PEC source frame."""