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

1from scipy._lib.uarray import generate_multimethod, Dispatchable 

2import numpy as np 

3 

4 

5def _x_replacer(args, kwargs, dispatchables): 

6 """ 

7 uarray argument replacer to replace the transform input array (``x``) 

8 """ 

9 if len(args) > 0: 

10 return (dispatchables[0],) + args[1:], kwargs 

11 kw = kwargs.copy() 

12 kw['x'] = dispatchables[0] 

13 return args, kw 

14 

15 

16def _dispatch(func): 

17 """ 

18 Function annotation that creates a uarray multimethod from the function 

19 """ 

20 return generate_multimethod(func, _x_replacer, domain="numpy.scipy.fft") 

21 

22 

23@_dispatch 

24def fft(x, n=None, axis=-1, norm=None, overwrite_x=False, workers=None, *, 

25 plan=None): 

26 """ 

27 Compute the 1-D discrete Fourier Transform. 

28 

29 This function computes the 1-D *n*-point discrete Fourier 

30 Transform (DFT) with the efficient Fast Fourier Transform (FFT) 

31 algorithm [1]_. 

32 

33 Parameters 

34 ---------- 

35 x : array_like 

36 Input array, can be complex. 

37 n : int, optional 

38 Length of the transformed axis of the output. 

39 If `n` is smaller than the length of the input, the input is cropped. 

40 If it is larger, the input is padded with zeros. If `n` is not given, 

41 the length of the input along the axis specified by `axis` is used. 

42 axis : int, optional 

43 Axis over which to compute the FFT. If not given, the last axis is 

44 used. 

45 norm : {None, "ortho"}, optional 

46 Normalization mode. Default is None, meaning no normalization on the 

47 forward transforms and scaling by ``1/n`` on the `ifft`. 

48 For ``norm="ortho"``, both directions are scaled by ``1/sqrt(n)``. 

49 overwrite_x : bool, optional 

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

51 See the notes below for more details. 

52 workers : int, optional 

53 Maximum number of workers to use for parallel computation. If negative, 

54 the value wraps around from ``os.cpu_count()``. See below for more 

55 details. 

56 plan: object, optional 

57 This argument is reserved for passing in a precomputed plan provided 

58 by downstream FFT vendors. It is currently not used in SciPy. 

59 

60 .. versionadded:: 1.5.0 

61 

62 Returns 

63 ------- 

64 out : complex ndarray 

65 The truncated or zero-padded input, transformed along the axis 

66 indicated by `axis`, or the last one if `axis` is not specified. 

67 

68 Raises 

69 ------ 

70 IndexError 

71 if `axes` is larger than the last axis of `x`. 

72 

73 See Also 

74 -------- 

75 ifft : The inverse of `fft`. 

76 fft2 : The 2-D FFT. 

77 fftn : The N-D FFT. 

78 rfftn : The N-D FFT of real input. 

79 fftfreq : Frequency bins for given FFT parameters. 

80 next_fast_len : Size to pad input to for most efficient transforms 

81 

82 Notes 

83 ----- 

84 

85 FFT (Fast Fourier Transform) refers to a way the discrete Fourier Transform 

86 (DFT) can be calculated efficiently, by using symmetries in the calculated 

87 terms. The symmetry is highest when `n` is a power of 2, and the transform 

88 is therefore most efficient for these sizes. For poorly factorizable sizes, 

89 `scipy.fft` uses Bluestein's algorithm [2]_ and so is never worse than 

90 O(`n` log `n`). Further performance improvements may be seen by zero-padding 

91 the input using `next_fast_len`. 

92 

93 If ``x`` is a 1d array, then the `fft` is equivalent to :: 

94 

95 y[k] = np.sum(x * np.exp(-2j * np.pi * k * np.arange(n)/n)) 

96 

97 The frequency term ``f=k/n`` is found at ``y[k]``. At ``y[n/2]`` we reach 

98 the Nyquist frequency and wrap around to the negative-frequency terms. So, 

99 for an 8-point transform, the frequencies of the result are 

100 [0, 1, 2, 3, -4, -3, -2, -1]. To rearrange the fft output so that the 

101 zero-frequency component is centered, like [-4, -3, -2, -1, 0, 1, 2, 3], 

102 use `fftshift`. 

103 

104 Transforms can be done in single, double, or extended precision (long 

105 double) floating point. Half precision inputs will be converted to single 

106 precision and non-floating-point inputs will be converted to double 

107 precision. 

108 

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

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

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

112 outputs half of the symmetrical spectrum. If the data are both real and 

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

114 half of the spectrum from half of the signal. 

115 

116 When ``overwrite_x=True`` is specified, the memory referenced by ``x`` may 

117 be used by the implementation in any way. This may include reusing the 

118 memory for the result, but this is in no way guaranteed. You should not 

119 rely on the contents of ``x`` after the transform as this may change in 

120 future without warning. 

121 

122 The ``workers`` argument specifies the maximum number of parallel jobs to 

123 split the FFT computation into. This will execute independent 1-D 

124 FFTs within ``x``. So, ``x`` must be at least 2-D and the 

125 non-transformed axes must be large enough to split into chunks. If ``x`` is 

126 too small, fewer jobs may be used than requested. 

127 

128 References 

129 ---------- 

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

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

132 19: 297-301. 

133 .. [2] Bluestein, L., 1970, "A linear filtering approach to the 

134 computation of discrete Fourier transform". *IEEE Transactions on 

135 Audio and Electroacoustics.* 18 (4): 451-455. 

136 

137 Examples 

138 -------- 

139 >>> import scipy.fft 

140 >>> scipy.fft.fft(np.exp(2j * np.pi * np.arange(8) / 8)) 

141 array([-2.33486982e-16+1.14423775e-17j, 8.00000000e+00-1.25557246e-15j, 

142 2.33486982e-16+2.33486982e-16j, 0.00000000e+00+1.22464680e-16j, 

143 -1.14423775e-17+2.33486982e-16j, 0.00000000e+00+5.20784380e-16j, 

144 1.14423775e-17+1.14423775e-17j, 0.00000000e+00+1.22464680e-16j]) 

145 

146 In this example, real input has an FFT which is Hermitian, i.e., symmetric 

147 in the real part and anti-symmetric in the imaginary part: 

148 

149 >>> from scipy.fft import fft, fftfreq, fftshift 

150 >>> import matplotlib.pyplot as plt 

151 >>> t = np.arange(256) 

152 >>> sp = fftshift(fft(np.sin(t))) 

153 >>> freq = fftshift(fftfreq(t.shape[-1])) 

154 >>> plt.plot(freq, sp.real, freq, sp.imag) 

155 [<matplotlib.lines.Line2D object at 0x...>, <matplotlib.lines.Line2D object at 0x...>] 

156 >>> plt.show() 

157 

158 """ 

159 return (Dispatchable(x, np.ndarray),) 

160 

161 

162@_dispatch 

163def ifft(x, n=None, axis=-1, norm=None, overwrite_x=False, workers=None, *, 

164 plan=None): 

