FXC-3724 support multimodal waveports

[dmarek-flex]

Greptile Overview

Updated On: 2025-10-16 20:12:05 UTC

Greptile Summary

This PR implements multimodal waveport support in the S-matrix component modeler, enabling waveguide ports to handle multiple propagating modes simultaneously. The changes refactor the WavePort class to use MicrowaveModeSpec instead of manual impedance calculations, introduce a network indexing system that creates separate entries for each port-mode combination, and update the analysis pipeline to work with NetworkIndex identifiers rather than simple port references.

Key architectural changes include replacing the single mode_index field with a multimodal approach, switching from TerminalPortType to NetworkIndex for port identification, and implementing caching optimizations for voltage/current calculations to avoid redundant computations across modes of the same port. The refactoring leverages existing microwave components for transmission line calculations while maintaining backward compatibility with lumped ports.

Important Files Changed

Changed Files

Filename	Score	Overview
tidy3d/plugins/smatrix/ports/wave.py	4/5	Major refactoring to support multimodal operation using MicrowaveModeSpec and removing manual impedance calculations
tidy3d/plugins/smatrix/component_modelers/terminal.py	4/5	Core network indexing changes to create separate entries for each port-mode combination
tidy3d/plugins/smatrix/analysis/terminal.py	4/5	Added caching optimization for voltage/current calculations and mode_index parameter support
tidy3d/plugins/smatrix/data/terminal.py	4/5	Updated method signature from TerminalPortType to NetworkIndex for multimodal support
tidy3d/plugins/smatrix/component_modelers/base.py	5/5	Removed automatic mode_index assignment to require explicit specification
tidy3d/plugins/smatrix/analysis/antenna.py	4/5	Refactored to use NetworkIndex-based processing instead of port-based iteration
tests/test_plugins/smatrix/test_terminal_component_modeler.py	3/5	Updated test suite with incomplete validation migration and duplicate code blocks
tests/test_plugins/smatrix/terminal_component_modeler_def.py	4/5	Updated WavePort configuration to use MicrowaveModeSpec with CustomImpedanceSpec
tests/utils.py	4/5	Added data generator functions for microwave monitor data with transmission line support

Confidence score: 3/5

• This PR requires careful review due to significant architectural changes affecting the S-matrix analysis pipeline
• Score reflects the comprehensive nature of the refactoring with multiple interdependent changes, incomplete test validation migration, and potential for runtime issues if network indexing logic has edge cases
• Pay close attention to test files with TODO comments and duplicate code blocks, and verify that all validation logic has been properly migrated to the new API

Sequence Diagram

sequenceDiagram
    participant User
    participant TerminalComponentModeler
    participant WavePort
    participant MicrowaveModeSpec
    participant Simulation
    participant TerminalComponentModelerData
    participant SMatrixCalculation

    User->>TerminalComponentModeler: "Create modeler with multimodal wave ports"
    TerminalComponentModeler->>WavePort: "Initialize with MicrowaveModeSpec"
    WavePort->>MicrowaveModeSpec: "Configure num_modes > 1"
    
    User->>TerminalComponentModeler: "Generate simulation dictionary"
    TerminalComponentModeler->>TerminalComponentModeler: "Build network_dict mapping"
    Note over TerminalComponentModeler: Maps each mode to unique NetworkIndex
    
    loop For each mode in each WavePort
        TerminalComponentModeler->>WavePort: "Create source for mode_index"
        WavePort->>Simulation: "Add ModeSource with specific mode"
        TerminalComponentModeler->>WavePort: "Create monitors for mode"
        WavePort->>Simulation: "Add MicrowaveModeMonitor"
    end
    
    User->>TerminalComponentModeler: "Run simulations"
    loop For each simulation task
        TerminalComponentModeler->>Simulation: "Execute FDTD simulation"
        Simulation->>TerminalComponentModelerData: "Return SimulationData"
    end
    
    User->>TerminalComponentModelerData: "Calculate S-matrix"
    TerminalComponentModelerData->>SMatrixCalculation: "Process multimodal data"
    
    loop For each port and mode combination
        SMatrixCalculation->>WavePort: "Compute voltage/current for mode"
        WavePort->>SMatrixCalculation: "Return modal V/I data"
        SMatrixCalculation->>SMatrixCalculation: "Convert to wave amplitudes"
    end
    
    SMatrixCalculation->>TerminalComponentModelerData: "Return complete S-matrix"
    TerminalComponentModelerData->>User: "Provide multimodal S-parameters"

Loading

[greptile-apps]

Additional Comments (1)

1. tests/test_plugins/smatrix/test_terminal_component_modeler.py, line 799-817 (link)

   logic: This code block is duplicated from lines780-798. The duplicate should be removed.

_{9 files reviewed, 5 comments}

_{Edit Code Review Agent Settings | Greptile}

[github-actions]

Diff Coverage

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

• tidy3d/components/microwave/mode_spec.py (100%)
• tidy3d/components/microwave/path_integrals/integrals/current.py (100%)
• tidy3d/components/microwave/path_integrals/specs/current.py (100%)
• tidy3d/components/mode/mode_solver.py (100%)
• tidy3d/components/simulation.py (100%)
• tidy3d/plugins/smatrix/analysis/antenna.py (100%)
• tidy3d/plugins/smatrix/analysis/terminal.py (100%)
• tidy3d/plugins/smatrix/component_modelers/terminal.py (100%)
• tidy3d/plugins/smatrix/data/terminal.py (100%)
• tidy3d/plugins/smatrix/ports/wave.py (100%)

Summary

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

[weiliangjin2021]

Looks quite solid. One question: consider that the transmission line supports 2 modes, and only mode_index=1 is involved in a modeling. Previously, I can setup a modeler by setting mode_index=1 in Waveport definition. Currently, with num_modes=2, simulations for both mode indices will be performed, unless one specify run_only parameters. Maybe it can be helpful to provide a convenient function to setup the previous behavior?

[daquinteroflex]

Looks good just a few comments

[weiliangjin2021]

Just one comment.

[George-Guryev-flxcmp]

Looks solid — great work! Just one note on de-embedding: in its current state, it doesn’t support multimode waveport de-embedding due to a dimensionality mismatch.