feat(rf): support multimodal waveports

Author: dmarek-flex

CHANGELOG.md

@@ -27,20 +27,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Introduced a profile-based configuration manager with TOML persistence and runtime overrides exposed via `tidy3d.config`.
 - Added support of `os.PathLike` objects as paths like `pathlib.Path` alongside `str` paths in all path-related functions.
 - Added configurable local simulation result caching with checksum validation, eviction limits, and per-call overrides across `web.run`, `web.load`, and job workflows.
+- Added multimode support to `WavePort` in the smatrix plugin, allowing multiple modes to be analyzed per port.
+
+### Breaking Changes
+**Note: These breaking changes only affect the microwave and smatrix plugins.**
+- Renamed path integral classes for improved consistency. Please see our migration guide for details on updating your code.
+  - `VoltageIntegralAxisAligned` → `AxisAlignedVoltageIntegral`
+  - `CurrentIntegralAxisAligned` → `AxisAlignedCurrentIntegral`
+  - `CustomPathIntegral2D` → `Custom2DPathIntegral`
+  - `CustomVoltageIntegral2D` → `Custom2DVoltageIntegral`
+  - `CustomCurrentIntegral2D` → `Custom2DCurrentIntegral`
+  - Path integral and impedance calculator classes have been refactored and moved from the microwave plugin into Tidy3D components. They are now publicly exported via the top-level package `__init__.py`.
+- `WavePort` has been refactored to use `MicrowaveModeSpec`. The fields `voltage_integral`, and `current_integral` have been removed. Impedance specifications are now defined in `MicrowaveModeSpec.impedance_specs`. Please see our migration guide for details on updating your code.
 
 ### Changed
 - Improved performance of antenna metrics calculation by utilizing cached wave amplitude calculations instead of recomputing wave amplitudes for each port excitation in the `TerminalComponentModelerData`.
 - Changed hashing method in `Tidy3dBaseModel` from sha256 to md5.
 - Allowing for more geometries in a ClipOperation geometry.
 - Improved the speed of computing `Box` shape derivatives when used inside a `GeometryGroup`.
 - All RF and microwave specific components now inherit from `MicrowaveBaseModel`.
-- **[BREAKING]** Renamed path integral classes in `tidy3d.plugins.microwave` for improved consistency. Please see our migration guide for details on updating your code.
-  - `VoltageIntegralAxisAligned` → `AxisAlignedVoltageIntegral`
-  - `CurrentIntegralAxisAligned` → `AxisAlignedCurrentIntegral`
-  - `CustomPathIntegral2D` → `Custom2DPathIntegral`
-  - `CustomVoltageIntegral2D` → `Custom2DVoltageIntegral`
-  - `CustomCurrentIntegral2D` → `Custom2DCurrentIntegral`
-  - Path integral and impedance calculator classes have been refactored and moved from `tidy3d.plugins.microwave` to `tidy3d.components.microwave`. They are now publicly exported via the top-level package `__init__.py`, so you can import them directly, e.g. `from tidy3d import ImpedanceCalculator, AxisAlignedVoltageIntegral, AxisAlignedCurrentIntegral, Custom2DVoltageIntegral, Custom2DCurrentIntegral, Custom2DPathIntegral`.
 - `DirectivityMonitor` now forces `far_field_approx` to `True`, which was previously configurable.
 - Unified run submission API: `web.run(...)` is now a container-aware wrapper that accepts a single simulation or arbitrarily nested containers (`list`, `tuple`, `dict` values) and returns results in the same shape.
 - `web.Batch(ComponentModeler)` and `web.Job(ComponentModeler)` native support

docs/api/microwave/microwave_migration.rst

@@ -1,18 +1,27 @@
 .. _microwave_migration:
 
-v2.10 Refactor Migration
--------------------------
+v2.10 Refactor Migration Guide
+-------------------------------
 
-In version ``v2.10.0``, microwave plugin path integral classes were renamed for improved consistency and clarity. Additionally, these classes (and the impedance calculator) were refactored out of the plugin and moved into ``tidy3d.components.microwave`` and re-exported at the top-level package for convenience. This guide helps you update your scripts to use the new class names and imports.
+In version ``v2.10.0``, the microwave and RF simulation capabilities underwent significant refactoring to improve consistency, clarity, and functionality. This guide covers two major sets of breaking changes:
 
