Enhance Custom Validator Error Messages with Object Names

[jewettaijfc]

This PR is an attempt to address issue #2614 .

This PR changes the warnings error messages printed to the user for Monitor, Source, and Structure. If the user specified a "name" argument when instantiating these classes, the error message will refer to that name instead of the internal expression that refers to it (which means nothing to the user).

Example input:

import tidy3d as td

# structure = td.Structure(
#     geometry=td.Box(center=(1.0, 1.0, 0.0), size=(0.5, 0.5, 0.5)), medium=td.Medium(permittivity=2.0), name="structure_1"
# ) 
#
# monitor = td.FieldMonitor(
#     center=(-1.0, 0, 0), size=(0.5, 0, 1), freqs=[100e14], name="field_monitor_1"
# )

source = td.UniformCurrentSource(
    center=(0, -1.0, 0),
    size=(1, 0, 0.5),
    polarization="Ex",
    source_time=td.GaussianPulse(
        freq0=100e14,
        fwidth=10e14,
    ),
    name="source_1",
)

# make simulation
sim = td.Simulation(
    size=(1, 1, 1),
    grid_spec=td.GridSpec.auto(wavelength=4),
    boundary_spec=td.BoundarySpec(
        x=td.Boundary.pml(num_layers=10),
        y=td.Boundary.periodic(),
        z=td.Boundary.pml(num_layers=10),
    ),
    sources=[source],
    # monitors=[monitor],
    # structures=[structure],
    run_time=1e-12,
)

(test file: test_pr2618.ipynb.zip

Before this PR (example error message)

This generates:

simulation.sources[0] is outside of the simulation domain.

Similarly cryptic errors are displayed for Structures and Monitors if you uncomment the # structures=[structure]. and # monitors=[monitor], lines in the code above.

After this PR (example error message)

'source_1' (simulation.sources[0]) is outside of the simulation domain.

• If the name argument is omitted from the argument list, then a (vague) error messages is generated. For example:
  "simulation.sources[0] (no 'name' was specified) is outside of the simulation domain."
• This does not do any good unless users provide names for the various objects in their simulations. To encourage that, a warning messages is generated when a Source is created without a name argument. For example: WARNING: UniformCurrentSource instantiated without a name argument.

Greptile Summary

Enhances error message clarity by incorporating user-specified names for Monitor, Source, and Structure objects in validation messages.

• Added new named_obj_descr helper function in components/validators.py to generate more descriptive error strings
• Updated error messages to show both user-specified names and internal references (e.g., 'source_1' (simulation.sources[0]))
• Modified validation messages in components/simulation.py to use component names when available
• Falls back to descriptive placeholder when no name specified (e.g., '(no name was specified)')
• Renamed validation function to more descriptive assert_objects_completely_in_sim_bounds

[jewettaijfc]

Passing unit tests.
Ready for review.

[github-actions]

Diff Coverage

Diff: origin/develop...HEAD, staged and unstaged changes

• tidy3d/components/simulation.py (100%)
• tidy3d/components/validators.py (100%)

Summary

• Total: 22 lines
• Missing: 0 lines
• Coverage: 100%

[greptile-apps]

_{2 files reviewed, 1 comment
Edit PR Review Bot Settings | Greptile}

[yaugenst-flex]

Thanks @jewettaijfc I think the implementation looks good! Still needs some tests though.

[yaugenst-flex]

@jewettaijfc you should be able to catch and match a logged warning using AssertLogLevel like for example here. Basically just add a test where you set up a simulation with some named object that's not in bounds, and use AssertLogLevel to check whether the warning is being raised. Probably this would also go into test_simulation.py rather than test_log.py.

[jewettaijfc]

@jewettaijfc you should be able to catch and match a logged warning using AssertLogLevel like for example here. Basically just add a test where you set up a simulation with some named object that's not in bounds, and use AssertLogLevel to check whether the warning is being raised.

Cool! Do you want me to parse the content of the warning messages and error messages (to make sure the message contains the object name)?

Probably this would also rather go into test_simulation.py rather than test_log.py.

Thanks! (I was wondering this too.)

[jewettaijfc]

I guess that wasn't so bad! I added a new test (test_simulation.py::test_messages_contain_object_names). Yay! I think I was partially driven insane by by my earlier experiences. At the moment, all the tests are passing.

[jewettaijfc]

Sorry. I misunderstood what you were asking for. (You were clear. This is my fault.)

I will add AssertLogLevel to my unit test. Hold on.

[jewettaijfc]

Done.

[jewettaijfc]

Now using pytest.raises().
This PR is ready for review.

[yaugenst-flex]

Nice! Some minor test cleanup and this should be good to go!

[yaugenst-flex]

Great! One last nitpick, then we need a changelog entry (under "Changed"), squash & rebase and this is good to go!

[jewettaijfc]

we need a changelog entry

I can't believe I forgot to update the changelog (again). Sorry about that!

All ready now.

[yaugenst-flex]

LGTM! Thanks @jewettaijfc