Repository: numpy/numpy

Issue:
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.)


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.

Resolving patch:
diff --git a/numpy/fft/_pocketfft.py b/numpy/fft/_pocketfft.py
--- 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.
+    rfft : The one-dimensional FFT for real input.
+    irfft : The inverse of the one-dimensional FFT of real input.
     irfftn : Compute the inverse of the N-dimensional FFT of real input.
 
     Notes


Test patch: