Skip to content

Commit b0c49ec

Browse files
alvgaonaalvgaona
committed
Update docstrings
1 parent 949cab0 commit b0c49ec

File tree

1 file changed

+107
-46
lines changed

1 file changed

+107
-46
lines changed

‎torch/signal/windows/windows.py‎

Lines changed: 107 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@
44

55
from torch import Tensor
66
from torch.types import _dtype, _device, _layout
7-
from torch.fft import fft
87

98
__all__ = [
109
'cosine_window',
@@ -13,7 +12,16 @@
1312
]
1413

1514

16-
def _window_function_checks(function_name: str, window_length: int, dtype: _dtype, layout: _layout):
15+
def _window_function_checks(function_name: str, window_length: int, dtype: _dtype, layout: _layout) -> None:
16+
r"""Performs common checks for all the defined windows.
17+
This function should be called before computing any window
18+
19+
Args:
20+
function_name (str): name of the window function.
21+
window_length (int): length of the window.
22+
dtype (:class:`torch.dtype`): the desired data type of the window tensor.
23+
layout (:class:`torch.layout`): the desired layout of the window tensor.
24+
"""
1725
def is_floating_type(t: _dtype) -> bool:
1826
return t == torch.float32 or t == torch.bfloat16 or t == torch.float64 or t == torch.float16
1927

