.. :html_theme.sidebar_secondary.remove:

:orphan:

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

.. py:module:: comyx.network.ris


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

Classes
~~~~~~~

.. autoapisummary::

   comyx.network.ris.RIS
   comyx.network.ris.STAR_RIS





Reference
---------

.. py:class:: RIS(id_: str, n_elements: int, position: Union[List[float], None] = None)


   Represents a reconfigurable intelligent surface (RIS).

   An RIS is a surface with a large number of elements that can be
   electronically controlled to reflect the incoming signal in a desired
   direction.

   Mathematically, the reflection matrix of the RIS is given by

   .. math::
       \mathbf{R} = \text{diag}(\mathbf{a} \odot \exp(j \mathbf{\Phi})),

   where :math:`\mathbf{a}` is the vector of amplitudes, :math:`\mathbf{\Phi}`
   is the vector of phase shifts, and :math:`\odot` is the Hadamard product.

   .. py:property:: amplitudes
      :type: NDArrayFloat

      Return the amplitudes of the RIS.

   .. py:property:: id
      :type: str

      Return the unique identifier of the RIS.

   .. py:property:: n_elements
      :type: int

      Return the number of elements of the RIS.

   .. py:property:: phase_shifts
      :type: NDArrayFloat

      Return the phase shifts of the RIS.

   .. py:property:: position
      :type: List[float]

      Return the position of the RIS in the environment.

   .. py:property:: reflection_matrix
      :type: NDArrayComplex

      Return the reflection matrix of the RIS.

      The reflection matrix is a diagonal matrix with the phase shifts and
      amplitudes as its diagonal elements. The phase shifts and amplitudes
      must be set before accessing the reflection matrix.

      The diagonality of the reflection matrix is due to the fact that the
      each element of the RIS reflects the incoming signal independently of
      the other elements.

      :returns: The reflection matrix of the RIS.


.. py:class:: STAR_RIS(id_: str, n_elements: int, position: Union[List[float], None] = None)


   Represents a STAR-RIS (Simultaneously Transmitting and Reflecting RIS).

   An STAR-RIS is a surface with a large number of elements that can be
   electronically controlled to reflect and transmit the incoming signal in a
   both spaces.

   Mathematically, the characteristic matrices of the STAR-RIS is given by

   .. math::
       \mathbf{R}^{n} = \text{diag}(\mathbf{a}^{n} \odot \exp(j \mathbf{\Phi}^{n})),

   where :math:`n \in \{t, r\}` and represents the transmission and reflection
   mode, respectively. Furthermore, $\mathbf{a}^{n}$ is the vector of
   amplitudes, :math:`\mathbf{\Phi}^{n}` is the vector of phase shifts, and $\odot$
   is the Hadamard product.

   Note that STAR-RIS must satisfy the law of conservation of energy, that is,
   :math:`\forall i \in \{1, \ldots, N\}` (where :math:`N` is the number of
   elements of the STAR-RIS), :math:`(a^{t}_{i})^2 + (a^{r}_{i})^2 = 1`.

   .. py:property:: id
      :type: str

      Return the unique identifier of the STAR-RIS.

   .. py:property:: n_elements
      :type: int

      Return the number of antennas of the STAR-RIS.

   .. py:property:: position
      :type: List[float]

      Return the position of the STAR-RIS in the environment.

   .. py:property:: reflection_amplitudes
      :type: NDArrayFloat

      Return the reflection amplitudes of the STAR-RIS.

   .. py:property:: reflection_matrix
      :type: NDArrayComplex

      Return the reflection matrix of the STAR-RIS.

      The reflection matrix is a diagonal matrix with the phase shifts and
      amplitudes as its diagonal elements. The phase shifts and amplitudes
      must be set before accessing the reflection matrix.

      The diagonality of the reflection matrix is due to the fact that the
      each element of the RIS reflects the incoming signal independently of
      the other elements.

      :returns: The reflection matrix of the RIS.

   .. py:property:: reflection_phases
      :type: NDArrayFloat

      Return the reflection phase shifts of the STAR-RIS.

   .. py:property:: transmission_amplitudes
      :type: NDArrayFloat

      Return the transmission amplitudes of the STAR-RIS.

   .. py:property:: transmission_matrix
      :type: NDArrayComplex

      Return the transmission matrix of the STAR-RIS.

      The transmission matrix is a diagonal matrix with the phase shifts and
      amplitudes as its diagonal elements. The phase shifts and amplitudes
      must be set before accessing the transmission matrix.

      The diagonality of the transmission matrix is due to the fact that the
      each element of the RIS reflects the incoming signal independently of
      the other elements.

      :returns: The transmission matrix of the STAR-RIS.

   .. py:property:: transmission_phases
      :type: NDArrayFloat

      Return the transmission phase shifts of the STAR-RIS.