improve validation when using power waves

Author: dmarek-flex

tests/test_plugins/smatrix/test_terminal_component_modeler.py

@@ -1147,6 +1147,58 @@ def test_run_only_and_element_mappings(monkeypatch, tmp_path):
     assert len(modeler_with_mappings.sim_dict) == 2
 
 
+def test_validate_S_def():
+    """Test that the S_def field is validated correctly, especially when it is set to 'power'."""
+    # Create a base modeler using the existing convenience function
+    modeler = make_component_modeler(planar_pec=True)
+
+    port0_idx = modeler.network_index(modeler.ports[0])
+    port1_idx = modeler.network_index(modeler.ports[1])
+    S11 = (port0_idx, port0_idx)
+    S21 = (port1_idx, port0_idx)
+    S12 = (port0_idx, port1_idx)
+    S22 = (port1_idx, port1_idx)
+    element_mappings = ((S11, S22, 1),)
+
+    # S_def="pseudo" is the most flexible choice when running a subset of simulations
+    modeler_pseudo = (
+        modeler.updated_copy(
+            S_def="pseudo",
+            assume_ideal_excitation=True,
+            run_only=(modeler.ports[0].name,),
+        ),
+    )
+
+    # S_def="power" with assume_ideal_excitation=True should fail
+    with pytest.raises(pd.ValidationError):
+        modeler.updated_copy(
+            S_def="power",
+            assume_ideal_excitation=True,
+        )
+
+    # S_def="power" with run_only not None should fail
+    with pytest.raises(pd.ValidationError):
+        modeler.updated_copy(
+            S_def="power",
+            run_only=(modeler.ports[0].name,),
+        )
+
+    # S_def="power" with element_mappings not empty should fail
+    with pytest.raises(pd.ValidationError):
+        modeler.updated_copy(
+            S_def="power",
+            element_mappings=element_mappings,
+        )
+
+    # S_def="power" with all valid settings should pass
+    modeler_power_valid = modeler.updated_copy(
+        S_def="power",
+        assume_ideal_excitation=False,
+        run_only=None,
+        element_mappings=(),
+    )
+
+
 def test_internal_construct_smatrix_with_port_vi(monkeypatch):
     """Test _internal_construct_smatrix method by monkeypatching compute_port_VI
     with precomputed voltage and current values and comparing the final S-matrix to expected results.

tidy3d/plugins/smatrix/component_modelers/terminal.py

@@ -72,10 +72,10 @@ class TerminalComponentModeler(AbstractComponentModeler[NetworkIndex, NetworkEle
         title="Assume Ideal Excitation",
         description="If ``True``, only the excited port is assumed to have a nonzero incident wave "
         "amplitude power. This choice simplifies the calculation of the scattering matrix. "
-        "If ``False``, every entry in the vector of incident power wave "
-        "amplitudes (a) is calculated explicitly. This choice requires a matrix inversion when "
-        "calculating the scattering matrix, but may lead to more accurate scattering parameters "
-        "when there are reflections from simulation boundaries. ",
+        "If ``False``, every entry in the vector of incident wave amplitudes (a) is calculated "
+        "explicitly. This choice requires a matrix inversion when calculating the scattering "
+        "matrix, but may lead to more accurate scattering parameters when there are "
+        "reflections from simulation boundaries. ",
     )
 
     S_def: SDef = pd.Field(
@@ -92,6 +92,45 @@ def _warn_rf_license(cls, values):
         )
         return values
 
+    @pd.validator("S_def", always=True)
+    def _validate_S_def(cls, S_def, values):
+        """
+        Check that the scattering parameter computation is set up correctly for the power wave definition.
+        """
+
+        if S_def == "pseudo":
+            return S_def
+
+        assume_ideal_excitation = values.get("assume_ideal_excitation")
+        if assume_ideal_excitation is True:
+            raise SetupError(
+                "Setting `assume_ideal_excitation` to ``True`` is incompatible with "
+                "using the power wave definition of scattering parameters. "
+                "Either use the pseudo wave definition by setting 'S_def' to 'pseudo', "
+                "or set 'assume_ideal_excitation' to ``False``. "
+            )
+
+        run_only = values.get("run_only")
+        if run_only is not None:
+            raise SetupError(
+                "Computing scattering parameters using the power wave definition "
+                "requires running a number of simulations equal to the number of ports. "
+                "Either use the pseudo wave definition by setting 'S_def' to 'pseudo', "
+                "or ensure all simulations are run by setting 'run_only' to 'None'. "
+            )
+
+        element_mappings = values.get("element_mappings")
+        if len(element_mappings) != 0:
+            raise SetupError(
+                "Computing scattering parameters using the power wave definition "
+                "requires running a number of simulations equal to the number of ports. "
+                "Either use the pseudo wave definition by setting 'S_def' to 'pseudo', "
+                "or ensure all simulations are run by keeping 'element_mappings' as its "
+                "default value of an empty 'tuple'. "
+            )
+
+        return S_def
+
     @equal_aspect
     @add_ax_if_none
     def plot_sim(
@@ -132,15 +171,15 @@ def plot_sim_eps(
 
     @staticmethod
     def network_index(port: TerminalPortType, mode_index: Optional[int] = None) -> NetworkIndex:
-        """Converts the port, and a ``mode_index`` when the port is a :class:`.WavePort``, to a unique string specifier.
+        """Converts the port, and a ``mode_index`` when the port is a :class:`.WavePort`, to a unique string specifier.
 
         Parameters
         ----------
         port : ``TerminalPortType``
             The port to convert to an index.
         mode_index : Optional[int]
             Selects a single mode from those supported by the ``port``, which is only used when
-            the ``port`` is a :class:`.WavePort``
+            the ``port`` is a :class:`.WavePort`
 
         Returns
         -------