Hide keyboard shortcuts

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============================================= 

4 

5.. currentmodule:: numpy.fft 

6 

7Standard FFTs 

8------------- 

9 

10.. autosummary:: 

11 :toctree: generated/ 

12 

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. 

19 

20Real FFTs 

21--------- 

22 

23.. autosummary:: 

24 :toctree: generated/ 

25 

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. 

32 

33Hermitian FFTs 

34-------------- 

35 

36.. autosummary:: 

37 :toctree: generated/ 

38 

39 hfft Hermitian discrete Fourier transform. 

40 ihfft Inverse Hermitian discrete Fourier transform. 

41 

42Helper routines 

43--------------- 

44 

45.. autosummary:: 

46 :toctree: generated/ 

47 

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. 

52 

53 

54Background information 

55---------------------- 

56 

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. 

67 

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*. 

75 

76Implementation details 

77---------------------- 

78 

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 

82 

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. 

86 

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. 

92 

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. 

107 

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)``. 

111 

112The inverse DFT is defined as 

113 

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. 

117 

118It differs from the forward transform by the sign of the exponential 

119argument and the default normalization by :math:`1/n`. 

120 

121Type Promotion 

122-------------- 

123 

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`. 

127 

128Normalization 

129------------- 

130 

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}`. 

136 

137Real and Hermitian transforms 

138----------------------------- 

139 

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. 

151 

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. 

156 

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. 

162 

163Higher dimensions 

164----------------- 

165 

166In two dimensions, the DFT is defined as 

167 

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, 

172 

173which extends in the obvious way to higher dimensions, and the inverses 

174in higher dimensions also extend in the same way. 

175 

176References 

177---------- 

178 

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. 

182 

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. 

186 

187Examples 

188-------- 

189 

190For examples, see the various functions. 

191 

192""" 

193 

194from ._pocketfft import * 

195from .helper import * 

196 

197from numpy._pytesttester import PytestTester 

198test = PytestTester(__name__) 

199del PytestTester