Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/scipy/fft/_basic.py: 64%

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 : {"backward", "ortho", "forward"}, optional 

46 Normalization mode. Default is "backward", meaning no normalization on 

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

48 "forward" instead applies the ``1/n`` factor on the forward tranform. 

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

50 

51 .. versionadded:: 1.6.0 

52 ``norm={"forward", "backward"}`` options were added 

53 

54 overwrite_x : bool, optional 

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

56 See the notes below for more details. 

57 workers : int, optional 

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

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

60 details. 

61 plan : object, optional 

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

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

64 

65 .. versionadded:: 1.5.0 

66 

67 Returns 

68 ------- 

69 out : complex ndarray 

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

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

72 

73 Raises 

74 ------ 

75 IndexError 

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

77 

78 See Also 

79 -------- 

80 ifft : The inverse of `fft`. 

81 fft2 : The 2-D FFT. 

82 fftn : The N-D FFT. 

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

84 fftfreq : Frequency bins for given FFT parameters. 

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

86 

87 Notes 

88 ----- 

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

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

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

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

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

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

95 the input using `next_fast_len`. 

96 

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

98 

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

100 

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

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

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

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

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

106 use `fftshift`. 

107 

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

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

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

111 precision. 

112 

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

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

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

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

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

118 half of the spectrum from half of the signal. 

119 

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

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

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

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

124 future without warning. 

125 

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

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

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

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

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

131 

132 References 

133 ---------- 

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

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

136 19: 297-301. 

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

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

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

140 

141 Examples 

142 -------- 

143 >>> import scipy.fft 

144 >>> import numpy as np 

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

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

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

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

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

150 

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

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

153 

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

155 >>> import matplotlib.pyplot as plt 

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

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

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

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

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

161 >>> plt.show() 

162 

163 """ 

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

165 

166 

167@_dispatch 

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

169 plan=None): 

170 """ 

171 Compute the 1-D inverse discrete Fourier Transform. 

172 

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

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

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

176 

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

178 i.e., 

179 

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

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

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

183 increasing order starting from the most negative frequency. 

184 

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

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

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

188 

189 Parameters 

190 ---------- 

191 x : array_like 

192 Input array, can be complex. 

193 n : int, optional 

194 Length of the transformed axis of the output. 

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

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

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

198 See notes about padding issues. 

199 axis : int, optional 

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

201 axis is used. 

202 norm : {"backward", "ortho", "forward"}, optional 

203 Normalization mode (see `fft`). Default is "backward". 

204 overwrite_x : bool, optional 

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

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

207 workers : int, optional 

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

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

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

211 plan : object, optional 

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

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

214 

215 .. versionadded:: 1.5.0 

216 

217 Returns 

218 ------- 

219 out : complex ndarray 

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

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

222 

223 Raises 

224 ------ 

225 IndexError 

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

227 

228 See Also 

229 -------- 

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

231 ifft2 : The 2-D inverse FFT. 

232 ifftn : The N-D inverse FFT. 

233 

234 Notes 

235 ----- 

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

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

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

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

240 

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

242 

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

244 

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

246 optimized for real input. 

247 

248 Examples 

249 -------- 

250 >>> import scipy.fft 

251 >>> import numpy as np 

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

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

254 

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

256 

257 >>> import matplotlib.pyplot as plt 

258 >>> rng = np.random.default_rng() 

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

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

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

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

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

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

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

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

267 >>> plt.show() 

268 

269 """ 

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

271 

272 

273@_dispatch 

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

275 plan=None): 

276 """ 

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

278 

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

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

281 called the Fast Fourier Transform (FFT). 

282 

283 Parameters 

284 ---------- 

285 x : array_like 

286 Input array 

287 n : int, optional 

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

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

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

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

292 axis : int, optional 

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

294 used. 

295 norm : {"backward", "ortho", "forward"}, optional 

296 Normalization mode (see `fft`). Default is "backward". 

297 overwrite_x : bool, optional 

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

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

300 workers : int, optional 

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

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

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

304 plan : object, optional 

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

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

307 

308 .. versionadded:: 1.5.0 

309 

310 Returns 

311 ------- 

312 out : complex ndarray 

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

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

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

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

317 

318 Raises 

319 ------ 

320 IndexError 

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

322 

323 See Also 

324 -------- 

325 irfft : The inverse of `rfft`. 

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

327 fftn : The N-D FFT. 

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

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

330 

331 Notes 

332 ----- 

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

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

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

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

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

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

339 

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

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

342 

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

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

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

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

347 general case. 

348 

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

350 

351 Examples 

352 -------- 

353 >>> import scipy.fft 

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

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

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

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

358 

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

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

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

362 

363 """ 

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

365 

366 

367@_dispatch 

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

369 plan=None): 

370 """ 

371 Computes the inverse of `rfft`. 