165 """ 

166 Compute the 1-D inverse discrete Fourier Transform. 

167 

168 This function computes the inverse of the 1-D *n*-point 

169 discrete Fourier transform computed by `fft`. In other words, 

170 ``ifft(fft(x)) == x`` to within numerical accuracy. 

171 

172 The input should be ordered in the same way as is returned by `fft`, 

173 i.e., 

174 

175 * ``x[0]`` should contain the zero frequency term, 

176 * ``x[1:n//2]`` should contain the positive-frequency terms, 

177 * ``x[n//2 + 1:]`` should contain the negative-frequency terms, in 

178 increasing order starting from the most negative frequency. 

179 

180 For an even number of input points, ``x[n//2]`` represents the sum of 

181 the values at the positive and negative Nyquist frequencies, as the two 

182 are aliased together. See `fft` for details. 

183 

184 Parameters 

185 ---------- 

186 x : array_like 

187 Input array, can be complex. 

188 n : int, optional 

189 Length of the transformed axis of the output. 

190 If `n` is smaller than the length of the input, the input is cropped. 

191 If it is larger, the input is padded with zeros. If `n` is not given, 

192 the length of the input along the axis specified by `axis` is used. 

193 See notes about padding issues. 

194 axis : int, optional 

195 Axis over which to compute the inverse DFT. If not given, the last 

196 axis is used. 

197 norm : {None, "ortho"}, optional 

198 Normalization mode (see `fft`). Default is None. 

199 overwrite_x : bool, optional 

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

201 See :func:`fft` for more details. 

202 workers : int, optional 

203 Maximum number of workers to use for parallel computation. If negative, 

204 the value wraps around from ``os.cpu_count()``. 

205 See :func:`~scipy.fft.fft` for more details. 

206 plan: object, optional 

207 This argument is reserved for passing in a precomputed plan provided 

208 by downstream FFT vendors. It is currently not used in SciPy. 

209 

210 .. versionadded:: 1.5.0 

211 

212 Returns 

213 ------- 

214 out : complex ndarray 

215 The truncated or zero-padded input, transformed along the axis 

216 indicated by `axis`, or the last one if `axis` is not specified. 

217 

218 Raises 

219 ------ 

220 IndexError 

221 If `axes` is larger than the last axis of `x`. 

222 

223 See Also 

224 -------- 

225 fft : The 1-D (forward) FFT, of which `ifft` is the inverse. 

226 ifft2 : The 2-D inverse FFT. 

227 ifftn : The N-D inverse FFT. 

228 

229 Notes 

230 ----- 

231 If the input parameter `n` is larger than the size of the input, the input 

232 is padded by appending zeros at the end. Even though this is the common 

233 approach, it might lead to surprising results. If a different padding is 

234 desired, it must be performed before calling `ifft`. 

235 

236 If ``x`` is a 1-D array, then the `ifft` is equivalent to :: 

237 

238 y[k] = np.sum(x * np.exp(2j * np.pi * k * np.arange(n)/n)) / len(x) 

239 

240 As with `fft`, `ifft` has support for all floating point types and is 

241 optimized for real input. 

242 

243 Examples 

244 -------- 

245 >>> import scipy.fft 

246 >>> scipy.fft.ifft([0, 4, 0, 0]) 

247 array([ 1.+0.j, 0.+1.j, -1.+0.j, 0.-1.j]) # may vary 

248 

249 Create and plot a band-limited signal with random phases: 

250 

251 >>> import matplotlib.pyplot as plt 

252 >>> t = np.arange(400) 

253 >>> n = np.zeros((400,), dtype=complex) 

254 >>> n[40:60] = np.exp(1j*np.random.uniform(0, 2*np.pi, (20,))) 

255 >>> s = scipy.fft.ifft(n) 

256 >>> plt.plot(t, s.real, 'b-', t, s.imag, 'r--') 

257 [<matplotlib.lines.Line2D object at ...>, <matplotlib.lines.Line2D object at ...>] 

258 >>> plt.legend(('real', 'imaginary')) 

259 <matplotlib.legend.Legend object at ...> 

260 >>> plt.show() 

261 

262 """ 

263 return (Dispatchable(x, np.ndarray),) 

264 

265 

266@_dispatch 

267def rfft(x, n=None, axis=-1, norm=None, overwrite_x=False, workers=None, *, 

268 plan=None): 

269 """ 

270 Compute the 1-D discrete Fourier Transform for real input. 

271 

272 This function computes the 1-D *n*-point discrete Fourier 

273 Transform (DFT) of a real-valued array by means of an efficient algorithm 

274 called the Fast Fourier Transform (FFT). 

275 

276 Parameters 

277 ---------- 

278 a : array_like 

279 Input array 

280 n : int, optional 

281 Number of points along transformation axis in the input to use. 

282 If `n` is smaller than the length of the input, the input is cropped. 

283 If it is larger, the input is padded with zeros. If `n` is not given, 

284 the length of the input along the axis specified by `axis` is used. 

285 axis : int, optional 

286 Axis over which to compute the FFT. If not given, the last axis is 

287 used. 

288 norm : {None, "ortho"}, optional 

289 Normalization mode (see `fft`). Default is None. 

290 overwrite_x : bool, optional 

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

292 See :func:`fft` for more details. 

293 workers : int, optional 

294 Maximum number of workers to use for parallel computation. If negative, 

295 the value wraps around from ``os.cpu_count()``. 

296 See :func:`~scipy.fft.fft` for more details. 

297 plan: object, optional 

298 This argument is reserved for passing in a precomputed plan provided 

299 by downstream FFT vendors. It is currently not used in SciPy. 

300 

301 .. versionadded:: 1.5.0 

302 

303 Returns 

304 ------- 

305 out : complex ndarray 

306 The truncated or zero-padded input, transformed along the axis 

307 indicated by `axis`, or the last one if `axis` is not specified. 

308 If `n` is even, the length of the transformed axis is ``(n/2)+1``. 

309 If `n` is odd, the length is ``(n+1)/2``. 

310 

311 Raises 

312 ------ 

313 IndexError 

314 If `axis` is larger than the last axis of `a`. 

315 

316 See Also 

317 -------- 

318 irfft : The inverse of `rfft`. 

319 fft : The 1-D FFT of general (complex) input. 

320 fftn : The N-D FFT. 

321 rfft2 : The 2-D FFT of real input. 

322 rfftn : The N-D FFT of real input. 

323 

324 Notes 

325 ----- 

326 When the DFT is computed for purely real input, the output is 

327 Hermitian-symmetric, i.e., the negative frequency terms are just the complex 

328 conjugates of the corresponding positive-frequency terms, and the 

329 negative-frequency terms are therefore redundant. This function does not 

330 compute the negative frequency terms, and the length of the transformed 

331 axis of the output is therefore ``n//2 + 1``. 

332 

333 When ``X = rfft(x)`` and fs is the sampling frequency, ``X[0]`` contains 

334 the zero-frequency term 0*fs, which is real due to Hermitian symmetry. 

335 

336 If `n` is even, ``A[-1]`` contains the term representing both positive 

337 and negative Nyquist frequency (+fs/2 and -fs/2), and must also be purely 

338 real. If `n` is odd, there is no term at fs/2; ``A[-1]`` contains 

339 the largest positive frequency (fs/2*(n-1)/n), and is complex in the 

340 general case. 

341 

342 If the input `a` contains an imaginary part, it is silently discarded. 

343 

344 Examples 

345 -------- 

346 >>> import scipy.fft 

347 >>> scipy.fft.fft([0, 1, 0, 0]) 

348 array([ 1.+0.j, 0.-1.j, -1.+0.j, 0.+1.j]) # may vary 

349 >>> scipy.fft.rfft([0, 1, 0, 0]) 

350 array([ 1.+0.j, 0.-1.j, -1.+0.j]) # may vary 

351 

352 Notice how the final element of the `fft` output is the complex conjugate 

353 of the second element, for real input. For `rfft`, this symmetry is 

354 exploited to compute only the non-negative frequency terms. 

355 

356 """ 

357 return (Dispatchable(x, np.ndarray),) 

358 

359 

360@_dispatch 

361def irfft(x, n=None, axis=-1, norm=None, overwrite_x=False, workers=None, *, 

362 plan=None): 