@@ -36,35 +44,52 @@ def exponential_window(window_length: int,
3644
layout: _layout = torch.strided,
3745
device: _device = None,
3846
requires_grad: bool = False) -> Tensor:
39-
"""r
40-
Computes a window with an exponential form. The window
41-
is also known as Poisson window.
47+
r"""Computes a window with an exponential form.
48+
The window is also known as Poisson window.
4249
4350
The exponential window is defined as follows:
4451
4552
.. math::
46-
w(n) = \exp{-\frac{|n - center|}{\tau}}
53+
w(n) = e^{-\frac{|n - center|}{\tau}}
4754
4855
Args:
49-
window_length: the length of the output window. In other words, the number of points of the cosine window.
50-
periodic: If `True`, returns a periodic window suitable for use in spectral analysis. If `False`,
51-
returns a symmetric window suitable for use in filter design.
52-
center: this value defines where the center of the window will be located. In other words, at which
53-
sample the peak of the window can be found.
54-
tau: the decay value. For `center = 0`, it's suggested to use `tau = -(M - 1) / ln(x)`, if `` is
55-
the fraction of the window remaining at the end.
56+
window_length (int): the length of the output window. In other words, the number of points of the cosine window.
57+
periodic (bool, optional): If `True`, returns a periodic window suitable for use in spectral analysis.
58+
If `False`,returns a symmetric window suitable for use in filter design.
59+
center (float, optional): this value defines where the center of the window will be located.
60+
In other words, at which sample the peak of the window can be found.
61+
tau (float, optional): the decay value. For `center = 0`, it's suggested to use `tau = -(M - 1) / ln(x)`,
62+
if `x` is the fraction of the window remaining at the end.
5663
5764
Keyword args:
58-
{dtype}
59-
layout (:class:`torch.layout`, optional): the desired layout of returned window tensor. Only
60-
`torch.strided` (dense layout) is supported.
61-
{device}
62-
{requires_grad}
65+
dtype (:class:`torch.dtype`, optional): the desired data type of returned tensor.
66+
Default: if ``None``, uses a global default (see :func:`torch.set_default_tensor_type`).
67+
layout (:class:`torch.layout`, optional): the desired layout of returned window tensor.
68+
Only `torch.strided` (dense layout) is supported.
69+
device (:class:`torch.device`, optional): the desired device of returned tensor.
70+
Default: if ``None``, uses the current device for the default tensor type
71+
(see :func:`torch.set_default_tensor_type`).
72+
:attr:`device` will be the CPU for CPU tensor types and the current CUDA device for CUDA tensor types.
73+
requires_grad (bool, optional): If autograd should record operations on the returned tensor. Default: ``False``.
74+
75+
Returns:
76+
(torch.Tensor): window in the form of a tensor.
77+
78+
Examples:
79+
>>> # Generate an exponential window without keyword args.
80+
>>> torch.signal.windows.exponential_window(10)
81+
tensor([0.0067, 0.0183, 0.0498, 0.1353, 0.3679, 1.0000, 0.3679, 0.1353, 0.0498,
82+
0.0183])
83+
84+
>>> # Generate a symmetric exponential window and decay factor equal to .5
85+
>>> torch.signal.windows.exponential_window(10, tau=.5, periodic=False)
86+
tensor([1.2341e-04, 9.1188e-04, 6.7379e-03, 4.9787e-02, 3.6788e-01, 3.6788e-01,
87+
4.9787e-02, 6.7379e-03, 9.1188e-04, 1.2341e-04])
6388
"""
6489
if dtype is None:
6590
dtype = torch.get_default_dtype()
6691

67-
_window_function_checks('exponential_window', window_length, dtype, layout, device)
92+
_window_function_checks('exponential_window', window_length, dtype, layout)
6893

6994
if window_length == 0:
7095
return torch.empty((0,), dtype=dtype, layout=layout, device=device, requires_grad=requires_grad)
@@ -93,34 +118,51 @@ def cosine_window(window_length: int,
93118
layout: _layout = torch.strided,
94119
device: _device = None,
95120
requires_grad: bool = False) -> Tensor:
96-
"""r
97-
Computes a window with a simple cosine waveform.
121+
r"""Computes a window with a simple cosine waveform.
98122
99123
The cosine window is also known as the sine window due to the following
100124
equality:
101125
102126
.. math::
103-
w(n) = \cos{(\frac{\pi n}{M}) - \frac{\pi}{2})} = \sin{(\frac{\pi n}{M})}
127+
w(n) = \cos{\left(\frac{\pi n}{M} - \frac{\pi}{2}\right)} = \sin{\left(\frac{\pi n}{M}\right)}
104128
105129
Where `M` is the window length.
106130
107-
108131
Args:
109-
window_length: the length of the output window. In other words, the number of points of the cosine window.
110-
periodic: If `True`, returns a periodic window suitable for use in spectral analysis. If `False`,
111-
returns a symmetric window suitable for use in filter design.
132+
window_length (int): the length of the output window.
133+
In other words, the number of points of the cosine window.
134+
periodic (bool): If `True`, returns a periodic window suitable for use in spectral analysis.
135+
If `False`, returns a symmetric window suitable for use in filter design.
112136
113137
Keyword args:
114-
{dtype}
115-
layout (:class:`torch.layout`, optional): the desired layout of returned window tensor. Only
116-
`torch.strided` (dense layout) is supported.
117-
{device}
118-
{requires_grad}
138+
dtype (:class:`torch.dtype`, optional): the desired data type of returned tensor.
139+
Default: if ``None``, uses a global default (see :func:`torch.set_default_tensor_type`).
140+
layout (:class:`torch.layout`, optional): the desired layout of returned window tensor.
141+
Only `torch.strided` (dense layout) is supported.
142+
device (:class:`torch.device`, optional): the desired device of returned tensor.
143+
Default: if ``None``, uses the current device for the default tensor type
144+
(see :func:`torch.set_default_tensor_type`).
145+
:attr:`device` will be the CPU for CPU tensor types and the current CUDA device for CUDA tensor types.
146+
requires_grad (bool, optional): If autograd should record operations on the returned tensor. Default: ``False``.
147+
148+
Returns:
149+
(torch.Tensor): window in the form of a tensor.
150+
151+
Examples:
152+
>>> # Generate a cosine window without keyword args.
153+
>>> torch.signal.windows.cosine_window(10)
154+
tensor([0.1423, 0.4154, 0.6549, 0.8413, 0.9595, 1.0000, 0.9595, 0.8413, 0.6549,
155+
0.4154])
156+
157+
>>> # Generate a symmetric cosine window.
158+
>>> torch.signal.windows.cosine_window(10, periodic=False)
159+
tensor([0.1564, 0.4540, 0.7071, 0.8910, 0.9877, 0.9877, 0.8910, 0.7071, 0.4540,
160+
0.1564])
119161
"""
120162
if dtype is None:
121163
dtype = torch.get_default_dtype()
122164

123-
_window_function_checks('cosine_window', window_length, dtype, layout, device)
165+
_window_function_checks('cosine_window', window_length, dtype, layout)
124166

