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 Transforms - basic.py 

3""" 

4# Created by Pearu Peterson, August,September 2002 

5__all__ = ['fft','ifft','fftn','ifftn','rfft','irfft', 

6 'fft2','ifft2'] 

7 

8from scipy.fft import _pocketfft 

9from .helper import _good_shape 

10 

11 

12def fft(x, n=None, axis=-1, overwrite_x=False): 

13 """ 

14 Return discrete Fourier transform of real or complex sequence. 

15 

16 The returned complex array contains ``y(0), y(1),..., y(n-1)``, where 

17 

18 ``y(j) = (x * exp(-2*pi*sqrt(-1)*j*np.arange(n)/n)).sum()``. 

19 

20 Parameters 

21 ---------- 

22 x : array_like 

23 Array to Fourier transform. 

24 n : int, optional 

25 Length of the Fourier transform. If ``n < x.shape[axis]``, `x` is 

26 truncated. If ``n > x.shape[axis]``, `x` is zero-padded. The 

27 default results in ``n = x.shape[axis]``. 

28 axis : int, optional 

29 Axis along which the fft's are computed; the default is over the 

30 last axis (i.e., ``axis=-1``). 

31 overwrite_x : bool, optional 

32 If True, the contents of `x` can be destroyed; the default is False. 

33 

34 Returns 

35 ------- 

36 z : complex ndarray 

37 with the elements:: 

38 

39 [y(0),y(1),..,y(n/2),y(1-n/2),...,y(-1)] if n is even 

40 [y(0),y(1),..,y((n-1)/2),y(-(n-1)/2),...,y(-1)] if n is odd 

41 

42 where:: 

43 

44 y(j) = sum[k=0..n-1] x[k] * exp(-sqrt(-1)*j*k* 2*pi/n), j = 0..n-1 

45 

46 See Also 

47 -------- 

48 ifft : Inverse FFT 

49 rfft : FFT of a real sequence 

50 

51 Notes 

52 ----- 

53 The packing of the result is "standard": If ``A = fft(a, n)``, then 

54 ``A[0]`` contains the zero-frequency term, ``A[1:n/2]`` contains the 

55 positive-frequency terms, and ``A[n/2:]`` contains the negative-frequency 

56 terms, in order of decreasingly negative frequency. So ,for an 8-point 

57 transform, the frequencies of the result are [0, 1, 2, 3, -4, -3, -2, -1]. 

58 To rearrange the fft output so that the zero-frequency component is 

59 centered, like [-4, -3, -2, -1, 0, 1, 2, 3], use `fftshift`. 

60 

61 Both single and double precision routines are implemented. Half precision 

62 inputs will be converted to single precision. Non-floating-point inputs 

63 will be converted to double precision. Long-double precision inputs are 

64 not supported. 

65 

66 This function is most efficient when `n` is a power of two, and least 

67 efficient when `n` is prime. 

68 

69 Note that if ``x`` is real-valued, then ``A[j] == A[n-j].conjugate()``. 

70 If ``x`` is real-valued and ``n`` is even, then ``A[n/2]`` is real. 

71 

72 If the data type of `x` is real, a "real FFT" algorithm is automatically 

73 used, which roughly halves the computation time. To increase efficiency 

74 a little further, use `rfft`, which does the same calculation, but only 

75 outputs half of the symmetrical spectrum. If the data is both real and 

76 symmetrical, the `dct` can again double the efficiency by generating 

77 half of the spectrum from half of the signal. 

78 

79 Examples 

80 -------- 

81 >>> from scipy.fftpack import fft, ifft 

82 >>> x = np.arange(5) 

83 >>> np.allclose(fft(ifft(x)), x, atol=1e-15) # within numerical accuracy. 

84 True 

85 

86 """ 

87 return _pocketfft.fft(x, n, axis, None, overwrite_x) 

88 

89 

90def ifft(x, n=None, axis=-1, overwrite_x=False): 

91 """ 

92 Return discrete inverse Fourier transform of real or complex sequence. 

93 

94 The returned complex array contains ``y(0), y(1),..., y(n-1)``, where 

95 

