feat: warning for upcoming change in waist_distance convention with direction='-'

Author: momchil-flex

tests/test_components/test_beam.py

@@ -13,6 +13,8 @@
 )
 from tidy3d.components.data.monitor_data import FieldData
 
+from ..utils import AssertLogLevel
+
 FREQS = np.linspace(1e14, 2e14, 10).tolist()
 
 
@@ -90,6 +92,63 @@ def test_astigmatic_gaussian_beam():
     assert field_data.flux == -field_data_bwd.flux
 
 
+def test_gaussian_beam_profile_backward_waist_distance_warning():
+    center = (0, 0, 0)
+    size = (10, 10, 0)
+    resolution = 100
+
+    with AssertLogLevel(
+        "WARNING",
+        contains_str="GaussianBeamProfile with direction '-' and non-zero 'waist_distance'",
+    ):
+        GaussianBeamProfile(
+            center=center,
+            size=size,
+            resolution=resolution,
+            freqs=FREQS,
+            direction="-",
+            waist_distance=1.0,
+        )
+
+    with AssertLogLevel(None):
+        GaussianBeamProfile(
+            center=center,
+            size=size,
+            resolution=resolution,
+            freqs=FREQS,
+            direction="-",
+            waist_distance=0.0,
+        )
+
+
+def test_astigmatic_gaussian_beam_profile_backward_waist_distance_warning():
+    center = (0, 0, 0)
+    size = (0, 20, 20)
+
+    with AssertLogLevel(
+        "WARNING",
+        contains_str="AstigmaticGaussianBeamProfile with direction '-' and non-zero 'waist_distances'",
+    ):
+        AstigmaticGaussianBeamProfile(
+            center=center,
+            size=size,
+            freqs=FREQS,
+            direction="-",
+            waist_sizes=(4.0, 2.0),
+            waist_distances=(1.0, 0.0),
+        )
+
+    with AssertLogLevel(None):
+        AstigmaticGaussianBeamProfile(
+            center=center,
+            size=size,
+            freqs=FREQS,
+            direction="-",
+            waist_sizes=(4.0, 2.0),
+            waist_distances=(0.0, 0.0),
+        )
+
+
 def test_invalid_beam_size():
     """
     Test that a beam with three nonzero size values raises a validation error.

tests/test_components/test_source.py

@@ -338,6 +338,58 @@ def test_FieldSource():
     # plt.close()
 
 
+def test_gaussian_beam_backward_waist_distance_warning():
+    g = td.GaussianPulse(freq0=1e12, fwidth=0.1e12)
+
+    with AssertLogLevel(
+        "WARNING",
+        contains_str="GaussianBeam with direction '-' and non-zero 'waist_distance'",
+    ):
+        td.GaussianBeam(
+            size=(0, 1, 1),
+            source_time=g,
+            pol_angle=np.pi / 2,
+            direction="-",
+            waist_distance=1.0,
+        )
+
+    with AssertLogLevel(None):
+        td.GaussianBeam(
+            size=(0, 1, 1),
+            source_time=g,
+            pol_angle=np.pi / 2,
+            direction="-",
+            waist_distance=0.0,
+        )
+
+
+def test_astigmatic_gaussian_beam_backward_waist_distance_warning():
+    g = td.GaussianPulse(freq0=1e12, fwidth=0.1e12)
+
+    with AssertLogLevel(
+        "WARNING",
+        contains_str="AstigmaticGaussianBeam with direction '-' and non-zero 'waist_distances'",
+    ):
+        td.AstigmaticGaussianBeam(
+            size=(0, 1, 1),
+            source_time=g,
+            pol_angle=np.pi / 2,
+            direction="-",
+            waist_sizes=(0.2, 0.4),
+            waist_distances=(0.1, 0.0),
+        )
+
+    with AssertLogLevel(None):
+        td.AstigmaticGaussianBeam(
+            size=(0, 1, 1),
+            source_time=g,
+            pol_angle=np.pi / 2,
+            direction="-",
+            waist_sizes=(0.2, 0.4),
+            waist_distances=(0.0, 0.0),
+        )
+
+
 def test_pol_arrow():
     g = td.GaussianPulse(freq0=1e12, fwidth=0.1e12)
 

tidy3d/components/beam.py

@@ -20,7 +20,7 @@
 from .monitor import FieldMonitor
 from .source.field import FixedAngleSpec, FixedInPlaneKSpec
 from .types import TYPE_TAG_STR, Direction, FreqArray, Numpy
-from .validators import assert_plane
+from .validators import assert_plane, warn_backward_waist_distance
 
 DEFAULT_RESOLUTION = 200
 
@@ -374,6 +374,7 @@ class GaussianBeamProfile(BeamProfile):
         "For an angled beam, the distance is defined along the rotated propagation direction.",
         units=MICROMETER,
     )
+    _backward_waist_warning = warn_backward_waist_distance("waist_distance")
 
     def beam_params(self, z: Numpy, k0: Numpy) -> tuple[Numpy, Numpy, Numpy]:
         """Compute the parameters needed to evaluate a Gaussian beam at z.
@@ -440,6 +441,7 @@ class AstigmaticGaussianBeamProfile(BeamProfile):
         "the beam plane.",
         units=MICROMETER,
     )
+    _backward_waist_warning = warn_backward_waist_distance("waist_distances")
 
     def beam_params(self, z: Numpy, k0: Numpy) -> tuple[Numpy, Numpy, Numpy, Numpy]:
         """Compute the parameters needed to evaluate an astigmatic Gaussian beam at z.

tidy3d/components/source/field.py

@@ -19,6 +19,7 @@
     assert_plane,
     assert_single_freq_in_range,
     assert_volumetric,
+    warn_backward_waist_distance,
     warn_if_dataset_none,
 )
 from tidy3d.constants import GLANCING_CUTOFF, MICROMETER, RADIAN, inf
@@ -602,6 +603,7 @@ class GaussianBeam(AngledFieldSource, PlanarSource, BroadbandSource):
         ge=1,
         le=20,
     )
+    _backward_waist_warning = warn_backward_waist_distance("waist_distance")
 
 
 class AstigmaticGaussianBeam(AngledFieldSource, PlanarSource, BroadbandSource):
@@ -662,6 +664,7 @@ class AstigmaticGaussianBeam(AngledFieldSource, PlanarSource, BroadbandSource):
         ge=1,
         le=20,
     )
+    _backward_waist_warning = warn_backward_waist_distance("waist_distances")
 
 
 class TFSF(AngledFieldSource, VolumeSource, BroadbandSource):

tidy3d/components/validators.py

@@ -306,6 +306,31 @@ def _warn_if_none(cls, val: Dataset) -> Dataset:
     return _warn_if_none
 
 
+def warn_backward_waist_distance(field_name: str):
+    """Warn if a backward-propagating beam uses a non-zero waist distance."""
+
+    @pydantic.root_validator(allow_reuse=True)
+    def _warn_backward_nonzero(cls, values):
+        """Emit deprecation warning for backward propagation with non-zero waist."""
+        direction = values.get("direction")
+        if direction != "-":
+            return values
+        waist_value = values.get(field_name)
+        waist_array = np.atleast_1d(waist_value)
+        if not np.all(np.isclose(waist_array, 0.0)):
+            log.warning(
+                f"Behavior of {cls.__name__} with direction '-' and non-zero '{field_name}' will "
+                "change in version 2.11 to be consistent with upcoming beam overlap monitors and "
+                "ports. Currently, the waist distance is interpreted w.r.t. the directed "
+                "propagation axis, so switching 'direction' also switches the position of the "
+                "waist in the global reference frame. In the future, the waist position will be "
+                "defined such that it is the same for backward- and forward-propagating beams.",
+            )
+        return values
+
+    return _warn_backward_nonzero
+
+
 def assert_single_freq_in_range(field_name: str):
     """Assert only one frequency supplied in source and it's in source time range."""