-Key Changes
-~~~~~~~~~~~
+1. **Path Integral Class Renames** - Classes were renamed for consistency
+2. **WavePort API Changes** - WavePort was refactored to support multiple modes with cleaner impedance specification
+
+This guide helps you update your scripts to work with v2.10+.
+
+1. Path Integral Class Renames
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Path integral classes were renamed for improved consistency and clarity. Additionally, these classes (and the impedance calculator) were refactored out of the plugin and re-exported at the top-level package for convenience.
+
+**Key changes:**
 
 *   **Renamed Classes**: Path integral classes have been renamed to follow a consistent naming pattern.
 *   **New Import Path (simplified)**: The path integral classes and impedance calculator are now exported at the top level. Prefer importing directly from ``tidy3d`` (e.g., ``from tidy3d import AxisAlignedVoltageIntegral, ImpedanceCalculator``). Existing plugin imports continue to work for backwards compatibility where applicable.
 
 Class Name Changes
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
 
 The following classes have been renamed for consistency:
 
@@ -31,7 +40,7 @@ The following classes have been renamed for consistency:
 *   ``CustomPathIntegral2D`` → ``Custom2DPathIntegral``
 
 Migration Examples
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
 
 **Before (v2.9.x):**
 
@@ -76,7 +85,7 @@ Migration Examples
     )
 
 Custom 2D Path Integrals
-~~~~~~~~~~~~~~~~~~~~~~~~~
+""""""""""""""""""""""""
 
 **Before:**
 
@@ -125,6 +134,302 @@ Custom 2D Path Integrals
     )
 
 Summary
-~~~~~~~
+^^^^^^^
 
 All functionality remains the same—only class names and preferred import paths have changed. Update your imports to the top level (``from tidy3d import ...``) and class names according to the table above, and your code will work with v2.10. For impedance calculations, import ``ImpedanceCalculator`` directly via ``from tidy3d import ImpedanceCalculator``.
