add selective simulation capabilities to TerminalComponentModeler

refactored common code into AbstractComponentModeler

add toggle for controlling how s matrix is calculated

added validation of run_only and element_mappings for modelers

schema update

Author: dmarek-flex

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Selective simulation capabilities to `TerminalComponentModeler` via `run_only` and `element_mappings` fields, allowing users to run fewer simulations and extract only needed scattering matrix elements.
+
 ### Changed
 - Validate mode solver object for large number of grid points on the modal plane.
 

schemas/TerminalComponentModeler.json

@@ -1,6 +1,6 @@
 {
   "title": "TerminalComponentModeler",
-  "description": "Tool for modeling two-terminal multiport devices and computing port parameters\nwith lumped and wave ports.\n\nParameters\n----------\nattrs : dict = {}\n    Dictionary storing arbitrary metadata for a Tidy3D object. This dictionary can be freely used by the user for storing data without affecting the operation of Tidy3D as it is not used internally. Note that, unlike regular Tidy3D fields, ``attrs`` are mutable. For example, the following is allowed for setting an ``attr`` ``obj.attrs['foo'] = bar``. Also note that `Tidy3D`` will raise a ``TypeError`` if ``attrs`` contain objects that can not be serialized. One can check if ``attrs`` are serializable by calling ``obj.json()``.\nsimulation : Simulation\n    Simulation describing the device without any sources present.\nports : Tuple[Union[LumpedPort, CoaxialLumpedPort, WavePort], ...] = ()\n    Collection of lumped and wave ports associated with the network. For each port, one simulation will be run with a source that is associated with the port.\nfreqs : Union[tuple[float, ...], ArrayLike[dtype=float, ndim=1]]\n    [units = Hz].  Array or list of frequencies at which to compute port parameters.\nremove_dc_component : bool = True\n    Whether to remove the DC component in the Gaussian pulse spectrum. If ``True``, the Gaussian pulse is modified at low frequencies to zero out the DC component, which is usually desirable so that the fields will decay. However, for broadband simulations, it may be better to have non-vanishing source power near zero frequency. Setting this to ``False`` results in an unmodified Gaussian pulse spectrum which can have a nonzero DC component.\nfolder_name : str = default\n    Name of the folder for the tasks on web.\nverbose : bool = False\n    Whether the :class:`.AbstractComponentModeler` should print status and progressbars.\ncallback_url : Optional[str] = None\n    Http PUT url to receive simulation finish event. The body content is a json file with fields ``{'id', 'status', 'name', 'workUnit', 'solverVersion'}``.\npath_dir : str = .\n    Base directory where data and batch will be downloaded.\nsolver_version : Optional[str] = None\n        batch_cached : Optional[Batch] = None\n    Optional field to specify ``batch``. Only used as a workaround internally so that ``batch`` is written when ``.to_file()`` and then the proper batch is loaded from ``.from_file()``. We recommend leaving unset as setting this field along with fields that were not used to create the task will cause errors.\nradiation_monitors : Tuple[DirectivityMonitor, ...] = ()\n    Facilitates the calculation of figures-of-merit for antennas. These monitor will be included in every simulation and record the radiated fields. ",
+  "description": "Tool for modeling two-terminal multiport devices and computing port parameters\nwith lumped and wave ports.\n\nParameters\n----------\nattrs : dict = {}\n    Dictionary storing arbitrary metadata for a Tidy3D object. This dictionary can be freely used by the user for storing data without affecting the operation of Tidy3D as it is not used internally. Note that, unlike regular Tidy3D fields, ``attrs`` are mutable. For example, the following is allowed for setting an ``attr`` ``obj.attrs['foo'] = bar``. Also note that `Tidy3D`` will raise a ``TypeError`` if ``attrs`` contain objects that can not be serialized. One can check if ``attrs`` are serializable by calling ``obj.json()``.\nsimulation : Simulation\n    Simulation describing the device without any sources present.\nports : Tuple[Union[LumpedPort, CoaxialLumpedPort, WavePort], ...] = ()\n    Collection of lumped and wave ports associated with the network. For each port, one simulation will be run with a source that is associated with the port.\nfreqs : Union[tuple[float, ...], ArrayLike[dtype=float, ndim=1]]\n    [units = Hz].  Array or list of frequencies at which to compute port parameters.\nremove_dc_component : bool = True\n    Whether to remove the DC component in the Gaussian pulse spectrum. If ``True``, the Gaussian pulse is modified at low frequencies to zero out the DC component, which is usually desirable so that the fields will decay. However, for broadband simulations, it may be better to have non-vanishing source power near zero frequency. Setting this to ``False`` results in an unmodified Gaussian pulse spectrum which can have a nonzero DC component.\nfolder_name : str = default\n    Name of the folder for the tasks on web.\nverbose : bool = False\n    Whether the :class:`.AbstractComponentModeler` should print status and progressbars.\ncallback_url : Optional[str] = None\n    Http PUT url to receive simulation finish event. The body content is a json file with fields ``{'id', 'status', 'name', 'workUnit', 'solverVersion'}``.\npath_dir : str = .\n    Base directory where data and batch will be downloaded.\nsolver_version : Optional[str] = None\n        batch_cached : Optional[Batch] = None\n    Optional field to specify ``batch``. Only used as a workaround internally so that ``batch`` is written when ``.to_file()`` and then the proper batch is loaded from ``.from_file()``. We recommend leaving unset as setting this field along with fields that were not used to create the task will cause errors.\nrun_only : Optional[Tuple[IndexType, ...]] = None\n    Set of matrix indices that define the simulations to run. If ``None``, simulations will be run for all indices in the scattering matrix. If a tuple is given, simulations will be run only for the given matrix indices.\nelement_mappings : Tuple[tuple[~ElementType, ~ElementType, Union[tidy3d.components.types.tidycomplex, tidy3d.components.types.ComplexNumber]], ...] = ()\n    Tuple of S matrix element mappings, each described by a tuple of (input_element, output_element, coefficient), where the coefficient is the element_mapping coefficient describing the relationship between the input and output matrix element. If all elements of a given column of the scattering matrix are defined by ``element_mappings``, the simulation corresponding to this column is skipped automatically.\nradiation_monitors : Tuple[DirectivityMonitor, ...] = ()\n    Facilitates the calculation of figures-of-merit for antennas. These monitor will be included in every simulation and record the radiated fields. \nassume_ideal_excitation : bool = False\n    If ``True``, only the excited port is assumed to have incident power, so the vector of incident power wave amplitudes (a) is assumed to be all zeros except for the entry associated with the excited port. 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. ",
   "type": "object",
   "properties": {
     "attrs": {
@@ -96,6 +96,53 @@
         }
       ]
     },
