
    sga[                     `	   d dl mZmZ d dlZd dlmZ d dlmZ d dlmZm	Z	m
Z
 g dZ e
 e	d      edd	i      Zd
 Zdededej                   dej"                  ddf
dZ ed dj&                  dEi e      ddddej(                  ddddedee   dededeej                      dej"                  deej.                     dedefd       Z ed dj&                  dEi e      ddej(                  ddddededeej                      dej"                  deej.                     dedefd        Z ed! d"j&                  dEi e      dddej(                  ddd#ded$ededeej                      dej"                  deej.                     dedefd%       Z ed& d'j&                  dEi e      d(ddej(                  ddd)ded*ededeej                      dej"                  deej.                     dedefd+       Z ed, d-j&                  dEi e      ddej(                  ddddededeej                      dej"                  deej.                     dedefd.       Z ed/ d0j&                  dEi e      ddej(                  ddddededeej                      dej"                  deej.                     dedefd1       Z ed2 d3j&                  dEi e      ddej(                  ddddededeej                      dej"                  deej.                     dedefd4       Z ed5 d6j&                  dEi e      ddej(                  ddddededeej                      dej"                  deej.                     dedefd7       Z ed8 d9j&                  dEi e      ddej(                  dddd:ededeej                      dej"                  deej.                     dedefd;       Z  ed< d=j&                  dEi e      d>ddej(                  ddd?d@ededeej                      dej"                  deej.                     dedefdA       Z! edB dCj&                  dEi e      ddej(                  ddddededeej                      dej"                  deej.                     dedefdD       Z"y)F    )OptionalIterableN)sqrt)Tensor)factory_common_argsparse_kwargsmerge_dicts)bartlettblackmancosineexponentialgaussiangeneral_cosinegeneral_hamminghamminghannkaisernuttalla6  
    M (int): the length of the window.
        In other words, the number of points of the returned window.
    sym (bool, optional): If `False`, returns a periodic window suitable for use in spectral analysis.
        If `True`, returns a symmetric window suitable for use in filter design. Default: `True`.
normalizationzThe window is normalized to 1 (maximum value is 1). However, the 1 doesn't appear if :attr:`M` is even and :attr:`sym` is `True`.c                        fd}|S )a8  Adds docstrings to a given decorated function.

    Specially useful when then docstrings needs string interpolation, e.g., with
    str.format().
    REMARK: Do not use this function if the docstring doesn't need string
    interpolation, just write a conventional docstring.

    Args:
        args (str):
    c                 4    dj                        | _        | S )N )join__doc__)oargss    O/var/www/html/venv/lib/python3.12/site-packages/torch/signal/windows/windows.py	decoratorz_add_docstr.<locals>.decorator6   s    GGDM	     )r   r   s   ` r   _add_docstrr!   *   s     r   function_nameMdtypelayoutreturnc                     |dk  rt        |  d|       |t        j                  urt        |  d|       |t        j                  t        j                  fvrt        |  d|       y)a  Performs common checks for all the defined windows.
     This function should be called before computing any window.

     Args:
         function_name (str): name of the window function.
         M (int): length of the window.
         dtype (:class:`torch.dtype`): the desired data type of returned tensor.
         layout (:class:`torch.layout`): the desired layout of returned tensor.
     r   z, requires non-negative window length, got M=z/ is implemented for strided tensors only, got: z) expects float32 or float64 dtypes, got: N)
