From 710288e413b4fb0e72f84b3144af4628d1a57520 Mon Sep 17 00:00:00 2001 From: Peter Bell Date: Sat, 24 Apr 2021 17:12:53 -0700 Subject: [PATCH] torch.fft: Document out argument (#56732) Summary: An oversight from https://github.com/pytorch/pytorch/issues/49335, the documentation was never updated to include `out` arguments. Pull Request resolved: https://github.com/pytorch/pytorch/pull/56732 Reviewed By: ezyang Differential Revision: D27960478 Pulled By: mruberry fbshipit-source-id: a342a4f590369d6d2e17bed014fa64e49ee72936 --- torch/fft/__init__.py | 106 ++++++++++++++++++++++++++++++------------ 1 file changed, 75 insertions(+), 31 deletions(-) diff --git a/torch/fft/__init__.py b/torch/fft/__init__.py index fcb41284eab9..566f62e9ecb4 100644 --- a/torch/fft/__init__.py +++ b/torch/fft/__init__.py @@ -2,7 +2,7 @@ import torch from torch._C import _add_docstr, _fft # type: ignore[attr-defined] -from torch._torch_docs import factory_common_args +from torch._torch_docs import factory_common_args, common_args __all__ = ['fft', 'ifft', 'fft2', 'ifft2', 'fftn', 'ifftn', 'rfft', 'irfft', 'rfft2', 'irfft2', 'rfftn', 'irfftn', @@ -15,7 +15,7 @@ # connects the torch.fft Python namespace to the torch._C._fft builtins. fft = _add_docstr(_fft.fft_fft, r""" -fft(input, n=None, dim=-1, norm=None) -> Tensor +fft(input, n=None, dim=-1, norm=None, *, out=None) -> Tensor Computes the one dimensional discrete Fourier transform of :attr:`input`. @@ -47,6 +47,9 @@ Default is ``"backward"`` (no normalization). +Keyword args: + {out} + Example: >>> t = torch.arange(4) @@ -58,10 +61,10 @@ >>> t = tensor([0.+1.j, 2.+3.j, 4.+5.j, 6.+7.j]) >>> torch.fft.fft(t) tensor([12.+16.j, -8.+0.j, -4.-4.j, 0.-8.j]) -""") +""".format(**common_args)) ifft = _add_docstr(_fft.fft_ifft, r""" -ifft(input, n=None, dim=-1, norm=None) -> Tensor +ifft(input, n=None, dim=-1, norm=None, *, out=None) -> Tensor Computes the one dimensional inverse discrete Fourier transform of :attr:`input`. @@ -84,15 +87,18 @@ Default is ``"backward"`` (normalize by ``1/n``). +Keyword args: + {out} + Example: >>> t = torch.tensor([ 6.+0.j, -2.+2.j, -2.+0.j, -2.-2.j]) >>> torch.fft.ifft(t) tensor([0.+0.j, 1.+0.j, 2.+0.j, 3.+0.j]) -""") +""".format(**common_args)) fft2 = _add_docstr(_fft.fft_fft2, r""" -fft2(input, s=None, dim=(-2, -1), norm=None) -> Tensor +fft2(input, s=None, dim=(-2, -1), norm=None, *, out=None) -> Tensor Computes the 2 dimensional discrete Fourier transform of :attr:`input`. Equivalent to :func:`~torch.fft.fftn` but FFTs only the last two dimensions by default. @@ -129,6 +135,9 @@ Default is ``"backward"`` (no normalization). +Keyword args: + {out} + Example: >>> x = torch.rand(10, 10, dtype=torch.complex64) @@ -140,10 +149,10 @@ >>> two_ffts = torch.fft.fft(torch.fft.fft(x, dim=0), dim=1) >>> torch.allclose(fft2, two_ffts) -""") +""".format(**common_args)) ifft2 = _add_docstr(_fft.fft_ifft2, r""" -ifft2(input, s=None, dim=(-2, -1), norm=None) -> Tensor +ifft2(input, s=None, dim=(-2, -1), norm=None, *, out=None) -> Tensor Computes the 2 dimensional inverse discrete Fourier transform of :attr:`input`. Equivalent to :func:`~torch.fft.ifftn` but IFFTs only the last two dimensions by default. @@ -172,6 +181,9 @@ Default is ``"backward"`` (normalize by ``1/n``). +Keyword args: + {out} + Example: >>> x = torch.rand(10, 10, dtype=torch.complex64) @@ -183,10 +195,10 @@ >>> two_iffts = torch.fft.ifft(torch.fft.ifft(x, dim=0), dim=1) >>> torch.allclose(ifft2, two_iffts) -""") +""".format(**common_args)) fftn = _add_docstr(_fft.fft_fftn, r""" -fftn(input, s=None, dim=None, norm=None) -> Tensor +fftn(input, s=None, dim=None, norm=None, *, out=None) -> Tensor Computes the N dimensional discrete Fourier transform of :attr:`input`. @@ -223,6 +235,9 @@ Default is ``"backward"`` (no normalization). +Keyword args: + {out} + Example: >>> x = torch.rand(10, 10, dtype=torch.complex64) @@ -234,10 +249,10 @@ >>> two_ffts = torch.fft.fft(torch.fft.fft(x, dim=0), dim=1) >>> torch.allclose(fftn, two_ffts) -""") +""".format(**common_args)) ifftn = _add_docstr(_fft.fft_ifftn, r""" -ifftn(input, s=None, dim=None, norm=None) -> Tensor +ifftn(input, s=None, dim=None, norm=None, *, out=None) -> Tensor Computes the N dimensional inverse discrete Fourier transform of :attr:`input`. @@ -265,6 +280,9 @@ Default is ``"backward"`` (normalize by ``1/n``). +Keyword args: + {out} + Example: >>> x = torch.rand(10, 10, dtype=torch.complex64) @@ -276,10 +294,10 @@ >>> two_iffts = torch.fft.ifft(torch.fft.ifft(x, dim=0), dim=1) >>> torch.allclose(ifftn, two_iffts) -""") +""".format(**common_args)) rfft = _add_docstr(_fft.fft_rfft, r""" -rfft(input, n=None, dim=-1, norm=None) -> Tensor +rfft(input, n=None, dim=-1, norm=None, *, out=None) -> Tensor Computes the one dimensional Fourier transform of real-valued :attr:`input`. @@ -306,6 +324,9 @@ Default is ``"backward"`` (no normalization). +Keyword args: + {out} + Example: >>> t = torch.arange(4) @@ -322,10 +343,10 @@ Notice that the symmetric element ``T[-1] == T[1].conj()`` is omitted. At the Nyquist frequency ``T[-2] == T[2]`` is it's own symmetric pair, and therefore must always be real-valued. -""") +""".format(**common_args)) irfft = _add_docstr(_fft.fft_irfft, r""" -irfft(input, n=None, dim=-1, norm=None) -> Tensor +irfft(input, n=None, dim=-1, norm=None, *, out=None) -> Tensor Computes the inverse of :func:`~torch.fft.rfft`. @@ -367,6 +388,9 @@ Default is ``"backward"`` (normalize by ``1/n``). +Keyword args: + {out} + Example: >>> t = torch.arange(5) @@ -386,10 +410,10 @@ >>> torch.fft.irfft(T, t.numel()) tensor([0.0000, 1.0000, 2.0000, 3.0000, 4.0000]) -""") +""".format(**common_args)) rfft2 = _add_docstr(_fft.fft_rfft2, r""" -rfft2(input, s=None, dim=(-2, -1), norm=None) -> Tensor +rfft2(input, s=None, dim=(-2, -1), norm=None, *, out=None) -> Tensor Computes the 2-dimensional discrete Fourier transform of real :attr:`input`. Equivalent to :func:`~torch.fft.rfftn` but FFTs only the last two dimensions by default. @@ -423,6 +447,9 @@ Default is ``"backward"`` (no normalization). +Keyword args: + {out} + Example: >>> t = torch.rand(10, 10) @@ -444,10 +471,10 @@ >>> two_ffts = torch.fft.fft(torch.fft.rfft(x, dim=1), dim=0) >>> torch.allclose(rfft2, two_ffts) -""") +""".format(**common_args)) irfft2 = _add_docstr(_fft.fft_irfft2, r""" -irfft2(input, s=None, dim=(-2, -1), norm=None) -> Tensor +irfft2(input, s=None, dim=(-2, -1), norm=None, *, out=None) -> Tensor Computes the inverse of :func:`~torch.fft.rfft2`. Equivalent to :func:`~torch.fft.irfftn` but IFFTs only the last two dimensions by default. @@ -495,6 +522,9 @@ Default is ``"backward"`` (normalize by ``1/n``). +Keyword args: + {out} + Example: >>> t = torch.rand(10, 9) @@ -515,10 +545,10 @@ >>> torch.allclose(roundtrip, t) True -""") +""".format(**common_args)) rfftn = _add_docstr(_fft.fft_rfftn, r""" -rfftn(input, s=None, dim=None, norm=None) -> Tensor +rfftn(input, s=None, dim=None, norm=None, *, out=None) -> Tensor Computes the N-dimensional discrete Fourier transform of real :attr:`input`. @@ -552,6 +582,9 @@ Default is ``"backward"`` (no normalization). +Keyword args: + {out} + Example: >>> t = torch.rand(10, 10) @@ -573,10 +606,10 @@ >>> two_ffts = torch.fft.fft(torch.fft.rfft(x, dim=1), dim=0) >>> torch.allclose(rfftn, two_ffts) -""") +""".format(**common_args)) irfftn = _add_docstr(_fft.fft_irfftn, r""" -irfftn(input, s=None, dim=None, norm=None) -> Tensor +irfftn(input, s=None, dim=None, norm=None, *, out=None) -> Tensor Computes the inverse of :func:`~torch.fft.rfftn`. @@ -623,6 +656,9 @@ Default is ``"backward"`` (normalize by ``1/n``). +Keyword args: + {out} + Example: >>> t = torch.rand(10, 9) @@ -643,10 +679,10 @@ >>> torch.allclose(roundtrip, t) True -""") +""".format(**common_args)) hfft = _add_docstr(_fft.fft_hfft, r""" -hfft(input, n=None, dim=-1, norm=None) -> Tensor +hfft(input, n=None, dim=-1, norm=None, *, out=None) -> Tensor Computes the one dimensional discrete Fourier transform of a Hermitian symmetric :attr:`input` signal. @@ -697,6 +733,9 @@ Default is ``"backward"`` (no normalization). +Keyword args: + {out} + Example: Taking a real-valued frequency signal and bringing it into the time domain @@ -722,10 +761,10 @@ >>> torch.fft.hfft(T[:3]) tensor([0.5000, 1.1236, 2.5000, 3.8764]) -""") +""".format(**common_args)) ihfft = _add_docstr(_fft.fft_ihfft, r""" -ihfft(input, n=None, dim=-1, norm=None) -> Tensor +ihfft(input, n=None, dim=-1, norm=None, *, out=None) -> Tensor Computes the inverse of :func:`~torch.fft.hfft`. @@ -754,6 +793,9 @@ Default is ``"backward"`` (normalize by ``1/n``). +Keyword args: + {out} + Example: >>> t = torch.arange(5) @@ -767,10 +809,10 @@ >>> torch.fft.ifft(t) tensor([ 2.0000+-0.0000j, -0.5000-0.6882j, -0.5000-0.1625j, -0.5000+0.1625j, -0.5000+0.6882j]) -""") +""".format(**common_args)) fftfreq = _add_docstr(_fft.fft_fftfreq, r""" -fftfreq(n, d=1.0, *, dtype=None, layout=torch.strided, device=None, requires_grad=False) -> Tensor +fftfreq(n, d=1.0, *, out=None, dtype=None, layout=torch.strided, device=None, requires_grad=False) -> Tensor Computes the discrete Fourier Transform sample frequencies for a signal of size :attr:`n`. @@ -796,6 +838,7 @@ spacing gives the result in physical frequency units. Keyword Args: + {out} {dtype} {layout} {device} @@ -815,7 +858,7 @@ """.format(**factory_common_args)) rfftfreq = _add_docstr(_fft.fft_rfftfreq, r""" -rfftfreq(n, d=1.0, *, dtype=None, layout=torch.strided, device=None, requires_grad=False) -> Tensor +rfftfreq(n, d=1.0, *, out=None, dtype=None, layout=torch.strided, device=None, requires_grad=False) -> Tensor Computes the sample frequencies for :func:`~torch.fft.rfft` with a signal of size :attr:`n`. @@ -839,6 +882,7 @@ spacing gives the result in physical frequency units. Keyword Args: + {out} {dtype} {layout} {device}