Documentation and file paths

Author: daquinteroflex

tidy3d/plugins/smatrix/__init__.py

@@ -6,7 +6,7 @@
 
 from .component_modelers.modal import AbstractComponentModeler, ComponentModeler, ModalPortDataArray
 from .component_modelers.terminal import TerminalComponentModeler
-from .data.terminal import PortDataArray, TerminalPortDataArray
+from .data.data_array import PortDataArray, TerminalPortDataArray
 from .ports.coaxial_lumped import CoaxialLumpedPort
 from .ports.modal import Port
 from .ports.rectangular_lumped import LumpedPort

tidy3d/plugins/smatrix/component_modelers/terminal.py

@@ -28,7 +28,7 @@
     AbstractComponentModeler,
     TerminalPortType,
 )
-from tidy3d.plugins.smatrix.data.terminal import PortDataArray, TerminalPortDataArray
+from tidy3d.plugins.smatrix.data.data_array import PortDataArray, TerminalPortDataArray
 from tidy3d.plugins.smatrix.ports.base_lumped import AbstractLumpedPort
 from tidy3d.plugins.smatrix.ports.coaxial_lumped import CoaxialLumpedPort
 from tidy3d.plugins.smatrix.ports.rectangular_lumped import LumpedPort
@@ -304,6 +304,7 @@ def run(self, path_dir: str = DEFAULT_DATA_DIR):
     ##### Backwards compatibility methods #####
     @staticmethod
     def _check_port_impedance_sign(Z_numpy: np.ndarray):
+        """Sanity check for consistent sign of real part of Z for each port across all frequencies."""
         from tidy3d.plugins.smatrix.utils import check_port_impedance_sign
 
         return check_port_impedance_sign(Z_numpy)
@@ -317,6 +318,7 @@ def _compute_F(Z_numpy: np.array):
         return compute_F(Z_numpy)
 
     def _construct_smatrix(self) -> TerminalPortDataArray:
+        """Post process :class:`.BatchData` to generate scattering matrix."""
         from tidy3d.plugins.smatrix.local_run import construct_smatrix
 
         return construct_smatrix(self)
@@ -387,6 +389,7 @@ def _upload_terminal_modeler(self):
     def ab_to_s(
         a_matrix: TerminalPortDataArray, b_matrix: TerminalPortDataArray
     ) -> TerminalPortDataArray:
+        """Get the scattering matrix given the power wave matrices."""
         from tidy3d.plugins.smatrix.utils import ab_to_s
 
         return ab_to_s(a_matrix=a_matrix, b_matrix=b_matrix)
