enhance custom validator error messages with object name fields (when specified)

Author: jewettaijfc

CHANGELOG.md

@@ -22,6 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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.
+- Warnings and error messages originating from `Structure`, `Source`, or `Monitor` classes now refer to problematic objects by their user-supplied `name` attribute, alongside their index.
 
 ### 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_simulation.py

@@ -3648,3 +3648,45 @@ def test_create_sim_multiphysics_with_incompatibilities():
                 ),
             ],
         )
+
+
+def test_messages_contain_object_names():
+    """Make sure that errors and warnings contain the name of the object."""
+    # Note: This function currently tests for out-of-bounds errors and warnings.
+    # Create an empty simulation.
+    sim = td.Simulation(
+        size=(1, 1, 1),
+        grid_spec=td.GridSpec.auto(wavelength=4),
+        run_time=1e-12,
+    )
+
+    # Test 1) Create a structure lying outside the simulation boundary.
+    # Check that a warning message is generated containing the structure's `name`.
+    name = "structure_123"
+    structure = td.Structure(
+        name=name,
+        geometry=td.Box(center=(1.0, 0.0, 0.0), size=(0.5, 0.5, 0.5)),
+        medium=td.Medium(permittivity=2.0),
+    )
+    with AssertLogLevel("WARNING", contains_str=name):
+        _ = sim.updated_copy(structures=[structure])
+
+    # Test 2) Create a source lying outside the simulation boundary.
+    # Check that an error message is generated containing the source's `name`.
+    name = "source_123"
+    source = td.UniformCurrentSource(
+        name=name,
+        center=(0, -1.0, 0),
+        size=(1, 0, 0.5),
+        polarization="Ex",
+        source_time=td.GaussianPulse(freq0=100e14, fwidth=10e14),
+    )
+    with pytest.raises(pydantic.ValidationError, match=name) as e:
+        _ = sim.updated_copy(sources=[source])
+
+    # Test 3) Create a monitor lying outside the simulation boundary.
+    # Check that an error message is generated containing the monitor's `name`.
+    name = "monitor_123"
+    monitor = td.FieldMonitor(name=name, center=(-1.0, 0, 0), size=(0.5, 0, 1), freqs=[100e14])
+    with pytest.raises(pydantic.ValidationError, match=name) as e:
+        _ = sim.updated_copy(monitors=[monitor])

tidy3d/components/simulation.py

