Scattering matrix equation
==========================

The scattering matrix is one of the ways to describe a microwave device. The
:math:`S`-parameters of the device act as elements of this matrix. The matrix equation
relates the waves reflected from the input and output to the waves incident on the input
and output.

**Notes:**

#. For definitions of :math:`a` and :math:`b` presented below, refer
   `here (Wikipedia) <https://en.wikipedia.org/wiki/Scattering_parameters#A_definition>`__.

**Links:**

#. `Wikipedia <https://en.wikipedia.org/wiki/Scattering_parameters#Two-port_S-parameters>`__.

..
    TODO: rename file

.. py:currentmodule:: symplyphysics.laws.electricity.circuits.transmission_lines.scattering_matrix

.. py:data:: input_reflected_power_wave

    Outgoing ("reflected") power wave at input port.

Symbol:
    :code:`b_i`

Latex:
    :math:`b_\text{i}`

Dimension:
    :code:`sqrt(power)`


.. py:data:: output_reflected_power_wave

    Outgoing ("reflected") power wave at output port.

Symbol:
    :code:`b_o`

Latex:
    :math:`b_\text{o}`

Dimension:
    :code:`sqrt(power)`


.. py:data:: input_incident_power_wave

    Incident power wave at input port.

Symbol:
    :code:`a_i`

Latex:
    :math:`a_\text{i}`

Dimension:
    :code:`sqrt(power)`


.. py:data:: output_incident_power_wave

    Incident power wave at output port.

Symbol:
    :code:`a_o`

Latex:
    :math:`a_\text{o}`

Dimension:
    :code:`sqrt(power)`


.. py:data:: input_voltage_reflection_coefficient

    Input port :attr:`~symplyphysics.symbols.electrodynamics.voltage` :attr:`~symplyphysics.symbols.electrodynamics.reflection_coefficient`.

Symbol:
    :code:`S_ii`

Latex:
    :math:`S_\text{ii}`

Dimension:
    :code:`dimensionless`


.. py:data:: reverse_voltage_gain

    Reverse :attr:`~symplyphysics.symbols.electrodynamics.voltage` :attr:`~symplyphysics.symbols.electrodynamics.circuit_gain`.

Symbol:
    :code:`S_io`

Latex:
    :math:`S_\text{io}`

Dimension:
    :code:`dimensionless`


.. py:data:: forward_voltage_gain

    Forward :attr:`~symplyphysics.symbols.electrodynamics.voltage` :attr:`~symplyphysics.symbols.electrodynamics.circuit_gain`.

Symbol:
    :code:`S_oi`

Latex:
    :math:`S_\text{oi}`

Dimension:
    :code:`dimensionless`


.. py:data:: output_voltage_reflection_coefficient

    Output port :attr:`~symplyphysics.symbols.electrodynamics.voltage` :attr:`~symplyphysics.symbols.electrodynamics.reflection_coefficient`.

Symbol:
    :code:`S_oo`

Latex:
    :math:`S_\text{oo}`

Dimension:
    :code:`dimensionless`


.. py:data:: law

    :code:`[b_i, b_o] = [[S_ii, S_io], [S_oi, S_oo]]*[a_i, a_o]`


    Latex:
        .. math::
            \begin{pmatrix} b_\text{i} \\ b_\text{o} \end{pmatrix} = \begin{pmatrix} S_\text{ii} & S_\text{io} \\ S_\text{oi} & S_\text{oo} \end{pmatrix} \begin{pmatrix} a_\text{i} \\ a_\text{o} \end{pmatrix}