.. :html_theme.sidebar_secondary.remove:

:py:mod:`comyx.fading`
======================

.. py:module:: comyx.fading


Package Summary
----------------

Classes
~~~~~~~

.. autoapisummary::

   comyx.fading.Nakagami
   comyx.fading.Rayleigh
   comyx.fading.Rician



Functions
~~~~~~~~~

.. autoapisummary::

   comyx.fading.get_rvs




Reference
---------

.. py:class:: Nakagami(m: float, omega: float = 1)


   Represents the :math:`\text{Nakagami}(m, \Omega)` distribution.

   The Nakagami distribution or the Nakagami-m distribution is a
   probability distribution related to the gamma distribution. The family
   of Nakagami distributions has two parameters: a shape parameter
   :math:`m` with :math:`m\geq 1/2` and a second parameter controlling
   spread :math:`\Omega > 0`.

   Density Function
       .. math::
           f(x; m, \Omega) = \frac{2m^m}{\Gamma(m)\Omega^m} x^{2m - 1} \exp\left(-\frac{m}{\Omega}x^2\right)

   , where :math:`\Gamma(.)` is the gamma function.

   Expected value
       .. math::
           \sqrt{\frac{\Omega}{m}} \frac{\Gamma\left(m + \frac{1}{2}\right)}{\Gamma(m)}


   Variance
       .. math::
           \Omega \left(1 - \frac{1}{m}\left(\frac{\Gamma\left(m + \frac{1}{2}\right)}{\Gamma(m)}\right)^2\right)

   Reference:
       https://en.wikipedia.org/wiki/Nakagami_distribution

   .. py:method:: cdf(x: NDArrayFloat) -> NDArrayFloat

      Cumulative distribution function of the Nakagami distribution.

      :param x: Value at which cdf is evaluated.

      :returns: Value of the cumulative distribution function evaluated at x.


   .. py:method:: expected_value() -> float

      Returns the expected value of the Nakagami distribution.


   .. py:method:: get_samples(size: Union[int, Tuple[int, Ellipsis]], seed: int = None) -> NDArrayFloat

      Generate random variables from the Nakagami distribution.

      :param size: Number of random variables to generate.
      :param seed: Seed for the random number generator.

      :returns: An array of size `size` containing random variables from the
                Nakagami distribution.


   .. py:method:: pdf(x: NDArrayFloat) -> NDArrayFloat

      Probability density function of the Nakagami distribution.

      :param x: Value at which pdf is evaluated.

      :returns: Value of the probability density function evaluated at x.


   .. py:method:: variance() -> float

      Returns the variance of the Nakagami distribution.



.. py:class:: Rayleigh(sigma: float = 1)


   Represents the :math:`\text{Rayleigh}(\sigma)` distribution.

   The Rayleigh distribution is a continuous probability distribution for
   nonnegative-valued random variables. Up to rescaling, it coincides with
   the chi distribution with two degrees of freedom.

   Density function
       .. math::
           f(x; \sigma) = \frac{x}{\sigma^2} \cdot \exp\left(-\frac{x^2}{2\sigma^2}\right)

   Expected value
       .. math::
           \sigma \cdot \sqrt{\frac{\pi}{2}}

   Variance
       .. math::
           \left(2 - \frac{\pi}{2}\right) \cdot \sigma^2

   RMS value
       .. math::
           \sqrt{2} \cdot \sigma

   Reference:
       https://en.wikipedia.org/wiki/Rayleigh_distribution

   .. py:method:: cdf(x: NDArrayFloat) -> NDArraySigned

      Cumulative distribution function of the Rayleigh distribution.

      :param x: Value at which cdf is evaluated.

      :returns: Value of the cumulative distribution function evaluated at x.


   .. py:method:: expected_value() -> float

      Returns the expected value of the Rayleigh distribution.


   .. py:method:: get_samples(size: Union[int, Tuple[int, Ellipsis]], seed: int = None) -> NDArrayFloat

      Generates random variables from the Rayleigh distribution.

      :param size: Number of random variables to generate.
      :param seed: Seed for the random number generator.

      :returns: An array of size `size` containing random variables from the
                Rayleigh distribution.


   .. py:method:: pdf(x: NDArrayFloat) -> NDArrayFloat

      Probability density function of the Rayleigh distribution.

      :param x: Value at which pdf is evaluated.

      :returns: Value of the probability density function evaluated at x.


   .. py:method:: rms_value() -> float

      Returns the RMS value of the Rayleigh distribution.


   .. py:method:: variance() -> float

      Returns the variance of the Rayleigh distribution.



.. py:class:: Rician(K: float, sigma: float = 1)


   Represents the :math:`\text{Rician}(K, \sigma)` distribution.

   The Rice distribution or Rician distribution (or, less commonly, Ricean
   distribution) is the probability distribution of the magnitude of a
   circularly-symmetric bivariate normal random variable, possibly with
   non-zero mean (noncentral).

   Density Function
       .. math::
           f(x; \nu, \sigma) = \frac{x}{\sigma^2} \exp\left(-\frac{x^2 + \nu^2}{2\sigma^2}\right) I_0\left(\frac{x\nu}{\sigma^2}\right)

   , where :math:`I_0` is the modified Bessel function of the first kind.

   Expected value
       .. math::
           \sigma \sqrt{\frac{\pi}{2}} \exp\left(-\frac{\nu^2}{2\sigma^2}\right)

   Variance
       .. math::
           2\sigma^2 + \nu^2 - \frac{\pi\sigma^2}{2}

   RMS value
       .. math::
           \sigma \sqrt{2 + \frac{\pi}{2}}

   Reference:
       https://en.wikipedia.org/wiki/Rice_distribution

   .. py:method:: cdf(x: NDArrayFloat) -> NDArrayFloat

      Cumulative distribution function of the the Rician distribution.

      :param x: Value at which cdf is evaluated.

      :returns: Value of the cumulative distribution function evaluated at x.


   .. py:method:: expected_value() -> float

      Returns the expected value of the Rician distribution.


   .. py:method:: get_samples(size: Union[int, Tuple[int, Ellipsis]], seed: int = None) -> NDArrayFloat

      Generate random variables from the Rician distribution.

      :param size: Nnumber of random variables to generate.
      :param seed: Seed for the random number generator.

      :returns: An array of size `size` containing random variables from the Rician
                distribution.


   .. py:method:: pdf(x: NDArrayFloat) -> NDArrayFloat

      Probability density function of the Rician distribution.

      :param x: Value at which pdf is evaluated.

      :returns: Value of the probability density function evaluated at x.


   .. py:method:: rms_value() -> float

      Returns the RMS value of the Rician distribution.


   .. py:method:: variance() -> float

      Returns the variance of the Rician distribution.



.. py:function:: get_rvs(shape: Union[int, Tuple[int, Ellipsis]], type: str, seed: Optional[int] = None, *args, **kwargs) -> NDArrayComplex

   Generates random variables from a distribution.

   Rayleigh
       - ``sigma``- Scale parameter of the Rayleigh distribution.

   Rician
       - ``K`` - Rician K-factor in dB.
       - ``sigma`` - Scale parameter of the Rician distribution.

   Nakagami
       - ``m`` - Shape parameter of the Nakagami distribution.
       - ``omega`` - Scale parameter of the Nakagami distribution.

   :param shape: Number of fading samples to generate.
   :param type: Type of the fading. ("rayleigh", "rician", "nakagami")
   :param seed: Seed for the random number generator.

   :returns: Channel gains.