In boundary.py, num_layers can now be >= 1, but a warning message is generated if num_layers < 6. (#2606)

All the tests passed.  I took the liberty to press the shiny "Squash and merge" button.  I hope that was okay.

Author: jewettaijfc

CHANGELOG.md

@@ -16,6 +16,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `GaussianBeam` and `AstigmaticGaussianBeam` default `num_freqs` reset to 1 (it was set to 3 in v2.8.0) and a warning is issued for a broadband, angled beam for which `num_freqs` may not be sufficiently large.
 - Set the maximum `num_freqs` to 20 for all broadband sources (we have been warning about the introduction of this hard limit for a while).
 - Significantly improved performance of the `tidy3d.plugins.autograd.grey_dilation` morphological operation and its gradient calculation. The new implementation is orders of magnitude faster, especially for large arrays and kernel sizes.
+- Warnings are now generated (instead of errors) when instantiating `PML`, `StablePML`,
+or `Absorber` classes (or when invoking `pml()`, `stable_pml()`, or `absorber()` functions)
+with fewer layers than recommended.
 
 ### Fixed
 - Arrow lengths are now scaled consistently in the X and Y directions, and their lengths no longer exceed the height of the plot window.

tests/test_components/test_boundaries.py

@@ -7,6 +7,9 @@
 
 import tidy3d as td
 from tidy3d.components.boundary import (
+    MIN_NUM_ABSORBER_LAYERS,
+    MIN_NUM_PML_LAYERS,
+    MIN_NUM_STABLE_PML_LAYERS,
     PML,
     Absorber,
     BlochBoundary,
@@ -73,7 +76,7 @@ def test_boundaryedge_types(plane_wave_dir):
 
 
 def test_boundary_validators():
-    """Test the validators in class `Boundary`"""
+    """Test the validators in class ``Boundary``"""
 
     bloch = BlochBoundary(bloch_vec=1)
     pec = PECBoundary()
@@ -91,20 +94,20 @@ def test_boundary_validators():
 
 @pytest.mark.parametrize("boundary, log_level", [(PMCBoundary(), None), (Periodic(), "WARNING")])
 def test_boundary_validator_warnings(boundary, log_level):
-    """Test the validators in class `Boundary` which should show a warning but not an error"""
+    """Test the validators in class ``Boundary`` which should show a warning but not an error"""
     with AssertLogLevel(log_level):
         _ = Boundary(plus=PECBoundary(), minus=boundary)
 
 
 @pytest.mark.parametrize("boundary, log_level", [(PMCBoundary(), None), (Periodic(), "WARNING")])
 def test_boundary_validator_warnings_switched(boundary, log_level):
-    """Test the validators in class `Boundary` which should show a warning but not an error"""
+    """Test the validators in class ``Boundary`` which should show a warning but not an error"""
     with AssertLogLevel(log_level):
         _ = Boundary(minus=PECBoundary(), plus=boundary)
 
 
 def test_boundary():
-    """Test that the various classmethods and combinations for Boundary work correctly."""
+    """Test that the various classmethods and combinations for ``Boundary`` to work correctly."""
 
     # periodic
     boundary = Boundary.periodic()
@@ -144,7 +147,7 @@ def test_boundary():
 
 
 def test_boundaryspec_classmethods():
-    """Test that the classmethods for BoundarySpec work correctly."""
+    """Test that the classmethods for ``BoundarySpec`` work correctly."""
 
     # pml
     boundary_spec = BoundarySpec.pml(x=False, y=True, z=True)
@@ -188,3 +191,26 @@ def test_boundaryspec_classmethods():
     assert all(
         isinstance(boundary, PML) for boundary_dim in boundaries for boundary in boundary_dim
     )
+
+
+@pytest.mark.parametrize("absorber_type", [PML, StablePML, Absorber])
+def test_num_layers_validator(absorber_type):
+    """Test the Field validators that enforce ``num_layers>0``."""
+    with pytest.raises(pydantic.ValidationError):
+        _ = absorber_type(num_layers=0)
+
+
+@pytest.mark.parametrize(
+    "absorber_type, num_layers",
+    [
+        (PML, MIN_NUM_PML_LAYERS),
+        (StablePML, MIN_NUM_STABLE_PML_LAYERS),
+        (Absorber, MIN_NUM_ABSORBER_LAYERS),
+    ],
+)
+def test_num_layers_validator_warning(absorber_type, num_layers):
+    """Test the validators in ``PML`` which should display a warning not an error."""
+    with AssertLogLevel(None):
+        _ = absorber_type(num_layers=num_layers)
+    with AssertLogLevel("WARNING"):
+        _ = absorber_type(num_layers=num_layers - 1)

tidy3d/components/boundary.py

@@ -18,6 +18,30 @@
 from .types import TYPE_TAG_STR, Axis, Complex
 
 MIN_NUM_PML_LAYERS = 6
+MIN_NUM_STABLE_PML_LAYERS = 6
+MIN_NUM_ABSORBER_LAYERS = 6
+
+
+def warn_num_layers_factory(min_num_layers: int, descr: str):
+    """Several similar classes defined have a ``num_layers`` data member, and they generate
+    similar warning messages when ``num_layers`` is too small.  This function creates a pydantic
+    validator which can be shared with all of these classes to create these warning messages."""
+
+    @pd.validator("num_layers", allow_reuse=True, always=True)
+    def _warn_num_layers(cls, val):
+        if val < min_num_layers:
+            cls_name = cls.__name__
+            log.warning(
+                f"A {descr} ({cls_name}) boundary was created with {val} layers. "
+                f"{cls_name}s with less than {min_num_layers} layers are highly subject to "
+                "unwanted numerical artifacts. We strongly recommend "
+                "increasing the number of layers. For more details refer to: "
+                f"'https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.{cls_name}.html'.",
+                log_once=True,
+            )
+        return val
+
+    return _warn_num_layers
 
 
 class BoundaryEdge(ABC, Tidy3dBaseModel):
@@ -267,7 +291,7 @@ class AbsorberSpec(BoundaryEdge):
         ...,
         title="Number of Layers",
         description="Number of layers of standard PML.",
-        ge=MIN_NUM_PML_LAYERS,
+        ge=1,
     )
     parameters: AbsorberParams = pd.Field(
         ...,
@@ -384,7 +408,7 @@ class PML(AbsorberSpec):
         12,
         title="Number of Layers",
         description="Number of layers of standard PML.",
-        ge=MIN_NUM_PML_LAYERS,
+        ge=1,
     )
 
     parameters: PMLParams = pd.Field(
@@ -393,6 +417,10 @@ class PML(AbsorberSpec):
         description="Parameters of the complex frequency-shifted absorption poles.",
     )
 
+    _warn_num_layers = warn_num_layers_factory(
+        min_num_layers=MIN_NUM_PML_LAYERS, descr="perfectly-matched layer"
+    )
+
 
 class StablePML(AbsorberSpec):
     """Specifies a 'stable' PML along a single dimension.
@@ -422,7 +450,7 @@ class StablePML(AbsorberSpec):
         40,
         title="Number of Layers",
         description="Number of layers of 'stable' PML.",
-        ge=MIN_NUM_PML_LAYERS,
+        ge=1,
     )
 
     parameters: PMLParams = pd.Field(
@@ -431,6 +459,10 @@ class StablePML(AbsorberSpec):
         description="'Stable' parameters of the complex frequency-shifted absorption poles.",
     )
 
+    _warn_num_layers = warn_num_layers_factory(
+        min_num_layers=MIN_NUM_STABLE_PML_LAYERS, descr="stable perfectly-matched layer"
+    )
+
 
 class Absorber(AbsorberSpec):
     """Specifies an adiabatic absorber along a single dimension.
@@ -475,7 +507,7 @@ class Absorber(AbsorberSpec):
         40,
         title="Number of Layers",
         description="Number of layers of absorber to add to + and - boundaries.",
-        ge=MIN_NUM_PML_LAYERS,
+        ge=1,
     )
 
     parameters: AbsorberParams = pd.Field(
@@ -484,6 +516,10 @@ class Absorber(AbsorberSpec):
         description="Adiabatic absorber parameters.",
     )
 
+    _warn_num_layers = warn_num_layers_factory(
+        min_num_layers=MIN_NUM_ABSORBER_LAYERS, descr="absorber"
+    )
+
 
 # pml types allowed in simulation init
 PMLTypes = Union[PML, StablePML, Absorber, None]