Merge pull request numpy#13710 from peterbell10/irfft-default-size

DOC: Add note to irfft-like functions about the default sizes

numpy/fft/pocketfft.py

@@ -392,8 +392,9 @@ def irfft(a, n=None, axis=-1, norm=None):
         Length of the transformed axis of the output.
         For `n` output points, ``n//2+1`` input points are necessary.  If the
         input is longer than this, it is cropped.  If it is shorter than this,
-        it is padded with zeros.  If `n` is not given, it is determined from
-        the length of the input along the axis specified by `axis`.
+        it is padded with zeros.  If `n` is not given, it is taken to be
+        ``2*(m-1)`` where ``m`` is the length of the input along the axis
+        specified by `axis`.
     axis : int, optional
         Axis over which to compute the inverse FFT. If not given, the last
         axis is used.
@@ -436,6 +437,14 @@ def irfft(a, n=None, axis=-1, norm=None):
     thus resample a series to `m` points via Fourier interpolation by:
     ``a_resamp = irfft(rfft(a), m)``.
 
+    The correct interpretation of the hermitian input depends on the length of
+    the original data, as given by `n`. This is because each input shape could
+    correspond to either an odd or even length signal. By default, `irfft`
+    assumes an even output length which puts the last entry at the Nyquist
+    frequency; aliasing with its symmetric counterpart. By Hermitian symmetry,
+    the value is thus treated as purely real. To avoid losing information, the
+    correct length of the real input **must** be given.
+
     Examples
     --------
     >>> np.fft.ifft([1, -1j, -1, 1j])
@@ -473,8 +482,9 @@ def hfft(a, n=None, axis=-1, norm=None):
         Length of the transformed axis of the output. For `n` output
         points, ``n//2 + 1`` input points are necessary.  If the input is
         longer than this, it is cropped.  If it is shorter than this, it is
-        padded with zeros.  If `n` is not given, it is determined from the
-        length of the input along the axis specified by `axis`.
+        padded with zeros.  If `n` is not given, it is taken to be ``2*(m-1)``
+        where ``m`` is the length of the input along the axis specified by
+        `axis`.
     axis : int, optional
         Axis over which to compute the FFT. If not given, the last
         axis is used.
@@ -513,6 +523,14 @@ def hfft(a, n=None, axis=-1, norm=None):
     * even: ``ihfft(hfft(a, 2*len(a) - 2) == a``, within roundoff error,
     * odd: ``ihfft(hfft(a, 2*len(a) - 1) == a``, within roundoff error.
 
+    The correct interpretation of the hermitian input depends on the length of
+    the original data, as given by `n`. This is because each input shape could
+    correspond to either an odd or even length signal. By default, `hfft`
+    assumes an even output length which puts the last entry at the Nyquist
+    frequency; aliasing with its symmetric counterpart. By Hermitian symmetry,
+    the value is thus treated as purely real. To avoid losing information, the
+    shape of the full signal **must** be given.
+
     Examples
     --------
     >>> signal = np.array([1, 2, 3, 4, 3, 2])
@@ -1167,8 +1185,9 @@ def irfftn(a, s=None, axes=None, norm=None):
         where ``s[-1]//2+1`` points of the input are used.
         Along any axis, if the shape indicated by `s` is smaller than that of
         the input, the input is cropped.  If it is larger, the input is padded
-        with zeros. If `s` is not given, the shape of the input along the
-        axes specified by `axes` is used.
+        with zeros. If `s` is not given, the shape of the input along the axes
+        specified by axes is used. Except for the last axis which is taken to be
+        ``2*(m-1)`` where ``m`` is the length of the input along that axis.
     axes : sequence of ints, optional
         Axes over which to compute the inverse FFT. If not given, the last
         `len(s)` axes are used, or all axes if `s` is also not specified.
@@ -1213,6 +1232,15 @@ def irfftn(a, s=None, axes=None, norm=None):
 
     See `rfft` for definitions and conventions used for real input.
 
+    The correct interpretation of the hermitian input depends on the shape of
+    the original data, as given by `s`. This is because each input shape could
+    correspond to either an odd or even length signal. By default, `irfftn`
+    assumes an even output length which puts the last entry at the Nyquist
+    frequency; aliasing with its symmetric counterpart. When performing the
+    final complex to real transform, the last value is thus treated as purely
+    real. To avoid losing information, the correct shape of the real input
+    **must** be given.
+
     Examples
     --------
     >>> a = np.zeros((3, 2, 2))
@@ -1244,7 +1272,7 @@ def irfft2(a, s=None, axes=(-2, -1), norm=None):
     a : array_like
         The input array
     s : sequence of ints, optional
-        Shape of the inverse FFT.
+        Shape of the real output to the inverse FFT.
     axes : sequence of ints, optional
         The axes over which to compute the inverse fft.
         Default is the last two axes.