more docstrings and changelog

Author: dbochkov-flexcompute

CHANGELOG.md

@@ -12,6 +12,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added KLayout plugin, with DRC functionality for running design rule checks in `plugins.klayout.drc`. Supports running DRC on GDS files as well as `Geometry`, `Structure`, and `Simulation` objects.
 - Added "mil" and "in" (inch) units to `plot_length_units`.
 - Objective functions that involve running `tidy3d.plugins.smatrix.ComponentModeler` can be differentiated with autograd.
+- Access field decay values in `SimulationData` via `sim_data.field_decay` as `TimeDataArray`.
+- Added ability to set first-order absorbing boundary conditions on simulation domain boundaries using either `ABCBoundary` or `ModeABCBoundary` classes.
+- Added `frame` field to `ModeSource` (default: `None`) and `WavePort` (default: `PECFrame()`). Setting this to `PECFrame(length=...)` automatically places a thin PEC frame of specified length around the source/port. The automatically created frames can be inspected using `Simulation._finalized` property.
+- Added `InternalAbsorber` class for placing first-order absorbing boundary conditions on planes inside the simulation domain. Internal absorbers are automatically wrapped in a PEC frame with a backing PEC plate on the non-absorbing side.
+- Added `absorber` field (default: `True`) to `WavePort` for automatically placing an absorber behind the port.
+- Added `conjugated_dot_product` field in `ModeMonitor` (default: `True`) and `WavePort` (default: `False`) to allow selecting the conjugated or non-conjugated dot product for mode decomposition.
 
 ### Changed
 - Validate mode solver object for large number of grid points on the modal plane.

tidy3d/components/boundary.py

@@ -233,7 +233,9 @@ def from_monitor(
 
 
 class InternalAbsorber(Box):
-    """Internally placed plane with one-way wave equation boundary conditions for absorption of electromagnetic waves."""
+    """Internally placed plane with one-way wave equation boundary conditions for absorption of electromagnetic waves.
+    Note that internal absorbers are automatically wrapped in a PEC frame with a backing PEC plate on the non-absorbing side.
+    """
 
     direction: Direction = pd.Field(
         ...,

tidy3d/components/simulation.py

@@ -368,7 +368,8 @@ class AbstractYeeGridSimulation(AbstractSimulation, ABC):
     internal_absorbers: tuple[InternalAbsorber, ...] = pydantic.Field(
         (),
         title="Internal Absorbers",
-        description="Planes with the first order absorbing boundary conditions placed inside the computational domain.",
+        description="Planes with the first order absorbing boundary conditions placed inside the computational domain. "
+        "Note that internal absorbers are automatically wrapped in a PEC frame with a backing PEC plate on the non-absorbing side.",
     )
 
     @pydantic.validator("simulation_type", always=True)
@@ -5633,7 +5634,10 @@ def from_scene(cls, scene: Scene, **kwargs) -> Simulation:
     _boundaries_for_zero_dims = validate_boundaries_for_zero_dims()
 
     def _make_pec_frame(self, obj: Union[ModeSource, InternalAbsorber]) -> Structure:
-        """Make a pec frame around a mode source."""
+        """Make a pec frame around a mode source or an internal absorber. For mode sources,
+        the frame is added around the injection plane. For internal absorbers, a backing pec
+        plate is also added on the non-absorbing side.
+        """
         span_inds = np.array(self.grid.discretize_inds(obj))
 
         coords = self.grid.boundaries.to_list