96 ``y(j) = (x * exp(2*pi*sqrt(-1)*j*np.arange(n)/n)).mean()``. 

97 

98 Parameters 

99 ---------- 

100 x : array_like 

101 Transformed data to invert. 

102 n : int, optional 

103 Length of the inverse Fourier transform. If ``n < x.shape[axis]``, 

104 `x` is truncated. If ``n > x.shape[axis]``, `x` is zero-padded. 

105 The default results in ``n = x.shape[axis]``. 

106 axis : int, optional 

107 Axis along which the ifft's are computed; the default is over the 

108 last axis (i.e., ``axis=-1``). 

109 overwrite_x : bool, optional 

110 If True, the contents of `x` can be destroyed; the default is False. 

111 

112 Returns 

113 ------- 

114 ifft : ndarray of floats 

115 The inverse discrete Fourier transform. 

116 

117 See Also 

118 -------- 

119 fft : Forward FFT 

120 

121 Notes 

122 ----- 

123 Both single and double precision routines are implemented. Half precision 

124 inputs will be converted to single precision. Non-floating-point inputs 

125 will be converted to double precision. Long-double precision inputs are 

126 not supported. 

127 

128 This function is most efficient when `n` is a power of two, and least 

129 efficient when `n` is prime. 

130 

131 If the data type of `x` is real, a "real IFFT" algorithm is automatically 

132 used, which roughly halves the computation time. 

133 

134 Examples 

135 -------- 

136 >>> from scipy.fftpack import fft, ifft 

137 >>> import numpy as np 

138 >>> x = np.arange(5) 

139 >>> np.allclose(ifft(fft(x)), x, atol=1e-15) # within numerical accuracy. 

140 True 

141 

142 """ 

143 return _pocketfft.ifft(x, n, axis, None, overwrite_x) 

144 

145 

146def rfft(x, n=None, axis=-1, overwrite_x=False): 

147 """ 

148 Discrete Fourier transform of a real sequence. 

149 

150 Parameters 

151 ---------- 

152 x : array_like, real-valued 

153 The data to transform. 

154 n : int, optional 

155 Defines the length of the Fourier transform. If `n` is not specified 

156 (the default) then ``n = x.shape[axis]``. If ``n < x.shape[axis]``, 

157 `x` is truncated, if ``n > x.shape[axis]``, `x` is zero-padded. 

158 axis : int, optional 

159 The axis along which the transform is applied. The default is the 

160 last axis. 

161 overwrite_x : bool, optional 

162 If set to true, the contents of `x` can be overwritten. Default is 

163 False. 

164 

165 Returns 

166 ------- 

167 z : real ndarray 

168 The returned real array contains:: 

169 

170 [y(0),Re(y(1)),Im(y(1)),...,Re(y(n/2))] if n is even 

171 [y(0),Re(y(1)),Im(y(1)),...,Re(y(n/2)),Im(y(n/2))] if n is odd 

172 

173 where:: 

174 

175 y(j) = sum[k=0..n-1] x[k] * exp(-sqrt(-1)*j*k*2*pi/n) 

176 j = 0..n-1 

177 

178 See Also 

179 -------- 

180 fft, irfft, scipy.fft.rfft 

181 

182 Notes 

183 ----- 

184 Within numerical accuracy, ``y == rfft(irfft(y))``. 

185 

186 Both single and double precision routines are implemented. Half precision 

187 inputs will be converted to single precision. Non-floating-point inputs 

188 will be converted to double precision. Long-double precision inputs are 

189 not supported. 

190 

191 To get an output with a complex datatype, consider using the newer 

192 function `scipy.fft.rfft`. 

193 

194 Examples 

195 -------- 

196 >>> from scipy.fftpack import fft, rfft 

197 >>> a = [9, -9, 1, 3] 

198 >>> fft(a) 

199 array([ 4. +0.j, 8.+12.j, 16. +0.j, 8.-12.j]) 

200 >>> rfft(a) 

201 array([ 4., 8., 12., 16.]) 

202 

203 """ 

204 return _pocketfft.rfft_fftpack(x, n, axis, None, overwrite_x) 

205 

206 

207def irfft(x, n=None, axis=-1, overwrite_x=False): 

208 """ 

