minor edits

Author: dbochkov-flexcompute

tidy3d/components/boundary.py

@@ -243,7 +243,9 @@ class PortAbsorber(Box):
     shift: int = pd.Field(
         0,
         title="Absorber Shift",
-        description="Displacement of absorber in the normal positive direction in number of cells.",
+        description="Displacement of absorber in the normal positive direction in number of cells. "
+        "This could be used to conveniently place an absorber right behind a source: "
+        "one can use the same `size` and `center` as for the source and simply set `shift` to 1.",
     )
 
     boundary_spec: Union[ModeABCBoundary, ABCBoundary] = pd.Field(

tidy3d/components/eme/simulation.py

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

tidy3d/components/mode/simulation.py

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

tidy3d/components/simulation.py

@@ -113,6 +113,7 @@
     Ax,
     Axis,
     CoordinateOptional,
+    Direction,
     FreqBound,
     InterpMethod,
     PermittivityComponent,
@@ -368,7 +369,7 @@ class AbstractYeeGridSimulation(AbstractSimulation, ABC):
     absorbers: tuple[PortAbsorber, ...] = pydantic.Field(
         (),
         title="Port Absorbers",
-        description="Absorbers based on the first order boundary conditions placed inside the computational domain.",
+        description="Planes with the first order absorbing boundary conditions placed inside the computational domain.",
     )
 
     @pydantic.validator("simulation_type", always=True)
@@ -558,6 +559,10 @@ def plot(
             Opacity of the monitors. If ``None``, uses Tidy3d default.
         lumped_element_alpha : float = None
             Opacity of the lumped elements. If ``None``, uses Tidy3d default.
+        absorber_alpha : float = None
+            Opacity of the port absorbers. If ``None``, uses Tidy3d default.
+        absorber_actual_placement : bool = False
+            Use the exact placement of port absorbers which take into account their ``shift`` values.
         ax : matplotlib.axes._subplots.Axes = None
             Matplotlib axes to plot on, if not specified, one is created.
         hlim : Tuple[float, float] = None
@@ -660,6 +665,10 @@ def plot_eps(
             Opacity of the monitors. If ``None``, uses Tidy3d default.
         lumped_element_alpha : float = None
             Opacity of the lumped elements. If ``None``, uses Tidy3d default.
+        absorber_alpha : float = None
+            Opacity of the port absorbers. If ``None``, uses Tidy3d default.
+        absorber_actual_placement : bool = False
+            Use the exact placement of port absorbers which take into account their ``shift`` values.
         ax : matplotlib.axes._subplots.Axes = None
             Matplotlib axes to plot on, if not specified, one is created.
         hlim : Tuple[float, float] = None
@@ -2080,8 +2089,15 @@ def _invalidate_solver_cache(self) -> None:
         """Clear cached attributes that become stale when subpixel changes."""
         self._cached_properties.pop("_mode_solver", None)
 
-    def _shift_value_signed(self, obj, direction, shift) -> float:
-        """How far (signed) to shift the source from the monitor."""
+    def _shift_value_signed(
+        self, obj: Box, direction: Direction, shift: int, name: Optional[str] = None
+    ) -> float:
+        """Calculate the signed distance corresponding to moving the object by ``shift`` number
+        of cells in the positive or negative ``direction`` along the dimension given by
+        ``obj._normal_axis``.
+        """
+        if name is None:
+            name = f"A '{obj.type}'"
 
         # get the grid boundaries and sizes along port normal from the simulation
         normal_axis = obj._normal_axis
@@ -2103,7 +2119,7 @@ def _shift_value_signed(self, obj, direction, shift) -> float:
             shifted_index = port_index + signed_shift
             if shifted_index < 0 or grid_centers[shifted_index] <= self.bounds[0][normal_axis]:
                 raise SetupError(
-                    # f"Port {port.name} normal is less than 2 cells to the boundary "
+                    f"{name} normal is less than 2 cells to the boundary "
                     f"on -{'xyz'[normal_axis]} side. "
                     "Please either increase the mesh resolution near the port or "
                     "move the port away from the boundary."
@@ -2117,7 +2133,7 @@ def _shift_value_signed(self, obj, direction, shift) -> float:
                 or grid_centers[shifted_index] >= self.bounds[1][normal_axis]
             ):
                 raise SetupError(
-                    # f"Port {port.name} normal is tless than 2 cells to the boundary "
+                    f"{name} normal is less than 2 cells to the boundary "
                     f"on +{'xyz'[normal_axis]} side."
                     "Please either increase the mesh resolution near the port or "
                     "move the port away from the boundary."

tidy3d/plugins/smatrix/component_modelers/base.py

@@ -255,51 +255,9 @@ def inv(matrix: DataArray):
     def _shift_value_signed(self, port: Union[Port, WavePort]) -> float:
         """How far (signed) to shift the source from the monitor."""
 
-        # get the grid boundaries and sizes along port normal from the simulation
-        normal_axis = port.size.index(0.0)
-        grid = self.simulation.grid
-        grid_boundaries = grid.boundaries.to_list[normal_axis]
-        grid_centers = grid.centers.to_list[normal_axis]
-
-        # get the index of the grid cell where the port lies
-        port_position = port.center[normal_axis]
-        port_pos_gt_grid_bounds = np.argwhere(port_position > grid_boundaries)
-
-        # no port index can be determined
-        if len(port_pos_gt_grid_bounds) == 0:
-            raise SetupError(f"Port position '{port_position}' outside of simulation bounds.")
-        port_index = port_pos_gt_grid_bounds[-1]
-
-        # shift the port to the left
-        if port.direction == "+":
-            shifted_index = port_index - 2
-            if (
-                shifted_index < 0
-                or grid_centers[shifted_index] <= self.simulation.bounds[0][normal_axis]
-            ):
-                raise SetupError(
-                    f"Port {port.name} normal is less than 2 cells to the boundary "
-                    f"on -{'xyz'[normal_axis]} side. "
-                    "Please either increase the mesh resolution near the port or "
-                    "move the port away from the boundary."
-                )
-
-        # shift the port to the right
-        else:
-            shifted_index = port_index + 2
-            if (
-                shifted_index >= len(grid_centers)
-                or grid_centers[shifted_index] >= self.simulation.bounds[1][normal_axis]
-            ):
-                raise SetupError(
-                    f"Port {port.name} normal is tless than 2 cells to the boundary "
-                    f"on +{'xyz'[normal_axis]} side."
-                    "Please either increase the mesh resolution near the port or "
-                    "move the port away from the boundary."
-                )
-
-        new_pos = grid_centers[shifted_index]
-        return new_pos - port_position
+        return self.simulation._shift_value_signed(
+            obj=port, direction=port.direction, shift=-2, name=f"Port {port.name}"
+        )
 
     def sim_data_by_task_name(self, task_name: str) -> SimulationData:
         """Get the simulation data by task name, avoids emitting warnings from the ``Simulation``."""