ValueErrortorchstridedfloat32float64)r"   r#   r$   r%   s       r   _window_function_checksr-   =   s|     	1uM?*VWXVYZ[[U]]"M?*YZ`YabccU]]EMM22M?*STYSZ[\\ 3r   z
Computes a window with an exponential waveform.
Also known as Poisson window.

The exponential window is defined as follows:

.. math::
    w_n = \exp{\left(-\frac{|n - c|}{\tau}\right)}

where `c` is the ``center`` of the window.
    aF  

{normalization}

Args:
    {M}

Keyword args:
    center (float, optional): where the center of the window will be located.
        Default: `M / 2` if `sym` is `False`, else `(M - 1) / 2`.
    tau (float, optional): the decay value.
        Tau is generally associated with a percentage, that means, that the value should
        vary within the interval (0, 100]. If tau is 100, it is considered the uniform window.
        Default: 1.0.
    {sym}
    {dtype}
    {layout}
    {device}
    {requires_grad}

Examples::

    >>> # Generates a symmetric exponential window of size 10 and with a decay value of 1.0.
    >>> # The center will be at (M - 1) / 2, where M is 10.
    >>> torch.signal.windows.exponential(10)
    tensor([0.0111, 0.0302, 0.0821, 0.2231, 0.6065, 0.6065, 0.2231, 0.0821, 0.0302, 0.0111])

    >>> # Generates a periodic exponential window and decay factor equal to .5
    >>> torch.signal.windows.exponential(10, sym=False,tau=.5)
    tensor([4.5400e-05, 3.3546e-04, 2.4788e-03, 1.8316e-02, 1.3534e-01, 1.0000e+00, 1.3534e-01, 1.8316e-02, 2.4788e-03, 3.3546e-04])
          ?TF)centertausymr$   r%   devicerequires_gradr/   r0   r1   r2   r3   c          	         |t        j                         }t        d| ||       |dk  rt        d| d      |r|t        d      | dk(  rt        j                  d||||      S ||s| dkD  r| n| dz
  d	z  }d|z  }t        j
                  | |z  | | dz
  z   |z  | ||||
      }	t        j                  t        j                  |	             S )Nr   r   zTau must be positive, got: 	 instead.z)Center must be None for symmetric windowsr   r$   r%   r2   r3             @startendstepsr$   r%   r2   r3   )r)   get_default_dtyper-   r(   emptylinspaceexpabs)
r#   r/   r0   r1   r$   r%   r2   r3   constantks
             r   r   r   O   s    r }'')M1eV<
ax6se9EFF
v!DEEAv{{4uVFZghh~1q5!a!es:3wHfWx/#Gq1u-9"$$%2	4A 99eiil]##r   a  
Computes a window with a simple cosine waveform, following the same implementation as SciPy.
This window is also known as the sine window.

The cosine window is defined as follows:

.. math::
    w_n = \sin\left(\frac{\pi (n + 0.5)}{M}\right)

This formula differs from the typical cosine window formula by incorporating a 0.5 term in the numerator,
which shifts the sample positions. This adjustment results in a window that starts and ends with non-zero values.

a  

{normalization}

Args:
    {M}

Keyword args:
    {sym}
    {dtype}
    {layout}
    {device}
    {requires_grad}

Examples::

    >>> # Generates a symmetric cosine window.
    >>> torch.signal.windows.cosine(10)
    tensor([0.1564, 0.4540, 0.7071, 0.8910, 0.9877, 0.9877, 0.8910, 0.7071, 0.4540, 0.1564])

    >>> # Generates a periodic cosine window.
    >>> torch.signal.windows.cosine(10, sym=False)
    tensor([0.1423, 0.4154, 0.6549, 0.8413, 0.9595, 1.0000, 0.9595, 0.8413, 0.6549, 0.4154])
r1   r$   r%   r2   r3   c          	      D   |t        j                         }t        d| ||       | dk(  rt        j                  d||||      S d}t         j                  |s
| dkD  r| dz   n| z  }t        j
                  ||z  || dz
  z   |z  | ||||      }t        j                  |      S )Nr   r   r6   r7         ?r8   r:   )r)   r>   r-   r?   pir@   sin	r#   r1   r$   r%   r2   r3   r;   rC   rD   s	            r   r   r      s    d }'')Ha7Av{{4uVFZghhExxA1q51=HUX-!QUOx7"$$%2	4A 99Q<r   z
Computes a window with a gaussian waveform.

The gaussian window is defined as follows:

.. math::
    w_n = \exp{\left(-\left(\frac{n}{2\sigma}\right)^2\right)}
    a   

{normalization}

Args:
    {M}

Keyword args:
    std (float, optional): the standard deviation of the gaussian. It controls how narrow or wide the window is.
        Default: 1.0.
    {sym}
    {dtype}
    {layout}
    {device}
    {requires_grad}

Examples::

    >>> # Generates a symmetric gaussian window with a standard deviation of 1.0.
    >>> torch.signal.windows.gaussian(10)
    tensor([4.0065e-05, 2.1875e-03, 4.3937e-02, 3.2465e-01, 8.8250e-01, 8.8250e-01, 3.2465e-01, 4.3937e-02, 2.1875e-03, 4.0065e-05])

    >>> # Generates a periodic gaussian window and standard deviation equal to 0.9.
    >>> torch.signal.windows.gaussian(10, sym=False,std=0.9)
    tensor([1.9858e-07, 5.1365e-05, 3.8659e-03, 8.4658e-02, 5.3941e-01, 1.0000e+00, 5.3941e-01, 8.4658e-02, 3.8659e-03, 5.1365e-05])
)stdr1   r$   r%   r2   r3   rK   c          	      x   |t        j                         }t        d| ||       |dk  rt        d| d      | dk(  rt        j                  d||||      S |s| dkD  r| n| dz
   dz  }d|t        d	      z  z  }t        j                  ||z  || dz
  z   |z  | ||||
      }	t        j                  |	d	z         S )Nr   r   z*Standard deviation must be positive, got: r5   r6   r7   r8   r9      r:   )r)   r>   r-   r(   r?   r   r@   rA   )
r#   rK   r1   r$   r%   r2   r3   r;   rC   rD   s
             r   r   r      s    ` }'')J5&9
