Coverage for /home/martinb/.local/share/virtualenvs/camcops/lib/python3.6/site-packages/scipy/fft/_basic.py : 64%

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
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
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")
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.
29 This function computes the 1-D *n*-point discrete Fourier
30 Transform (DFT) with the efficient Fast Fourier Transform (FFT)
31 algorithm [1]_.
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.
60 .. versionadded:: 1.5.0
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.
68 Raises
69 ------
70 IndexError
71 if `axes` is larger than the last axis of `x`.
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
82 Notes
83 -----
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`.
93 If ``x`` is a 1d array, then the `fft` is equivalent to ::
95 y[k] = np.sum(x * np.exp(-2j * np.pi * k * np.arange(n)/n))
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`.
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.
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.
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.
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.
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.
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])
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:
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()
158 """
159 return (Dispatchable(x, np.ndarray),)
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.
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.
172 The input should be ordered in the same way as is returned by `fft`,
173 i.e.,
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.
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.
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.
210 .. versionadded:: 1.5.0
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.
218 Raises
219 ------
220 IndexError
221 If `axes` is larger than the last axis of `x`.
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.
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`.
236 If ``x`` is a 1-D array, then the `ifft` is equivalent to ::
238 y[k] = np.sum(x * np.exp(2j * np.pi * k * np.arange(n)/n)) / len(x)
240 As with `fft`, `ifft` has support for all floating point types and is
241 optimized for real input.
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
249 Create and plot a band-limited signal with random phases:
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()
262 """
263 return (Dispatchable(x, np.ndarray),)
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.
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).
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.
301 .. versionadded:: 1.5.0
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``.
311 Raises
312 ------
313 IndexError
314 If `axis` is larger than the last axis of `a`.
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.
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``.
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.
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.
342 If the input `a` contains an imaginary part, it is silently discarded.
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
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.
356 """
357 return (Dispatchable(x, np.ndarray),)
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`.
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.)
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.
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.
404 .. versionadded:: 1.5.0
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.
415 Raises
416 ------
417 IndexError
418 If `axis` is larger than the last axis of `x`.
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.
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.
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)``.
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.
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.])
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.
457 """
458 return (Dispatchable(x, np.ndarray),)
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.
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.
495 .. versionadded:: 1.5.0
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,
507 Raises
508 ------
509 IndexError
510 If `axis` is larger than the last axis of `a`.
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.
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.
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),)
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.
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.
575 .. versionadded:: 1.5.0
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``.
584 See also
585 --------
586 hfft, irfft
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.
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),)
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.
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).
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.
647 .. versionadded:: 1.5.0
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.
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`.
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.
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.
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]]])
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()
708 """
709 return (Dispatchable(x, np.ndarray),)
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.
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.
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.
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.
758 .. versionadded:: 1.5.0
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.
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`.
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.
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.
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]])
800 Create and plot an image with band-limited frequency content:
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()
810 """
811 return (Dispatchable(x, np.ndarray),)
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
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.
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.
853 .. versionadded:: 1.5.0
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.
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`.
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.
878 Notes
879 -----
880 `fft2` is just `fftn` with a different default for `axes`.
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.
888 See `fftn` for details and a plotting example, and `fft` for
889 definitions and conventions used.
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 ]])
908 """
909 return (Dispatchable(x, np.ndarray),)
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.
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.
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.
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.
958 .. versionadded:: 1.5.0
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.
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`.
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.
981 Notes
982 -----
983 `ifft2` is just `ifftn` with a different default for `axes`.
985 See `ifftn` for details and a plotting example, and `fft` for
986 definition and conventions used.
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.
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]])
1003 """
1004 return (Dispatchable(x, np.ndarray),)
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.
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.
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.
1048 .. versionadded:: 1.5.0
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.
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`.
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.
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.
1084 See `fft` for details, definitions and conventions used.
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]]])
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]]])
1102 """
1103 return (Dispatchable(x, np.ndarray),)
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.
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.
1133 .. versionadded:: 1.5.0
1135 Returns
1136 -------
1137 out : ndarray
1138 The result of the real 2-D FFT.
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.
1147 Notes
1148 -----
1149 This is really just `rfftn` with different default behavior.
1150 For more details see `rfftn`.
1152 """
1153 return (Dispatchable(x, np.ndarray),)
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`
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.)
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.
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.
1203 .. versionadded:: 1.5.0
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.
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`.
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.
1233 Notes
1234 -----
1235 See `fft` for definitions and conventions used.
1237 See `rfft` for definitions and conventions used for real input.
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.
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.]]])
1258 """
1259 return (Dispatchable(x, np.ndarray),)
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`
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.
1290 .. versionadded:: 1.5.0
1292 Returns
1293 -------
1294 out : ndarray
1295 The result of the inverse real 2-D FFT.
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.
1303 Notes
1304 -----
1305 This is really `irfftn` with different defaults.
1306 For more details see `irfftn`.
1308 """
1309 return (Dispatchable(x, np.ndarray),)
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.
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`.)
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.
1356 .. versionadded:: 1.5.0
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.
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`.
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.
1384 Notes
1385 -----
1387 For a 1-D signal ``x`` to have a real spectrum, it must satisfy
1388 the Hermitian property::
1390 x[i] == np.conj(x[-i]) for all i
1392 This generalizes into higher dimensions by reflecting over each axis in
1393 turn::
1395 x[i, j, k, ...] == np.conj(x[-i, -j, -k, ...]) for all i, j, k, ...
1397 This should not be confused with a Hermitian matrix, for which the
1398 transpose is its own conjugate::
1400 x[i, j] == np.conj(x[j, i]) for all i, j
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.
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.]]])
1421 """
1422 return (Dispatchable(x, np.ndarray),)
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.
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.
1452 .. versionadded:: 1.5.0
1454 Returns
1455 -------
1456 out : ndarray
1457 The real result of the 2-D Hermitian complex real FFT.
1459 See Also
1460 --------
1461 hfftn : Compute the N-D discrete Fourier Transform for Hermitian
1462 complex input.
1464 Notes
1465 -----
1466 This is really just `hfftn` with different default behavior.
1467 For more details see `hfftn`.
1469 """
1470 return (Dispatchable(x, np.ndarray),)
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.
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.
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.
1513 .. versionadded:: 1.5.0
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.
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`.
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.
1540 Notes
1541 -----
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`.
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]]])
1563 """
1564 return (Dispatchable(x, np.ndarray),)
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.
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.
1595 .. versionadded:: 1.5.0
1597 Returns
1598 -------
1599 out : ndarray
1600 The result of the inverse real 2-D FFT.
1602 See Also
1603 --------
1604 ihfftn : Compute the inverse of the N-D FFT of Hermitian input.
1606 Notes
1607 -----
1608 This is really `ihfftn` with different defaults.
1609 For more details see `ihfftn`.
1611 """
1612 return (Dispatchable(x, np.ndarray),)