Introduce SubpixelSpec to allow for selecting subpixel averaging meth…

…ods for different materials

Validate dielectric subpixel in adjoint plugin

Enable VolumetricAveraging to automatically switch to Staircasing if the field is substantially normal to the interface

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - A batch of `ModeSolver` objects can be run concurrently using `tidy3d.plugins.mode.web.run_batch()`
 - `RectangularWaveguide.plot_field` optionally draws geometry edges over fields. 
 - `RectangularWaveguide` supports layered cladding above and below core.
+- `SubpixelSpec` accepted by `Simulation.subpixel` to select subpixel averaging methods separately for dielectric, metal, and PEC materials. Specifically, added support for conformal mesh methods near PEC structures that can be specified through the field `pec` in the `SubpixelSpec` class. Note: previously, `subpixel=False` was implementing staircasing for every material except PEC. Now, `subpixel=False` implements direct staircasing for all materials. For PEC, the behavior of `subpixel=False` in Tidy3D < 2.7 is now achieved through `subpixel=SubpixelSpec(pec=HeuristicPECStaircasing())`, while `subpixel=True` in Tidy3D < 2.7 is now achieved through `subpixel=SubpixelSpec(pec=Staircasing())`. The default is `subpixel=SubpixelSpec(pec=PECConformal())` for more accurate PEC modelling.
 
 ### Fixed
 - `ModeSolver.plot_field` correctly returning the plot axes.
@@ -52,7 +53,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Introduces the `microwave` plugin which includes `ImpedanceCalculator` for computing the characteristic impedance of transmission lines.
 - `Simulation` now accepts `LumpedElementType`, which currently only supports the `LumpedResistor` type. `LumpedPort` together with `LumpedResistor` make up the new `TerminalComponentModeler` in the `smatrix` plugin.
 - Uniaxial medium Lithium Niobate to material library.
-- Added support for conformal mesh methods near PEC structures that can be specified through the field `pec_conformal_mesh_spec` in the `Simulation` class. Note: previously, `subpixel=False` was implementing staircasing for every material except PEC. Now, `subpixel=False` implements direct staircasing for all materials. For PEC, the behavior of `subpixel=False` in Tidy3D < 2.7 is now achieved through `subpixel=True` and `pec_conformal_mesh_spec=HeuristicConformalMeshSpec()`, while `subpixel=True` in Tidy3D < 2.7 is now achieved through the default settings `subpixel=True` and `pec_conformal_mesh_spec=StaircasingConformalMeshSpec()`. Additionally, a new `BenklerConformalMeshSpec()` was introduced for more accurate PEC modelling.
 - Properties `num_time_steps_adjoint` and `tmesh_adjoint` to `JaxSimulation` to estimate adjoint run time.
 - Ability to add `path` to `updated_copy()` method to recursively update sub-components of a tidy3d model. For example `sim2 = sim.updated_copy(size=new_size, path="structures/0/geometry")` creates a recursively updated copy of `sim` where `sim.structures[0].geometry` is updated with `size=new_size`.
 - Python 3.12 support. Python 3.8 deprecation. Updated dependencies.

docs/api/discretization.rst

@@ -15,14 +15,3 @@ Discretization
    tidy3d.FieldGrid
    tidy3d.YeeGrid
    tidy3d.Grid
-
-PEC Conformal Mesh Spec
------------------------
-
-.. autosummary::
-   :toctree: _autosummary/
-   :template: module.rst
-
-   tidy3d.StaircasingConformalMeshSpec
-   tidy3d.HeuristicConformalMeshSpec
-   tidy3d.BenklerConformalMeshSpec

docs/api/index.rst

@@ -16,6 +16,7 @@ API |:computer:|
     mode
     lumped_elements
     discretization
+    subpixel_averaging
     output_data
     scene
     logging
@@ -38,6 +39,7 @@ API |:computer:|
 .. include:: /api/mode.rst
 .. include:: /api/lumped_elements.rst
 .. include:: /api/discretization.rst
+.. include:: /api/subpixel_averaging.rst
 .. include:: /api/output_data.rst
 .. include:: /api/scene.rst
 .. include:: /api/logging.rst

docs/api/subpixel_averaging.rst

