prevent very small bandwidth sources from being used in TerminalComponentModeler

Author: Gregory Roberts

CHANGELOG.md

@@ -34,6 +34,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Adaptive minimum spacing for `PolySlab` integration is now wavelength relative and a minimum discretization is set for computing gradients for cylinders.
 - The `TerminalComponentModeler` defaults to the pseudo wave definition of scattering parameters. The new field `s_param_def` can be used to switch between either pseudo or power wave definitions.
 - Restructured the smatrix plugin with backwards-incompatible changes for a more robust architecture. Notably, `ComponentModeler` has been renamed to `ModalComponentModeler` and internal web API methods have been removed. Please see our migration guide for details on updating your workflows.
+- Prevent small bandwidth sources from being created in `TerminalComponentModeler` when modeler frequencies are close together.
 
 ### Fixed
 - Fixed missing amplitude factor and handling of negative normal direction case when making adjoint sources from `DiffractionMonitor`.

tests/test_components/test_source.py

@@ -15,6 +15,7 @@
 
 ST = td.GaussianPulse(freq0=2e14, fwidth=1e14)
 S = td.PointDipole(source_time=ST, polarization="Ex")
+FWIDTH_FRAC = 0.1
 
 
 ATOL = 1e-8
@@ -106,6 +107,18 @@ def test_gaussian_from_frequency_range():
     # error with fmin >= fmax
     with pytest.raises(ValueError):
         _ = td.GaussianPulse.from_frequency_range(fmin=1e10, fmax=0.9e10)
+    # error with minimum_source_bandwidth negative or 0
+    with pytest.raises(ValueError):
+        _ = td.GaussianPulse.from_frequency_range(
+            fmin=9e10, fmax=11e10, minimum_source_bandwidth=0.0
+        )
+        _ = td.GaussianPulse.from_frequency_range(
+            fmin=9e10, fmax=11e10, minimum_source_bandwidth=-1.0
+        )
+        # error with minimum_source_bandwidth greater than 1
+        _ = td.GaussianPulse.from_frequency_range(
+            fmin=9e10, fmax=11e10, minimum_source_bandwidth=1.0
+        )
 
     fmin = 1e9
     fmax = 20e9
@@ -137,6 +150,41 @@ def test_gaussian_from_frequency_range():
     assert abs(g.freq0 - fmin) / fmin < 1e-4
 
 
+def test_frequency_source_width():
+    """Ensure the source bandwidth has a lower bound regardless of the input frequencies."""
+
+    middle_freq = 1e10
+    fmin_large_bw = middle_freq * (1 - 2 * FWIDTH_FRAC)
+    fmax_large_bw = middle_freq * (1 + 2 * FWIDTH_FRAC)
+    fmin, fmax = td.GaussianPulse._minimum_source_bandwidth(
+        fmin=fmin_large_bw, fmax=fmax_large_bw, minimum_source_bandwidth=FWIDTH_FRAC
+    )
+
+    assert np.isclose(fmin, fmin_large_bw), (
+        "Expected no change in bandwidth (fmin unexpectedly changed)."
+    )
+
+    assert np.isclose(fmax, fmax_large_bw), (
+        "Expected no change in bandwidth (fmax unexpectedly changed)."
+    )
+
+    fmin_small_bw = middle_freq * (1 - 0.1 * FWIDTH_FRAC)
+    fmax_small_bw = middle_freq * (1 + 0.1 * FWIDTH_FRAC)
+    fmin, fmax = td.GaussianPulse._minimum_source_bandwidth(
+        fmin=fmin_small_bw, fmax=fmax_small_bw, minimum_source_bandwidth=FWIDTH_FRAC
+    )
+    fmin_expected = middle_freq * (1 - 0.5 * FWIDTH_FRAC)
+    fmax_expected = middle_freq * (1 + 0.5 * FWIDTH_FRAC)
+
+    assert np.isclose(fmin, fmin_expected), (
+        "Expected increase in bandwidth (fmin unexpected value)."
+    )
+
+    assert np.isclose(fmax, fmax_expected), (
+        "Expected increase in bandwidth (fmax unexpected value)."
+    )
+
+
 def test_dipole():
     g = td.GaussianPulse(freq0=1e12, fwidth=0.1e12)
     _ = td.PointDipole(center=(1, 2, 3), source_time=g, polarization="Ex", interpolate=True)

tidy3d/components/source/time.py

@@ -185,9 +185,34 @@ def from_amp_complex(cls, amp: complex, **kwargs) -> GaussianPulse:
         phase = np.angle(amp)
         return cls(amplitude=amplitude, phase=phase, **kwargs)
 
+    @staticmethod
+    def _minimum_source_bandwidth(
+        fmin: float, fmax: float, minimum_source_bandwidth: float
+    ) -> tuple[float, float]:
+        """Define a source bandwidth based on fmin and fmax, but enforce a minimum bandwidth."""
+        if minimum_source_bandwidth <= 0:
+            raise ValidationError("'minimum_source_bandwidth' must be positive")
+        if minimum_source_bandwidth >= 1:
+            raise ValidationError("'minimum_source_bandwidth' must less than or equal to 1")
+
+        f_difference = fmax - fmin
+        f_middle = 0.5 * (fmin + fmax)
+
+        full_width = minimum_source_bandwidth * f_middle
+        if f_difference < full_width:
+            half_width = 0.5 * full_width
+            fmin = f_middle - half_width
+            fmax = f_middle + half_width
+
+        return fmin, fmax
+
     @classmethod
     def from_frequency_range(
-        cls, fmin: pydantic.PositiveFloat, fmax: pydantic.PositiveFloat, **kwargs
+        cls,
+        fmin: pydantic.PositiveFloat,
+        fmax: pydantic.PositiveFloat,
+        minimum_source_bandwidth: pydantic.PositiveFloat = None,
+        **kwargs,
     ) -> GaussianPulse:
         """Create a ``GaussianPulse`` that maximizes its amplitude in the frequency range [fmin, fmax].
 
@@ -211,6 +236,9 @@ def from_frequency_range(
         if fmax <= fmin:
             raise ValidationError("'fmax' must be greater than 'fmin'.")
 
+        if minimum_source_bandwidth is not None:
+            fmin, fmax = cls._minimum_source_bandwidth(fmin, fmax, minimum_source_bandwidth)
+
         # frequency range and center
         freq_range = fmax - fmin
         freq_center = (fmax + fmin) / 2.0

tidy3d/plugins/smatrix/component_modelers/terminal.py

@@ -342,8 +342,14 @@ def _source_time(self):
         if len(self.freqs) == 1:
             freq0 = self.freqs[0]
             return GaussianPulse(freq0=self.freqs[0], fwidth=freq0 * FWIDTH_FRAC)
+
+        # Using the minimum_source_bandwidth, ensure we don't create a pulse that is too narrowband
+        # when fmin and fmax are close together
         return GaussianPulse.from_frequency_range(
-            fmin=min(self.freqs), fmax=max(self.freqs), remove_dc_component=self.remove_dc_component
+            fmin=np.min(self.freqs),
+            fmax=np.max(self.freqs),
+            remove_dc_component=self.remove_dc_component,
+            minimum_source_bandwidth=FWIDTH_FRAC,
         )
 
     @pd.validator("simulation")