Better validation of TFSF sources, and enabling broadband

Author: momchil-flex

CHANGELOG.md

@@ -13,12 +13,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - A property `interior_angle` in `PolySlab` that stores angles formed inside polygon by two adjacent edges.
 - `eps_component` argument in `td.Simulation.plot_eps()` to optionally select a specific permittivity component to plot (eg. `"xx"`).
 - Monitor `AuxFieldTimeMonitor` for aux fields like the free carrier density in `TwoPhotonAbsorption`.
+- Broadband handling (`num_freqs` argument) to the TFSF source.
 
 ### Fixed
 - Compatibility with `xarray>=2025.03`.
 - Inaccurate gradient when auto-grabbing permittivities for structures using `td.PolySlab` when using dispersive material models.
 - Fixed scaling for adjoint sources when differentiating with respect to `FieldData` to account for the mesh size of the monitor and thus the created source. This aligns adjoint gradient magnitudes with numerical finite difference gradients for field data.
 - Warn when mode solver pml covers a significant portion of the mode plane.
+- TFSF server errors related to the auxiliary plane wave source that would previously happen on the server are now caught upon simulation creation.
+
+### Changed
+- `num_freqs` in Gaussian beam type sources limited to 20, which should besufficient for all cases.
 
 ## [2.8.1] - 2025-03-20
 

tests/test_components/test_simulation.py

@@ -1887,6 +1887,30 @@ def test_tfsf_symmetry():
         )
 
 
+def test_tfsf_aux_source_outside_domain():
+    """Test that a TFSF source cannot be too close to the simulation domain boundaries
+    along the injection direction."""
+    src_time = td.GaussianPulse(freq0=1e12, fwidth=0.1e12)
+
+    source = td.TFSF(
+        size=[1, 1, 1],
+        source_time=src_time,
+        pol_angle=0,
+        angle_theta=np.pi / 4,
+        angle_phi=np.pi / 6,
+        direction="+",
+        injection_axis=2,
+    )
+
+    with pytest.raises(SetupError):
+        _ = td.Simulation(
+            size=(2.0, 2.0, 1.01),
+            grid_spec=td.GridSpec.auto(wavelength=td.C_0 / 1.0),
+            run_time=1e-12,
+            sources=[source],
+        )
+
+
 def test_tfsf_boundaries():
     """Test that a TFSF source is allowed to cross boundaries only in particular cases."""
     src_time = td.GaussianPulse(freq0=td.C_0, fwidth=0.1e12)

tests/test_package/test_log.py

@@ -148,7 +148,6 @@ def test_logging_warning_capture():
         medium=td.Medium(permittivity=6),
     )
 
-    # 1 warning: too high "num_freqs"
     # 1 warning: glancing angle
     gaussian_beam = td.GaussianBeam(
         center=(4, 0, 0),
@@ -157,7 +156,6 @@ def test_logging_warning_capture():
         waist_distance=1,
         source_time=source_time,
         direction="+",
-        num_freqs=30,
         angle_theta=np.pi / 2.1,
     )
 
@@ -217,7 +215,7 @@ def test_logging_warning_capture():
     sim.validate_pre_upload()
     warning_list = td.log.captured_warnings()
     print(json.dumps(warning_list, indent=4))
-    assert len(warning_list) == 31
+    assert len(warning_list) == 30
     td.log.set_capture(False)
 
     # check that capture doesn't change validation errors

tidy3d/components/simulation.py

@@ -2657,7 +2657,7 @@ def bloch_boundaries_diff_mnt(cls, val, values):
     @pydantic.validator("boundary_spec", always=True)
     @skip_if_fields_missing(["medium", "center", "size", "structures", "sources"])
     def tfsf_boundaries(cls, val, values):
-        """Error if the boundary conditions are compatible with TFSF sources, if any."""
+        """Error if the boundary conditions are incompatible with TFSF sources, if any."""
         boundaries = val.to_list
         sources = values.get("sources")
         size = values.get("size")
@@ -3572,6 +3572,7 @@ def _post_init_validators(self) -> None:
         _ = self.scene
         self._validate_no_structures_pml()
         self._validate_tfsf_nonuniform_grid()
+        self._validate_tfsf_aux_sources()
         self._validate_nonlinear_specs()
         self._validate_custom_source_time()
         self._validate_mode_object_bends()
@@ -3707,6 +3708,54 @@ def _validate_tfsf_nonuniform_grid(self) -> None:
                             custom_loc=["sources", source_ind],
                         )
 
