ABC broadband

[dbochkov-flexcompute]

Implements python interface to broadband ABC boundary conditions. overall structure and implementation is similar to LossyMetalMedium. Specifically:

• introduced BroadbandModeABCSpec(frequency_range=...) to specify range in which absorption is desired. It can be passed as argument freq_spec (previously, frequency) in ModeABCBoundary(..., freq_spec=...)
• introduced BroadbandModeABCFitterParam to control max number of poles, number of frequency points, and fit tolerance, it is passed as fit_param in BroadbandModeABCSpec

Greptile Summary

This PR introduces broadband absorbing boundary conditions (ABC) for electromagnetic simulations in Tidy3D. The implementation extends the existing single-frequency mode absorption capabilities to work over frequency ranges, following a similar design pattern to the existing LossyMetalMedium functionality.

The core changes involve:

1. New Classes: Introduction of BroadbandModeABCFitterParam and BroadbandModeABCSpec classes that define broadband absorption behavior using pole-residue fitting to approximate mode propagation index over frequency ranges.

2. API Evolution: The ModeABCBoundary class has been updated to replace the frequency field with freq_spec, which accepts either a single frequency (float) or a BroadbandModeABCSpec object for broadband operation.

3. Enhanced Wave Port Support: Wave ports now support custom boundary conditions through an expanded absorber field that accepts boolean values, ABCBoundary, or ModeABCBoundary objects.

4. Backward Compatibility: The changes maintain full backward compatibility - existing code using single-frequency absorption continues to work unchanged, while new broadband capabilities are available through the updated API.

The broadband functionality uses pole-residue pairs to model frequency-dependent absorption characteristics, which is a standard electromagnetics approach for approximating complex frequency-dependent material properties. The implementation includes proper parameter validation, frequency range constraints, and utilities for converting between wavelength and frequency specifications. This enhancement allows users to achieve effective absorption across entire simulation frequency ranges rather than being limited to single frequency points, which is particularly valuable for broadband electromagnetic simulations.

Important Files Changed

Files Changed

Filename	Score	Overview
tidy3d/components/boundary.py	4/5	Adds new BroadbandModeABCFitterParam and BroadbandModeABCSpec classes and updates ModeABCBoundary to use freq_spec instead of frequency
tidy3d/init.py	5/5	Exposes the two new broadband ABC classes in the public API through proper imports and __all__ additions
tests/test_components/test_absorbers.py	5/5	Updates all test cases to use freq_spec parameter and adds comprehensive tests for broadband ABC functionality
tidy3d/components/simulation.py	5/5	Updates validation logic to check freq_spec field instead of deprecated frequency field
tidy3d/plugins/smatrix/ports/wave.py	4/5	Expands wave port absorber support to accept custom boundary conditions and updates parameter naming
tidy3d/plugins/smatrix/component_modelers/terminal.py	4/5	Updates wave port absorber creation to use broadband frequency specifications over the full simulation range
tests/test_plugins/smatrix/test_terminal_component_modeler.py	5/5	Adds test coverage for the new broadband wave port absorber functionality

Confidence score: 4/5

• This PR is generally safe to merge with some considerations for the complexity of the broadband fitting implementation
• Score reflects well-structured changes with comprehensive testing, but the mathematical complexity of pole-residue fitting requires careful validation
• Pay close attention to tidy3d/components/boundary.py and tidy3d/plugins/smatrix/ports/wave.py for the core broadband implementation logic

Sequence Diagram

sequenceDiagram
    participant User
    participant BroadbandModeABCSpec
    participant BroadbandModeABCFitterParam
    participant ModeABCBoundary
    participant Simulation
    participant Grid
    participant Solver

    User->>BroadbandModeABCFitterParam: "Create fitter parameters"
    Note over BroadbandModeABCFitterParam: max_num_poles=5<br/>tolerance_rms=1e-4<br/>frequency_sampling_points=10
    BroadbandModeABCFitterParam->>User: "Return fitter parameters"

    User->>BroadbandModeABCSpec: "Create frequency specification"
    Note over BroadbandModeABCSpec: frequency_range=(100e12, 120e12)<br/>fit_param=fitter_params
    BroadbandModeABCSpec->>User: "Return frequency spec"

    User->>ModeABCBoundary: "Create boundary with broadband spec"
    Note over ModeABCBoundary: plane=Box(...)<br/>freq_spec=broadband_spec
    ModeABCBoundary->>User: "Return configured boundary"

    User->>Simulation: "Create simulation with ABC boundary"
    Note over Simulation: boundary_spec=BoundarySpec(...)<br/>internal_absorbers=[abc_boundary]
    Simulation->>Grid: "Discretize simulation domain"
    Grid->>Simulation: "Return grid configuration"

    Simulation->>ModeABCBoundary: "Validate frequency specification"
    ModeABCBoundary->>BroadbandModeABCSpec: "Check frequency range validity"
    BroadbandModeABCSpec->>BroadbandModeABCFitterParam: "Validate fitting parameters"
    BroadbandModeABCFitterParam->>BroadbandModeABCSpec: "Parameters valid"
    BroadbandModeABCSpec->>ModeABCBoundary: "Frequency range valid"
    ModeABCBoundary->>Simulation: "Boundary configuration valid"

    User->>Simulation: "Run FDTD simulation"
    Simulation->>Solver: "Initialize with broadband ABC"
    Note over Solver: Apply pole-residue fitting<br/>for mode propagation index<br/>across frequency range
    Solver->>Simulation: "Return simulation results"
    Simulation->>User: "Return completed simulation data"

Loading

[greptile-apps]

_{7 files reviewed, 1 comment}

_{Edit Code Review Bot Settings | Greptile}

[greptile-apps]

syntax: Documentation says range is [1, 21] for frequency sampling points but MAX_BROADBAND_MODE_ABC_NUM_FREQS = 101, creating inconsistency

Suggested change

	The number of poles and frequency sampling points are constrained to be within the range [1, 10] and [1, 21] respectively.
	The number of poles and frequency sampling points are constrained to be within the range [1, 10] and [1, 101] respectively.