Spaces:
Sleeping
Sleeping
| """ | |
| Discrete Fourier Transform (:mod:`numpy.fft`) | |
| ============================================= | |
| .. currentmodule:: numpy.fft | |
| The SciPy module `scipy.fft` is a more comprehensive superset | |
| of ``numpy.fft``, which includes only a basic set of routines. | |
| Standard FFTs | |
| ------------- | |
| .. autosummary:: | |
| :toctree: generated/ | |
| fft Discrete Fourier transform. | |
| ifft Inverse discrete Fourier transform. | |
| fft2 Discrete Fourier transform in two dimensions. | |
| ifft2 Inverse discrete Fourier transform in two dimensions. | |
| fftn Discrete Fourier transform in N-dimensions. | |
| ifftn Inverse discrete Fourier transform in N dimensions. | |
| Real FFTs | |
| --------- | |
| .. autosummary:: | |
| :toctree: generated/ | |
| rfft Real discrete Fourier transform. | |
| irfft Inverse real discrete Fourier transform. | |
| rfft2 Real discrete Fourier transform in two dimensions. | |
| irfft2 Inverse real discrete Fourier transform in two dimensions. | |
| rfftn Real discrete Fourier transform in N dimensions. | |
| irfftn Inverse real discrete Fourier transform in N dimensions. | |
| Hermitian FFTs | |
| -------------- | |
| .. autosummary:: | |
| :toctree: generated/ | |
| hfft Hermitian discrete Fourier transform. | |
| ihfft Inverse Hermitian discrete Fourier transform. | |
| Helper routines | |
| --------------- | |
| .. autosummary:: | |
| :toctree: generated/ | |
| fftfreq Discrete Fourier Transform sample frequencies. | |
| rfftfreq DFT sample frequencies (for usage with rfft, irfft). | |
| fftshift Shift zero-frequency component to center of spectrum. | |
| ifftshift Inverse of fftshift. | |
| Background information | |
| ---------------------- | |
| Fourier analysis is fundamentally a method for expressing a function as a | |
| sum of periodic components, and for recovering the function from those | |
| components. When both the function and its Fourier transform are | |
| replaced with discretized counterparts, it is called the discrete Fourier | |
| transform (DFT). The DFT has become a mainstay of numerical computing in | |
| part because of a very fast algorithm for computing it, called the Fast | |
| Fourier Transform (FFT), which was known to Gauss (1805) and was brought | |
| to light in its current form by Cooley and Tukey [CT]_. Press et al. [NR]_ | |
| provide an accessible introduction to Fourier analysis and its | |
| applications. | |
| Because the discrete Fourier transform separates its input into | |
| components that contribute at discrete frequencies, it has a great number | |
| of applications in digital signal processing, e.g., for filtering, and in | |
| this context the discretized input to the transform is customarily | |
| referred to as a *signal*, which exists in the *time domain*. The output | |
| is called a *spectrum* or *transform* and exists in the *frequency | |
| domain*. | |
| Implementation details | |
| ---------------------- | |
| There are many ways to define the DFT, varying in the sign of the | |
| exponent, normalization, etc. In this implementation, the DFT is defined | |
| as | |
| .. math:: | |
| A_k = \\sum_{m=0}^{n-1} a_m \\exp\\left\\{-2\\pi i{mk \\over n}\\right\\} | |
| \\qquad k = 0,\\ldots,n-1. | |
| The DFT is in general defined for complex inputs and outputs, and a | |
| single-frequency component at linear frequency :math:`f` is | |
| represented by a complex exponential | |
| :math:`a_m = \\exp\\{2\\pi i\\,f m\\Delta t\\}`, where :math:`\\Delta t` | |
| is the sampling interval. | |
| The values in the result follow so-called "standard" order: If ``A = | |
| fft(a, n)``, then ``A[0]`` contains the zero-frequency term (the sum of | |
| the signal), which is always purely real for real inputs. Then ``A[1:n/2]`` | |
| contains the positive-frequency terms, and ``A[n/2+1:]`` contains the | |
| negative-frequency terms, in order of decreasingly negative frequency. | |
| For an even number of input points, ``A[n/2]`` represents both positive and | |
| negative Nyquist frequency, and is also purely real for real input. For | |
| an odd number of input points, ``A[(n-1)/2]`` contains the largest positive | |
| frequency, while ``A[(n+1)/2]`` contains the largest negative frequency. | |
| The routine ``np.fft.fftfreq(n)`` returns an array giving the frequencies | |
| of corresponding elements in the output. The routine | |
| ``np.fft.fftshift(A)`` shifts transforms and their frequencies to put the | |
| zero-frequency components in the middle, and ``np.fft.ifftshift(A)`` undoes | |
| that shift. | |
| When the input `a` is a time-domain signal and ``A = fft(a)``, ``np.abs(A)`` | |
| is its amplitude spectrum and ``np.abs(A)**2`` is its power spectrum. | |
| The phase spectrum is obtained by ``np.angle(A)``. | |
| The inverse DFT is defined as | |
| .. math:: | |
| a_m = \\frac{1}{n}\\sum_{k=0}^{n-1}A_k\\exp\\left\\{2\\pi i{mk\\over n}\\right\\} | |
| \\qquad m = 0,\\ldots,n-1. | |
| It differs from the forward transform by the sign of the exponential | |
| argument and the default normalization by :math:`1/n`. | |
| Type Promotion | |
| -------------- | |
| `numpy.fft` promotes ``float32`` and ``complex64`` arrays to ``float64`` and | |
| ``complex128`` arrays respectively. For an FFT implementation that does not | |
| promote input arrays, see `scipy.fftpack`. | |
| Normalization | |
| ------------- | |
| The argument ``norm`` indicates which direction of the pair of direct/inverse | |
| transforms is scaled and with what normalization factor. | |
| The default normalization (``"backward"``) has the direct (forward) transforms | |
| unscaled and the inverse (backward) transforms scaled by :math:`1/n`. It is | |
| possible to obtain unitary transforms by setting the keyword argument ``norm`` | |
| to ``"ortho"`` so that both direct and inverse transforms are scaled by | |
| :math:`1/\\sqrt{n}`. Finally, setting the keyword argument ``norm`` to | |
| ``"forward"`` has the direct transforms scaled by :math:`1/n` and the inverse | |
| transforms unscaled (i.e. exactly opposite to the default ``"backward"``). | |
| `None` is an alias of the default option ``"backward"`` for backward | |
| compatibility. | |
| Real and Hermitian transforms | |
| ----------------------------- | |
| When the input is purely real, its transform is Hermitian, i.e., the | |
| component at frequency :math:`f_k` is the complex conjugate of the | |
| component at frequency :math:`-f_k`, which means that for real | |
| inputs there is no information in the negative frequency components that | |
| is not already available from the positive frequency components. | |
| The family of `rfft` functions is | |
| designed to operate on real inputs, and exploits this symmetry by | |
| computing only the positive frequency components, up to and including the | |
| Nyquist frequency. Thus, ``n`` input points produce ``n/2+1`` complex | |
| output points. The inverses of this family assumes the same symmetry of | |
| its input, and for an output of ``n`` points uses ``n/2+1`` input points. | |
| Correspondingly, when the spectrum is purely real, the signal is | |
| Hermitian. The `hfft` family of functions exploits this symmetry by | |
| using ``n/2+1`` complex points in the input (time) domain for ``n`` real | |
| points in the frequency domain. | |
| In higher dimensions, FFTs are used, e.g., for image analysis and | |
| filtering. The computational efficiency of the FFT means that it can | |
| also be a faster way to compute large convolutions, using the property | |
| that a convolution in the time domain is equivalent to a point-by-point | |
| multiplication in the frequency domain. | |
| Higher dimensions | |
| ----------------- | |
| In two dimensions, the DFT is defined as | |
| .. math:: | |
| A_{kl} = \\sum_{m=0}^{M-1} \\sum_{n=0}^{N-1} | |
| a_{mn}\\exp\\left\\{-2\\pi i \\left({mk\\over M}+{nl\\over N}\\right)\\right\\} | |
| \\qquad k = 0, \\ldots, M-1;\\quad l = 0, \\ldots, N-1, | |
| which extends in the obvious way to higher dimensions, and the inverses | |
| in higher dimensions also extend in the same way. | |
| References | |
| ---------- | |
| .. [CT] Cooley, James W., and John W. Tukey, 1965, "An algorithm for the | |
| machine calculation of complex Fourier series," *Math. Comput.* | |
| 19: 297-301. | |
| .. [NR] Press, W., Teukolsky, S., Vetterline, W.T., and Flannery, B.P., | |
| 2007, *Numerical Recipes: The Art of Scientific Computing*, ch. | |
| 12-13. Cambridge Univ. Press, Cambridge, UK. | |
| Examples | |
| -------- | |
| For examples, see the various functions. | |
| """ | |
| from . import _pocketfft, helper | |
| from ._pocketfft import * | |
| from .helper import * | |
| __all__ = _pocketfft.__all__.copy() | |
| __all__ += helper.__all__ | |
| from numpy._pytesttester import PytestTester | |
| test = PytestTester(__name__) | |
| del PytestTester | |