209 Return inverse discrete Fourier transform of real sequence x. 

210 

211 The contents of `x` are interpreted as the output of the `rfft` 

212 function. 

213 

214 Parameters 

215 ---------- 

216 x : array_like 

217 Transformed data to invert. 

218 n : int, optional 

219 Length of the inverse Fourier transform. 

220 If n < x.shape[axis], x is truncated. 

221 If n > x.shape[axis], x is zero-padded. 

222 The default results in n = x.shape[axis]. 

223 axis : int, optional 

224 Axis along which the ifft's are computed; the default is over 

225 the last axis (i.e., axis=-1). 

226 overwrite_x : bool, optional 

227 If True, the contents of `x` can be destroyed; the default is False. 

228 

229 Returns 

230 ------- 

231 irfft : ndarray of floats 

232 The inverse discrete Fourier transform. 

233 

234 See Also 

235 -------- 

236 rfft, ifft, scipy.fft.irfft 

237 

238 Notes 

239 ----- 

240 The returned real array contains:: 

241 

242 [y(0),y(1),...,y(n-1)] 

243 

244 where for n is even:: 

245 

246 y(j) = 1/n (sum[k=1..n/2-1] (x[2*k-1]+sqrt(-1)*x[2*k]) 

247 * exp(sqrt(-1)*j*k* 2*pi/n) 

248 + c.c. + x[0] + (-1)**(j) x[n-1]) 

249 

250 and for n is odd:: 

251 

252 y(j) = 1/n (sum[k=1..(n-1)/2] (x[2*k-1]+sqrt(-1)*x[2*k]) 

253 * exp(sqrt(-1)*j*k* 2*pi/n) 

254 + c.c. + x[0]) 

255 

256 c.c. denotes complex conjugate of preceding expression. 

257 

258 For details on input parameters, see `rfft`. 

259 

260 To process (conjugate-symmetric) frequency-domain data with a complex 

261 datatype, consider using the newer function `scipy.fft.irfft`. 

262 

263 Examples 

264 -------- 

265 >>> from scipy.fftpack import rfft, irfft 

266 >>> a = [1.0, 2.0, 3.0, 4.0, 5.0] 

267 >>> irfft(a) 

268 array([ 2.6 , -3.16405192, 1.24398433, -1.14955713, 1.46962473]) 

269 >>> irfft(rfft(a)) 

270 array([1., 2., 3., 4., 5.]) 

271 

272 """ 

273 return _pocketfft.irfft_fftpack(x, n, axis, None, overwrite_x) 

274 

275 

276def fftn(x, shape=None, axes=None, overwrite_x=False): 

277 """ 

278 Return multidimensional discrete Fourier transform. 

279 

280 The returned array contains:: 

281 

282 y[j_1,..,j_d] = sum[k_1=0..n_1-1, ..., k_d=0..n_d-1] 

283 x[k_1,..,k_d] * prod[i=1..d] exp(-sqrt(-1)*2*pi/n_i * j_i * k_i) 

284 

285 where d = len(x.shape) and n = x.shape. 

286 

287 Parameters 

288 ---------- 

289 x : array_like 

290 The (N-D) array to transform. 

291 shape : int or array_like of ints or None, optional 

292 The shape of the result. If both `shape` and `axes` (see below) are 

293 None, `shape` is ``x.shape``; if `shape` is None but `axes` is 

294 not None, then `shape` is ``scipy.take(x.shape, axes, axis=0)``. 

295 If ``shape[i] > x.shape[i]``, the ith dimension is padded with zeros. 

296 If ``shape[i] < x.shape[i]``, the ith dimension is truncated to 

297 length ``shape[i]``. 

298 If any element of `shape` is -1, the size of the corresponding 

299 dimension of `x` is used. 

300 axes : int or array_like of ints or None, optional 

301 The axes of `x` (`y` if `shape` is not None) along which the 

302 transform is applied. 

303 The default is over all axes. 

304 overwrite_x : bool, optional 

305 If True, the contents of `x` can be destroyed. Default is False. 

306 

307 Returns 

308 ------- 

309 y : complex-valued N-D NumPy array 

310 The (N-D) DFT of the input array. 

311 

312 See Also 

313 -------- 

314 ifftn 

315 

316 Notes 

317 ----- 

318 If ``x`` is real-valued, then 

319 ``y[..., j_i, ...] == y[..., n_i-j_i, ...].conjugate()``. 

320 

321 Both single and double precision routines are implemented. Half precision 

322 inputs will be converted to single precision. Non-floating-point inputs 

323 will be converted to double precision. Long-double precision inputs are 

324 not supported. 

325 

326 Examples 

327 -------- 

328 >>> from scipy.fftpack import fftn, ifftn 

329 >>> y = (-np.arange(16), 8 - np.arange(16), np.arange(16)) 

330 >>> np.allclose(y, fftn(ifftn(y))) 

331 True 

332 

333 """ 

334 shape = _good_shape(x, shape, axes) 

335 return _pocketfft.fftn(x, shape, axes, None, overwrite_x) 

336 

337 

338def ifftn(x, shape=None, axes=None, overwrite_x=False): 

339 """ 

340 Return inverse multidimensional discrete Fourier transform. 

341 

342 The sequence can be of an arbitrary type. 

343 

344 The returned array contains:: 

345 

346 y[j_1,..,j_d] = 1/p * sum[k_1=0..n_1-1, ..., k_d=0..n_d-1] 

347 x[k_1,..,k_d] * prod[i=1..d] exp(sqrt(-1)*2*pi/n_i * j_i * k_i) 

348 

349 where ``d = len(x.shape)``, ``n = x.shape``, and ``p = prod[i=1..d] n_i``. 

350 

351 For description of parameters see `fftn`. 

352 

353 See Also 

354 -------- 

355 fftn : for detailed information. 

356 

357 Examples 

358 -------- 

359 >>> from scipy.fftpack import fftn, ifftn 

360 >>> import numpy as np 

361 >>> y = (-np.arange(16), 8 - np.arange(16), np.arange(16)) 

362 >>> np.allclose(y, ifftn(fftn(y))) 

363 True 

364 

365 """ 

366 shape = _good_shape(x, shape, axes) 

367 return _pocketfft.ifftn(x, shape, axes, None, overwrite_x) 

368 

369 

370def fft2(x, shape=None, axes=(-2,-1), overwrite_x=False): 

371 """ 

372 2-D discrete Fourier transform. 

373 

374 Return the 2-D discrete Fourier transform of the 2-D argument 

375 `x`. 

376 

377 See Also 

378 -------- 

379 fftn : for detailed information. 

380 

381 Examples 

382 -------- 

383 >>> from scipy.fftpack import fft2, ifft2 

384 >>> y = np.mgrid[:5, :5][0] 

385 >>> y 

386 array([[0, 0, 0, 0, 0], 

387 [1, 1, 1, 1, 1], 

388 [2, 2, 2, 2, 2], 

389 [3, 3, 3, 3, 3], 

390 [4, 4, 4, 4, 4]]) 

391 >>> np.allclose(y, ifft2(fft2(y))) 

392 True 

393 """ 

394 return fftn(x,shape,axes,overwrite_x) 

395 

396 

397def ifft2(x, shape=None, axes=(-2,-1), overwrite_x=False): 

398 """ 

399 2-D discrete inverse Fourier transform of real or complex sequence. 

400 

401 Return inverse 2-D discrete Fourier transform of 

402 arbitrary type sequence x. 

403 

404 See `ifft` for more information. 

405 

406 See also 

407 -------- 

408 fft2, ifft 

409 

410 Examples 

411 -------- 

412 >>> from scipy.fftpack import fft2, ifft2 

413 >>> y = np.mgrid[:5, :5][0] 

414 >>> y 

415 array([[0, 0, 0, 0, 0], 

416 [1, 1, 1, 1, 1], 

417 [2, 2, 2, 2, 2], 

418 [3, 3, 3, 3, 3], 

419 [4, 4, 4, 4, 4]]) 

420 >>> np.allclose(y, fft2(ifft2(y))) 

421 True 

422 

423 """ 

424 return ifftn(x,shape,axes,overwrite_x)