Improve docs

Author: daquinteroflex

tidy3d/plugins/smatrix/utils.py

@@ -19,7 +19,18 @@
 def ab_to_s(
     a_matrix: TerminalPortDataArray, b_matrix: TerminalPortDataArray
 ) -> TerminalPortDataArray:
-    """Get the scattering matrix given the power wave matrices."""
+    """Get the scattering matrix given the power wave matrices.
+
+    The scattering matrix S is computed from the incident (a) and reflected (b)
+    power wave amplitude matrices using the formula :math:`S = b * a^-1`.
+
+    Args:
+        a_matrix: Matrix of incident power wave amplitudes.
+        b_matrix: Matrix of reflected power wave amplitudes.
+
+    Returns:
+        The computed scattering (S) matrix.
+    """
     # Ensure dimensions are ordered properly
     a_matrix = a_matrix.transpose(*TerminalPortDataArray._dims)
     b_matrix = b_matrix.transpose(*TerminalPortDataArray._dims)
@@ -35,7 +46,19 @@ def ab_to_s(
 
 
 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."""
+    """Sanity check for consistent sign of real part of Z for each port.
+
+    This check iterates through each port and ensures that the sign of the real
+    part of its impedance does not change across all frequencies. A sign change
+    can indicate an unphysical result or numerical instability.
+
+    Args:
+        Z_numpy: NumPy array of impedance values with shape (num_freqs, num_ports).
+
+    Raises:
+        Tidy3dError: If an inconsistent sign of the real part of the impedance
+            is detected for any port.
+    """
     for port_idx in range(Z_numpy.shape[1]):
         port_Z = Z_numpy[:, port_idx]
         signs = np.sign(np.real(port_Z))
@@ -48,8 +71,18 @@ def check_port_impedance_sign(Z_numpy: np.ndarray):
 
 
 def compute_F(Z_numpy: np.array):
-    """Helper to convert port impedance matrix to F, which is used for
-    computing generalized scattering parameters."""
+    r"""Helper to convert port impedance matrix to F for generalized S-parameters.
+
+    The matrix F is used when converting between S and Z parameters for circuits
+    with differing port impedances. Its diagonal elements are defined as
+    :math:`F_{kk} = 1 / (2 * \sqrt{Re(Z_k)})`.
+
+    Args:
+        Z_numpy: NumPy array of complex port impedances.
+
+    Returns:
+        NumPy array containing the computed F values.
+    """
     return 1.0 / (2.0 * np.sqrt(np.real(Z_numpy)))
 
 
@@ -78,8 +111,12 @@ def compute_port_VI(
 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.
+    """Calculates the unnormalized power wave amplitudes from port voltage (V),
+    current (I), and impedance (Z0) using:
+
+    .. math::
+        a = (V + Z0*I) / (2 * sqrt(Re(Z0)))
+        b = (V - Z0*I) / (2 * sqrt(Re(Z0)))
 
     Parameters
     ----------
@@ -105,6 +142,9 @@ def compute_power_delivered_by_port(
 ) -> FreqDataArray:
     """Compute the power delivered to the network by a lumped port.
 
+    The power is calculated as the incident power minus the reflected power:
+    P = 0.5 * (|a|^2 - |b|^2).
+
     Parameters
     ----------
     port : Union[:class:`.LumpedPort`, :class:`.CoaxialLumpedPort`]
@@ -123,7 +163,19 @@ def compute_power_delivered_by_port(
 
 
 def s_to_z(s_matrix: TerminalPortDataArray, reference: Union[complex, PortDataArray]) -> DataArray:
-    """Get the impedance matrix given the scattering matrix and a reference impedance."""
+    """Get the impedance matrix given the scattering matrix and a reference impedance.
+
+    This function converts an S-matrix to a Z-matrix. It handles both a single
+    uniform reference impedance and generalized per-port reference impedances.
+
+    Args:
+        s_matrix: The scattering (S) matrix to convert.
+        reference: The reference impedance. Can be a single complex value for all
+            ports or a PortDataArray for per-port impedances.
+
+    Returns:
+        The computed impedance (Z) matrix as a DataArray.
+    """
 
     # Ensure dimensions are ordered properly
     z_matrix = s_matrix.transpose(*TerminalPortDataArray._dims).copy(deep=True)