+    def _aux_tfsf_source(self, source: TFSF) -> PlaneWave:
+        """Create the auxiliary plane wave source for a give TFSF source."""
+        # center and size of the plane wave source
+        source_size = [inf] * 3
+        source_size[source.injection_axis] = 0
+        source_center = list(source.injection_plane_center)
+
+        # since we need to access values of the aux self at dual grid locations below the actual
+        # injection plane, we need to place the aux sim's source at least one full cell below the
+        # location of the injection plane; for good measure, we'll offset the source by two cells
+        src_grid = self.discretize(source, extend=False)
+        src_grid_sizes = src_grid.sizes.to_list
+        if source.direction == "+":
+            offset = -sum(src_grid_sizes[source.injection_axis][0:2])
+        else:
+            offset = sum(src_grid_sizes[source.injection_axis][-1:-3:-1])
+        source_center[source.injection_axis] += offset
+
+        # Make sure that the new source center is within the simulation bounds
+        sim_axis_bounds = [self.bounds[i][source.injection_axis] for i in range(2)]
+        if (
+            source_center[source.injection_axis] < sim_axis_bounds[0]
+            or source_center[source.injection_axis] > sim_axis_bounds[1]
+        ):
+            raise SetupError(
+                "The TFSF source is too close to the simulation domain boundary along the "
+                "injection axis. Slightly increase the simulation domain size along that "
+                "dimension, or decrease the source size."
+            )
+
+        # Note: broadband injection for TFSF not currently supported
+        return PlaneWave(
+            size=source_size,
+            center=source_center,
+            source_time=source.source_time,
+            angle_theta=source.angle_theta,
+            angle_phi=source.angle_phi,
+            pol_angle=source.pol_angle,
+            direction=source.direction,
+            num_freqs=source.num_freqs,
+        )
+
+    def _validate_tfsf_aux_sources(self):
+        """Validate that PlaneWave sources auxiliary to TFSF sources can be successfully created."""
+        for source in self.sources:
+            if isinstance(source, TFSF):
+                _ = self._aux_tfsf_source(source)
+
     def _validate_nonlinear_specs(self) -> None:
         """Run :class:`.NonlinearSpec` validators that depend on knowing the central
         frequencies of the sources. Also print some warnings only once per unique medium."""

tidy3d/components/source/field.py

@@ -95,14 +95,16 @@ def _dir_vector(self) -> Tuple[float, float, float]:
 class BroadbandSource(Source, ABC):
     """A source with frequency dependent field distributions."""
 
+    # Default as for analytic beam sources; overwrriten for ModeSource below
     num_freqs: int = pydantic.Field(
-        1,
+        3,
         title="Number of Frequency Points",
-        description="Number of points used to approximate the frequency dependence of injected "
-        "field. A Chebyshev interpolation is used, thus, only a small number of points, i.e., less "
-        "than 20, is typically sufficient to obtain converged results.",
+        description="Number of points used to approximate the frequency dependence of the injected "
+        "field. Default is 3, which should cover even very broadband sources. For simulations "
+        "which are not very broadband and the source is very large (e.g. metalens simulations), "
+        "decreasing the value to 1 may lead to a speed up in the preprocessing.",
         ge=1,
-        le=99,
+        le=20,
     )
 
     @cached_property
@@ -425,6 +427,16 @@ class ModeSource(DirectionalSource, PlanarSource, BroadbandSource):
         "``num_modes`` in the solver will be set to ``mode_index + 1``.",
     )
 
+    num_freqs: int = pydantic.Field(
+        1,
+        title="Number of Frequency Points",
+        description="Number of points used to approximate the frequency dependence of injected "
+        "field. A Chebyshev interpolation is used, thus, only a small number of points, i.e., less "
+        "than 20, is typically sufficient to obtain converged results.",
+        ge=1,
+        le=99,
+    )
+
     @cached_property
     def angle_theta(self):
         """Polar angle of propagation."""
@@ -500,17 +512,6 @@ class PlaneWave(AngledFieldSource, PlanarSource, BroadbandSource):
         discriminator=TYPE_TAG_STR,
     )
 
-    num_freqs: int = pydantic.Field(
-        3,
-        title="Number of Frequency Points",
-        description="Number of points used to approximate the frequency dependence of the injected "
-        "field. Default is 3, which should cover even very broadband sources. For simulations "
-        "which are not very broadband and the source is very large (e.g. metalens simulations), "
-        "decreasing the value to 1 may lead to a speed up in the preprocessing.",
-        ge=1,
-        le=10,
-    )
-
     @cached_property
     def _is_fixed_angle(self) -> bool:
         """Whether the plane wave is at a fixed non-zero angle."""
@@ -590,16 +591,6 @@ class GaussianBeam(AngledFieldSource, PlanarSource, BroadbandSource):
         units=MICROMETER,
     )
 
-    num_freqs: int = pydantic.Field(
-        3,
-        title="Number of Frequency Points",
-        description="Number of points used to approximate the frequency dependence of injected "
-        "field. A Chebyshev interpolation is used, thus, only a small number of points, i.e., less "
-        "than 20, is typically sufficient to obtain converged results.",
-        ge=1,
-        le=99,
-    )
-
 
 class AstigmaticGaussianBeam(AngledFieldSource, PlanarSource, BroadbandSource):
     """The simple astigmatic Gaussian distribution allows
@@ -648,18 +639,8 @@ class AstigmaticGaussianBeam(AngledFieldSource, PlanarSource, BroadbandSource):
         units=MICROMETER,
     )
 
-    num_freqs: int = pydantic.Field(
-        3,
-        title="Number of Frequency Points",
-        description="Number of points used to approximate the frequency dependence of injected "
-        "field. A Chebyshev interpolation is used, thus, only a small number of points, i.e., less "
-        "than 20, is typically sufficient to obtain converged results.",
-        ge=1,
-        le=99,
-    )
-
 
-class TFSF(AngledFieldSource, VolumeSource):
+class TFSF(AngledFieldSource, VolumeSource, BroadbandSource):
     """Total-field scattered-field (TFSF) source that can inject a plane wave in a finite region.
 
     Notes