axEcU)TUUAv{{4uVFZghhq1ua!a%036EC$q'M"HUX-!QUOx7"$$%2	4A 99a1fWr   aK  
Computes the Kaiser window.

The Kaiser window is defined as follows:

.. math::
    w_n = I_0 \left( \beta \sqrt{1 - \left( {\frac{n - N/2}{N/2}} \right) ^2 } \right) / I_0( \beta )

where ``I_0`` is the zeroth order modified Bessel function of the first kind (see :func:`torch.special.i0`), and
``N = M - 1 if sym else M``.
    a  

{normalization}

Args:
    {M}

Keyword args:
    beta (float, optional): shape parameter for the window. Must be non-negative. Default: 12.0
    {sym}
    {dtype}
    {layout}
    {device}
    {requires_grad}

Examples::

    >>> # Generates a symmetric gaussian window with a standard deviation of 1.0.
    >>> torch.signal.windows.kaiser(5)
    tensor([4.0065e-05, 2.1875e-03, 4.3937e-02, 3.2465e-01, 8.8250e-01, 8.8250e-01, 3.2465e-01, 4.3937e-02, 2.1875e-03, 4.0065e-05])
    >>> # Generates a periodic gaussian window and standard deviation equal to 0.9.
    >>> torch.signal.windows.kaiser(5, sym=False,std=0.9)
    tensor([1.9858e-07, 5.1365e-05, 3.8659e-03, 8.4658e-02, 5.3941e-01, 1.0000e+00, 5.3941e-01, 8.4658e-02, 3.8659e-03, 5.1365e-05])
g      (@)betar1   r$   r%   r2   r3   rN   c          	      h   |t        j                         }t        d| ||       |dk  rt        d| d      | dk(  rt        j                  d||||      S | dk(  rt        j
                  d||||      S t        j                  |||	      }| }d
|z  |s| n| dz
  z  }t        j                  ||| dz
  |z  z         }	t        j                  ||	| ||||      }
t        j                  t        j                  ||z  t        j                  |
d      z
              t        j                  |      z  S )Nr   r   z beta must be non-negative, got: r5   r6   r7   r8   r8   )r$   r2   r9   r:   rM   )r)   r>   r-   r(   r?   onestensorminimumr@   i0r   pow)r#   rN   r1   r$   r%   r2   r3   r;   rC   r<   rD   s              r   r   r   8  s+   b }'')Ha7ax;D6KLLAv{{4uVFZghhAvzz$eF6Yfgg <<E&9DEETzcQq1u5H
--eq1u&88
9CU"$$%2	4A 88EJJtd{UYYq!_<=>$OOr   z
Computes the Hamming window.

The Hamming window is defined as follows:

