.. :html_theme.sidebar_secondary.remove:

:orphan:

:py:mod:`comyx.network.links`
=============================

.. py:module:: comyx.network.links


Module Summary
---------------

Classes
~~~~~~~

.. autoapisummary::

   comyx.network.links.Link



Functions
~~~~~~~~~

.. autoapisummary::

   comyx.network.links.cascaded_channel_gain
   comyx.network.links.effective_channel_gain




Reference
---------

.. py:class:: Link(tx: comyx.network.transceiver.Transceiver | comyx.network.ris.RIS, rx: comyx.network.transceiver.Transceiver | comyx.network.ris.RIS, fading_args: dict[str, Any], pathloss_args: dict[str, Any], shape: Tuple[int, Ellipsis], rician_args: Union[dict[str, Any], None] = None, custom_rvs: Union[NDArrayComplex, None] = None, distance: Union[float, None] = None, seed: Union[int, None] = None)


   Represents a link in the modelled environment.

   A link is a connection between two transceivers. It is characterized by the
   distance between the two transceivers, the path loss, and the channel gain.

   If rician_args are provided, the fading_args are used for the NLOS component
   and the rician_args are used for the LOS component.

   Mathematically, the channel gain is given by

   .. math::
       h_{t,r} = g_{t,r} \sqrt{PL(d_{t,r})},

   where :math:`g_{t,r}` is the small-scale fading (sampled from a
   distribution), :math:`PL(d_{t,r})` is the path loss, and
   :math:`d_{t,r}` is the distance between the transceivers.

   .. attribute:: tx

      Transmitter of the link.

   .. attribute:: rx

      Receiver of the link.

   .. attribute:: shape

      Number of shape for the channel gain.

   .. py:property:: channel_gain
      :type: NDArrayComplex

      Channel gain between the transceivers.

   .. py:property:: distance
      :type: float

      Distance between the transceivers.

   .. py:property:: magnitude
      :type: NDArrayFloat

      Magnitude of the channel

   .. py:property:: pathloss
      :type: NDArrayFloat

      Path loss between the transceivers.

   .. py:property:: phase
      :type: NDArrayFloat

      Phase of the channel

   .. py:method:: generate_rvs(custom_rvs: NDArrayComplex | None = None, seed: int = None) -> None

      Generate random variables for the channel gain.

      Not private to allow for the generation of new channel gains for more
      flexible simulations.


   .. py:method:: rician_fading(K: float, order: str = 'post', ris: bool = True) -> NDArrayComplex

      Generate Rician fading channel gain between the transceivers.

      :param K: Rician K-factor.
      :param pos_a: Position of the first transceiver.
      :param pos_b: Position of the second transceiver.
      :param order: Order of RIS in the link.
                    Possible values are 'post' and 'pre'.
      :param ris: Whether to consider the RIS in the link.

      :returns: Rician fading channel gain.


   .. py:method:: update_channel(distance: Union[float, None] = None, custom_rvs: NDArrayComplex | None = None, ex_pathloss: bool = False, ex_rvs: bool = False, seed: Union[int, None] = None) -> None

      Update the channel gain.

      :param distance: New distance between the transceivers.
      :param custom_rvs: New random variables for the channel gain.
      :param ex_pathloss: Whether to exclude distance-based params from the update.
      :param ex_rvs: Whether to exclude the random variables from the update.
      :param seed: Seed for the random number generator.


   .. py:method:: update_params(distance: Union[float, None] = None) -> None

      Update the parameters of the link.

      :param distance: New distance between the transceivers.



.. py:function:: cascaded_channel_gain(tR_link: Link, Rr_link: Link, style: str = 'sum', ele_idx: int = 0) -> NDArrayComplex

   Calculate the cascaded channel gain.

   The cascaded channel gain is the channel gain between the transmitter and
   the receiver through the RIS. Mathematically, the cascaded channel gain
   through the RIS is given by

   .. math::
       h_{csc}= \mathbf{h}_{R,r}^T \mathbf{R} \mathbf{h}_{t,R},

   where :math:`\mathbf{h}_{t,R}` is the channel gain between the transmitter
   and the RIS, :math:`\mathbf{h}_{R,r}` is the channel gain between the RIS
   and the receiver, and :math:`\mathbf{R}` is the reflection matrix of the
   RIS. The superscript :math:`T` denotes the transpose operator.

   If channel_gain_tR is of shape (Nt, K, Mc), and channel_gain_Rr is of shape
   (K, Nr, Mc), where Nt is the number of transmit antennas, K is the number of
   RIS elements, Nr is the number of receive antennas, and Mc is the number of
   channel realizations, then the cascaded channel gain is of shape (Nt, Nr,
   Mc). For SISO links, the cascaded channel gain is of shape (1, 1, Mc).

   :param tR_link: Link between the transmitter and the RIS.
   :param Rr_link: Link between the RIS and the receiver.
   :param style: Formula used to calculate the cascaded channel gain.
                 Possible values are 'sum' and 'matrix'.
   :param ele_idx: Index of the elements of RIS in channel gain matrix.

   :returns: Cascaded channel gain.


.. py:function:: effective_channel_gain(tr_link: Link, tR_link: Link, Rr_link: Link, style: str = 'sum', ele_idx: int = 0) -> NDArrayComplex

   Calculate the effective channel gain.

   The effective channel gain is the channel gain between the transceiver and
   the receiver through the RIS. Mathematically, the effective channel gain
   through the RIS is given by

   .. math::
       h_{eff}= h_{t,r} + \mathbf{h}_{R,r}^T \mathbf{R} \mathbf{h}_{t,R},

   where :math:`\mathbf{h}_{t,R}` is the channel gain between the transmitter
   and the RIS, :math:`\mathbf{h}_{R,r}` is the channel gain between the RIS
   and the receiver, :math:`\mathbf{R}` is the reflection matrix of the RIS,
   and :math:`h_{t,r}` is the channel gain between the transmitter and the
   receiver. The superscript :math:`T` denotes the transpose operator.

   :param tr: Direct link.
   :param tR: Link between the transmitter and the RIS.
   :param Rr: Link between the RIS and the receiver.
   :param style: Formula used to calculate the cascaded channel gain.
                 Possible values are 'sum' and 'matrix'.
   :param ele_idx: Index of the elements of RIS in channel gain matrix.

   :returns: Effective channel gain.