8000 Improves fft doc consistency and makes deprecation warnings more prom… · pytorch/pytorch@bb19a55 · GitHub
[go: up one dir, main page]
Skip to content

Commit bb19a55

Browse files
Mike Ruberryfacebook-github-bot
Mike Ruberry
authored and
facebook-github-bot
committed
Improves fft doc consistency and makes deprecation warnings more prominent (#45409)
Summary: This PR makes the deprecation warnings for existing fft functions more prominent and makes the torch.stft deprecation warning consistent with our current deprecation planning. Pull Request resolved: #45409 Reviewed By: ngimel Differential Revision: D23974975 Pulled By: mruberry fbshipit-source-id: b90d8276095122ac3542ab625cb49b991379c1f8
1 parent 0a38aed commit bb19a55

File tree

3 files changed

+47
-47
lines changed

3 files changed

+47
-47
lines changed

‎aten/src/ATen/native/SpectralOps.cpp

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -262,12 +262,12 @@ ShapeAndDims canonicalize_fft_shape_and_dim_args(
262262
ret.shape[i] = input_sizes[ret.dim[i]];
263263
}
264264
}
265-
265+
266266
for (int64_t i = 0; i < ret.shape.size(); ++i) {
267267
TORCH_CHECK(ret.shape[i] > 0,
268268
"Invalid number of data points (", ret.shape[i], ") specified");
269269
}
270-
270+
271271
return ret;
272272
}
273273

