1"""

2 Discrete Fourier Transform (:mod:`numpy.fft`)

3=============================================

4

5.. currentmodule:: numpy.fft

6

7 The SciPy module `scipy.fft` is a more comprehensive superset

8 of ``numpy.fft``, which includes only a basic set of routines.

9

10 Standard FFTs

11-------------

12

13.. autosummary::

14 :toctree: generated/

15

16 fft Discrete Fourier transform.

17 ifft Inverse discrete Fourier transform.

18 fft2 Discrete Fourier transform in two dimensions.

19 ifft2 Inverse discrete Fourier transform in two dimensions.

20 fftn Discrete Fourier transform in N-dimensions.

21 ifftn Inverse discrete Fourier transform in N dimensions.

22

23 Real FFTs

24---------

25

26.. autosummary::

27 :toctree: generated/

28

29 rfft Real discrete Fourier transform.

30 irfft Inverse real discrete Fourier transform.

31 rfft2 Real discrete Fourier transform in two dimensions.

32 irfft2 Inverse real discrete Fourier transform in two dimensions.

33 rfftn Real discrete Fourier transform in N dimensions.

34 irfftn Inverse real discrete Fourier transform in N dimensions.

35

36 Hermitian FFTs

37--------------

38

39.. autosummary::

40 :toctree: generated/

41

42 hfft Hermitian discrete Fourier transform.

43 ihfft Inverse Hermitian discrete Fourier transform.

44

45 Helper routines

46---------------

47

48.. autosummary::

49 :toctree: generated/

50

51 fftfreq Discrete Fourier Transform sample frequencies.

52 rfftfreq DFT sample frequencies (for usage with rfft, irfft).

53 fftshift Shift zero-frequency component to center of spectrum.

54 ifftshift Inverse of fftshift.

55

56

57 Background information

58----------------------

59

60 Fourier analysis is fundamentally a method for expressing a function as a

61 sum of periodic components, and for recovering the function from those

62 components. When both the function and its Fourier transform are

63 replaced with discretized counterparts, it is called the discrete Fourier

64 transform (DFT). The DFT has become a mainstay of numerical computing in

65 part because of a very fast algorithm for computing it, called the Fast

66 Fourier Transform (FFT), which was known to Gauss (1805) and was brought

67 to light in its current form by Cooley and Tukey [CT]_. Press et al. [NR]_

68 provide an accessible introduction to Fourier analysis and its

69 applications.

70

71 Because the discrete Fourier transform separates its input into

72 components that contribute at discrete frequencies, it has a great number

73 of applications in digital signal processing, e.g., for filtering, and in

74 this context the discretized input to the transform is customarily

75 referred to as a *signal*, which exists in the *time domain*. The output

76 is called a *spectrum* or *transform* and exists in the *frequency

77 domain*.

78

79 Implementation details

80----------------------

81

82 There are many ways to define the DFT, varying in the sign of the

83 exponent, normalization, etc. In this implementation, the DFT is defined

84 as

85

86.. math::

87 A_k = \\sum_{m=0}^{n-1} a_m \\exp\\left\\{-2\\pi i{mk \\over n}\\right\\}

88 \\qquad k = 0,\\ldots,n-1.

89

90 The DFT is in general defined for complex inputs and outputs, and a

91 single-frequency component at linear frequency :math:`f` is

92 represented by a complex exponential

93:math:`a_m = \\exp\\{2\\pi i\\,f m\\Delta t\\}`, where :math:`\\Delta t`

94 is the sampling interval.

95

96 The values in the result follow so-called "standard" order: If ``A =

97 fft(a, n)``, then ``A[0]`` contains the zero-frequency term (the sum of

98 the signal), which is always purely real for real inputs. Then ``A[1:n/2]``

99 contains the positive-frequency terms, and ``A[n/2+1:]`` contains the

100 negative-frequency terms, in order of decreasingly negative frequency.

101 For an even number of input points, ``A[n/2]`` represents both positive and

102 negative Nyquist frequency, and is also purely real for real input. For

103 an odd number of input points, ``A[(n-1)/2]`` contains the largest positive

104 frequency, while ``A[(n+1)/2]`` contains the largest negative frequency.

105 The routine ``np.fft.fftfreq(n)`` returns an array giving the frequencies

106 of corresponding elements in the output. The routine

107``np.fft.fftshift(A)`` shifts transforms and their frequencies to put the

108 zero-frequency components in the middle, and ``np.fft.ifftshift(A)`` undoes

109 that shift.

110

111 When the input `a` is a time-domain signal and ``A = fft(a)``, ``np.abs(A)``

112 is its amplitude spectrum and ``np.abs(A)**2`` is its power spectrum.

113 The phase spectrum is obtained by ``np.angle(A)``.

114

115 The inverse DFT is defined as

116

117.. math::

118 a_m = \\frac{1}{n}\\sum_{k=0}^{n-1}A_k\\exp\\left\\{2\\pi i{mk\\over n}\\right\\}

119 \\qquad m = 0,\\ldots,n-1.

120

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

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

123

124 Type Promotion

125--------------

126

127`numpy.fft` promotes ``float32`` and ``complex64`` arrays to ``float64`` and

128``complex128`` arrays respectively. For an FFT implementation that does not

129 promote input arrays, see `scipy.fftpack`.

130

131 Normalization

132-------------

133

134 The argument ``norm`` indicates which direction of the pair of direct/inverse

135 transforms is scaled and with what normalization factor.

136 The default normalization (``"backward"``) has the direct (forward) transforms

137 unscaled and the inverse (backward) transforms scaled by :math:`1/n`. It is

138 possible to obtain unitary transforms by setting the keyword argument ``norm``

139 to ``"ortho"`` so that both direct and inverse transforms are scaled by

140:math:`1/\\sqrt{n}`. Finally, setting the keyword argument ``norm`` to

141``"forward"`` has the direct transforms scaled by :math:`1/n` and the inverse

142 transforms unscaled (i.e. exactly opposite to the default ``"backward"``).

143`None` is an alias of the default option ``"backward"`` for backward

144 compatibility.

145

146 Real and Hermitian transforms

147-----------------------------

148

149 When the input is purely real, its transform is Hermitian, i.e., the

150 component at frequency :math:`f_k` is the complex conjugate of the

151 component at frequency :math:`-f_k`, which means that for real

152 inputs there is no information in the negative frequency components that

153 is not already available from the positive frequency components.

154 The family of `rfft` functions is

155 designed to operate on real inputs, and exploits this symmetry by

156 computing only the positive frequency components, up to and including the

157 Nyquist frequency. Thus, ``n`` input points produce ``n/2+1`` complex

158 output points. The inverses of this family assumes the same symmetry of

159 its input, and for an output of ``n`` points uses ``n/2+1`` input points.

160

161 Correspondingly, when the spectrum is purely real, the signal is

162 Hermitian. The `hfft` family of functions exploits this symmetry by

163 using ``n/2+1`` complex points in the input (time) domain for ``n`` real

164 points in the frequency domain.

165

166 In higher dimensions, FFTs are used, e.g., for image analysis and

167 filtering. The computational efficiency of the FFT means that it can

168 also be a faster way to compute large convolutions, using the property

169 that a convolution in the time domain is equivalent to a point-by-point

170 multiplication in the frequency domain.

171

172 Higher dimensions

173-----------------

174

175 In two dimensions, the DFT is defined as

176

177.. math::

178 A_{kl} = \\sum_{m=0}^{M-1} \\sum_{n=0}^{N-1}

179 a_{mn}\\exp\\left\\{-2\\pi i \\left({mk\\over M}+{nl\\over N}\\right)\\right\\}

180 \\qquad k = 0, \\ldots, M-1;\\quad l = 0, \\ldots, N-1,

181

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

183 in higher dimensions also extend in the same way.

184

185 References

186----------

187

188.. [CT] Cooley, James W., and John W. Tukey, 1965, "An algorithm for the

189 machine calculation of complex Fourier series," *Math. Comput.*

190 19: 297-301.

191

192.. [NR] Press, W., Teukolsky, S., Vetterline, W.T., and Flannery, B.P.,

193 2007, *Numerical Recipes: The Art of Scientific Computing*, ch.

194 12-13. Cambridge Univ. Press, Cambridge, UK.

195

196 Examples

197--------

198

199 For examples, see the various functions.

200

201"""

202

203 from . import _pocketfft, helper

204 from ._pocketfft import *

205 from .helper import *

206

207__all__ = _pocketfft.__all__.copy()

208__all__ += helper.__all__

209

210 from numpy._pytesttester import PytestTester

211 test = PytestTester(__name__)

212 del PytestTester