@@ -117,6 +117,7 @@
 from .validators import (
     assert_objects_contained_in_sim_bounds,
     assert_objects_in_sim_bounds,
+    named_obj_descr,
     validate_mode_objects_symmetry,
 )
 from .viz import (
@@ -2961,8 +2962,9 @@ def _validate_2d_geometry_has_2d_medium(cls, val, values):
                 for geom in flatten_groups(structure.geometry):
                     zero_dims = geom.zero_dims
                     if len(zero_dims) > 0:
+                        obj_descr = named_obj_descr(structure, "structures", i)
                         consolidated_logger.warning(
-                            f"Structure at 'structures[{i}]' has geometry with zero size along "
+                            f"Structure: {obj_descr} has geometry with zero size along "
                             f"dimensions {zero_dims}, and with a medium that is not a 'Medium2D'. "
                             "This is probably not correct, since the resulting simulation will "
                             "depend on the details of the numerical grid. Consider either "
@@ -3018,10 +3020,11 @@ def _structures_not_close_pml(cls, val, values):
 
         with log as consolidated_logger:
 
-            def warn(istruct, side):
+            def warn(structure, istruct, side):
                 """Warning message for a structure too close to PML."""
+                obj_descr = named_obj_descr(structure, "structures", istruct)
                 consolidated_logger.warning(
-                    f"Structure at structures[{istruct}] was detected as being less "
+                    f"Structure: {obj_descr} was detected as being less "
                     f"than half of a central wavelength from a PML on side {side}. "
                     "To avoid inaccurate results or divergence, please increase gap between "
                     "any structures and PML or fully extend structure through the pml.",
@@ -3044,7 +3047,7 @@ def warn(istruct, side):
                             and struct_val > sim_val
                             and abs(sim_val - struct_val) < lambda0 / 2
                         ):
-                            warn(istruct, axis + "-min")
+                            warn(structure, istruct, axis + "-min")
 
                     zipped = zip(["x", "y", "z"], sim_bound_max, struct_bound_max, boundaries)
                     for axis, sim_val, struct_val, boundary in zipped:
@@ -3056,7 +3059,7 @@ def warn(istruct, side):
                             and struct_val < sim_val
                             and abs(sim_val - struct_val) < lambda0 / 2
                         ):
-                            warn(istruct, axis + "-max")
+                            warn(structure, istruct, axis + "-max")
 
         return val
 
@@ -3095,20 +3098,20 @@ def _warn_monitor_mediums_frequency_range(cls, val, values):
                             medium_str = "The simulation background medium"
                             custom_loc = ["medium", "frequency_range"]
                         else:
-                            medium_str = (
-                                f"The medium associated with structures[{medium_index - 1}]"
-                            )
+                            medium_descr = named_obj_descr(medium, "mediums", medium_index)
+                            medium_str = f"The medium associated with {medium_descr}"
                             custom_loc = [
                                 "structures",
                                 medium_index - 1,
                                 "medium",
                                 "frequency_range",
                             ]
 
+                        monitor_descr = named_obj_descr(monitor, "monitors", monitor_index)
                         consolidated_logger.warning(
                             f"{medium_str} has a frequency range: ({sci_fmin_med}, {sci_fmax_med}) "
-                            "(Hz) that does not fully cover the frequencies contained in "
-                            f"monitors[{monitor_index}]. "
+                            "(Hz) that does not fully cover the frequencies contained "
+                            f"in {monitor_descr}."
                             "This can cause inaccuracies in the recorded results.",
                             custom_loc=custom_loc,
                         )
@@ -3806,8 +3809,9 @@ def _validate_custom_source_time(self):
                     data_times = source.source_time.data_times
                     mint = np.min(data_times)
                     maxt = np.max(data_times)
+                    obj_descr = named_obj_descr(source, "sources", idx)
                     log.warning(
-                        f"'CustomSourceTime' at 'sources[{idx}]' is defined over a time range "
+                        f"'CustomSourceTime': {obj_descr} is defined over a time range "
                         f"'({mint}, {maxt})' which does not include any of the 'Simulation' "
                         f"times '({0, run_time})'. The envelope will be constant extrapolated "
                         "from the first or last value in the 'CustomSourceTime', which may not "
@@ -3837,8 +3841,9 @@ def _validate_no_structures_pml(self) -> None:
                         if not isinstance(bound_edge, Absorber) and (in_pml_plus or in_pml_mnus):
                             warn = True
                 if warn:
+                    obj_descr = named_obj_descr(structure, "structures", i)
                     consolidated_logger.warning(
-                        f"A bound of Simulation.structures[{i}] was detected as being "
+                        f"A bound of {obj_descr} was detected as being "
                         "within the simulation PML. We recommend extending structures to "
                         "infinity or completely outside of the simulation PML to avoid "
                         "unexpected effects when the structures are not translationally "
@@ -3956,8 +3961,9 @@ def _validate_nonlinear_specs(self) -> None:
             if isinstance(monitor, AuxFieldTimeMonitor):
                 for aux_field in monitor.fields:
                     if aux_field not in self.aux_fields:
+                        obj_descr = named_obj_descr(monitor, "monitors", i)
                         log.warning(
-                            f"Monitor at 'monitors[{i}]' stores field '{aux_field}', "
+                            f"Monitor: {obj_descr} stores field '{aux_field}', "
                             "which is not used by any of the nonlinear models present "
                             "in the mediums in the simulation. The resulting data "
                             "will be zero."

tidy3d/components/validators.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Optional
+from typing import Any, Optional
 
 import numpy as np
 import pydantic.v1 as pydantic
@@ -52,6 +52,14 @@
 MIN_FREQUENCY = 1e5
 
 
+def named_obj_descr(obj: Any, field_name: str, position_index: int) -> str:
+    """Generate a string describing a named object which can be used in error messages."""
+    descr = f"simulation.{field_name}[{position_index}] (no `name` was specified)"
+    if hasattr(obj, "name") and obj.name:
+        descr = f"'{obj.name}' (simulation.{field_name}[{position_index}])"
+    return descr
+
+
 def assert_line():
     """makes sure a field's ``size`` attribute has exactly 2 zeros"""
 
@@ -156,10 +164,10 @@ def check_symmetry(cls, val, values):
                         and bounds_min[dim] < sim_center[dim]
                         and geometric_object.center[dim] != sim_center[dim]
                     ):
+                        obj_descr = named_obj_descr(geometric_object, field_name, position_index)
                         raise SetupError(
-                            f"{obj_type} at 'simulation.{field_name}[{position_index}]' "
-                            "in presence of symmetries must be in the main quadrant, "
-                            "or centered on the symmetry axis."
+                            f"{obj_type}: {obj_descr} in presence of symmetries must be in the main "
+                            "quadrant, or centered on the symmetry axis."
                         )
 
         return val
@@ -201,12 +209,9 @@ def objects_in_sim_bounds(cls, val, values):
         with log as consolidated_logger:
             for position_index, geometric_object in enumerate(val):
                 if not sim_box.intersects(geometric_object.geometry, strict_inequality=strict_ineq):
-                    message = (
-                        f"'simulation.{field_name}[{position_index}]' "
-                        "is outside of the simulation domain."
-                    )
+                    obj_descr = named_obj_descr(geometric_object, field_name, position_index)
+                    message = f"{obj_descr} is outside of the simulation domain."
                     custom_loc = [field_name, position_index]
-
                     if error:
                         raise SetupError(message)
                     consolidated_logger.warning(message, custom_loc=custom_loc)
@@ -245,12 +250,9 @@ def objects_contained_in_sim_bounds(cls, val, values):
                 if not sim_box.contains(
                     geometric_object.geometry, strict_inequality=geo_strict_ineq
                 ):
-                    message = (
-                        f"'simulation.{field_name}[{position_index}]' "
-                        "is not completely inside the simulation domain."
-                    )
+                    obj_descr = named_obj_descr(geometric_object, field_name, position_index)
+                    message = f"{obj_descr} is not completely inside the simulation domain."
                     custom_loc = [field_name, position_index]
-
                     if error:
                         raise SetupError(message)
                     consolidated_logger.warning(message, custom_loc=custom_loc)