363 """ 

364 Computes the inverse of `rfft`. 

365 

366 This function computes the inverse of the 1-D *n*-point 

367 discrete Fourier Transform of real input computed by `rfft`. 

368 In other words, ``irfft(rfft(x), len(x)) == x`` to within numerical 

369 accuracy. (See Notes below for why ``len(a)`` is necessary here.) 

370 

371 The input is expected to be in the form returned by `rfft`, i.e., the 

372 real zero-frequency term followed by the complex positive frequency terms 

373 in order of increasing frequency. Since the discrete Fourier Transform of 

374 real input is Hermitian-symmetric, the negative frequency terms are taken 

375 to be the complex conjugates of the corresponding positive frequency terms. 

376 

377 Parameters 

378 ---------- 

379 x : array_like 

380 The input array. 

381 n : int, optional 

382 Length of the transformed axis of the output. 

383 For `n` output points, ``n//2+1`` input points are necessary. If the 

384 input is longer than this, it is cropped. If it is shorter than this, 

385 it is padded with zeros. If `n` is not given, it is taken to be 

386 ``2*(m-1)``, where ``m`` is the length of the input along the axis 

387 specified by `axis`. 

388 axis : int, optional 

389 Axis over which to compute the inverse FFT. If not given, the last 

390 axis is used. 

391 norm : {None, "ortho"}, optional 

392 Normalization mode (see `fft`). Default is None. 

393 overwrite_x : bool, optional 

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

395 See :func:`fft` for more details. 

396 workers : int, optional 

397 Maximum number of workers to use for parallel computation. If negative, 

398 the value wraps around from ``os.cpu_count()``. 

399 See :func:`~scipy.fft.fft` for more details. 

400 plan: object, optional 

401 This argument is reserved for passing in a precomputed plan provided 

402 by downstream FFT vendors. It is currently not used in SciPy. 

403 

404 .. versionadded:: 1.5.0 

405 

406 Returns 

407 ------- 

408 out : ndarray 

409 The truncated or zero-padded input, transformed along the axis 

410 indicated by `axis`, or the last one if `axis` is not specified. 

411 The length of the transformed axis is `n`, or, if `n` is not given, 

412 ``2*(m-1)`` where ``m`` is the length of the transformed axis of the 

413 input. To get an odd number of output points, `n` must be specified. 

414 

415 Raises 

416 ------ 

417 IndexError 

418 If `axis` is larger than the last axis of `x`. 

419 

420 See Also 

421 -------- 

422 rfft : The 1-D FFT of real input, of which `irfft` is inverse. 

423 fft : The 1-D FFT. 

424 irfft2 : The inverse of the 2-D FFT of real input. 

425 irfftn : The inverse of the N-D FFT of real input. 

426 

427 Notes 

428 ----- 

429 Returns the real valued `n`-point inverse discrete Fourier transform 

430 of `x`, where `x` contains the non-negative frequency terms of a 

431 Hermitian-symmetric sequence. `n` is the length of the result, not the 

432 input. 

433 

434 If you specify an `n` such that `a` must be zero-padded or truncated, the 

435 extra/removed values will be added/removed at high frequencies. One can 

436 thus resample a series to `m` points via Fourier interpolation by: 

437 ``a_resamp = irfft(rfft(a), m)``. 

438 

439 The default value of `n` assumes an even output length. By the Hermitian 

440 symmetry, the last imaginary component must be 0 and so is ignored. To 

441 avoid losing information, the correct length of the real input *must* be 

442 given. 

443 

444 Examples 

445 -------- 

446 >>> import scipy.fft 

447 >>> scipy.fft.ifft([1, -1j, -1, 1j]) 

448 array([0.+0.j, 1.+0.j, 0.+0.j, 0.+0.j]) # may vary 

449 >>> scipy.fft.irfft([1, -1j, -1]) 

450 array([0., 1., 0., 0.]) 

451 

452 Notice how the last term in the input to the ordinary `ifft` is the 

453 complex conjugate of the second term, and the output has zero imaginary 

454 part everywhere. When calling `irfft`, the negative frequencies are not 

455 specified, and the output array is purely real. 

456 

457 """ 

458 return (Dispatchable(x, np.ndarray),) 

459 

460 

461@_dispatch 

462def hfft(x, n=None, axis=-1, norm=None, overwrite_x=False, workers=None, *, 

463 plan=None): 

464 """ 

465 Compute the FFT of a signal that has Hermitian symmetry, i.e., a real 

466 spectrum. 

467 

468 Parameters 

469 ---------- 

470 x : array_like 

471 The input array. 

472 n : int, optional 

473 Length of the transformed axis of the output. For `n` output 

474 points, ``n//2 + 1`` input points are necessary. If the input is 

475 longer than this, it is cropped. If it is shorter than this, it is 

476 padded with zeros. If `n` is not given, it is taken to be ``2*(m-1)``, 

477 where ``m`` is the length of the input along the axis specified by 

478 `axis`. 

479 axis : int, optional 

480 Axis over which to compute the FFT. If not given, the last 

481 axis is used. 

482 norm : {None, "ortho"}, optional 

483 Normalization mode (see `fft`). Default is None. 

484 overwrite_x : bool, optional 

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

486 See `fft` for more details. 

487 workers : int, optional 

488 Maximum number of workers to use for parallel computation. If negative, 

489 the value wraps around from ``os.cpu_count()``. 

490 See :func:`~scipy.fft.fft` for more details. 

491 plan: object, optional 

492 This argument is reserved for passing in a precomputed plan provided 

493 by downstream FFT vendors. It is currently not used in SciPy. 

494 

495 .. versionadded:: 1.5.0 

496 

497 Returns 

498 ------- 

499 out : ndarray 

500 The truncated or zero-padded input, transformed along the axis 

501 indicated by `axis`, or the last one if `axis` is not specified. 

502 The length of the transformed axis is `n`, or, if `n` is not given, 

503 ``2*m - 2``, where ``m`` is the length of the transformed axis of 

504 the input. To get an odd number of output points, `n` must be 

505 specified, for instance, as ``2*m - 1`` in the typical case, 

506 

507 Raises 

508 ------ 

509 IndexError 

510 If `axis` is larger than the last axis of `a`. 

511 

512 See also 

513 -------- 

514 rfft : Compute the 1-D FFT for real input. 

515 ihfft : The inverse of `hfft`. 

516 hfftn : Compute the N-D FFT of a Hermitian signal. 

517 

518 Notes 

519 ----- 

520 `hfft`/`ihfft` are a pair analogous to `rfft`/`irfft`, but for the 

521 opposite case: here the signal has Hermitian symmetry in the time 

522 domain and is real in the frequency domain. So, here, it's `hfft`, for 

523 which you must supply the length of the result if it is to be odd. 

524 * even: ``ihfft(hfft(a, 2*len(a) - 2) == a``, within roundoff error, 

525 * odd: ``ihfft(hfft(a, 2*len(a) - 1) == a``, within roundoff error. 

526 

527 Examples 

528 -------- 

529 >>> from scipy.fft import fft, hfft 

530 >>> a = 2 * np.pi * np.arange(10) / 10 

531 >>> signal = np.cos(a) + 3j * np.sin(3 * a) 

532 >>> fft(signal).round(10) 

533 array([ -0.+0.j, 5.+0.j, -0.+0.j, 15.-0.j, 0.+0.j, 0.+0.j, 

534 -0.+0.j, -15.-0.j, 0.+0.j, 5.+0.j]) 

535 >>> hfft(signal[:6]).round(10) # Input first half of signal 

536 array([ 0., 5., 0., 15., -0., 0., 0., -15., -0., 5.]) 

537 >>> hfft(signal, 10) # Input entire signal and truncate 

538 array([ 0., 5., 0., 15., -0., 0., 0., -15., -0., 5.]) 

539 """ 

540 return (Dispatchable(x, np.ndarray),) 

541 

542 

543@_dispatch 

544def ihfft(x, n=None, axis=-1, norm=None, overwrite_x=False, workers=None, *, 

545 plan=None): 

546 """ 

547 Compute the inverse FFT of a signal that has Hermitian symmetry. 

548 

549 Parameters 

550 ---------- 

551 x : array_like 

552 Input array. 

553 n : int, optional 

554 Length of the inverse FFT, the number of points along 

555 transformation axis in the input to use. If `n` is smaller than 

556 the length of the input, the input is cropped. If it is larger, 

557 the input is padded with zeros. If `n` is not given, the length of 

558 the input along the axis specified by `axis` is used. 

559 axis : int, optional 

560 Axis over which to compute the inverse FFT. If not given, the last 

561 axis is used. 

562 norm : {None, "ortho"}, optional 

563 Normalization mode (see `fft`). Default is None. 

564 overwrite_x : bool, optional 

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

566 See `fft` for more details. 

567 workers : int, optional 

568 Maximum number of workers to use for parallel computation. If negative, 

569 the value wraps around from ``os.cpu_count()``. 

570 See :func:`~scipy.fft.fft` for more details. 

571 plan: object, optional 

572 This argument is reserved for passing in a precomputed plan provided 

573 by downstream FFT vendors. It is currently not used in SciPy. 

574 

575 .. versionadded:: 1.5.0 

576 

577 Returns 

578 ------- 

579 out : complex ndarray 

580 The truncated or zero-padded input, transformed along the axis 

581 indicated by `axis`, or the last one if `axis` is not specified. 

582 The length of the transformed axis is ``n//2 + 1``. 

583 

584 See also 

585 -------- 

586 hfft, irfft 

587 

588 Notes 

589 ----- 

590 `hfft`/`ihfft` are a pair analogous to `rfft`/`irfft`, but for the 

591 opposite case: here, the signal has Hermitian symmetry in the time 

592 domain and is real in the frequency domain. So, here, it's `hfft`, for 

593 which you must supply the length of the result if it is to be odd: 

594 * even: ``ihfft(hfft(a, 2*len(a) - 2) == a``, within roundoff error, 

595 * odd: ``ihfft(hfft(a, 2*len(a) - 1) == a``, within roundoff error. 

596 

597 Examples 

598 -------- 

599 >>> from scipy.fft import ifft, ihfft 

600 >>> spectrum = np.array([ 15, -4, 0, -1, 0, -4]) 

601 >>> ifft(spectrum) 

602 array([1.+0.j, 2.+0.j, 3.+0.j, 4.+0.j, 3.+0.j, 2.+0.j]) # may vary 

603 >>> ihfft(spectrum) 

604 array([ 1.-0.j, 2.-0.j, 3.-0.j, 4.-0.j]) # may vary 

605 """ 

