feat(source_time): broadband pulse

Author: weiliangjin2021

CHANGELOG.md

@@ -30,6 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `DirectivityMonitorSpec` for automated creation and configuration of directivity radiation monitors in `TerminalComponentModeler`.
 - Added multimode support to `WavePort` in the smatrix plugin, allowing multiple modes to be analyzed per port.
 - Added support for `.lydrc` files for design rule checking in the `klayout` plugin.
+- Introduced `BroadbandPulse` for exciting simulations across a wide frequency spectrum.
 
 ### Breaking Changes
 - Edge singularity correction at PEC and lossy metal edges defaults to `True`.

docs/api/sources.rst

@@ -34,6 +34,7 @@ Source Time Dependence
 
    tidy3d.GaussianPulse
    tidy3d.ContinuousWave
+   tidy3d.BroadbandPulse
    tidy3d.SourceTime
    tidy3d.CustomSourceTime
 

tidy3d/__init__.py

@@ -411,6 +411,7 @@
 
 # sources
 from .components.source.time import (
+    BroadbandPulse,
     ContinuousWave,
     CustomSourceTime,
     GaussianPulse,
@@ -516,6 +517,7 @@ def set_logging_level(level: str) -> None:
     "Box",
     "BroadbandModeABCFitterParam",
     "BroadbandModeABCSpec",
+    "BroadbandPulse",
     "CaugheyThomasMobility",
     "CellDataArray",
     "ChargeConductorMedium",

tidy3d/components/source/time.py

@@ -21,6 +21,7 @@
 from tidy3d.constants import HERTZ
 from tidy3d.exceptions import ValidationError
 from tidy3d.log import log
+from tidy3d.packaging import check_tidy3d_extras_licensed_feature, tidy3d_extras
 
 # how many units of ``twidth`` from the ``offset`` until a gaussian pulse is considered "off"
 END_TIME_FACTOR_GAUSSIAN = 10
@@ -605,4 +606,83 @@ def end_time(self) -> Optional[float]:
         return np.max(t_non_zero)
 
 
-SourceTimeType = Union[GaussianPulse, ContinuousWave, CustomSourceTime]
+class BroadbandPulse(SourceTime):
+    """A source time injecting significant energy in the entire custom frequency range."""
+
+    freq_range: FreqBound = pydantic.Field(
+        ...,
+        title="Frequency Range",
+        description="Frequency range where the pulse should have significant energy.",
+        units=HERTZ,
+    )
+    minimum_amplitude: float = pydantic.Field(
+        0.3,
+        title="Minimum Amplitude",
+        description="Minimum amplitude of the pulse relative to the peak amplitude in the frequency range.",
+        gt=0.05,
+        lt=0.5,
+    )
+    offset: float = pydantic.Field(
+        5.0,
+        title="Offset",
+        description="Time delay of the maximum value of the "
+        "pulse in units of 1 / (``2pi * fwidth``).",
+        ge=2.5,
+    )
+
+    @pydantic.validator("freq_range", always=True)
+    def _validate_freq_range(cls, val):
+        """Validate that freq_range is positive and properly ordered."""
+        if val[0] <= 0 or val[1] <= 0:
+            raise ValidationError("Both elements of 'freq_range' must be positive.")
+        if val[1] <= val[0]:
+            raise ValidationError(
+                f"'freq_range[1]' ({val[1]}) must be greater than 'freq_range[0]' ({val[0]})."
+            )
+        return val
+
+    @pydantic.root_validator()
+    def _check_broadband_pulse_available(cls, values):
+        """Check if BroadbandPulse is available."""
+        check_tidy3d_extras_licensed_feature("BroadbandPulse")
+        return values
+
+    @cached_property
+    def _source(self):
+        """Implementation of broadband pulse."""
+        return tidy3d_extras["mod"].extension.BroadbandPulse(
+            fmin=self.freq_range[0],
+            fmax=self.freq_range[1],
+            minRelAmp=self.minimum_amplitude,
+            amp=self.amplitude,
+            phase=self.phase,
+            offset=self.offset,
+        )
+
+    def end_time(self) -> float:
+        """Time after which the source is effectively turned off / close to zero amplitude."""
+        return self._source.end_time(END_TIME_FACTOR_GAUSSIAN)
+
+    def amp_time(self, time: float) -> complex:
+        """Complex-valued source amplitude as a function of time."""
+        return self._source.amp_time(time)
+
+    def amp_freq(self, freq: float) -> complex:
+        """Complex-valued source amplitude as a function of frequency."""
+        return self._source.amp_freq(freq)
+
+    def frequency_range_sigma(self, sigma: float = DEFAULT_SIGMA) -> FreqBound:
+        """Frequency range where the source amplitude is within ``exp(-sigma**2/2)`` of the peak amplitude."""
+        return self._source.frequency_range(sigma)
+
+    def frequency_range(self, num_fwidth: float = DEFAULT_SIGMA) -> FreqBound:
+        """Frequency range where the source amplitude is within ``exp(-sigma**2/2)`` of the peak amplitude."""
+        return self.frequency_range_sigma(num_fwidth)
+
+    @cached_property
+    def _freq0(self) -> float:
+        """Central frequency from frequency range."""
+        return np.mean(self.freq_range)
+
+
+SourceTimeType = Union[GaussianPulse, ContinuousWave, CustomSourceTime, BroadbandPulse]

tidy3d/packaging.py

@@ -183,6 +183,74 @@ def get_numpy_major_version(module=np):
     return major_version
 
 
+def _check_tidy3d_extras_available():
+    """Helper function to check if 'tidy3d-extras' is available and version matched.
+
+    Raises
+    ------
+    Tidy3dImportError
+        If tidy3d-extras is not available or not properly initialized.
+    """
+    if tidy3d_extras["mod"] is None:
+        try:
+            import tidy3d_extras as tidy3d_extras_mod
+
+        except ImportError as exc:
+            tidy3d_extras["mod"] = None
+            raise Tidy3dImportError(
+                "The package 'tidy3d-extras' is required for this "
+                "operation. Please install the 'tidy3d-extras' package using, for "
+                "example, 'pip install tidy3d[extras]'."
+            ) from exc
+
+        else:
+            version = tidy3d_extras_mod.__version__
+
+            if version is None:
+                tidy3d_extras["mod"] = None
+                raise Tidy3dImportError(
+                    "The package 'tidy3d-extras' did not initialize correctly, "
+                    "likely due to an invalid API key."
+                )
+
+            if version != __version__:
+                log.warning(
+                    "The package 'tidy3d-extras' is required for this "
+                    "operation. The version of 'tidy3d-extras' should match "
+                    "the version of 'tidy3d'. You can install the correct "
+                    "version using 'pip install tidy3d[extras]'."
+                )
+
+            tidy3d_extras["mod"] = tidy3d_extras_mod
+
+
+def check_tidy3d_extras_licensed_feature(feature_name: str):
+    """Helper function to check if a specific feature is licensed in 'tidy3d-extras'.
+
+    Parameters
+    ----------
+    feature_name : str
+        The name of the feature to check for.
+
+    Raises
+    ------
+    Tidy3dImportError
+        If the feature is not available with your license.
+    """
+
+    try:
+        _check_tidy3d_extras_available()
+    except Tidy3dImportError as exc:
+        raise Tidy3dImportError(f"Failed to load 'tidy3d-extras'. {exc!s}") from exc
+    else:
+        features = tidy3d_extras["mod"].extension._features()
+        if feature_name not in features:
+            raise Tidy3dImportError(
+                f"The feature '{feature_name}' is not available with your license. "
+                "Please contact Tidy3D support, or upgrade your license."
+            )
+
+
 def supports_local_subpixel(fn):
     """When decorating a method, checks that 'tidy3d-extras' is available,
     conditioned on 'config.use_local_subpixel'."""
@@ -193,47 +261,14 @@ def _fn(*args: Any, **kwargs: Any):
 
         if preference is False:
             tidy3d_extras["use_local_subpixel"] = False
-            tidy3d_extras["mod"] = None
         else:
-            # first try to import the module
-            if tidy3d_extras["mod"] is None:
-                try:
-                    import tidy3d_extras as tidy3d_extras_mod
-
-                except ImportError as exc:
-                    tidy3d_extras["mod"] = None
-                    tidy3d_extras["use_local_subpixel"] = False
-                    if preference is True:
-                        raise Tidy3dImportError(
-                            "The package 'tidy3d-extras' is required for this "
-                            "operation when 'config.use_local_subpixel' is 'True'. "
-                            "Please install the 'tidy3d-extras' package using, for "
-                            "example, 'pip install tidy3d[extras]'."
-                        ) from exc
-
-                else:
-                    version = tidy3d_extras_mod.__version__
-
-                    if version is None:
-                        tidy3d_extras["mod"] = None
-                        tidy3d_extras["use_local_subpixel"] = False
-                        raise Tidy3dImportError(
-                            "The package 'tidy3d-extras' did not initialize correctly, "
-                            "likely due to an invalid API key."
-                        )
-
-                    if version != __version__:
-                        log.warning(
-                            "The package 'tidy3d-extras' is required for this "
-                            "operation. The version of 'tidy3d-extras' should match "
-                            "the version of 'tidy3d'. You can install the correct "
-                            "version using 'pip install tidy3d[extras]'."
-                        )
-
-                    features = tidy3d_extras_mod.extension._features()
-
-                    tidy3d_extras["mod"] = tidy3d_extras_mod
-                    tidy3d_extras["use_local_subpixel"] = "local_subpixel" in features
+            try:
+                _check_tidy3d_extras_available()
+            except Tidy3dImportError as exc:
+                tidy3d_extras["use_local_subpixel"] = False
+                raise Tidy3dImportError(
+                    f"Failed to load 'tidy3d-extras' for local subpixel support. {exc!s}"
+                ) from exc
             else:
                 features = tidy3d_extras["mod"].extension._features()
                 tidy3d_extras["use_local_subpixel"] = "local_subpixel" in features