.. math::
    w_n = \alpha - \beta\ \cos \left( \frac{2 \pi n}{M - 1} \right)
    a  

{normalization}

Arguments:
    {M}

Keyword args:
    {sym}
    alpha (float, optional): The coefficient :math:`\alpha` in the equation above.
    beta (float, optional): The coefficient :math:`\beta` in the equation above.
    {dtype}
    {layout}
    {device}
    {requires_grad}

Examples::

    >>> # Generates a symmetric Hamming window.
    >>> torch.signal.windows.hamming(10)
    tensor([0.0800, 0.1876, 0.4601, 0.7700, 0.9723, 0.9723, 0.7700, 0.4601, 0.1876, 0.0800])

    >>> # Generates a periodic Hamming window.
    >>> torch.signal.windows.hamming(10, sym=False)
    tensor([0.0800, 0.1679, 0.3979, 0.6821, 0.9121, 1.0000, 0.9121, 0.6821, 0.3979, 0.1679])
c                $    t        | |||||      S )NrE   r   r#   r1   r$   r%   r2   r3   s         r   r   r     s    Z 1#U6&`mnnr   z
Computes the Hann window.

The Hann window is defined as follows:

.. math::
    w_n = \frac{1}{2}\ \left[1 - \cos \left( \frac{2 \pi n}{M - 1} \right)\right] =
    \sin^2 \left( \frac{\pi n}{M - 1} \right)
    a  

{normalization}

Arguments:
    {M}

Keyword args:
    {sym}
    {dtype}
    {layout}
    {device}
    {requires_grad}

Examples::

    >>> # Generates a symmetric Hann window.
    >>> torch.signal.windows.hann(10)
    tensor([0.0000, 0.1170, 0.4132, 0.7500, 0.9698, 0.9698, 0.7500, 0.4132, 0.1170, 0.0000])

    >>> # Generates a periodic Hann window.
    >>> torch.signal.windows.hann(10, sym=False)
    tensor([0.0000, 0.0955, 0.3455, 0.6545, 0.9045, 1.0000, 0.9045, 0.6545, 0.3455, 0.0955])
c          	      &    t        | d|||||      S )NrG   alphar1   r$   r%   r2   r3   rW   rX   s         r   r   r     s&    X 1!$"!&"("()68 8r   z
Computes the Blackman window.

The Blackman window is defined as follows:

.. math::
    w_n = 0.42 - 0.5 \cos \left( \frac{2 \pi n}{M - 1} \right) + 0.08 \cos \left( \frac{4 \pi n}{M - 1} \right)
    a  

{normalization}

Arguments:
    {M}

Keyword args:
    {sym}
    {dtype}
    {layout}
    {device}
    {requires_grad}

Examples::

    >>> # Generates a symmetric Blackman window.
    >>> torch.signal.windows.blackman(5)
    tensor([-1.4901e-08,  3.4000e-01,  1.0000e+00,  3.4000e-01, -1.4901e-08])

    >>> # Generates a periodic Blackman window.
    >>> torch.signal.windows.blackman(5, sym=False)
    tensor([-1.4901e-08,  2.0077e-01,  8.4923e-01,  8.4923e-01,  2.0077e-01])
c          	      r    |t        j                         }t        d| ||       t        | g d|||||      S )Nr   )gzG?rG   g{Gz?ar1   r$   r%   r2   r3   )r)   r>   r-   r   rX   s         r   r   r     sD    V }'')J5&9!0cv^d(57 7r   a4  
Computes the Bartlett window.

The Bartlett window is defined as follows:

.. math::
    w_n = 1 - \left| \frac{2n}{M - 1} - 1 \right| = \begin{cases}
        \frac{2n}{M - 1} & \text{if } 0 \leq n \leq \frac{M - 1}{2} \\
        2 - \frac{2n}{M - 1} & \text{if } \frac{M - 1}{2} < n < M \\ \end{cases}
    a  

{normalization}

Arguments:
    {M}

Keyword args:
    {sym}
    {dtype}
    {layout}
    {device}
    {requires_grad}

Examples::

    >>> # Generates a symmetric Bartlett window.
    >>> torch.signal.windows.bartlett(10)
    tensor([0.0000, 0.2222, 0.4444, 0.6667, 0.8889, 0.8889, 0.6667, 0.4444, 0.2222, 0.0000])

    >>> # Generates a periodic Bartlett window.
    >>> torch.signal.windows.bartlett(10, sym=False)
    tensor([0.0000, 0.2000, 0.4000, 0.6000, 0.8000, 1.0000, 0.8000, 0.6000, 0.4000, 0.2000])
c          	      \   |t        j                         }t        d| ||       | dk(  rt        j                  d||||      S | dk(  rt        j                  d||||      S d}d|s| n| dz
  z  }t        j
                  ||| dz
  |z  z   | ||||	      }dt        j                  |      z
  S )