125167
if window_length == 0:
126168
return torch.empty((0,), dtype=dtype, layout=layout, device=device, requires_grad=requires_grad)
@@ -133,6 +175,7 @@ def cosine_window(window_length: int,
133175

134176
k = torch.arange(window_length, dtype=dtype, layout=layout, device=device, requires_grad=requires_grad)
135177
window = torch.sin(torch.pi / window_length * (k + .5))
178+
136179
return window[:-1] if periodic else window
137180

138181

@@ -143,32 +186,49 @@ def gaussian_window(window_length: int,
143186
layout: _layout = torch.strided,
144187
device: _device = None,
145188
requires_grad: bool = False) -> Tensor:
146-
"""r
147-
Computes a window with a gaussian waveform.
189+
r"""Computes a window with a gaussian waveform.
148190
149191
The gaussian window is defined as follows:
150192
151193
.. math::
152-
w(n) = \exp{-\frac{1}{2}\frac{n}{\sigma}^2}
194+
w(n) = w(n) = e^{-\left(\frac{n}{2\sigma}\right)^2}
153195
154196
Args:
155-
window_length: the length of the output window. In other words, the number of points of the cosine window.
156-
periodic: If `True`, returns a periodic window suitable for use in spectral analysis. If `False`,
157-
returns a symmetric window suitable for use in filter design.
158-
std: the standard deviation of the gaussian. It controls how narrow or wide the window is.
159-
197+
window_length (int): the length of the output window.
198+
In other words, the number of points of the cosine window.
199+
periodic (bool, optional): If `True`, returns a periodic window suitable for use in spectral analysis.
200+
If `False`, returns a symmetric window suitable for use in filter design.
201+
std (float, optional): the standard deviation of the gaussian. It controls how narrow or wide the window is.
160202
161203
Keyword args:
162-
{dtype}
163-
layout (:class:`torch.layout`, optional): the desired layout of returned window tensor. Only
164-
`torch.strided` (dense layout) is supported.
165-
{device}
166-
{requires_grad}
204+
dtype (:class:`torch.dtype`, optional): the desired data type of returned tensor.
205+
Default: if ``None``, uses a global default (see :func:`torch.set_default_tensor_type`).
206+
layout (:class:`torch.layout`, optional): the desired layout of returned window tensor.
207+
Only `torch.strided` (dense layout) is supported.
208+
device (:class:`torch.device`, optional): the desired device of returned tensor.
209+
Default: if ``None``, uses the current device for the default tensor type
210+
(see :func:`torch.set_default_tensor_type`).
211+
:attr:`device` will be the CPU for CPU tensor types and the current CUDA device for CUDA tensor types.
212+
requires_grad (bool, optional): If autograd should record operations on the returned tensor. Default: ``False``.
213+
214+
Returns:
215+
(torch.Tensor): window in the form of a tensor.
216+
217+
Examples:
218+
>>> # Generate a gaussian window without keyword args.
219+
>>> torch.signal.windows.gaussian_window(10)
220+
tensor([1.9287e-22, 1.2664e-14, 1.5230e-08, 3.3546e-04, 1.3534e-01, 1.0000e+00,
221+
1.3534e-01, 3.3546e-04, 1.5230e-08, 1.2664e-14])
222+
223+
>>> # Generate a symmetric gaussian window and standard deviation equal to 0.9.
224+
>>> torch.signal.windows.gaussian_window(10, std=0.9, periodic=False)
225+
tensor([3.7267e-06, 5.1998e-04, 2.1110e-02, 2.4935e-01, 8.5700e-01, 8.5700e-01,
226+
2.4935e-01, 2.1110e-02, 5.1998e-04, 3.7267e-06])
167227
"""
168228
if dtype is None:
169229
dtype = torch.get_default_dtype()
170230

171-
_window_function_checks('cosine_window', window_length, dtype, layout, device)
231+
_window_function_checks('cosine_window', window_length, dtype, layout)
172232

173233
if window_length == 0:
174234
return torch.empty((0,), dtype=dtype, layout=layout, device=device, requires_grad=requires_grad)
@@ -183,4 +243,5 @@ def gaussian_window(window_length: int,
183243
k = k - (window_length - 1.0) / 2.0
184244
sig2 = 2 * std * std
185245
window = torch.exp(-k ** 2 / sig2)
246+
186247
return window[:-1] if periodic else window

0 commit comments

Comments
 (0)