606 return (Dispatchable(x, np.ndarray),) 

607 

608 

609@_dispatch 

610def fftn(x, s=None, axes=None, norm=None, overwrite_x=False, workers=None, *, 

611 plan=None): 

612 """ 

613 Compute the N-D discrete Fourier Transform. 

614 

615 This function computes the N-D discrete Fourier Transform over 

616 any number of axes in an M-D array by means of the Fast Fourier 

617 Transform (FFT). 

618 

619 Parameters 

620 ---------- 

621 x : array_like 

622 Input array, can be complex. 

623 s : sequence of ints, optional 

624 Shape (length of each transformed axis) of the output 

625 (``s[0]`` refers to axis 0, ``s[1]`` to axis 1, etc.). 

626 This corresponds to ``n`` for ``fft(x, n)``. 

627 Along any axis, if the given shape is smaller than that of the input, 

628 the input is cropped. If it is larger, the input is padded with zeros. 

629 if `s` is not given, the shape of the input along the axes specified 

630 by `axes` is used. 

631 axes : sequence of ints, optional 

632 Axes over which to compute the FFT. If not given, the last ``len(s)`` 

633 axes are used, or all axes if `s` is also not specified. 

634 norm : {None, "ortho"}, optional 

635 Normalization mode (see `fft`). Default is None. 

636 overwrite_x : bool, optional 

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

638 See :func:`fft` for more details. 

639 workers : int, optional 

640 Maximum number of workers to use for parallel computation. If negative, 

641 the value wraps around from ``os.cpu_count()``. 

642 See :func:`~scipy.fft.fft` for more details. 

643 plan: object, optional 

644 This argument is reserved for passing in a precomputed plan provided 

645 by downstream FFT vendors. It is currently not used in SciPy. 

646 

647 .. versionadded:: 1.5.0 

648 

649 Returns 

650 ------- 

651 out : complex ndarray 

652 The truncated or zero-padded input, transformed along the axes 

653 indicated by `axes`, or by a combination of `s` and `x`, 

654 as explained in the parameters section above. 

655 

656 Raises 

657 ------ 

658 ValueError 

659 If `s` and `axes` have different length. 

660 IndexError 

661 If an element of `axes` is larger than than the number of axes of `x`. 

662 

663 See Also 

664 -------- 

665 ifftn : The inverse of `fftn`, the inverse N-D FFT. 

666 fft : The 1-D FFT, with definitions and conventions used. 

667 rfftn : The N-D FFT of real input. 

668 fft2 : The 2-D FFT. 

669 fftshift : Shifts zero-frequency terms to centre of array. 

670 

671 Notes 

672 ----- 

673 The output, analogously to `fft`, contains the term for zero frequency in 

674 the low-order corner of all axes, the positive frequency terms in the 

675 first half of all axes, the term for the Nyquist frequency in the middle 

676 of all axes and the negative frequency terms in the second half of all 

677 axes, in order of decreasingly negative frequency. 

678 

679 Examples 

680 -------- 

681 >>> import scipy.fft 

682 >>> x = np.mgrid[:3, :3, :3][0] 

683 >>> scipy.fft.fftn(x, axes=(1, 2)) 

684 array([[[ 0.+0.j, 0.+0.j, 0.+0.j], # may vary 

685 [ 0.+0.j, 0.+0.j, 0.+0.j], 

686 [ 0.+0.j, 0.+0.j, 0.+0.j]], 

687 [[ 9.+0.j, 0.+0.j, 0.+0.j], 

688 [ 0.+0.j, 0.+0.j, 0.+0.j], 

689 [ 0.+0.j, 0.+0.j, 0.+0.j]], 

690 [[18.+0.j, 0.+0.j, 0.+0.j], 

691 [ 0.+0.j, 0.+0.j, 0.+0.j], 

692 [ 0.+0.j, 0.+0.j, 0.+0.j]]]) 

693 >>> scipy.fft.fftn(x, (2, 2), axes=(0, 1)) 

694 array([[[ 2.+0.j, 2.+0.j, 2.+0.j], # may vary 

695 [ 0.+0.j, 0.+0.j, 0.+0.j]], 

696 [[-2.+0.j, -2.+0.j, -2.+0.j], 

697 [ 0.+0.j, 0.+0.j, 0.+0.j]]]) 

698 

699 >>> import matplotlib.pyplot as plt 

700 >>> [X, Y] = np.meshgrid(2 * np.pi * np.arange(200) / 12, 

701 ... 2 * np.pi * np.arange(200) / 34) 

702 >>> S = np.sin(X) + np.cos(Y) + np.random.uniform(0, 1, X.shape) 

703 >>> FS = scipy.fft.fftn(S) 

704 >>> plt.imshow(np.log(np.abs(scipy.fft.fftshift(FS))**2)) 

705 <matplotlib.image.AxesImage object at 0x...> 

706 >>> plt.show() 

707 

708 """ 

709 return (Dispatchable(x, np.ndarray),) 

710 

711 

712@_dispatch 

713def ifftn(x, s=None, axes=None, norm=None, overwrite_x=False, workers=None, *, 

714 plan=None): 

715 """ 

716 Compute the N-D inverse discrete Fourier Transform. 

717 

718 This function computes the inverse of the N-D discrete 

719 Fourier Transform over any number of axes in an M-D array by 

720 means of the Fast Fourier Transform (FFT). In other words, 

721 ``ifftn(fftn(x)) == x`` to within numerical accuracy. 

722 

723 The input, analogously to `ifft`, should be ordered in the same way as is 

724 returned by `fftn`, i.e., it should have the term for zero frequency 

725 in all axes in the low-order corner, the positive frequency terms in the 

726 first half of all axes, the term for the Nyquist frequency in the middle 

727 of all axes and the negative frequency terms in the second half of all 

728 axes, in order of decreasingly negative frequency. 

729 

730 Parameters 

731 ---------- 

732 x : array_like 

733 Input array, can be complex. 

734 s : sequence of ints, optional 

735 Shape (length of each transformed axis) of the output 

736 (``s[0]`` refers to axis 0, ``s[1]`` to axis 1, etc.). 

737 This corresponds to ``n`` for ``ifft(x, n)``. 

738 Along any axis, if the given shape is smaller than that of the input, 

739 the input is cropped. If it is larger, the input is padded with zeros. 

740 if `s` is not given, the shape of the input along the axes specified 

741 by `axes` is used. See notes for issue on `ifft` zero padding. 

742 axes : sequence of ints, optional 

743 Axes over which to compute the IFFT. If not given, the last ``len(s)`` 

744 axes are used, or all axes if `s` is also not specified. 

745 norm : {None, "ortho"}, optional 

746 Normalization mode (see `fft`). Default is None. 

747 overwrite_x : bool, optional 

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

749 See :func:`fft` for more details. 

750 workers : int, optional 

751 Maximum number of workers to use for parallel computation. If negative, 

752 the value wraps around from ``os.cpu_count()``. 

753 See :func:`~scipy.fft.fft` for more details. 

754 plan: object, optional 

755 This argument is reserved for passing in a precomputed plan provided 

756 by downstream FFT vendors. It is currently not used in SciPy. 

757 

758 .. versionadded:: 1.5.0 

759 

760 Returns 

761 ------- 

762 out : complex ndarray 

763 The truncated or zero-padded input, transformed along the axes 

764 indicated by `axes`, or by a combination of `s` or `x`, 

765 as explained in the parameters section above. 

766 

767 Raises 

768 ------ 

769 ValueError 

770 If `s` and `axes` have different length. 

771 IndexError 

772 If an element of `axes` is larger than than the number of axes of `x`. 

773 

774 See Also 

775 -------- 

776 fftn : The forward N-D FFT, of which `ifftn` is the inverse. 

777 ifft : The 1-D inverse FFT. 

778 ifft2 : The 2-D inverse FFT. 

779 ifftshift : Undoes `fftshift`, shifts zero-frequency terms to beginning 

780 of array. 

781 

782 Notes 

783 ----- 

784 Zero-padding, analogously with `ifft`, is performed by appending zeros to 

785 the input along the specified dimension. Although this is the common 

786 approach, it might lead to surprising results. If another form of zero 

787 padding is desired, it must be performed before `ifftn` is called. 

788 

789 Examples 

790 -------- 

791 >>> import scipy.fft 

792 >>> x = np.eye(4) 

793 >>> scipy.fft.ifftn(scipy.fft.fftn(x, axes=(0,)), axes=(1,)) 

794 array([[1.+0.j, 0.+0.j, 0.+0.j, 0.+0.j], # may vary 

795 [0.+0.j, 1.+0.j, 0.+0.j, 0.+0.j], 

796 [0.+0.j, 0.+0.j, 1.+0.j, 0.+0.j], 

797 [0.+0.j, 0.+0.j, 0.+0.j, 1.+0.j]]) 

798 

799 

800 Create and plot an image with band-limited frequency content: 

801 

802 >>> import matplotlib.pyplot as plt 

803 >>> n = np.zeros((200,200), dtype=complex) 

804 >>> n[60:80, 20:40] = np.exp(1j*np.random.uniform(0, 2*np.pi, (20, 20))) 

805 >>> im = scipy.fft.ifftn(n).real 

806 >>> plt.imshow(im) 

807 <matplotlib.image.AxesImage object at 0x...> 

808 >>> plt.show() 

809 

810 """ 

811 return (Dispatchable(x, np.ndarray),) 

812 

813 

814@_dispatch 

815def fft2(x, s=None, axes=(-2, -1), norm=None, overwrite_x=False, workers=None, *, 

816 plan=None): 

817 """ 

818 Compute the 2-D discrete Fourier Transform 

819 

820 This function computes the N-D discrete Fourier Transform 

821 over any axes in an M-D array by means of the 

822 Fast Fourier Transform (FFT). By default, the transform is computed over 

823 the last two axes of the input array, i.e., a 2-dimensional FFT. 

824 

825 Parameters 

826 ---------- 

827 x : array_like 

828 Input array, can be complex 

829 s : sequence of ints, optional 

830 Shape (length of each transformed axis) of the output 

831 (``s[0]`` refers to axis 0, ``s[1]`` to axis 1, etc.). 

832 This corresponds to ``n`` for ``fft(x, n)``. 

833 Along each axis, if the given shape is smaller than that of the input, 

834 the input is cropped. If it is larger, the input is padded with zeros. 

835 if `s` is not given, the shape of the input along the axes specified 

836 by `axes` is used. 

837 axes : sequence of ints, optional 

838 Axes over which to compute the FFT. If not given, the last two axes are 

839 used. 

840 norm : {None, "ortho"}, optional 

841 Normalization mode (see `fft`). Default is None. 

842 overwrite_x : bool, optional 

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

844 See :func:`fft` for more details. 

845 workers : int, optional 

846 Maximum number of workers to use for parallel computation. If negative, 

847 the value wraps around from ``os.cpu_count()``. 

848 See :func:`~scipy.fft.fft` for more details. 

849 plan: object, optional 

850 This argument is reserved for passing in a precomputed plan provided 

851 by downstream FFT vendors. It is currently not used in SciPy. 

852 

853 .. versionadded:: 1.5.0 

854 

855 Returns 

856 ------- 

857 out : complex ndarray 

858 The truncated or zero-padded input, transformed along the axes 

859 indicated by `axes`, or the last two axes if `axes` is not given. 

860 

861 Raises 

862 ------ 

863 ValueError 

864 If `s` and `axes` have different length, or `axes` not given and 

865 ``len(s) != 2``. 

866 IndexError 

867 If an element of `axes` is larger than than the number of axes of `x`. 

868 

869 See Also 

870 -------- 

871 ifft2 : The inverse 2-D FFT. 

872 fft : The 1-D FFT. 

873 fftn : The N-D FFT. 

874 fftshift : Shifts zero-frequency terms to the center of the array. 

875 For 2-D input, swaps first and third quadrants, and second 

876 and fourth quadrants. 

877 

878 Notes 

879 ----- 

880 `fft2` is just `fftn` with a different default for `axes`. 

881 

882 The output, analogously to `fft`, contains the term for zero frequency in 

883 the low-order corner of the transformed axes, the positive frequency terms 

884 in the first half of these axes, the term for the Nyquist frequency in the 

885 middle of the axes and the negative frequency terms in the second half of 

886 the axes, in order of decreasingly negative frequency. 

887 

888 See `fftn` for details and a plotting example, and `fft` for 

889 definitions and conventions used. 

890 

891 

892 Examples 

893 -------- 

894 >>> import scipy.fft 

895 >>> x = np.mgrid[:5, :5][0] 

896 >>> scipy.fft.fft2(x) 

897 array([[ 50. +0.j , 0. +0.j , 0. +0.j , # may vary 

898 0. +0.j , 0. +0.j ], 

899 [-12.5+17.20477401j, 0. +0.j , 0. +0.j , 

900 0. +0.j , 0. +0.j ], 

901 [-12.5 +4.0614962j , 0. +0.j , 0. +0.j , 

902 0. +0.j , 0. +0.j ], 

903 [-12.5 -4.0614962j , 0. +0.j , 0. +0.j , 

904 0. +0.j , 0. +0.j ], 

905 [-12.5-17.20477401j, 0. +0.j , 0. +0.j , 

906 0. +0.j , 0. +0.j ]]) 

907 

908 """ 

909 return (Dispatchable(x, np.ndarray),) 

910 

911 

912@_dispatch 

913def ifft2(x, s=None, axes=(-2, -1), norm=None, overwrite_x=False, workers=None, *, 

914 plan=None): 

915 """ 

916 Compute the 2-D inverse discrete Fourier Transform. 

917 

918 This function computes the inverse of the 2-D discrete Fourier 

919 Transform over any number of axes in an M-D array by means of 

920 the Fast Fourier Transform (FFT). In other words, ``ifft2(fft2(x)) == x`` 

921 to within numerical accuracy. By default, the inverse transform is 

922 computed over the last two axes of the input array. 

923 

924 The input, analogously to `ifft`, should be ordered in the same way as is 

925 returned by `fft2`, i.e., it should have the term for zero frequency 

926 in the low-order corner of the two axes, the positive frequency terms in 

927 the first half of these axes, the term for the Nyquist frequency in the 

928 middle of the axes and the negative frequency terms in the second half of 

929 both axes, in order of decreasingly negative frequency. 

930 

931 Parameters 

932 ---------- 

933 x : array_like 

934 Input array, can be complex. 

935 s : sequence of ints, optional 

936 Shape (length of each axis) of the output (``s[0]`` refers to axis 0, 

937 ``s[1]`` to axis 1, etc.). This corresponds to `n` for ``ifft(x, n)``. 

938 Along each axis, if the given shape is smaller than that of the input, 

939 the input is cropped. If it is larger, the input is padded with zeros. 

940 if `s` is not given, the shape of the input along the axes specified 

941 by `axes` is used. See notes for issue on `ifft` zero padding. 

942 axes : sequence of ints, optional 

943 Axes over which to compute the FFT. If not given, the last two 

944 axes are used. 

945 norm : {None, "ortho"}, optional 

946 Normalization mode (see `fft`). Default is None. 

947 overwrite_x : bool, optional 

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

949 See :func:`fft` for more details. 

950 workers : int, optional 

951 Maximum number of workers to use for parallel computation. If negative, 

952 the value wraps around from ``os.cpu_count()``. 

953 See :func:`~scipy.fft.fft` for more details. 

954 plan: object, optional 

955 This argument is reserved for passing in a precomputed plan provided 

956 by downstream FFT vendors. It is currently not used in SciPy. 

957 

958 .. versionadded:: 1.5.0 

959 

960 Returns 

961 ------- 

962 out : complex ndarray 

963 The truncated or zero-padded input, transformed along the axes 

964 indicated by `axes`, or the last two axes if `axes` is not given. 

965 

966 Raises 

967 ------ 

968 ValueError 

969 If `s` and `axes` have different length, or `axes` not given and 

970 ``len(s) != 2``. 

971 IndexError 

972 If an element of `axes` is larger than than the number of axes of `x`. 

973 

974 See Also 

975 -------- 

976 fft2 : The forward 2-D FFT, of which `ifft2` is the inverse. 

977 ifftn : The inverse of the N-D FFT. 

978 fft : The 1-D FFT. 

979 ifft : The 1-D inverse FFT. 

980 

981 Notes 

982 ----- 

983 `ifft2` is just `ifftn` with a different default for `axes`. 

984 

985 See `ifftn` for details and a plotting example, and `fft` for 

986 definition and conventions used. 

987 

988 Zero-padding, analogously with `ifft`, is performed by appending zeros to 

989 the input along the specified dimension. Although this is the common 

990 approach, it might lead to surprising results. If another form of zero 

991 padding is desired, it must be performed before `ifft2` is called. 

992 

993 Examples 

994 -------- 

995 >>> import scipy.fft 

996 >>> x = 4 * np.eye(4) 

997 >>> scipy.fft.ifft2(x) 

998 array([[1.+0.j, 0.+0.j, 0.+0.j, 0.+0.j], # may vary 

999 [0.+0.j, 0.+0.j, 0.+0.j, 1.+0.j], 

1000 [0.+0.j, 0.+0.j, 1.+0.j, 0.+0.j], 

1001 [0.+0.j, 1.+0.j, 0.+0.j, 0.+0.j]]) 

1002 

1003 """ 