+
+2. WavePort API Changes for Multimodal Support
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``WavePort`` class was refactored to support multiple modes and to provide cleaner integration with the microwave mode solver. This required several breaking changes to the API.
+
+Overview of Changes
+^^^^^^^^^^^^^^^^^^^
+
+The key improvements in v2.10 include:
+
+*   **Multimodal support**: WavePorts can now excite and monitor multiple modes simultaneously
+*   **Cleaner impedance specification**: Voltage and current path integrals are now specified via ``MicrowaveModeSpec`` instead of directly on the port
+*   **Mode selection at source creation**: The mode to excite is now specified when creating a source, not when defining the port
+*   **Improved type safety**: Uses ``MicrowaveModeSpec`` and ``MicrowaveModeMonitor`` for clearer RF-specific behavior
+
+Removed Fields
+^^^^^^^^^^^^^^
+
+The following fields have been **removed** from ``WavePort``:
+
+*   ``voltage_integral: Optional[VoltageIntegralType]`` - Path integral for voltage calculation
+*   ``current_integral: Optional[CurrentIntegralType]`` - Path integral for current calculation
+
+Changed Fields
+^^^^^^^^^^^^^^
+
+*   ``mode_index`` - The behavior has changed. Previously a required ``int`` specifying which single mode to use (default: 0). Now an optional ``Union[int, tuple[int, ...]]`` that selects which modes to monitor and excite. When ``None`` (default), all modes from ``mode_spec`` are used.
+
+New MicrowaveModeSpec Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``mode_spec`` field now requires a ``MicrowaveModeSpec`` (instead of the generic ``ModeSpec``). This new class includes:
+
+*   ``impedance_specs``: Defines how to compute voltage, current, and characteristic impedance for each mode
+
+Migration Examples
+^^^^^^^^^^^^^^^^^^
+
+Single-Mode WavePort
+""""""""""""""""""""
+
+**Before (v2.9.x):**
+
+.. code-block:: python
+
+    import tidy3d as td
+    from tidy3d.plugins.smatrix import WavePort
+
+    # Define path integrals
+    voltage_path = td.AxisAlignedVoltageIntegralSpec(
+        center=(0, 0, 0),
+        size=(1.0, 0, 0),
+        sign="+",
+    )
+
+    current_path = td.Custom2DCurrentIntegralSpec.from_circular_path(
+        center=(0, 0, 0),
+        radius=0.5,
+        num_points=21,
+        normal_axis=2,
+        clockwise=False
+    )
+
+    # Create WavePort - path integrals attached directly to port
+    port = WavePort(
+        center=(0, 0, -5),
+        size=(2, 2, 0),
+        direction="+",
+        mode_spec=td.ModeSpec(num_modes=1),  # Generic ModeSpec
+        mode_index=0,  # Which mode to excite
+        voltage_integral=voltage_path,  # Attached to port
+        current_integral=current_path,  # Attached to port
+        name="port1"
+    )
+
+**After (v2.10+):**
+
+.. code-block:: python
+
+    import tidy3d as td
+    from tidy3d.plugins.smatrix import WavePort
+
+    # Define path integrals (same as before)
+    voltage_path = td.AxisAlignedVoltageIntegralSpec(
+        center=(0, 0, 0),
+        size=(1.0, 0, 0),
+        sign="+",
+    )
+
+    current_path = td.Custom2DCurrentIntegralSpec.from_circular_path(
+        center=(0, 0, 0),
+        radius=0.5,
+        num_points=21,
+        normal_axis=2,
+        clockwise=False
+    )
+
+    # Create WavePort - path integrals now in MicrowaveModeSpec
+    port = WavePort(
+        center=(0, 0, -5),
+        size=(2, 2, 0),
+        direction="+",
+        mode_spec=td.MicrowaveModeSpec(  # Use MicrowaveModeSpec
+            num_modes=1,
+            impedance_specs=td.CustomImpedanceSpec(
+                voltage_spec=voltage_path,  # Moved to impedance_specs
+                current_spec=current_path
+            )
+        ),
+        name="port1"
+        # Note: mode_index, voltage_integral, current_integral removed
+    )
+
+    # Mode selection now happens at source creation
+    source_time = td.GaussianPulse(freq0=10e9, fwidth=1e9)
+    source = port.to_source(source_time, mode_index=0)  # Mode selected here
+
+Multi-Mode WavePort (New Feature!)
+"""""""""""""""""""""""""""""""""""
+
+The new API enables WavePorts to support multiple modes simultaneously:
+
+.. code-block:: python
+
+    import tidy3d as td
+    from tidy3d.plugins.smatrix import WavePort
+
+    # Create a 3-mode WavePort
+    port = WavePort(
+        center=(0, 0, -5),
+        size=(4, 4, 0),
+        direction="+",
+        mode_spec=td.MicrowaveModeSpec(
+            num_modes=3,  # Solve for 3 modes
+            impedance_specs=td.AutoImpedanceSpec()  # Auto-compute impedance for all modes
+        ),
+        name="multimode_port"
+    )
+
+    # Create sources for different modes
+    source_time = td.GaussianPulse(freq0=10e9, fwidth=1e9)
+    source_mode0 = port.to_source(source_time, mode_index=0)  # Excite mode 0
+    source_mode1 = port.to_source(source_time, mode_index=1)  # Excite mode 1
+    source_mode2 = port.to_source(source_time, mode_index=2)  # Excite mode 2
+
+Per-Mode Impedance Specifications
+""""""""""""""""""""""""""""""""""
+
+For advanced use cases, you can specify different impedance calculation methods for each mode:
+
+.. code-block:: python
+
+    # Define custom specs for mode 0, auto for modes 1 and 2
+    port = WavePort(
+        center=(0, 0, -5),
+        size=(4, 4, 0),
+        direction="+",
+        mode_spec=td.MicrowaveModeSpec(
+            num_modes=3,
+            impedance_specs=(
+                td.CustomImpedanceSpec(
+                    voltage_spec=custom_voltage_path,
+                    current_spec=custom_current_path
+                ),  # Mode 0 uses custom specs
+                td.AutoImpedanceSpec(),  # Mode 1 uses auto
+                td.AutoImpedanceSpec(),  # Mode 2 uses auto
+            )
+        ),
+        name="mixed_impedance_port"
+    )
+
+Method Changes
+^^^^^^^^^^^^^^
+
+``compute_port_impedance()`` → ``get_port_impedance()``
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+The method for retrieving port impedance has been renamed and now requires a ``mode_index`` parameter:
+
+**Before (v2.9.x):**
+
+.. code-block:: python
+
+    # Get impedance - implicitly used port.mode_index
+    Z0 = port.compute_port_impedance(sim_data)
+
+**After (v2.10+):**
+
+.. code-block:: python
+
+    # Get impedance for mode 0
+    Z0_mode0 = port.get_port_impedance(sim_data, mode_index=0)
+
+    # Get impedance for mode 1 (multimodal port)
+    Z0_mode1 = port.get_port_impedance(sim_data, mode_index=1)
+
+Voltage and Current Computation Shape Changes
+""""""""""""""""""""""""""""""""""""""""""""""
+
+For multimodal ports, ``compute_voltage()`` and ``compute_current()`` now return data for **all modes** with a ``mode_index`` dimension:
+
+**Before (v2.9.x):**
+
+.. code-block:: python
+
+    # Returns shape: (n_freqs,) - single mode only
+    voltage = port.compute_voltage(sim_data)
+    current = port.compute_current(sim_data)
+
+**After (v2.10+):**
+
+.. code-block:: python
+
+    # For single-mode port: Returns shape: (n_freqs, 1)
+    # For multi-mode port: Returns shape: (n_freqs, n_modes)
+    voltage = port.compute_voltage(sim_data)
+    current = port.compute_current(sim_data)
+
+    # Select specific mode using xarray selection
+    voltage_mode0 = voltage.sel(mode_index=0)
+    voltage_mode1 = voltage.sel(mode_index=1)
+
+Using AutoImpedanceSpec for Simplified Setup
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For most cases, you can use ``AutoImpedanceSpec`` which automatically computes voltage, current, and impedance from the electromagnetic fields:
+
+.. code-block:: python
+
+    # Simplest form - let Tidy3D auto-compute everything
+    port = WavePort(
+        center=(0, 0, -5),
+        size=(2, 2, 0),
+        direction="+",
+        mode_spec=td.MicrowaveModeSpec(
+            num_modes=2,
+            impedance_specs=td.AutoImpedanceSpec()  # Works for all modes
+        ),
+        name="simple_port"
+    )
+
+Breaking Changes Summary
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following table summarizes all breaking changes to the ``WavePort`` API:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 30 40
+
+   * - Change
+     - Old (v2.9.x)
+     - New (v2.10+)
+   * - Port field: mode_index
+     - Required ``int``, single mode (default: 0)
+     - Optional ``Union[int, tuple[int, ...]]``, selects modes to monitor/excite (default: ``None`` = all modes)
+   * - Port field: voltage_integral
+     - ``voltage_integral=path``
+     - Removed. Use ``mode_spec.impedance_specs``
+   * - Port field: current_integral
+     - ``current_integral=path``
+     - Removed. Use ``mode_spec.impedance_specs``
+   * - mode_spec type
+     - ``ModeSpec``
+     - ``MicrowaveModeSpec``
+   * - Impedance method
+     - ``compute_port_impedance(sim_data)``
+     - ``get_port_impedance(sim_data, mode_index)``
+   * - Monitor type
+     - Returns ``ModeMonitor``
+     - Returns ``MicrowaveModeMonitor``
+   * - Voltage/current shape
+     - ``(n_freqs,)`` - single mode
+     - ``(n_freqs, n_modes)`` - all modes
+   * - Multimodal support
+     - Not supported
+     - Fully supported via ``num_modes``
+
+Benefits of the New API
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The refactored API provides several advantages:
+
+*   **Multimodal ports**: Support for multiple modes enables more accurate modeling of multimode waveguides and transmission lines
+*   **Cleaner separation of concerns**: Mode selection happens at excitation time, not port definition time
+*   **Type safety**: ``MicrowaveModeSpec`` and ``MicrowaveModeMonitor`` make RF-specific behavior explicit
+*   **Flexibility**: Per-mode impedance specifications allow fine-grained control
+*   **Consistency**: Aligns with the general pattern of ``ModeSource`` where ``mode_index`` is a source parameter
+
+Backward Compatibility
+^^^^^^^^^^^^^^^^^^^^^^
+
+There is **no backward compatibility** for WavePort instantiation with the old field names (``voltage_integral``, ``current_integral``). Attempting to use these fields will result in a Pydantic validation error.
+
+The ``mode_index`` field has **changed behavior**: In v2.9, it was a required ``int`` specifying a single mode. In v2.10, it is optional and can select multiple modes via a tuple. Code using ``mode_index=0`` will work but now means "only use mode 0" rather than being the default.