@@ -0,0 +1,23 @@
+.. currentmodule:: tidy3d
+
+Subpixel Averaging
+==================
+
+.. autosummary::
+   :toctree: _autosummary/
+   :template: module.rst
+
+   tidy3d.SubpixelSpec
+
+Types of Subpixel Averaging Methods
+-----------------------------------
+
+.. autosummary::
+   :toctree: _autosummary/
+   :template: module.rst
+
+   tidy3d.Staircasing
+   tidy3d.VolumetricAveraging
+   tidy3d.HeuristicPECStaircasing
+   tidy3d.PolarizedAveraging
+   tidy3d.PECConformal

tests/sims/simulation_sample.json

@@ -2722,9 +2722,5 @@
     "courant": 0.8,
     "normalize_index": 0,
     "shutoff": 0.0001,
-    "pec_conformal_mesh_spec": {
-        "attrs": {},
-        "type": "StaircasingConformalMeshSpec"
-    },
     "run_time": 1e-12
 }

tests/test_components/test_simulation.py

@@ -1969,30 +1969,32 @@ def test_dt():
 
 
 def test_conformal_dt():
-    """make sure dt is reduced when BenklerConformalMeshSpec is applied."""
+    """make sure dt is reduced when PEC structures are present and PECConformal is used."""
+    box = td.Structure(
+        geometry=td.Box(size=(1, 1, 1)),
+        medium=td.PECMedium(),
+    )
     sim = td.Simulation(
         size=(2.0, 2.0, 2.0),
         run_time=1e-12,
+        structures=[box],
         grid_spec=td.GridSpec.uniform(dl=0.1),
+        subpixel=td.SubpixelSpec(pec=td.Staircasing()),
     )
     dt = sim.dt
 
-    # Benkler
-    sim_conformal = sim.updated_copy(pec_conformal_mesh_spec=td.BenklerConformalMeshSpec())
+    # Conformal
+    sim_conformal = sim.updated_copy(subpixel=td.SubpixelSpec(pec=td.PECConformal()))
     assert sim_conformal.dt < dt
 
-    # Benkler: same courant
+    # Conformal: same courant
     sim_conformal2 = sim.updated_copy(
-        pec_conformal_mesh_spec=td.BenklerConformalMeshSpec(timestep_reduction=0)
+        subpixel=td.SubpixelSpec(pec=td.PECConformal(timestep_reduction=0))
     )
     assert sim_conformal2.dt == dt
 
-    # staircasing
-    sim_staircasing = sim.updated_copy(pec_conformal_mesh_spec=td.StaircasingConformalMeshSpec())
-    assert sim_staircasing.dt == dt
-
     # heuristic
-    sim_heuristic = sim.updated_copy(pec_conformal_mesh_spec=td.StaircasingConformalMeshSpec())
+    sim_heuristic = sim.updated_copy(subpixel=td.SubpixelSpec(pec=td.HeuristicPECStaircasing()))
     assert sim_heuristic.dt == dt
 
 

tidy3d/__init__.py

@@ -3,8 +3,11 @@
 # grid
 from .components.grid.grid import Grid, Coords
 from .components.grid.grid_spec import GridSpec, UniformGrid, CustomGrid, AutoGrid
-from .components.grid.grid_spec import BenklerConformalMeshSpec, StaircasingConformalMeshSpec
-from .components.grid.grid_spec import HeuristicConformalMeshSpec
+
+# subpixel
+from .components.subpixel_spec import SubpixelSpec, Staircasing
+from .components.subpixel_spec import VolumetricAveraging, PolarizedAveraging
+from .components.subpixel_spec import HeuristicPECStaircasing, PECConformal
 
 # geometry
 from .components.geometry.base import Box, Transformed, ClipOperation, GeometryGroup
@@ -352,9 +355,12 @@ def set_logging_level(level: str) -> None:
     "TriangularGridDataset",
     "TetrahedralGridDataset",
     "medium_from_nk",
-    "BenklerConformalMeshSpec",
-    "StaircasingConformalMeshSpec",
-    "HeuristicConformalMeshSpec",
+    "SubpixelSpec",
+    "Staircasing",
+    "VolumetricAveraging",
+    "PolarizedAveraging",
+    "HeuristicPECStaircasing",
+    "PECConformal",
     "EMESimulation",
     "EMESimulationData",
     "EMEMonitor",

tidy3d/components/eme/simulation.py

@@ -175,13 +175,6 @@ class EMESimulation(AbstractYeeGridSimulation):
         validate_default=True,
     )
 