@@ -395,13 +398,42 @@ def ab_to_s(
     def compute_port_VI(
         port_out: TerminalPortType, sim_data: SimulationData
     ) -> tuple[FreqDataArray, FreqDataArray]:
+        """Compute the port voltages and currents.
+
+        Parameters
+        ----------
+        port_out : ``TerminalPortType``
+            Port for computing voltage and current.
+        sim_data : :class:`.SimulationData`
+            Results from simulation containing field data.
+
+        Returns
+        -------
+        tuple[FreqDataArray, FreqDataArray]
+            Voltage and current values at the port as frequency arrays.
+        """
         from tidy3d.plugins.smatrix.utils import compute_port_VI
 
         return compute_port_VI(port_out=port_out, sim_data=sim_data)
 
     def compute_power_wave_amplitudes_at_each_port(
         self, port_reference_impedances: PortDataArray, sim_data: SimulationData
     ) -> tuple[PortDataArray, PortDataArray]:
+        """Compute the incident and reflected power wave amplitudes at each port.
+        The computed amplitudes have not been normalized.
+
+        Parameters
+        ----------
+        port_reference_impedances : :class:`.PortDataArray`
+            Reference impedance at each port.
+        sim_data : :class:`.SimulationData`
+            Results from the simulation.
+
+        Returns
+        -------
+        tuple[:class:`.PortDataArray`, :class:`.PortDataArray`]
+            Incident (a) and reflected (b) power wave amplitudes at each port.
+        """
         from tidy3d.plugins.smatrix.local_run import compute_power_wave_amplitudes_at_each_port
 
         data = compute_power_wave_amplitudes_at_each_port(
@@ -413,6 +445,20 @@ def compute_power_wave_amplitudes_at_each_port(
     def compute_power_delivered_by_port(
         port: Union[LumpedPort, CoaxialLumpedPort], sim_data: SimulationData
     ) -> FreqDataArray:
+        """Compute the power delivered to the network by a lumped port.
+
+        Parameters
+        ----------
+        port : Union[:class:`.LumpedPort`, :class:`.CoaxialLumpedPort`]
+            Port for computing voltage and current.
+        sim_data : :class:`.SimulationData`
+            Results from the simulation.
+
+        Returns
+        -------
+        FreqDataArray
+            Power in units of Watts as a frequency array.
+        """
         from tidy3d.plugins.smatrix.utils import compute_power_delivered_by_port
 
         return compute_power_delivered_by_port(port=port, sim_data=sim_data)
@@ -421,6 +467,21 @@ def compute_power_delivered_by_port(
     def compute_power_wave_amplitudes(
         port: Union[LumpedPort, CoaxialLumpedPort], sim_data: SimulationData
     ) -> tuple[FreqDataArray, FreqDataArray]:
+        """Compute the incident and reflected power wave amplitudes at a lumped port.
+        The computed amplitudes have not been normalized.
+
+        Parameters
+        ----------
+        port : Union[:class:`.LumpedPort`, :class:`.CoaxialLumpedPort`]
+            Port for computing voltage and current.
+        sim_data : :class:`.SimulationData`
+            Results from the simulation.
+
+        Returns
+        -------
+        tuple[FreqDataArray, FreqDataArray]
+            Incident (a) and reflected (b) power wave amplitude frequency arrays.
+        """
         from tidy3d.plugins.smatrix.utils import compute_power_wave_amplitudes
 
         return compute_power_wave_amplitudes(port=port, sim_data=sim_data)
@@ -443,6 +504,9 @@ def get_antenna_metrics_data(
 
     @cached_property
     def port_reference_impedances(self) -> PortDataArray:
+        """Tabulates the reference impedance of each port at each frequency using the
+        supplied :class:`.BatchData`.
+        """
         from tidy3d.plugins.smatrix.data.data import (
             MicrowaveSMatrixData,
             TerminalComponentModelerData,
@@ -458,6 +522,7 @@ def port_reference_impedances(self) -> PortDataArray:
     def s_to_z(
         s_matrix: TerminalPortDataArray, reference: Union[complex, PortDataArray]
     ) -> DataArray:
+        """Get the impedance matrix given the scattering matrix and a reference impedance."""
         from tidy3d.plugins.smatrix.utils import s_to_z
 
         return s_to_z(s_matrix=s_matrix, reference=reference)

tidy3d/plugins/smatrix/data/data.py

@@ -17,7 +17,7 @@
     TerminalPortType,
 )
 from tidy3d.plugins.smatrix.component_modelers.terminal import TerminalComponentModeler
-from tidy3d.plugins.smatrix.data.terminal import PortDataArray, TerminalPortDataArray
+from tidy3d.plugins.smatrix.data.data_array import PortDataArray, TerminalPortDataArray
 
 
 class MicrowavePortSimulationData(Tidy3dBaseModel):

tidy3d/plugins/smatrix/data/terminal.py renamed to tidy3d/plugins/smatrix/data/data_array.py

@@ -7,7 +7,7 @@
 import numpy as np
 
 from tidy3d.components.data.sim_data import SimulationData
-from tidy3d.plugins.smatrix.data.terminal import PortDataArray, TerminalPortDataArray
+from tidy3d.plugins.smatrix.data.data_array import PortDataArray, TerminalPortDataArray
 from tidy3d.plugins.smatrix.ports.wave import WavePort
 from tidy3d.plugins.smatrix.utils import check_port_impedance_sign, compute_F, compute_port_VI
 

tidy3d/plugins/smatrix/local_run.py

@@ -11,7 +11,7 @@
     AbstractComponentModeler,
     TerminalPortType,
 )
-from tidy3d.plugins.smatrix.data.terminal import PortDataArray, TerminalPortDataArray
+from tidy3d.plugins.smatrix.data.data_array import PortDataArray, TerminalPortDataArray
 from tidy3d.plugins.smatrix.ports.coaxial_lumped import CoaxialLumpedPort
 from tidy3d.plugins.smatrix.ports.rectangular_lumped import LumpedPort