DOC: Correct documentation of hfft/ihfft.

Corrections to #7492.

Correct the examples in the notes specifying the output length for the
hfft. Also clean up the documentation a bit.

[ci skip]

1 files changed, 33 insertions, 28 deletions

diff --git a/numpy/fft/fftpack.py b/numpy/fft/fftpack.py
index 8dc3eccbc..7486ff51e 100644
--- a/numpy/fft/fftpack.py
+++ b/numpy/fft/fftpack.py
@@ -467,34 +467,36 @@ def irfft(a, n=None, axis=-1, norm=None):
 
 def hfft(a, n=None, axis=-1, norm=None):
     """
-    Compute the FFT of a signal which has Hermitian symmetry (real spectrum).
+    Compute the FFT of a signal that has Hermitian symmetry, i.e., a real
+    spectrum.
 
     Parameters
     ----------
     a : array_like
         The input array.
     n : int, optional
-        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`.
+        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`.
     axis : int, optional
         Axis over which to compute the FFT. If not given, the last
         axis is used.
     norm : {None, "ortho"}, optional
-        .. versionadded:: 1.10.0
-
         Normalization mode (see `numpy.fft`). Default is None.
 
+        .. versionadded:: 1.10.0
+
     Returns
     -------
     out : ndarray
         The truncated or zero-padded input, transformed along the axis
         indicated by `axis`, or the last one if `axis` is not specified.
         The length of the transformed axis is `n`, or, if `n` is not given,
-        ``2*(m-1)`` where ``m`` is the length of the transformed axis of the
-        input. To get an odd number of output points, `n` must be specified.
+        ``2*m - 2`` where ``m`` is the length of the transformed axis of
+        the input. To get an odd number of output points, `n` must be
+        specified, for instance as ``2*m - 1`` in the typical case,
 
     Raises
     ------
@@ -509,10 +511,12 @@ def hfft(a, n=None, axis=-1, norm=None):
     Notes
     -----
     `hfft`/`ihfft` are a pair analogous to `rfft`/`irfft`, but for the
-    opposite case: here the signal has Hermitian symmetry in the time domain
-    and is real in the frequency domain. So here it's `hfft` for which
-    you must supply the length of the result if it is to be odd:
-    ``ihfft(hfft(a), len(a)) == a``, within numerical accuracy.
+    opposite case: here the signal has Hermitian symmetry in the time
+    domain and is real in the frequency domain. So here it's `hfft` for
+    which you must supply the length of the result if it is to be odd.
+
+    * even: ``ihfft(hfft(a, 2*len(a) - 2) == a``, within roundoff error,
+    * odd: ``ihfft(hfft(a, 2*len(a) - 1) == a``, within roundoff error.
 
     Examples
     --------
@@ -545,33 +549,32 @@ def hfft(a, n=None, axis=-1, norm=None):
 
 def ihfft(a, n=None, axis=-1, norm=None):
     """
-    Compute the inverse FFT of a signal which has Hermitian symmetry.
+    Compute the inverse FFT of a signal that has Hermitian symmetry.
 
     Parameters
     ----------
     a : array_like
         Input array.
     n : int, optional
-        Length of the inverse FFT.
-        Number of points along transformation axis in the input to use.
-        If `n` is smaller than the length of the input, the input is cropped.
-        If it is larger, the input is padded with zeros. If `n` is not given,
-        the length of the input along the axis specified by `axis` is used.
+        Length of the inverse FFT, the number of points along
+        transformation axis in the input to use.  If `n` is smaller than
+        the length of the input, the input is cropped.  If it is larger,
+        the input is padded with zeros. If `n` is not given, the length of
+        the input along the axis specified by `axis` is used.
     axis : int, optional
         Axis over which to compute the inverse FFT. If not given, the last
         axis is used.
     norm : {None, "ortho"}, optional
-        .. versionadded:: 1.10.0
-
         Normalization mode (see `numpy.fft`). Default is None.
 
+        .. versionadded:: 1.10.0
+
     Returns
     -------
     out : complex ndarray
         The truncated or zero-padded input, transformed along the axis
         indicated by `axis`, or the last one if `axis` is not specified.
-        If `n` is even, the length of the transformed axis is ``(n/2)+1``.
-        If `n` is odd, the length is ``(n+1)/2``.
+        The length of the transformed axis is ``n//2 + 1``.
 
     See also
     --------
@@ -580,10 +583,12 @@ def ihfft(a, n=None, axis=-1, norm=None):
     Notes
     -----
     `hfft`/`ihfft` are a pair analogous to `rfft`/`irfft`, but for the
-    opposite case: here the signal has Hermitian symmetry in the time domain
-    and is real in the frequency domain. So here it's `hfft` for which
-    you must supply the length of the result if it is to be odd:
-    ``ihfft(hfft(a), len(a)) == a``, within numerical accuracy.
+    opposite case: here the signal has Hermitian symmetry in the time
+    domain and is real in the frequency domain. So here it's `hfft` for
+    which you must supply the length of the result if it is to be odd:
+
+    * even: ``ihfft(hfft(a, 2*len(a) - 2) == a``, within roundoff error,
+    * odd: ``ihfft(hfft(a, 2*len(a) - 1) == a``, within roundoff error.
 
     Examples
     --------