1004 return (Dispatchable(x, np.ndarray),) 

1005 

1006 

1007@_dispatch 

1008def rfftn(x, s=None, axes=None, norm=None, overwrite_x=False, workers=None, *, 

1009 plan=None): 

1010 """ 

1011 Compute the N-D discrete Fourier Transform for real input. 

1012 

1013 This function computes the N-D discrete Fourier Transform over 

1014 any number of axes in an M-D real array by means of the Fast 

1015 Fourier Transform (FFT). By default, all axes are transformed, with the 

1016 real transform performed over the last axis, while the remaining 

1017 transforms are complex. 

1018 

1019 Parameters 

1020 ---------- 

1021 x : array_like 

1022 Input array, taken to be real. 

1023 s : sequence of ints, optional 

1024 Shape (length along each transformed axis) to use from the input. 

1025 (``s[0]`` refers to axis 0, ``s[1]`` to axis 1, etc.). 

1026 The final element of `s` corresponds to `n` for ``rfft(x, n)``, while 

1027 for the remaining axes, it corresponds to `n` for ``fft(x, n)``. 

1028 Along any axis, if the given shape is smaller than that of the input, 

1029 the input is cropped. If it is larger, the input is padded with zeros. 

1030 if `s` is not given, the shape of the input along the axes specified 

1031 by `axes` is used. 

1032 axes : sequence of ints, optional 

1033 Axes over which to compute the FFT. If not given, the last ``len(s)`` 

1034 axes are used, or all axes if `s` is also not specified. 

1035 norm : {None, "ortho"}, optional 

1036 Normalization mode (see `fft`). Default is None. 

1037 overwrite_x : bool, optional 

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

1039 See :func:`fft` for more details. 

1040 workers : int, optional 

1041 Maximum number of workers to use for parallel computation. If negative, 

1042 the value wraps around from ``os.cpu_count()``. 

1043 See :func:`~scipy.fft.fft` for more details. 

1044 plan: object, optional 

1045 This argument is reserved for passing in a precomputed plan provided 

1046 by downstream FFT vendors. It is currently not used in SciPy. 

1047 

1048 .. versionadded:: 1.5.0 

1049 

1050 Returns 

1051 ------- 

1052 out : complex ndarray 

1053 The truncated or zero-padded input, transformed along the axes 

1054 indicated by `axes`, or by a combination of `s` and `x`, 

1055 as explained in the parameters section above. 

1056 The length of the last axis transformed will be ``s[-1]//2+1``, 

1057 while the remaining transformed axes will have lengths according to 

1058 `s`, or unchanged from the input. 

1059 

1060 Raises 

1061 ------ 

1062 ValueError 

1063 If `s` and `axes` have different length. 

1064 IndexError 

1065 If an element of `axes` is larger than than the number of axes of `x`. 

1066 

1067 See Also 

1068 -------- 

1069 irfftn : The inverse of `rfftn`, i.e., the inverse of the N-D FFT 

1070 of real input. 

1071 fft : The 1-D FFT, with definitions and conventions used. 

1072 rfft : The 1-D FFT of real input. 

1073 fftn : The N-D FFT. 

1074 rfft2 : The 2-D FFT of real input. 

1075 

1076 Notes 

1077 ----- 

1078 The transform for real input is performed over the last transformation 

1079 axis, as by `rfft`, then the transform over the remaining axes is 

1080 performed as by `fftn`. The order of the output is as for `rfft` for the 

1081 final transformation axis, and as for `fftn` for the remaining 

1082 transformation axes. 

1083 

1084 See `fft` for details, definitions and conventions used. 

1085 

1086 Examples 

1087 -------- 

1088 >>> import scipy.fft 

1089 >>> x = np.ones((2, 2, 2)) 

1090 >>> scipy.fft.rfftn(x) 

1091 array([[[8.+0.j, 0.+0.j], # may vary 

1092 [0.+0.j, 0.+0.j]], 

1093 [[0.+0.j, 0.+0.j], 

1094 [0.+0.j, 0.+0.j]]]) 

1095 

1096 >>> scipy.fft.rfftn(x, axes=(2, 0)) 

1097 array([[[4.+0.j, 0.+0.j], # may vary 

1098 [4.+0.j, 0.+0.j]], 

1099 [[0.+0.j, 0.+0.j], 

1100 [0.+0.j, 0.+0.j]]]) 

1101 

1102 """ 

1103 return (Dispatchable(x, np.ndarray),) 

1104 

1105 

1106@_dispatch 

1107def rfft2(x, s=None, axes=(-2, -1), norm=None, overwrite_x=False, workers=None, *, 

1108 plan=None): 

1109 """ 

1110 Compute the 2-D FFT of a real array. 

1111 

1112 Parameters 

1113 ---------- 

1114 x : array 

1115 Input array, taken to be real. 

1116 s : sequence of ints, optional 

1117 Shape of the FFT. 

1118 axes : sequence of ints, optional 

1119 Axes over which to compute the FFT. 

1120 norm : {None, "ortho"}, optional 

1121 Normalization mode (see `fft`). Default is None. 

1122 overwrite_x : bool, optional 

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

1124 See :func:`fft` for more details. 

1125 workers : int, optional 

1126 Maximum number of workers to use for parallel computation. If negative, 

1127 the value wraps around from ``os.cpu_count()``. 

1128 See :func:`~scipy.fft.fft` for more details. 

1129 plan: object, optional 

1130 This argument is reserved for passing in a precomputed plan provided 

1131 by downstream FFT vendors. It is currently not used in SciPy. 

1132 

1133 .. versionadded:: 1.5.0 

1134 

1135 Returns 

1136 ------- 

1137 out : ndarray 

1138 The result of the real 2-D FFT. 

1139 

1140 See Also 

1141 -------- 

1142 irfft2 : The inverse of the 2-D FFT of real input. 

1143 rfft : The 1-D FFT of real input. 

1144 rfftn : Compute the N-D discrete Fourier Transform for real 

1145 input. 

1146 

1147 Notes 

1148 ----- 

1149 This is really just `rfftn` with different default behavior. 

1150 For more details see `rfftn`. 

1151 

1152 """ 

1153 return (Dispatchable(x, np.ndarray),) 

1154 

1155 

1156@_dispatch 

1157def irfftn(x, s=None, axes=None, norm=None, overwrite_x=False, workers=None, *, 

1158 plan=None): 