+    "run_only": {
+      "title": "Run Only",
+      "description": "Set of matrix indices that define the simulations to run. If ``None``, simulations will be run for all indices in the scattering matrix. If a tuple is given, simulations will be run only for the given matrix indices.",
+      "type": "array",
+      "items": {}
+    },
+    "element_mappings": {
+      "title": "Element Mappings",
+      "description": "Tuple of S matrix element mappings, each described by a tuple of (input_element, output_element, coefficient), where the coefficient is the element_mapping coefficient describing the relationship between the input and output matrix element. If all elements of a given column of the scattering matrix are defined by ``element_mappings``, the simulation corresponding to this column is skipped automatically.",
+      "default": [],
+      "type": "array",
+      "items": {
+        "type": "array",
+        "minItems": 3,
+        "maxItems": 3,
+        "items": [
+          {},
+          {},
+          {
+            "anyOf": [
+              {
+                "title": "ComplexNumber",
+                "description": "Complex number with a well defined schema.",
+                "type": "object",
+                "properties": {
+                  "real": {
+                    "title": "Real",
+                    "type": "number"
+                  },
+                  "imag": {
+                    "title": "Imag",
+                    "type": "number"
+                  }
+                },
+                "required": [
+                  "real",
+                  "imag"
+                ]
+              },
+              {
+                "$ref": "#/definitions/ComplexNumber"
+              }
+            ]
+          }
+        ]
+      }
+    },
     "type": {
       "title": "Type",
       "default": "TerminalComponentModeler",
@@ -112,6 +159,12 @@
       "items": {
         "$ref": "#/definitions/DirectivityMonitor"
       }
+    },
+    "assume_ideal_excitation": {
+      "title": "Assume Ideal Excitation",
+      "description": "If ``True``, only the excited port is assumed to have incident power, so the vector of incident power wave amplitudes (a) is assumed to be all zeros except for the entry associated with the excited port. 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. ",
+      "default": false,
+      "type": "boolean"
     }
   },
   "required": [

tests/test_plugins/smatrix/terminal_component_modeler_def.py

@@ -276,7 +276,7 @@ def make_port(center, direction, type, name) -> Union[CoaxialLumpedPort, WavePor
                 inner_diameter=2 * Rinner,
                 normal_axis=2,
                 direction=direction,
-                name=name,
+                name="coax" + name,
                 num_grid_cells=port_cells,
                 impedance=reference_impedance,
             )
@@ -311,7 +311,7 @@ def make_port(center, direction, type, name) -> Union[CoaxialLumpedPort, WavePor
                 center=center,
                 size=[2 * Router, 2 * Router, 0],
                 direction=direction,
-                name=name,
+                name="wave" + name,
                 mode_spec=td.ModeSpec(num_modes=1),
                 mode_index=0,
                 voltage_integral=voltage_integral,
@@ -321,9 +321,9 @@ def make_port(center, direction, type, name) -> Union[CoaxialLumpedPort, WavePor
         return port
 
     center_src1 = [0, 0, -length / 2]
-    port_1 = make_port(center_src1, direction="+", type=port_types[0], name="coax_port_1")
+    port_1 = make_port(center_src1, direction="+", type=port_types[0], name="_1")
     center_src2 = [0, 0, length / 2]
-    port_2 = make_port(center_src2, direction="-", type=port_types[1], name="coax_port_2")
+    port_2 = make_port(center_src2, direction="-", type=port_types[1], name="_2")
     ports = [port_1, port_2]
     freqs = np.linspace(freq_start, freq_stop, 100)
 

tests/test_plugins/smatrix/test_component_modeler.py

@@ -374,6 +374,35 @@ def test_mapping_exclusion(monkeypatch):
     _test_mappings(element_mappings, s_matrix)
 
 
+def test_mapping_with_run_only():
+    """Make sure that the Modeler is correctly validated when both run_only and
+    element_mappings are provided."""
+    ports = make_ports()
+
+    EXCLUDE_INDEX = ("right_bot", 0)
+    element_mappings = []
+    run_only = []
+    # add a mapping to each element in the row of EXCLUDE_INDEX
+    for port in ports:
+        for mode_index in range(port.mode_spec.num_modes):
+            row_index = (port.name, mode_index)
+            run_only.append(row_index)
+            if row_index != EXCLUDE_INDEX:
+                mapping = ((row_index, row_index), (row_index, EXCLUDE_INDEX), +1)
+                element_mappings.append(mapping)
+
+    # add the self-self coupling element to complete row
+    mapping = ((("right_bot", 1), ("right_bot", 1)), (EXCLUDE_INDEX, EXCLUDE_INDEX), +1)
+    element_mappings.append(mapping)
+
+    # Will pass, since run_only covers all source indices in element_mapping
+    _ = make_component_modeler(element_mappings=element_mappings, run_only=run_only)
+
+    run_only.remove(EXCLUDE_INDEX)
+    with pytest.raises(pydantic.ValidationError):
+        _ = make_component_modeler(element_mappings=element_mappings, run_only=run_only)
+
+
 def test_batch_filename(tmp_path):
     modeler = make_component_modeler()
     path = modeler._batch_path

tests/test_plugins/smatrix/test_terminal_component_modeler.py

@@ -900,3 +900,44 @@ def test_get_combined_antenna_parameters_data(monkeypatch, tmp_path):
     assert not np.allclose(
         antenna_params.radiation_efficiency, single_port_params.radiation_efficiency
     )
+
+
+def test_run_only_and_element_mappings(monkeypatch, tmp_path):
+    """Checks the terminal component modeler works when running with a subset of excitations."""
+    z_grid = td.UniformGrid(dl=1 * 1e3)
+    xy_grid = td.UniformGrid(dl=0.1 * 1e3)
+    grid_spec = td.GridSpec(grid_x=xy_grid, grid_y=xy_grid, grid_z=z_grid)
+    modeler = make_coaxial_component_modeler(
+        path_dir=str(tmp_path), port_types=(CoaxialLumpedPort, WavePort), grid_spec=grid_spec
+    )
+    port0_idx = modeler.network_index(modeler.ports[0])
+    port1_idx = modeler.network_index(modeler.ports[1])
+    modeler_run1 = modeler.updated_copy(run_only=(port0_idx,))
+
+    # Make sure the smatrix and impedance calculations work for reduced simulations
+    s_matrix = run_component_modeler(monkeypatch, modeler_run1)
+    with pytest.raises(ValueError):
+        TerminalComponentModeler._validate_square_matrix(s_matrix, "test_method")
+    _ = modeler_run1.port_reference_impedances
+
+    assert len(modeler_run1.sim_dict) == 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),)
+    modeler_with_mappings = modeler.updated_copy(element_mappings=element_mappings)
+    assert len(modeler_with_mappings.sim_dict) == 2
+
+    # Column 1 is mapped to column 2, resulting in one simulation
+    element_mappings = ((S11, S22, 1), (S21, S12, 1))
+    modeler_with_mappings = modeler.updated_copy(element_mappings=element_mappings)
+    s_matrix = run_component_modeler(monkeypatch, modeler_with_mappings)
+    assert np.all(s_matrix.values[:, 0, 0] == s_matrix.values[:, 1, 1])
+    assert np.all(s_matrix.values[:, 0, 1] == s_matrix.values[:, 1, 0])
+    assert len(modeler_with_mappings.sim_dict) == 1
+
+    # Mapping is incomplete, so two simulations are run
+    element_mappings = ((S11, S22, 1), (S12, S21, 1))
+    modeler_with_mappings = modeler.updated_copy(element_mappings=element_mappings)
+    assert len(modeler_with_mappings.sim_dict) == 2