:orphan:

.. admonition:: Work in Progress
   :class: warning

   This document is still under development and may change frequently.

===================
S-parameters Report
===================

This report calculates scattering parameters, or S-parameters, which describe the
input-output relationships between various ports of a device.


Mathematically, for each port :math:`j` of the device, the S-parameter :math:`S_{ji}` is calculated as the overlap integral between the electric field amplitude :math:`\tilde{\mathbf{E}}`, obtained from simulation, and a specified waveguide mode :math:`\tilde{\mathbf{e}}_i`:

.. math::

   S_{ji} = \frac{\int_{\Gamma_j} \tilde{\mathbf{E}} \cdot \tilde{\mathbf{e}}_i\, d\Gamma} {\int_{\Gamma_j} \tilde{\mathbf{e}}_i \cdot \tilde{\mathbf{e}}_i\, d\Gamma} - \delta_{ik},


where the integral is taken over the plane surface :math:`\Gamma_j` of the port :math:`j`. The index :math:`k` in the Kronecker symbol :math:`\delta_{ik}` runs over the indices of all modes injected from the port :math:`j`. Thus, the Kronecker symbol :math:`\delta_{ik}` subtracts the radiation arriving through the port :math:`j`, which allows the corresponding S-parameter to be interpreted as a reflection coefficient in cases where the port of interest is also an input port.

In real simulations, the length of the waveguide with an input or output port is always fixed. However, it may be interesting to know what the phase of a given S-parameter will be at a different distance inside the waveguide. Since we assume that the field inside the waveguide propagates as a steady-state mode, its phase at different distances is known. We can use this information to calculate the S-parameter at any distance other than the one at which this parameter was originally calculated. The corresponding formula is

.. math::

   S_{ji}(l_1) = S_{ji}(l_0) e^{2i \beta_i d},

where :math:`\beta_i` is the propagation constant of the mode :math:`i` and :math:`d=l_1-l_0` is the shift distance with :math:`l_0` and :math:`l_1` being the original distance and the distance of interest.

To generate an S-parameters report, in addition to the report name, the user must specify the boundary condition corresponding to a given port :math:`j`, as well as the number of modes to consider at this port (this number will determine the range of the :math:`i` index):

.. testsetup::
   import mufem
   from mufem import Bnd
   from mufem.electromagnetics.timeharmonicmaxwell import (
       OutputPortCondition,
       SParametersReport,
   )

   sim = mufem.Simulation.New("My Case", "data/geometry.mesh")

   my_port_marker = "OutputPort" @ Bnd

   my_port_condition = OutputPortCondition("Output", my_port_marker)


.. testcode::

   my_report = SParametersReport(
      name = "My S-parameters Report",
      condition = my_port_condition,
      nmodes = 3,
   )

As an optional parameter one can also specify the shift distance :math:`d`:

.. testcode::

   my_report = SParametersReport(
      name = "My S-parameters Report",
      condition = my_port_condition,
      nmodes = 3,
      shift_distance = 1e-2,
   )

.. jupyter-execute::

   from mufem.electromagnetics.timeharmonicmaxwell import SParametersReport

   help(SParametersReport)