@@ -318,14 +318,14 @@ Tensor fftn_c2c(
318318
// torch.fft.fft, analogous to NumPy's numpy.fft.fft
319319
Tensor fft_fft(const Tensor& self, c10::optional<int64_t> n, int64_t dim,
320320
c10::optional<std::string> norm) {
321-
return self.is_complex() ?
321+
return self.is_complex() ?
322322
fft_c2c(self, n, dim, norm, /*forward=*/true) :
323323
fft_r2c(self, n, dim, norm, /*forward=*/true, /*onesided=*/false);
324324
}
325325

326326
Tensor fft_ifft(const Tensor& self, c10::optional<int64_t> n, int64_t dim,
327327
c10::optional<std::string> norm) {
328-
return self.is_complex() ?
328+
return self.is_complex() ?
329329
fft_c2c(self, n, dim, norm, /*forward=*/false) :
330330
fft_r2c(self, n, dim, norm, /*forward=*/false, /*onesided=*/false);
331331
}
@@ -647,8 +647,10 @@ Tensor stft(const Tensor& self, const int64_t n_fft, const optional<int64_t> hop
647647
const bool return_complex = return_complexOpt.value_or(
648648
self.is_complex() || (window.defined() && window.is_complex()));
649649
if (!return_complexOpt && !return_complex) {
650-
TORCH_WARN("stft will return complex tensors by default in future, use"
651-
" return_complex=False to preserve the current output format.");
650+
TORCH_WARN_ONCE("stft will require the return_complex parameter be explicitly "
651+
" specified in a future PyTorch release. Use return_complex=False "
652+
" to preserve the current behavior or return_complex=True to return "
653+
" a complex output.");
652654
}
653655

654656
if (!at::isFloatingType(self.scalar_type()) && !at::isComplexType(self.scalar_type())) {

‎torch/_torch_docs.py

Lines changed: 33 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -8505,7 +8505,13 @@ def merge_dicts(*dicts):
85058505
add_docstr(torch.fft, r"""
85068506
fft(input, signal_ndim, normalized=False) -> Tensor
85078507
8508-
Complex-to-complex Discrete Fourier Transform
8508+
Complex-to-complex Discrete Fourier Transform.
8509+
8510+
.. warning::
8511+
The function :func:`torch.fft` is deprecated and will be removed in
8512+
PyTorch 1.8. Use the new :ref:`torch.fft <torch-fft-module>` module
8513+
functions, instead, by importing :ref:`torch.fft <torch-fft-module>` and
8514+
calling :func:`torch.fft.fft` or :func:`torch.fft.fftn`.
85098515
85108516
This method computes the complex-to-complex discrete Fourier transform.
85118517
Ignoring the batch dimensions, it computes the following expression:
@@ -8531,12 +8537,6 @@ def merge_dicts(*dicts):
85318537
85328538
The inverse of this function is :func:`~torch.ifft`.
85338539
8534-
.. deprecated:: 1.7.0
8535-
The function :func:`torch.fft` is deprecated and will be removed in
8536-
PyTorch 1.8. Use the new :ref:`torch.fft <torch-fft-module>` module
8537-
functions, instead, by importing :ref:`torch.fft <torch-fft-module>` and
8538-
calling :func:`torch.fft.fft` or :func:`torch.fft.fftn`.
8539-
85408540
.. note::
85418541
For CUDA tensors, an LRU cache is used for cuFFT plans to speed up
85428542
repeatedly running FFT methods on tensors of same geometry with same
@@ -8611,11 +8611,16 @@ def merge_dicts(*dicts):
86118611
86128612
""")
86138613

8614-
add_docstr(torch.ifft,
8615-
r"""
8614+
add_docstr(torch.ifft, r"""
86168615
ifft(input, signal_ndim, normalized=False) -> Tensor
86178616
8618-
Complex-to-complex Inverse Discrete Fourier Transform
8617+
Complex-to-complex Inverse Discrete Fourier Transform.
8618+
8619+
.. warning::
8620 57AE +
The function :func:`torch.ifft` is deprecated and will be removed in a
8621+
future PyTorch release. Use the new :ref:`torch.fft <torch-fft-module>`
8622+
module functions, instead, by importing :ref:`torch.fft <torch-fft-module>`
8623+
and calling :func:`torch.fft.ifft` or :func:`torch.fft.ifftn`.
86198624
86208625
This method computes the complex-to-complex inverse discrete Fourier
86218626
transform. Ignoring the batch dimensions, it computes the following
@@ -8640,12 +8645,6 @@ def merge_dicts(*dicts):
86408645
86418646
The inverse of this function is :func:`~torch.fft`.
86428647
8643-
.. deprecated:: 1.7.0
8644-
The function :func:`torch.ifft` is deprecated and will be removed in a
8645-
future PyTorch release. Use the new :ref:`torch.fft <torch-fft-module>`
8646-
module functions, instead, by importing :ref:`torch.fft <torch-fft-module>`
8647-
and calling :func:`torch.fft.ifft` or :func:`torch.fft.ifftn`.
8648-
86498648
.. note::
86508649
For CUDA tensors, an LRU cache is used for cuFFT plans to speed up
86518650
repeatedly running FFT methods on tensors of same geometry with same
@@ -8702,11 +8701,17 @@ def merge_dicts(*dicts):
87028701
87038702
""")
87048703

8705-
add_docstr(torch.rfft,
8706-
r"""
8704+
add_docstr(torch.rfft, r"""
87078705
rfft(input, signal_ndim, normalized=False, onesided=True) -> Tensor
87088706
8709-
Real-to-complex Discrete Fourier Transform
8707+
Real-to-complex Discrete Fourier Transform.
8708+
8709+
.. warning::
8710+
The function :func:`torch.rfft` is deprecated and will be removed in a
8711+
future PyTorch release. Use the new :ref:`torch.fft <torch-fft-module>`
8712+
module functions, instead, by importing :ref:`torch.fft <torch-fft-module>`
8713+
and calling :func:`torch.fft.rfft` for one-sided output, or
8714+
:func:`torch.fft.fft` for two-sided output.
87108715
87118716
This method computes the real-to-complex discrete Fourier transform. It is
87128717
mathematically equivalent with :func:`~torch.fft` with differences only in
@@ -8734,13 +8739,6 @@ def merge_dicts(*dicts):
87348739
87358740
The inverse of this function is :func:`~torch.irfft`.
87368741
8737-
.. deprecated:: 1.7.0
8738-
The function :func:`torch.rfft` is deprecated and will be removed in a
8739-
future PyTorch release. Use the new :ref:`torch.fft <torch-fft-module>`
8740-
module functions, instead, by importing :ref:`torch.fft <torch-fft-module>`
8741-
and calling :func:`torch.fft.rfft` for one-sided output, or
8742-
:func:`torch.fft.fft` for two-sided output.
8743-
87448742
.. note::
87458743
For CUDA tensors, an LRU cache is used for cuFFT plans to speed up
87468744
repeatedly running FFT methods on tensors of same geometry with same
@@ -8778,11 +8776,17 @@ def merge_dicts(*dicts):
87788776
""")
87798777

87808778

8781-
add_docstr(torch.irfft,
8782-
r"""
8779+
add_docstr(torch.irfft, r"""
87838780
irfft(input, signal_ndim, normalized=False, onesided=True, signal_sizes=None) -> Tensor
87848781
8785-
Complex-to-real Inverse Discrete Fourier Transform
8782+
Complex-to-real Inverse Discrete Fourier Transform.
8783+
8784+
.. warning::
8785+
The function :func:`torch.irfft` is deprecated and will be removed in a
8786+
future PyTorch release. Use the new :ref:`torch.fft <torch-fft-module>`
8787+
module functions, instead, by importing :ref:`torch.fft <torch-fft-module>`
8788+
and calling :func:`torch.fft.irfft` for one-sided input, or
8789+
:func:`torch.fft.ifft` for two-sided input.
87868790
87878791
This method computes the complex-to-real inverse discrete Fourier transform.
87888792
It is mathematically equivalent with :func:`ifft` with differences only in
@@ -8813,13 +8817,6 @@ def merge_dicts(*dicts):
88138817
88148818
The inverse of this function is :func:`~torch.rfft`.
88158819
8816-
.. deprecated:: 1.7.0
8817-
The function :func:`torch.irfft` is deprecated and will be removed in a
8818-
future PyTorch release. Use the new :ref:`torch.fft <torch-fft-module>`
8819-
module functions, instead, by importing :ref:`torch.fft <torch-fft-module>`
8820-
and calling :func:`torch.fft.irfft` for one-sided input, or
8821-
:func:`torch.fft.ifft` for two-sided input.
8822-
88238820
.. warning::
88248821
Generally speaking, input to this function should contain values
88258822
following conjugate symmetry. Note that even if :attr:`onesided` is

‎torch/functional.py

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -398,9 +398,14 @@ def stft(input: Tensor, n_fft: int, hop_length: Optional[int] = None,
398398
return_complex: Optional[bool] = None) -> Tensor:
399399
r"""Short-time Fourier transform (STFT).
400400
401+
.. warning::
402+
Setting :attr:`return_complex` explicitly will be required in a future
403+
PyTorch release. Set it to False to preserve the current behavior or
404+
True to return a complex output.
405+
401406
The STFT computes the Fourier transform of short overlapping windows of the
402407
input. This giving frequency components of the signal as they change over
403-
time. The interface of this function is modeled after librosa_.
408+
time. The interface of this function is modeled after the librosa_ stft function.
404409
405410
.. _librosa: https://librosa.org/doc/latest/generated/librosa.stft.html
406411
@@ -456,10 +461,6 @@ def stft(input: Tensor, n_fft: int, hop_length: Optional[int] = None,
456461
the output is a ``input.dim() + 2`` dimensional real tensor where the last
457462
dimension represents the real and imaginary components.
458463
459-
.. warning::
460-
From pytorch 1.8.0, :attr:`return_complex` will default to ``True``
461-
for all input types.
462-
463464
Returns either a complex tensor of size :math:`(* \times N \times T)` if
464465
:attr:`return_complex` is true, or a real tensor of size :math:`(* \times N
465466
\times T \times 2)`. Where :math:`*` is the optional batch size of

0 commit comments

Comments
 (0)
0