Coverage for /home/martinb/.local/share/virtualenvs/camcops/lib/python3.6/site-packages/numpy/fft/__init__.py : 100%

Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""
2Discrete Fourier Transform (:mod:`numpy.fft`)
3=============================================
5.. currentmodule:: numpy.fft
7Standard FFTs
8-------------
10.. autosummary::
11 :toctree: generated/
13 fft Discrete Fourier transform.
14 ifft Inverse discrete Fourier transform.
15 fft2 Discrete Fourier transform in two dimensions.
16 ifft2 Inverse discrete Fourier transform in two dimensions.
17 fftn Discrete Fourier transform in N-dimensions.
18 ifftn Inverse discrete Fourier transform in N dimensions.
20Real FFTs
21---------
23.. autosummary::
24 :toctree: generated/
26 rfft Real discrete Fourier transform.
27 irfft Inverse real discrete Fourier transform.
28 rfft2 Real discrete Fourier transform in two dimensions.
29 irfft2 Inverse real discrete Fourier transform in two dimensions.
30 rfftn Real discrete Fourier transform in N dimensions.
31 irfftn Inverse real discrete Fourier transform in N dimensions.
33Hermitian FFTs
34--------------
36.. autosummary::
37 :toctree: generated/
39 hfft Hermitian discrete Fourier transform.
40 ihfft Inverse Hermitian discrete Fourier transform.
42Helper routines
43---------------
45.. autosummary::
46 :toctree: generated/
48 fftfreq Discrete Fourier Transform sample frequencies.
49 rfftfreq DFT sample frequencies (for usage with rfft, irfft).
50 fftshift Shift zero-frequency component to center of spectrum.
51 ifftshift Inverse of fftshift.
54Background information
55----------------------
57Fourier analysis is fundamentally a method for expressing a function as a
58sum of periodic components, and for recovering the function from those
59components. When both the function and its Fourier transform are
60replaced with discretized counterparts, it is called the discrete Fourier
61transform (DFT). The DFT has become a mainstay of numerical computing in
62part because of a very fast algorithm for computing it, called the Fast
63Fourier Transform (FFT), which was known to Gauss (1805) and was brought
64to light in its current form by Cooley and Tukey [CT]_. Press et al. [NR]_
65provide an accessible introduction to Fourier analysis and its
66applications.
68Because the discrete Fourier transform separates its input into
69components that contribute at discrete frequencies, it has a great number
70of applications in digital signal processing, e.g., for filtering, and in
71this context the discretized input to the transform is customarily
72referred to as a *signal*, which exists in the *time domain*. The output
73is called a *spectrum* or *transform* and exists in the *frequency
74domain*.
76Implementation details
77----------------------
79There are many ways to define the DFT, varying in the sign of the
80exponent, normalization, etc. In this implementation, the DFT is defined
81as
83.. math::
84 A_k = \\sum_{m=0}^{n-1} a_m \\exp\\left\\{-2\\pi i{mk \\over n}\\right\\}
85 \\qquad k = 0,\\ldots,n-1.
87The DFT is in general defined for complex inputs and outputs, and a
88single-frequency component at linear frequency :math:`f` is
89represented by a complex exponential
90:math:`a_m = \\exp\\{2\\pi i\\,f m\\Delta t\\}`, where :math:`\\Delta t`
91is the sampling interval.
93The values in the result follow so-called "standard" order: If ``A =
94fft(a, n)``, then ``A[0]`` contains the zero-frequency term (the sum of
95the signal), which is always purely real for real inputs. Then ``A[1:n/2]``
96contains the positive-frequency terms, and ``A[n/2+1:]`` contains the
97negative-frequency terms, in order of decreasingly negative frequency.
98For an even number of input points, ``A[n/2]`` represents both positive and
99negative Nyquist frequency, and is also purely real for real input. For
100an odd number of input points, ``A[(n-1)/2]`` contains the largest positive
101frequency, while ``A[(n+1)/2]`` contains the largest negative frequency.
102The routine ``np.fft.fftfreq(n)`` returns an array giving the frequencies
103of corresponding elements in the output. The routine
104``np.fft.fftshift(A)`` shifts transforms and their frequencies to put the
105zero-frequency components in the middle, and ``np.fft.ifftshift(A)`` undoes
106that shift.
108When the input `a` is a time-domain signal and ``A = fft(a)``, ``np.abs(A)``
109is its amplitude spectrum and ``np.abs(A)**2`` is its power spectrum.
110The phase spectrum is obtained by ``np.angle(A)``.
112The inverse DFT is defined as
114.. math::
115 a_m = \\frac{1}{n}\\sum_{k=0}^{n-1}A_k\\exp\\left\\{2\\pi i{mk\\over n}\\right\\}
116 \\qquad m = 0,\\ldots,n-1.
118It differs from the forward transform by the sign of the exponential
119argument and the default normalization by :math:`1/n`.
121Type Promotion
122--------------
124`numpy.fft` promotes ``float32`` and ``complex64`` arrays to ``float64`` and
125``complex128`` arrays respectively. For an FFT implementation that does not
126promote input arrays, see `scipy.fftpack`.
128Normalization
129-------------
131The default normalization has the direct transforms unscaled and the inverse
132transforms are scaled by :math:`1/n`. It is possible to obtain unitary
133transforms by setting the keyword argument ``norm`` to ``"ortho"`` (default is
134`None`) so that both direct and inverse transforms will be scaled by
135:math:`1/\\sqrt{n}`.
137Real and Hermitian transforms
138-----------------------------
140When the input is purely real, its transform is Hermitian, i.e., the
141component at frequency :math:`f_k` is the complex conjugate of the
142component at frequency :math:`-f_k`, which means that for real
143inputs there is no information in the negative frequency components that
144is not already available from the positive frequency components.
145The family of `rfft` functions is
146designed to operate on real inputs, and exploits this symmetry by
147computing only the positive frequency components, up to and including the
148Nyquist frequency. Thus, ``n`` input points produce ``n/2+1`` complex
149output points. The inverses of this family assumes the same symmetry of
150its input, and for an output of ``n`` points uses ``n/2+1`` input points.
152Correspondingly, when the spectrum is purely real, the signal is
153Hermitian. The `hfft` family of functions exploits this symmetry by
154using ``n/2+1`` complex points in the input (time) domain for ``n`` real
155points in the frequency domain.
157In higher dimensions, FFTs are used, e.g., for image analysis and
158filtering. The computational efficiency of the FFT means that it can
159also be a faster way to compute large convolutions, using the property
160that a convolution in the time domain is equivalent to a point-by-point
161multiplication in the frequency domain.
163Higher dimensions
164-----------------
166In two dimensions, the DFT is defined as
168.. math::
169 A_{kl} = \\sum_{m=0}^{M-1} \\sum_{n=0}^{N-1}
170 a_{mn}\\exp\\left\\{-2\\pi i \\left({mk\\over M}+{nl\\over N}\\right)\\right\\}
171 \\qquad k = 0, \\ldots, M-1;\\quad l = 0, \\ldots, N-1,
173which extends in the obvious way to higher dimensions, and the inverses
174in higher dimensions also extend in the same way.
176References
177----------
179.. [CT] Cooley, James W., and John W. Tukey, 1965, "An algorithm for the
180 machine calculation of complex Fourier series," *Math. Comput.*
181 19: 297-301.
183.. [NR] Press, W., Teukolsky, S., Vetterline, W.T., and Flannery, B.P.,
184 2007, *Numerical Recipes: The Art of Scientific Computing*, ch.
185 12-13. Cambridge Univ. Press, Cambridge, UK.
187Examples
188--------
190For examples, see the various functions.
192"""
194from ._pocketfft import *
195from .helper import *
197from numpy._pytesttester import PytestTester
198test = PytestTester(__name__)
199del PytestTester