372 

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

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

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

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

377 

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

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

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

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

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

383 

384 Parameters 

385 ---------- 

386 x : array_like 

387 The input array. 

388 n : int, optional 

389 Length of the transformed axis of the output. 

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

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

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

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

394 specified by `axis`. 

395 axis : int, optional 

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

397 axis is used. 

398 norm : {"backward", "ortho", "forward"}, optional 

399 Normalization mode (see `fft`). Default is "backward". 

400 overwrite_x : bool, optional 

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

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

403 workers : int, optional 

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

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

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

407 plan : object, optional 

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

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

410 

411 .. versionadded:: 1.5.0 

412 

413 Returns 

414 ------- 

415 out : ndarray 

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

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

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

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

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

421 

422 Raises 

423 ------ 

424 IndexError 

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

426 

427 See Also 

428 -------- 

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

430 fft : The 1-D FFT. 

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

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

433 

434 Notes 

435 ----- 

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

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

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

439 input. 

440 

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

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

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

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

445 

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

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

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

449 given. 

450 

451 Examples 

452 -------- 

453 >>> import scipy.fft 

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

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

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

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

458 

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

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

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

462 specified, and the output array is purely real. 

463 

464 """ 

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

466 

467 

468@_dispatch 

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

470 plan=None): 

471 """ 

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

473 spectrum. 

474 

475 Parameters 

476 ---------- 

477 x : array_like 

478 The input array. 

479 n : int, optional 

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

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

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

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

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

485 `axis`. 

486 axis : int, optional 

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

488 axis is used. 

489 norm : {"backward", "ortho", "forward"}, optional 

490 Normalization mode (see `fft`). Default is "backward". 

491 overwrite_x : bool, optional 

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

493 See `fft` for more details. 

494 workers : int, optional 

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

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

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

498 plan : object, optional 

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

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

501 

502 .. versionadded:: 1.5.0 

503 

504 Returns 

505 ------- 

506 out : ndarray 

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

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

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

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

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

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

513 

514 Raises 

515 ------ 

516 IndexError 

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

518 

519 See Also 

520 -------- 

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

522 ihfft : The inverse of `hfft`. 

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

524 

525 Notes 

526 ----- 

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

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

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

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

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

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

533 

534 Examples 

535 -------- 

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

537 >>> import numpy as np 

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

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

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

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

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

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

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

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

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

547 """ 

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

549 

550 

551@_dispatch 

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

553 plan=None): 

554 """ 

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

556 

557 Parameters 

558 ---------- 

559 x : array_like 

560 Input array. 

561 n : int, optional 

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

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

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

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

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

567 axis : int, optional 

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

569 axis is used. 

570 norm : {"backward", "ortho", "forward"}, optional 

571 Normalization mode (see `fft`). Default is "backward". 

572 overwrite_x : bool, optional 

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

574 See `fft` for more details. 

575 workers : int, optional 

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

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

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

579 plan : object, optional 

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

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

582 

583 .. versionadded:: 1.5.0 

584 

585 Returns 

586 ------- 

587 out : complex ndarray 

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

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

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

591 

592 See Also 

593 -------- 

594 hfft, irfft 

595 

596 Notes 

597 ----- 

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

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

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

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

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

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

604 

605 Examples 

606 -------- 

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

608 >>> import numpy as np 

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

610 >>> ifft(spectrum) 

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

612 >>> ihfft(spectrum) 

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

614 """ 

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

616 

617 

618@_dispatch 

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

620 plan=None): 

621 """ 

622 Compute the N-D discrete Fourier Transform. 

623 

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

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

626 Transform (FFT). 

627 

628 Parameters 

629 ---------- 

630 x : array_like 

631 Input array, can be complex. 

632 s : sequence of ints, optional 

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

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

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

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

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

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

639 by `axes` is used. 

640 axes : sequence of ints, optional 

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

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

643 norm : {"backward", "ortho", "forward"}, optional 

644 Normalization mode (see `fft`). Default is "backward". 

645 overwrite_x : bool, optional 

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

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

648 workers : int, optional 

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

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

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

652 plan : object, optional 

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

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

655 

656 .. versionadded:: 1.5.0 

657 

658 Returns 

659 ------- 

660 out : complex ndarray 

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

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

663 as explained in the parameters section above. 

664 

665 Raises 

666 ------ 

667 ValueError 

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

669 IndexError 

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

671 

672 See Also 

673 -------- 

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

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

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

677 fft2 : The 2-D FFT. 

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

679 

680 Notes 

681 ----- 

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

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

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

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

686 axes, in order of decreasingly negative frequency. 

687 

688 Examples 

689 -------- 

690 >>> import scipy.fft 

691 >>> import numpy as np 

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

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

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

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

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

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

698 [ 0.+0.j, 0.+0.j, 0.+0.j], 