1159 """ 

1160 Computes the inverse of `rfftn` 

1161 

1162 This function computes the inverse of the N-D discrete 

1163 Fourier Transform for real input over any number of axes in an 

1164 M-D array by means of the Fast Fourier Transform (FFT). In 

1165 other words, ``irfftn(rfftn(x), x.shape) == x`` to within numerical 

1166 accuracy. (The ``a.shape`` is necessary like ``len(a)`` is for `irfft`, 

1167 and for the same reason.) 

1168 

1169 The input should be ordered in the same way as is returned by `rfftn`, 

1170 i.e., as for `irfft` for the final transformation axis, and as for `ifftn` 

1171 along all the other axes. 

1172 

1173 Parameters 

1174 ---------- 

1175 x : array_like 

1176 Input array. 

1177 s : sequence of ints, optional 

1178 Shape (length of each transformed axis) of the output 

1179 (``s[0]`` refers to axis 0, ``s[1]`` to axis 1, etc.). `s` is also the 

1180 number of input points used along this axis, except for the last axis, 

1181 where ``s[-1]//2+1`` points of the input are used. 

1182 Along any axis, if the shape indicated by `s` is smaller than that of 

1183 the input, the input is cropped. If it is larger, the input is padded 

1184 with zeros. If `s` is not given, the shape of the input along the axes 

1185 specified by axes is used. Except for the last axis which is taken to be 

1186 ``2*(m-1)``, where ``m`` is the length of the input along that axis. 

1187 axes : sequence of ints, optional 

1188 Axes over which to compute the inverse FFT. If not given, the last 

1189 `len(s)` axes are used, or all axes if `s` is also not specified. 

1190 norm : {None, "ortho"}, optional 

1191 Normalization mode (see `fft`). Default is None. 

1192 overwrite_x : bool, optional 

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

1194 See :func:`fft` for more details. 

1195 workers : int, optional 

1196 Maximum number of workers to use for parallel computation. If negative, 

1197 the value wraps around from ``os.cpu_count()``. 

1198 See :func:`~scipy.fft.fft` for more details. 

1199 plan: object, optional 

1200 This argument is reserved for passing in a precomputed plan provided 

1201 by downstream FFT vendors. It is currently not used in SciPy. 

1202 

1203 .. versionadded:: 1.5.0 

1204 

1205 Returns 

1206 ------- 

1207 out : ndarray 

1208 The truncated or zero-padded input, transformed along the axes 

1209 indicated by `axes`, or by a combination of `s` or `x`, 

1210 as explained in the parameters section above. 

1211 The length of each transformed axis is as given by the corresponding 

1212 element of `s`, or the length of the input in every axis except for the 

1213 last one if `s` is not given. In the final transformed axis the length 

1214 of the output when `s` is not given is ``2*(m-1)``, where ``m`` is the 

1215 length of the final transformed axis of the input. To get an odd 

1216 number of output points in the final axis, `s` must be specified. 

1217 

1218 Raises 

1219 ------ 

1220 ValueError 

1221 If `s` and `axes` have different length. 

1222 IndexError 

1223 If an element of `axes` is larger than than the number of axes of `x`. 

1224 

1225 See Also 

1226 -------- 

1227 rfftn : The forward N-D FFT of real input, 

1228 of which `ifftn` is the inverse. 

1229 fft : The 1-D FFT, with definitions and conventions used. 

1230 irfft : The inverse of the 1-D FFT of real input. 

1231 irfft2 : The inverse of the 2-D FFT of real input. 

1232 

1233 Notes 

1234 ----- 

1235 See `fft` for definitions and conventions used. 

1236 

1237 See `rfft` for definitions and conventions used for real input. 

1238 

1239 The default value of `s` assumes an even output length in the final 

1240 transformation axis. When performing the final complex to real 

1241 transformation, the Hermitian symmetry requires that the last imaginary 

1242 component along that axis must be 0 and so it is ignored. To avoid losing 

1243 information, the correct length of the real input *must* be given. 

1244 

1245 Examples 

1246 -------- 

1247 >>> import scipy.fft 

1248 >>> x = np.zeros((3, 2, 2)) 

1249 >>> x[0, 0, 0] = 3 * 2 * 2 

1250 >>> scipy.fft.irfftn(x) 

1251 array([[[1., 1.], 

1252 [1., 1.]], 

1253 [[1., 1.], 

1254 [1., 1.]], 

1255 [[1., 1.], 

1256 [1., 1.]]]) 

1257 

1258 """ 

1259 return (Dispatchable(x, np.ndarray),) 

1260 

1261 

1262@_dispatch 

1263def irfft2(x, s=None, axes=(-2, -1), norm=None, overwrite_x=False, workers=None, *, 

1264 plan=None): 

1265 """ 

1266 Computes the inverse of `rfft2` 

1267 

1268 Parameters 

1269 ---------- 

1270 x : array_like 

1271 The input array 

1272 s : sequence of ints, optional 

1273 Shape of the real output to the inverse FFT. 

1274 axes : sequence of ints, optional 

1275 The axes over which to compute the inverse fft. 

1276 Default is the last two axes. 

1277 norm : {None, "ortho"}, optional 

1278 Normalization mode (see `fft`). Default is None. 

1279 overwrite_x : bool, optional 

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

1281 See :func:`fft` for more details. 

1282 workers : int, optional 

1283 Maximum number of workers to use for parallel computation. If negative, 

1284 the value wraps around from ``os.cpu_count()``. 

1285 See :func:`~scipy.fft.fft` for more details. 

1286 plan: object, optional 

1287 This argument is reserved for passing in a precomputed plan provided 

1288 by downstream FFT vendors. It is currently not used in SciPy. 

1289 

1290 .. versionadded:: 1.5.0 

1291 

1292 Returns 

1293 ------- 

1294 out : ndarray 

1295 The result of the inverse real 2-D FFT. 

1296 

1297 See Also 

1298 -------- 

1299 rfft2 : The 2-D FFT of real input. 

1300 irfft : The inverse of the 1-D FFT of real input. 

1301 irfftn : The inverse of the N-D FFT of real input. 

1302 

1303 Notes 

1304 ----- 

1305 This is really `irfftn` with different defaults. 

1306 For more details see `irfftn`. 

1307 

1308 """ 

1309 return (Dispatchable(x, np.ndarray),) 

1310 

1311 

1312@_dispatch 

1313def hfftn(x, s=None, axes=None, norm=None, overwrite_x=False, workers=None, *, 

1314 plan=None): 

1315 """ 

1316 Compute the N-D FFT of Hermitian symmetric complex input, i.e., a 

1317 signal with a real spectrum. 

1318 

1319 This function computes the N-D discrete Fourier Transform for a 

1320 Hermitian symmetric complex input over any number of axes in an 

1321 M-D array by means of the Fast Fourier Transform (FFT). In other 

1322 words, ``ihfftn(hfftn(x, s)) == x`` to within numerical accuracy. (``s`` 

1323 here is ``x.shape`` with ``s[-1] = x.shape[-1] * 2 - 1``, this is necessary 

1324 for the same reason ``x.shape`` would be necessary for `irfft`.) 

1325 

1326 Parameters 

1327 ---------- 

1328 x : array_like 

1329 Input array. 

1330 s : sequence of ints, optional 

1331 Shape (length of each transformed axis) of the output 

1332 (``s[0]`` refers to axis 0, ``s[1]`` to axis 1, etc.). `s` is also the 

1333 number of input points used along this axis, except for the last axis, 

1334 where ``s[-1]//2+1`` points of the input are used. 

1335 Along any axis, if the shape indicated by `s` is smaller than that of 

1336 the input, the input is cropped. If it is larger, the input is padded 

1337 with zeros. If `s` is not given, the shape of the input along the axes 

1338 specified by axes is used. Except for the last axis which is taken to be 

1339 ``2*(m-1)`` where ``m`` is the length of the input along that axis. 

1340 axes : sequence of ints, optional 

1341 Axes over which to compute the inverse FFT. If not given, the last 

1342 `len(s)` axes are used, or all axes if `s` is also not specified. 

1343 norm : {None, "ortho"}, optional 

1344 Normalization mode (see `fft`). Default is None. 

1345 overwrite_x : bool, optional 

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

1347 See :func:`fft` for more details. 

1348 workers : int, optional 

1349 Maximum number of workers to use for parallel computation. If negative, 

1350 the value wraps around from ``os.cpu_count()``. 

1351 See :func:`~scipy.fft.fft` for more details. 

1352 plan: object, optional 

1353 This argument is reserved for passing in a precomputed plan provided 

1354 by downstream FFT vendors. It is currently not used in SciPy. 

1355 

1356 .. versionadded:: 1.5.0 

1357 

1358 Returns 

1359 ------- 

1360 out : ndarray 

1361 The truncated or zero-padded input, transformed along the axes 

1362 indicated by `axes`, or by a combination of `s` or `x`, 

1363 as explained in the parameters section above. 

1364 The length of each transformed axis is as given by the corresponding 

1365 element of `s`, or the length of the input in every axis except for the 

1366 last one if `s` is not given. In the final transformed axis the length 

1367 of the output when `s` is not given is ``2*(m-1)`` where ``m`` is the 

1368 length of the final transformed axis of the input. To get an odd 

1369 number of output points in the final axis, `s` must be specified. 

1370 

1371 Raises 

1372 ------ 

1373 ValueError 

1374 If `s` and `axes` have different length. 

1375 IndexError 

1376 If an element of `axes` is larger than than the number of axes of `x`. 

1377 

1378 See Also 

1379 -------- 

1380 ihfftn : The inverse N-D FFT with real spectrum. Inverse of `hfftn`. 

1381 fft : The 1-D FFT, with definitions and conventions used. 

1382 rfft : Forward FFT of real input. 

1383 

1384 Notes 

1385 ----- 

1386 

1387 For a 1-D signal ``x`` to have a real spectrum, it must satisfy 

1388 the Hermitian property:: 

1389 

1390 x[i] == np.conj(x[-i]) for all i 

1391 

1392 This generalizes into higher dimensions by reflecting over each axis in 

1393 turn:: 

1394 

1395 x[i, j, k, ...] == np.conj(x[-i, -j, -k, ...]) for all i, j, k, ... 

1396 

1397 This should not be confused with a Hermitian matrix, for which the 

1398 transpose is its own conjugate:: 

1399 

1400 x[i, j] == np.conj(x[j, i]) for all i, j 

1401 

1402 

1403 The default value of `s` assumes an even output length in the final 

1404 transformation axis. When performing the final complex to real 

1405 transformation, the Hermitian symmetry requires that the last imaginary 

1406 component along that axis must be 0 and so it is ignored. To avoid losing 

1407 information, the correct length of the real input *must* be given. 

1408 

1409 Examples 

1410 -------- 

1411 >>> import scipy.fft 

1412 >>> x = np.ones((3, 2, 2)) 

1413 >>> scipy.fft.hfftn(x) 

1414 array([[[12., 0.], 

1415 [ 0., 0.]], 

1416 [[ 0., 0.], 

1417 [ 0., 0.]], 

1418 [[ 0., 0.], 

1419 [ 0., 0.]]]) 

1420 

1421 """ 