Nr
   r   r6   r7   r8   rP   rM   r:   )r)   r>   r-   r?   rQ   r@   rB   rJ   s	            r   r
   r
   "  s    Z }'')J5&9Av{{4uVFZghhAvzz$eF6YfggESAa!e,HU AEX#55"$$%2	4A uyy|r   z
Computes the general cosine window.

The general cosine window is defined as follows:

.. math::
    w_n = \sum^{M-1}_{i=0} (-1)^i a_i \cos{ \left( \frac{2 \pi i n}{M - 1}\right)}
    a  

{normalization}

Arguments:
    {M}

Keyword args:
    a (Iterable): the coefficients associated to each of the cosine functions.
    {sym}
    {dtype}
    {layout}
    {device}
    {requires_grad}

Examples::

    >>> # Generates a symmetric general cosine window with 3 coefficients.
    >>> torch.signal.windows.general_cosine(10, a=[0.46, 0.23, 0.31], sym=True)
    tensor([0.5400, 0.3376, 0.1288, 0.4200, 0.9136, 0.9136, 0.4200, 0.1288, 0.3376, 0.5400])

    >>> # Generates a periodic general cosine window wit 2 coefficients.
    >>> torch.signal.windows.general_cosine(10, a=[0.5, 1 - 0.5], sym=False)
    tensor([0.0000, 0.0955, 0.3455, 0.6545, 0.9045, 1.0000, 0.9045, 0.6545, 0.3455, 0.0955])
r^   c          	      .   |t        j                         }t        d| ||       | dk(  rt        j                  d||||      S | dk(  rt        j                  d||||      S t        |t              st        d      |st        d      d	t         j                  z  |s| n| dz
  z  }t        j                  d| dz
  |z  | ||||
      }t        j                  t        |      D 	