699 [ 0.+0.j, 0.+0.j, 0.+0.j]], 

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

701 [ 0.+0.j, 0.+0.j, 0.+0.j], 

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

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

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

705 [ 0.+0.j, 0.+0.j, 0.+0.j]], 

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

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

708 

709 >>> import matplotlib.pyplot as plt 

710 >>> rng = np.random.default_rng() 

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

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

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

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

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

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

717 >>> plt.show() 

718 

719 """ 

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

721 

722 

723@_dispatch 

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

725 plan=None): 

726 """ 

727 Compute the N-D inverse discrete Fourier Transform. 

728 

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

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

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

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

733 

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

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

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

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

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

739 axes, in order of decreasingly negative frequency. 

740 

741 Parameters 

742 ---------- 

743 x : array_like 

744 Input array, can be complex. 

745 s : sequence of ints, optional 

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

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

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

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

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

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

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

753 axes : sequence of ints, optional 

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

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

756 norm : {"backward", "ortho", "forward"}, optional 

757 Normalization mode (see `fft`). Default is "backward". 

758 overwrite_x : bool, optional 

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

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

761 workers : int, optional 

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

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

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

765 plan : object, optional 

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

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

768 

769 .. versionadded:: 1.5.0 

770 

771 Returns 

772 ------- 

773 out : complex ndarray 

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

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

776 as explained in the parameters section above. 

777 

778 Raises 

779 ------ 

780 ValueError 

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

782 IndexError 

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

784 

785 See Also 

786 -------- 

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

788 ifft : The 1-D inverse FFT. 

789 ifft2 : The 2-D inverse FFT. 

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

791 of array. 

792 

793 Notes 

794 ----- 

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

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

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

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

799 

800 Examples 

801 -------- 

802 >>> import scipy.fft 

803 >>> import numpy as np 

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

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

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

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

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

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

810 

811 

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

813 

814 >>> import matplotlib.pyplot as plt 

815 >>> rng = np.random.default_rng() 

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

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

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

819 >>> plt.imshow(im) 

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

821 >>> plt.show() 

822 

823 """ 

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

825 

826 

827@_dispatch 

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

829 plan=None): 

830 """ 

831 Compute the 2-D discrete Fourier Transform 

832 

833 This function computes the N-D discrete Fourier Transform 

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

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

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

837 

838 Parameters 

839 ---------- 

840 x : array_like 

841 Input array, can be complex 

842 s : sequence of ints, optional 

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

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

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

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

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

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

849 by `axes` is used. 

850 axes : sequence of ints, optional 

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

852 used. 

853 norm : {"backward", "ortho", "forward"}, optional 

854 Normalization mode (see `fft`). Default is "backward". 

855 overwrite_x : bool, optional 

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

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

858 workers : int, optional 

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

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

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

862 plan : object, optional 

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

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

865 

866 .. versionadded:: 1.5.0 

867 

868 Returns 

869 ------- 

870 out : complex ndarray 

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

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

873 

874 Raises 

875 ------ 

876 ValueError 

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

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

879 IndexError 

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

881 

882 See Also 

883 -------- 

884 ifft2 : The inverse 2-D FFT. 

885 fft : The 1-D FFT. 

886 fftn : The N-D FFT. 

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

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

889 and fourth quadrants. 

890 

891 Notes 

892 ----- 

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

894 

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

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

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

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

899 the axes, in order of decreasingly negative frequency. 

900 

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

902 definitions and conventions used. 

903 

904 

905 Examples 

906 -------- 

907 >>> import scipy.fft 

908 >>> import numpy as np 

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

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

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

912 0. +0.j , 0. +0.j ], 

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

914 0. +0.j , 0. +0.j ], 

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

916 0. +0.j , 0. +0.j ], 

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

918 0. +0.j , 0. +0.j ], 

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

920 0. +0.j , 0. +0.j ]]) 

921 

922 """ 

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

924 

925 

926@_dispatch 

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

928 plan=None): 

929 """ 

930 Compute the 2-D inverse discrete Fourier Transform. 

931 

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

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

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

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

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

937 

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

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

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

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

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

943 both axes, in order of decreasingly negative frequency. 

944 

945 Parameters 

946 ---------- 

947 x : array_like 

948 Input array, can be complex. 

949 s : sequence of ints, optional 

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

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

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

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

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

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

956 axes : sequence of ints, optional 

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

958 axes are used. 

959 norm : {"backward", "ortho", "forward"}, optional 

960 Normalization mode (see `fft`). Default is "backward". 

961 overwrite_x : bool, optional 

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

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

964 workers : int, optional 

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

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

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

968 plan : object, optional 

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

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

971 

972 .. versionadded:: 1.5.0 

973 

974 Returns 

975 ------- 

976 out : complex ndarray 

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

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

