Clean implementation of the mesh refinement structures

Author: vasilyzabelin

CHANGELOG.md

@@ -30,6 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Pretty printing enabled with `rich.print` for the material library, materials, and their variants. In notebooks, this can be accessed using `rich.print` or `display`, or by evaluating the material library, a material, or a variant in a cell.
 - `FieldData` and `ModeData` support exporting E fields to a Zemax Beam File (ZBF) with `.to_zbf()` (warning: experimental feature).
 - `FieldDataset` supports reading E fields from a Zemax Beam File (ZBF) with `.from_zbf()` (warning: experimental feature).
+- Unstructured grid now supports 2D/3D box-shaped refinement regions and 1D refinement lines of arbitrary direction.
 
 ### Changed
 - Performance enhancement for adjoint gradient calculations by optimizing field interpolation.

tidy3d/__init__.py

@@ -39,7 +39,12 @@
 )
 from tidy3d.components.tcad.doping import ConstantDoping, GaussianDoping
 from tidy3d.components.tcad.generation_recombination import FossumCarrierLifetime
-from tidy3d.components.tcad.grid import DistanceUnstructuredGrid, UniformUnstructuredGrid
+from tidy3d.components.tcad.grid import (
+    DistanceUnstructuredGrid,
+    GridRefinementLine,
+    GridRefinementRegion,
+    UniformUnstructuredGrid,
+)
 from tidy3d.components.tcad.monitors.charge import (
     SteadyCapacitanceMonitor,
     SteadyEnergyBandMonitor,
@@ -600,6 +605,8 @@ def set_logging_level(level: str) -> None:
     "HeatFromElectricSource",
     "UniformUnstructuredGrid",
     "DistanceUnstructuredGrid",
+    "GridRefinementRegion",
+    "GridRefinementLine",
     "TemperatureData",
     "TemperatureMonitor",
     "HeatChargeSimulation",

tidy3d/components/tcad/grid.py

@@ -5,12 +5,16 @@
 from abc import ABC
 from typing import Tuple, Union
 
+import numpy as np
 import pydantic.v1 as pd
 
 from tidy3d.components.base import Tidy3dBaseModel, skip_if_fields_missing
 from tidy3d.constants import MICROMETER
 from tidy3d.exceptions import ValidationError
 
+from ..geometry.base import Box
+from ..types import Coordinate, annotate_type
+
 
 class UnstructuredGrid(Tidy3dBaseModel, ABC):
     """Abstract unstructured grid."""
@@ -60,6 +64,92 @@ class UniformUnstructuredGrid(UnstructuredGrid):
     )
 
 
+class GridRefinementRegion(Box):
+    """Refinement region for the unstructured mesh. The cell size is enforced to be constant inside the region.
+    The cell size outside of the region depends on the distance from the region."""
+
+    dl_internal: pd.PositiveFloat = pd.Field(
+        ...,
+        title="Internal mesh cell size",
+        description="Mesh cell size inside the refinement region",
+        units=MICROMETER,
+    )
+
+    transition_thickness: pd.NonNegativeFloat = pd.Field(
+        ...,
+        title="Interface Distance",
+        description="Thickness of a transition layer outside the box where the mesh cell size changes from the"
+        "internal size to the external one.",
+        units=MICROMETER,
+    )
+
+
+class GridRefinementLine(Tidy3dBaseModel, ABC):
+    """Refinement line for the unstructured mesh. The cell size depends on the distance from the line."""
+
+    r1: Coordinate = pd.Field(
+        ...,
+        title="Start point of the line",
+        description="Start point of the line in x, y, and z.",
+        units=MICROMETER,
+    )
+
+    r2: Coordinate = pd.Field(
+        ...,
+        title="End point of the line",
+        description="End point of the line in x, y, and z.",
+        units=MICROMETER,
+    )
+
+    @pd.validator("r1", always=True)
+    def _r1_not_inf(cls, val):
+        """Make sure the point is not infinitiy."""
+        if any(np.isinf(v) for v in val):
+            raise ValidationError("Point can not contain td.inf terms.")
+        return val
+
+    @pd.validator("r2", always=True)
+    def _r2_not_inf(cls, val):
+        """Make sure the point is not infinitiy."""
+        if any(np.isinf(v) for v in val):
+            raise ValidationError("Point can not contain td.inf terms.")
+        return val
+
+    dl_near: pd.PositiveFloat = pd.Field(
+        ...,
+        title="Mesh cell size near the line",
+        description="Mesh cell size near the line",
+        units=MICROMETER,
+    )
+
+    distance_near: pd.NonNegativeFloat = pd.Field(
+        ...,
+        title="Near distance",
+        description="Distance from the line within which ``dl_near`` is enforced."
+        "Typically the same as ``dl_near`` or its multiple.",
+        units=MICROMETER,
+    )
+
+    distance_bulk: pd.NonNegativeFloat = pd.Field(
+        ...,
+        title="Bulk distance",
+        description="Distance from the line outside of which ``dl_bulk`` is enforced."
+        "Typically twice of ``dl_bulk`` or its multiple. Use larger values for a smoother "
+        "transition from ``dl_near`` to ``dl_bulk``.",
+        units=MICROMETER,
+    )
+
+    @pd.validator("distance_bulk", always=True)
+    @skip_if_fields_missing(["distance_near"])
+    def names_exist_bcs(cls, val, values):
+        """Error if distance_bulk is less than distance_near"""
+        distance_near = values.get("distance_near")
+        if distance_near > val:
+            raise ValidationError("'distance_bulk' cannot be smaller than 'distance_near'.")
+
+        return val
+
+
 class DistanceUnstructuredGrid(UnstructuredGrid):
     """Adaptive grid based on distance to material interfaces. Currently not recommended for larger
     simulations.
@@ -126,6 +216,14 @@ class DistanceUnstructuredGrid(UnstructuredGrid):
         "``dl_bulk`` is used instead.",
     )
 
+    mesh_refinements: Tuple[annotate_type(Union[GridRefinementRegion, GridRefinementLine]), ...] = (
+        pd.Field(
+            (),
+            title="Mesh refinement structures",
+            description="List of regions/lines for which the mesh refinement will be applied",
+        )
+    )
+
     @pd.validator("distance_bulk", always=True)
     @skip_if_fields_missing(["distance_interface"])
     def names_exist_bcs(cls, val, values):