cg c]  \  }	}
d|	z  |
z   c}
}	|||      }t        j                  |j                  d   |j                  |j                   |j"                        }	|j%                  d      t        j&                  |	j%                  d      |z        z  j)                  d      S c c}
}	w )Nr   r   r6   r7   r8   rP   z!Coefficients must be a list/tuplezCoefficients cannot be emptyrM   r:   r`   )r2   r$   r3   )r$   r2   r3   )r)   r>   r-   r?   rQ   
isinstancer   	TypeErrorr(   rH   r@   rR   	enumeratearangeshaper$   r2   r3   	unsqueezecossum)r#   r^   r1   r$   r%   r2   r3   rC   rD   iwa_is               r   r   r   h  sh   X }''),a?Av{{4uVFZghhAvzz$eF6Yfgga";<<788588|qQ7HQEX-"$$%2	4A ,,)A,?$!Q	A?V[kx
yCSYYq\3::UXUfUfgAMM"		!++b/A*= >>CCAFF @s   'F
z
Computes the general Hamming window.

The general Hamming window is defined as follows:

.. math::
    w_n = \alpha - (1 - \alpha) \cos{ \left( \frac{2 \pi n}{M-1} \right)}
    a  

{normalization}

Arguments:
    {M}

Keyword args:
    alpha (float, optional): the window coefficient. Default: 0.54.
    {sym}
    {dtype}
    {layout}
    {device}
    {requires_grad}

Examples::

    >>> # Generates a symmetric Hamming window with the general Hamming window.
    >>> torch.signal.windows.general_hamming(10, sym=True)
    tensor([0.0800, 0.1876, 0.4601, 0.7700, 0.9723, 0.9723, 0.7700, 0.4601, 0.1876, 0.0800])

    >>> # Generates a periodic Hann window with the general Hamming window.
    >>> torch.signal.windows.general_hamming(10, alpha=0.5, sym=False)
    tensor([0.0000, 0.0955, 0.3455, 0.6545, 0.9045, 1.0000, 0.9045, 0.6545, 0.3455, 0.0955])
gHzG?rZ   r[   c          	      0    t        | |d|z
  g|||||      S )Nr.   r]   r   )r#   r[   r1   r$   r%   r2   r3   s          r   r   r     s/    Z !"BJ/! %!'!'(57 7r   z
Computes the minimum 4-term Blackman-Harris window according to Nuttall.

.. math::
    w_n = 1 - 0.36358 \cos{(z_n)} + 0.48917 \cos{(2z_n)} - 0.13659 \cos{(3z_n)} + 0.01064 \cos{(4z_n)}

where :math:`z_n = \frac{2 \pi n}{M}`.
    a  

{normalization}

Arguments:
    {M}

Keyword args:
    {sym}
    {dtype}
    {layout}
    {device}
    {requires_grad}

References::

    - A. Nuttall, "Some windows with very good sidelobe behavior,"
      IEEE Transactions on Acoustics, Speech, and Signal Processing, vol. 29, no. 1, pp. 84-91,
      Feb 1981. https://doi.org/10.1109/TASSP.1981.1163506

    - Heinzel G. et al., "Spectrum and spectral density estimation by the Discrete Fourier transform (DFT),
      including a comprehensive list of window functions and some new flat-top windows",
      February 15, 2002 https://holometer.fnal.gov/GH_FFT.pdf

Examples::

    >>> # Generates a symmetric Nutall window.
    >>> torch.signal.windows.general_hamming(5, sym=True)
    tensor([3.6280e-04, 2.2698e-01, 1.0000e+00, 2.2698e-01, 3.6280e-04])

    >>> # Generates a periodic Nuttall window.
    >>> torch.signal.windows.general_hamming(5, sym=False)
    tensor([3.6280e-04, 1.1052e-01, 7.9826e-01, 7.9826e-01, 1.1052e-01])
c          	      *    t        | g d|||||      S )N)gzD?g;%N?g1|?gC ˅?r]   rn   rX   s         r   r   r     s&    n !H! %!'!'(57 7r   r    )#typingr   r   r)   mathr   r   torch._torch_docsr   r   r	   __all__window_common_argsr!   strintr$   r%   r-   formatr*   floatboolr2   r   r   r   r   r   r   r   r
   r   r   r   r    r   r   <module>rz      sn   &    L L !	  H "&]3 ]3 ]u{{ ]TYT`T` ]ei ]$ 
 < 	= > ? -b #''+$}})-#&$&$ &$ 	&$
 &$ $&$ &$ &&$ &$ &$]-\&$R  . F/0 1(X '+$}})-#  $	
  &  S(R>  2 F34 5%R '+$}})-#!! ! 	!
 $! ! &! ! !M%L!H 
 . F/0 1&T '+$}})-#'P'P 'P 	'P
 $'P 'P &'P 'P 'PO&N'PT  2 F34 5%P +/#(==-1"'os oo EKK(o LL	o
 U\\*o  o -3oM%Lo  . F/0 1$N (, %*.$8C 88 %8 	8
 %,,'8 8 *08K$J8   . F/0 1#L ,0$)MM.2#(7 77 U[[)7 \\	7
 ell+7 !7 .47I#H7  	 . F/0 1%P ,0$)MM.2#(  U[[) \\	
 ell+ ! .4M%L@  0 F12 3$N  $26*/--48).$G$G$G #5;;/$G !<<	$G
 $ELL1$G #'$G 4:$GK$J$GN  0 F12 3$N $( $37+0==59*/7 7 7 $EKK0	7
 "LL7 %U\\27 $(7 5;7K$J7" ! !B FC#D E#-b '+$}})-#77 7 $	7
 7 &7 7 7]-\7r   