Repository: numpy/numpy
Pull request: DOC: Clarify input to irfft/irfft2/irfftn
<!-- Please be sure you are following the instructions in the dev guidelines
http://www.numpy.org/devdocs/dev/development_workflow.html
-->

<!-- We'd appreciate it if your commit message is properly formatted
http://www.numpy.org/devdocs/dev/development_workflow.html#writing-the-commit-message
-->
Fixes #15622 in accordance with scipy/scipy#11743

Problem statement:
irfft/irfft2/irfftn docs are slightly confusing re: input type.
As of numpy 1.17, the docs for fft.irfft{,2,n} start with "Compute the inverse of the n-point DFT for real input." / "Compute the 2-dimensional inverse FFT of a real array." / "Compute the inverse of the N-dimensional FFT of real input.", which is slightly confusing if you're unfamiliar with fft conventions: a superficial reading would suggest that these functions take a real input, but actually the argument to irfft is complex, and it's the output which is real.
(Also, the inconsistency between the use of "DFT" and "FFT" could be avoided.)

Hints from issue discussion:
The distinction the docs are *trying* to make is that the `irfft*` functions are intended to compute the inverse of the result of the corresponding forward-`rfft*` functions. This distinction is important because the `rfft*` methods only compute the positive frequency terms, so mixing `fft*` and `rfft*` functions for the forward and backward transformations is dangerous

```python
>>> rg = np.random.default_rng()
>>> a = rg.random(1000)
>>> A = np.fft(a)
>>> ar = np.irfft(a)
>>> print(a.shape, ar.shape)
(1000,) (1998,)
```

I agree with you that the current wording is ambiguous: the important consideration is not the *type* of the input to `irfft*` (which, as you note, is indeed complex), but *which forward transform was used to produce it*. This distinction (i.e. that if you use an `rfft*` for the forward transform, you should use the corresponding `irfft*` for the inverse) must be made clear. PR's to help reduce this ambiguity would be welcome.
I'll go ahead an add a PR for the same.
This was nicely resolved in scipy/scipy#11743. Patching the numpy docs in the same way would be nice.

Commit message: DOC: Clarify input to irfft/irfft2/irfftn

Patch to review:
diff --git a/numpy/fft/_pocketfft.py b/numpy/fft/_pocketfft.py
index 38ea69834c6d..c164c6f84523 100644
--- a/numpy/fft/_pocketfft.py
+++ b/numpy/fft/_pocketfft.py
@@ -411,7 +411,7 @@ def rfft(a, n=None, axis=-1, norm=None):
 @array_function_dispatch(_fft_dispatcher)
 def irfft(a, n=None, axis=-1, norm=None):
     """
-    Compute the inverse of the n-point DFT for real input.
+    Computes the inverse of `rfft`.
 
     This function computes the inverse of the one-dimensional *n*-point
     discrete Fourier Transform of real input computed by `rfft`.
@@ -1249,7 +1249,7 @@ def rfft2(a, s=None, axes=(-2, -1), norm=None):
 @array_function_dispatch(_fftn_dispatcher)
 def irfftn(a, s=None, axes=None, norm=None):
     """
-    Compute the inverse of the N-dimensional FFT of real input.
+    Computes the inverse of `rfftn`.
 
     This function computes the inverse of the N-dimensional discrete
     Fourier Transform for real input over any number of axes in an
@@ -1359,7 +1359,7 @@ def irfftn(a, s=None, axes=None, norm=None):
 @array_function_dispatch(_fftn_dispatcher)
 def irfft2(a, s=None, axes=(-2, -1), norm=None):
     """
-    Compute the 2-dimensional inverse FFT of a real array.
+    Computes the inverse of `rfft2`.
 
     Parameters
     ----------
@@ -1388,6 +1388,10 @@ def irfft2(a, s=None, axes=(-2, -1), norm=None):
 
     See Also
     --------
+    rfft2 : The forward two-dimensional FFT of real input,
+            of which `irfft2` is the inverse.
+    fft : The one-dimensional FFT, with definitions and conventions used.
+    irfft : The inverse of the one-dimensional FFT of real input.
     irfftn : Compute the inverse of the N-dimensional FFT of real input.
 
     Notes


Code review comments:
diff_hunk: @@ -1388,6 +1388,10 @@ def irfft2(a, s=None, axes=(-2, -1), norm=None):
 
     See Also
     --------
+    rfft2 : The forward two-dimensional FFT of real input,
+            of which `irfft2` is the inverse.
+    fft : The one-dimensional FFT, with definitions and conventions used.
path: numpy/fft/_pocketfft.py
text: @user1:
I think `rfft` fits better here than `fft`

@author:
Updated