-    subpixel: bool = pd.Field(
-        True,
-        title="Subpixel Averaging",
-        description="If ``True``, uses subpixel averaging of the permittivity "
-        "based on structure definition, resulting in much higher accuracy for a given grid size.",
-    )
-
     store_port_modes: bool = pd.Field(
         True,
         title="Store Port Modes",

tidy3d/components/grid/grid_spec.py

@@ -9,7 +9,7 @@
 
 from .grid import Coords1D, Coords, Grid
 from .mesher import GradedMesher, MesherType
-from ..base import Tidy3dBaseModel, cached_property
+from ..base import Tidy3dBaseModel
 from ..types import Axis, Symmetry, annotate_type, TYPE_TAG_STR
 from ..source import SourceType
 from ..structure import Structure, StructureType
@@ -18,61 +18,6 @@
 from ...exceptions import SetupError
 from ...constants import MICROMETER, C_0, fp_eps
 
-# Default Courant number reduction rate in Benkler's scheme
-DEFAULT_COURANT_REDUCTION_BENKLER = 0.3
-
-
-class ConformalMeshSpec(Tidy3dBaseModel, ABC):
-    """Base class defining conformal mesh specifications."""
-
-    @cached_property
-    def courant_ratio(self) -> float:
-        """The scaling ratio applied to Courant number so that the courant number
-        in the simulation is ``sim.courant * courant_ratio``.
-        """
-        return 1.0
-
-
-class StaircasingConformalMeshSpec(ConformalMeshSpec):
-    """Simple staircasing scheme based on
-    [Taflove, The Electrical Engineering Handbook 3.629-670 (2005): 15.].
-    """
-
-
-class HeuristicConformalMeshSpec(ConformalMeshSpec):
-    """Slightly different from the staircasing scheme: the field component near PEC
-    is considered to be outside PEC if it's substantially normal to the interface.
-    """
-
-
-class BenklerConformalMeshSpec(ConformalMeshSpec):
-    """Conformal mesh scheme based on
-    [S. Benkler, IEEE Transactions on Antennas and Propagation 54.6, 1843 (2006)], which is similar
-    to the approach described in [S. Dey, R. Mittra, IEEE Microwave and Guided Wave Letters 7.9, 273 (1997)].
-    """
-
-    timestep_reduction: float = pd.Field(
-        DEFAULT_COURANT_REDUCTION_BENKLER,
-        title="Time Step Size Reduction Rate",
-        description="Reduction factor between 0 and 1 such that the simulation's time step size "
-        "will be ``1 - timestep_reduction`` times its default value. "
-        "Accuracy can be improved with a smaller time step size; but simulation time increased as well.",
-        lt=1,
-        ge=0,
-    )
-
-    @cached_property
-    def courant_ratio(self) -> float:
-        """The scaling ratio applied to Courant number so that the courant number
-        in the simulation is ``sim.courant * courant_ratio``.
-        """
-        return 1 - self.timestep_reduction
-
-
-ConformalMeshSpecType = Union[
-    BenklerConformalMeshSpec, StaircasingConformalMeshSpec, HeuristicConformalMeshSpec
-]
-
 
 class GridSpec1d(Tidy3dBaseModel, ABC):
 

tidy3d/components/medium.py

@@ -1107,9 +1107,9 @@ class AbstractCustomMedium(AbstractMedium, ABC):
     subpixel: bool = pd.Field(
         False,
         title="Subpixel averaging",
-        description="If ``True`` and simulation's ``subpixel`` is also ``True``, "
-        "applies subpixel averaging of the permittivity "
-        "on the interface of the structure, including exterior boundary and "
+        description="If ``True``, apply the subpixel averaging method specified by "
+        "``Simulation``'s field ``subpixel`` for this type of material on the "
+        "interface of the structure, including exterior boundary and "
         "intersection interfaces with other structures.",
     )
 
@@ -5249,8 +5249,8 @@ class AbstractPerturbationMedium(ABC, Tidy3dBaseModel):
         True,
         title="Subpixel averaging",
         description="This value will be transferred to the resulting custom medium. That is, "
-        "if ``True``, the subpixel averaging will be applied to the custom medium provided "
-        "the corresponding ``Simulation``'s field ``subpixel`` is set to ``True`` as well. "
+        "if ``True``, the subpixel averaging will be applied to the custom medium. The type "
+        "of subpixel averaging method applied is specified in ``Simulation``'s field ``subpixel``. "
         "If the resulting medium is not a custom medium (no perturbations), this field does not "
         "have an effect.",
     )