1422 return (Dispatchable(x, np.ndarray),) 

1423 

1424 

1425@_dispatch 

1426def hfft2(x, s=None, axes=(-2, -1), norm=None, overwrite_x=False, workers=None, *, 

1427 plan=None): 

1428 """ 

1429 Compute the 2-D FFT of a Hermitian complex array. 

1430 

1431 Parameters 

1432 ---------- 

1433 x : array 

1434 Input array, taken to be Hermitian complex. 

1435 s : sequence of ints, optional 

1436 Shape of the real output. 

1437 axes : sequence of ints, optional 

1438 Axes over which to compute the FFT. 

1439 norm : {None, "ortho"}, optional 

1440 Normalization mode (see `fft`). Default is None. 

1441 overwrite_x : bool, optional 

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

1443 See `fft` for more details. 

1444 workers : int, optional 

1445 Maximum number of workers to use for parallel computation. If negative, 

1446 the value wraps around from ``os.cpu_count()``. 

1447 See :func:`~scipy.fft.fft` for more details. 

1448 plan: object, optional 

1449 This argument is reserved for passing in a precomputed plan provided 

1450 by downstream FFT vendors. It is currently not used in SciPy. 

1451 

1452 .. versionadded:: 1.5.0 

1453 

1454 Returns 

1455 ------- 

1456 out : ndarray 

1457 The real result of the 2-D Hermitian complex real FFT. 

1458 

1459 See Also 

1460 -------- 

1461 hfftn : Compute the N-D discrete Fourier Transform for Hermitian 

1462 complex input. 

1463 

1464 Notes 

1465 ----- 

1466 This is really just `hfftn` with different default behavior. 

1467 For more details see `hfftn`. 

1468 

1469 """ 

1470 return (Dispatchable(x, np.ndarray),) 

1471 

1472 

1473@_dispatch 

1474def ihfftn(x, s=None, axes=None, norm=None, overwrite_x=False, workers=None, *, 

1475 plan=None): 

1476 """ 

1477 Compute the N-D inverse discrete Fourier Transform for a real 

1478 spectrum. 

1479 

1480 This function computes the N-D inverse discrete Fourier Transform 

1481 over any number of axes in an M-D real array by means of the Fast 

1482 Fourier Transform (FFT). By default, all axes are transformed, with the 

1483 real transform performed over the last axis, while the remaining transforms 

1484 are complex. 

1485 

1486 Parameters 

1487 ---------- 

1488 x : array_like 

1489 Input array, taken to be real. 

1490 s : sequence of ints, optional 

1491 Shape (length along each transformed axis) to use from the input. 

1492 (``s[0]`` refers to axis 0, ``s[1]`` to axis 1, etc.). 

1493 Along any axis, if the given shape is smaller than that of the input, 

1494 the input is cropped. If it is larger, the input is padded with zeros. 

1495 if `s` is not given, the shape of the input along the axes specified 

1496 by `axes` is used. 

1497 axes : sequence of ints, optional 

1498 Axes over which to compute the FFT. If not given, the last ``len(s)`` 

1499 axes are used, or all axes if `s` is also not specified. 

1500 norm : {None, "ortho"}, optional 

1501 Normalization mode (see `fft`). Default is None. 

1502 overwrite_x : bool, optional 

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

1504 See :func:`fft` for more details. 

1505 workers : int, optional 

1506 Maximum number of workers to use for parallel computation. If negative, 

1507 the value wraps around from ``os.cpu_count()``. 

1508 See :func:`~scipy.fft.fft` for more details. 

1509 plan: object, optional 

1510 This argument is reserved for passing in a precomputed plan provided 

1511 by downstream FFT vendors. It is currently not used in SciPy. 

1512 

1513 .. versionadded:: 1.5.0 

1514 

1515 Returns 

1516 ------- 

1517 out : complex ndarray 

1518 The truncated or zero-padded input, transformed along the axes 

1519 indicated by `axes`, or by a combination of `s` and `x`, 

1520 as explained in the parameters section above. 

1521 The length of the last axis transformed will be ``s[-1]//2+1``, 

1522 while the remaining transformed axes will have lengths according to 

1523 `s`, or unchanged from the input. 

1524 

1525 Raises 

1526 ------ 

1527 ValueError 

1528 If `s` and `axes` have different length. 

1529 IndexError 

1530 If an element of `axes` is larger than than the number of axes of `x`. 

1531 

1532 See Also 

1533 -------- 

1534 hfftn : The forward N-D FFT of Hermitian input. 

1535 hfft : The 1-D FFT of Hermitian input. 

1536 fft : The 1-D FFT, with definitions and conventions used. 

1537 fftn : The N-D FFT. 

1538 hfft2 : The 2-D FFT of Hermitian input. 

1539 

1540 Notes 

1541 ----- 

1542 

1543 The transform for real input is performed over the last transformation 

1544 axis, as by `ihfft`, then the transform over the remaining axes is 

1545 performed as by `ifftn`. The order of the output is the positive part of 

1546 the Hermitian output signal, in the same format as `rfft`. 

1547 

1548 Examples 

1549 -------- 

1550 >>> import scipy.fft 

1551 >>> x = np.ones((2, 2, 2)) 

1552 >>> scipy.fft.ihfftn(x) 

1553 array([[[1.+0.j, 0.+0.j], # may vary 

1554 [0.+0.j, 0.+0.j]], 

1555 [[0.+0.j, 0.+0.j], 

1556 [0.+0.j, 0.+0.j]]]) 

1557 >>> scipy.fft.ihfftn(x, axes=(2, 0)) 

1558 array([[[1.+0.j, 0.+0.j], # may vary 

1559 [1.+0.j, 0.+0.j]], 

1560 [[0.+0.j, 0.+0.j], 

1561 [0.+0.j, 0.+0.j]]]) 

1562 

1563 """ 

1564 return (Dispatchable(x, np.ndarray),) 

1565 

1566 

1567@_dispatch 

1568def ihfft2(x, s=None, axes=(-2, -1), norm=None, overwrite_x=False, workers=None, *, 

1569 plan=None): 

1570 """ 

1571 Compute the 2-D inverse FFT of a real spectrum. 

1572 

1573 Parameters 

1574 ---------- 

1575 x : array_like 

1576 The input array 

1577 s : sequence of ints, optional 

1578 Shape of the real input to the inverse FFT. 

1579 axes : sequence of ints, optional 

1580 The axes over which to compute the inverse fft. 

1581 Default is the last two axes. 

1582 norm : {None, "ortho"}, optional 

1583 Normalization mode (see `fft`). Default is None. 

1584 overwrite_x : bool, optional 

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

1586 See :func:`fft` for more details. 

1587 workers : int, optional 

1588 Maximum number of workers to use for parallel computation. If negative, 

1589 the value wraps around from ``os.cpu_count()``. 

1590 See :func:`~scipy.fft.fft` for more details. 

1591 plan: object, optional 

1592 This argument is reserved for passing in a precomputed plan provided 

1593 by downstream FFT vendors. It is currently not used in SciPy. 

1594 

1595 .. versionadded:: 1.5.0 

1596 

1597 Returns 

1598 ------- 

1599 out : ndarray 

1600 The result of the inverse real 2-D FFT. 

1601 

1602 See Also 

1603 -------- 

1604 ihfftn : Compute the inverse of the N-D FFT of Hermitian input. 

1605 

1606 Notes 

1607 ----- 

1608 This is really `ihfftn` with different defaults. 

1609 For more details see `ihfftn`. 

1610 

1611 """ 

1612 return (Dispatchable(x, np.ndarray),)