979 

980 Raises 

981 ------ 

982 ValueError 

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

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

985 IndexError 

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

987 

988 See Also 

989 -------- 

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

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

992 fft : The 1-D FFT. 

993 ifft : The 1-D inverse FFT. 

994 

995 Notes 

996 ----- 

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

998 

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

1000 definition and conventions used. 

1001 

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

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

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

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

1006 

1007 Examples 

1008 -------- 

1009 >>> import scipy.fft 

1010 >>> import numpy as np 

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

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

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

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

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

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

1017 

1018 """ 

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

1020 

1021 

1022@_dispatch 

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

1024 plan=None): 

1025 """ 

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

1027 

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

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

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

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

1032 transforms are complex. 

1033 

1034 Parameters 

1035 ---------- 

1036 x : array_like 

1037 Input array, taken to be real. 

1038 s : sequence of ints, optional 

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

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

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

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

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

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

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

1046 by `axes` is used. 

1047 axes : sequence of ints, optional 

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

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

1050 norm : {"backward", "ortho", "forward"}, optional 

1051 Normalization mode (see `fft`). Default is "backward". 

1052 overwrite_x : bool, optional 

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

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

1055 workers : int, optional 

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

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

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

1059 plan : object, optional 

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

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

1062 

1063 .. versionadded:: 1.5.0 

1064 

1065 Returns 

1066 ------- 

1067 out : complex ndarray 

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

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

1070 as explained in the parameters section above. 

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

1072 while the remaining transformed axes will have lengths according to 

1073 `s`, or unchanged from the input. 

1074 

1075 Raises 

1076 ------ 

1077 ValueError 

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

1079 IndexError 

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

1081 

1082 See Also 

1083 -------- 

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

1085 of real input. 

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

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

1088 fftn : The N-D FFT. 

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

1090 

1091 Notes 

1092 ----- 

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

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

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

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

1097 transformation axes. 

1098 

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

1100 

1101 Examples 

1102 -------- 

1103 >>> import scipy.fft 

1104 >>> import numpy as np 

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

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

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

1108 [0.+0.j, 0.+0.j]], 

1109 [[0.+0.j, 0.+0.j], 

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

1111 

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

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

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

1115 [[0.+0.j, 0.+0.j], 

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

1117 

1118 """ 

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

1120 

1121 

1122@_dispatch 

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

1124 plan=None): 

1125 """ 

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

1127 

1128 Parameters 

1129 ---------- 

1130 x : array 

1131 Input array, taken to be real. 

1132 s : sequence of ints, optional 

1133 Shape of the FFT. 

1134 axes : sequence of ints, optional 

1135 Axes over which to compute the FFT. 

1136 norm : {"backward", "ortho", "forward"}, optional 

1137 Normalization mode (see `fft`). Default is "backward". 

1138 overwrite_x : bool, optional 

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

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

1141 workers : int, optional 

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

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

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

1145 plan : object, optional 

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

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

1148 

1149 .. versionadded:: 1.5.0 

1150 

1151 Returns 

1152 ------- 

1153 out : ndarray 

1154 The result of the real 2-D FFT. 

1155 

1156 See Also 

1157 -------- 

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

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

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

1161 input. 

1162 

1163 Notes 

1164 ----- 

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

1166 For more details see `rfftn`. 

1167 

1168 """ 

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

1170 

1171 

1172@_dispatch 

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

1174 plan=None): 

1175 """ 

1176 Computes the inverse of `rfftn` 

1177 

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

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

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

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

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

1183 and for the same reason.) 

1184 

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

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

1187 along all the other axes. 

1188 

1189 Parameters 

1190 ---------- 

1191 x : array_like 

1192 Input array. 

1193 s : sequence of ints, optional 

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

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

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

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

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

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

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

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

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

1203 axes : sequence of ints, optional 

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

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

1206 norm : {"backward", "ortho", "forward"}, optional 

1207 Normalization mode (see `fft`). Default is "backward". 

1208 overwrite_x : bool, optional 

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

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

1211 workers : int, optional 

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

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

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

1215 plan : object, optional 

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

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

1218 

1219 .. versionadded:: 1.5.0 

1220 

1221 Returns 

1222 ------- 

1223 out : ndarray 

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

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

1226 as explained in the parameters section above. 

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

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

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

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

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

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

1233 

1234 Raises 

1235 ------ 

1236 ValueError 

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

1238 IndexError 

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

1240 

1241 See Also 

1242 -------- 

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

1244 of which `ifftn` is the inverse. 

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

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

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

1248 

1249 Notes 

1250 ----- 

1251 See `fft` for definitions and conventions used. 

1252 

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

1254 

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

1256 transformation axis. When performing the final complex to real 

1257 transformation, the Hermitian symmetry requires that the last imaginary 

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