From 6647bf7eaeb915e2d09db8b5c7584ee286962d3b Mon Sep 17 00:00:00 2001 From: Stefan van der Walt Date: Tue, 5 Aug 2008 09:20:07 +0000 Subject: Merge from documentation editor. --- numpy/fft/__init__.py | 34 +++++ numpy/fft/fftpack.py | 335 +++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 311 insertions(+), 58 deletions(-) (limited to 'numpy/fft') diff --git a/numpy/fft/__init__.py b/numpy/fft/__init__.py index 324e39f4d..1171a6026 100644 --- a/numpy/fft/__init__.py +++ b/numpy/fft/__init__.py @@ -1,3 +1,37 @@ +""" +Discrete Fast Fourier Transform (FFT) +===================================== + +========= ========================================================= +Standard FFTs +=================================================================== +fft Discrete Fourier transform. +ifft Inverse discrete Fourier transform. +fft2 Discrete Fourier transform in two dimensions. +ifft2 Inverse discrete Fourier transform in two dimensions. +fftn Discrete Fourier transform in N-dimensions. +ifftn Inverse discrete Fourier transform in N dimensions. +========= ========================================================= + +========= ========================================================== +Real FFTs +==================================================================== +rfft Real discrete Fourier transform. +irfft Inverse real discrete Fourier transform. +rfft2 Real discrete Fourier transform in two dimensions. +irfft2 Inverse real discrete Fourier transform in two dimensions. +rfftn Real discrete Fourier transform in N dimensions. +irfftn Inverse real discrete Fourier transform in N dimensions. +========= ========================================================== + +========= ========================================================= +Hermite FFTs +=================================================================== +hfft Hermite discrete Fourier transform. +ihfft Inverse hermite discrete Fourier transform. +========= ========================================================= + +""" # To get sub-modules from info import __doc__ diff --git a/numpy/fft/fftpack.py b/numpy/fft/fftpack.py index 6a0d3ab05..12c207cb0 100644 --- a/numpy/fft/fftpack.py +++ b/numpy/fft/fftpack.py @@ -70,12 +70,26 @@ def _raw_fft(a, n=None, axis=-1, init_function=fftpack.cffti, def fft(a, n=None, axis=-1): - """fft(a, n=None, axis=-1) + """ + Compute the one dimensional fft on a given axis. - Return the n point discrete Fourier transform of a. n defaults to - the length of a. If n is larger than the length of a, then a will - be zero-padded to make up the difference. If n is smaller than - the length of a, only the first n items in a will be used. + Return the n point discrete Fourier transform of a. n defaults to the + length of a. If n is larger than the length of a, then a will be + zero-padded to make up the difference. If n is smaller than the length of + a, only the first n items in a will be used. + + Parameters + ---------- + + a : array + input array + n : int + length of the fft + axis : int + axis over which to compute the fft + + Notes + ----- The packing of the result is "standard": If A = fft(a, n), then A[0] contains the zero-frequency term, A[1:n/2+1] contains the @@ -86,13 +100,16 @@ def fft(a, n=None, axis=-1): This is most efficient for n a power of two. This also stores a cache of working memory for different sizes of fft's, so you could theoretically run into memory problems if you call this too many times with too many - different n's.""" + different n's. + + """ return _raw_fft(a, n, axis, fftpack.cffti, fftpack.cfftf, _fft_cache) def ifft(a, n=None, axis=-1): - """ifft(a, n=None, axis=-1) + """ + Compute the one-dimensonal inverse fft on a given axis. Return the n point inverse discrete Fourier transform of a. n defaults to the length of a. If n is larger than the length of a, @@ -100,8 +117,20 @@ def ifft(a, n=None, axis=-1): smaller than the length of a, then a will be truncated to reduce its size. + Parameters + ---------- + + a : array + input array + n : int + length of the fft + axis : int + axis over which to compute the inverse fft + + Notes + ----- The input array is expected to be packed the same way as the output of - fft, as discussed in it's documentation. + fft, as discussed in the fft documentation. This is the inverse of fft: ifft(fft(a)) == a within numerical accuracy. @@ -109,7 +138,9 @@ def ifft(a, n=None, axis=-1): This is most efficient for n a power of two. This also stores a cache of working memory for different sizes of fft's, so you could theoretically run into memory problems if you call this too many times with too many - different n's.""" + different n's. + + """ a = asarray(a).astype(complex) if n is None: @@ -118,12 +149,26 @@ def ifft(a, n=None, axis=-1): def rfft(a, n=None, axis=-1): - """rfft(a, n=None, axis=-1) + """ + Compute the one-dimensional fft for real input. Return the n point discrete Fourier transform of the real valued array a. n defaults to the length of a. n is the length of the input, not the output. + Parameters + ---------- + + a : array + input array with real data type + n : int + length of the fft + axis : int + axis over which to compute the fft + + Notes + ----- + The returned array will be the nonnegative frequency terms of the Hermite-symmetric, complex transform of the real array. So for an 8-point transform, the frequencies in the result are [ 0, 1, 2, 3, 4]. The first @@ -132,14 +177,20 @@ def rfft(a, n=None, axis=-1): positive frequency terms. (This is what I mean when I say Hermite-symmetric.) - This is most efficient for n a power of two.""" + This is most efficient for n a power of two. + + """ a = asarray(a).astype(float) return _raw_fft(a, n, axis, fftpack.rffti, fftpack.rfftf, _real_fft_cache) def irfft(a, n=None, axis=-1): - """irfft(a, n=None, axis=-1) + """ + Compute the one-dimensional inverse fft for real input. + + Notes + ----- Return the real valued n point inverse discrete Fourier transform of a, where a contains the nonnegative frequency terms of a @@ -147,14 +198,27 @@ def irfft(a, n=None, axis=-1): input. If n is not supplied, the default is 2*(len(a)-1). If you want the length of the result to be odd, you have to say so. + Parameters + ---------- + + a : array + input array with real data type + n : int + length of the fft + axis : int + axis over which to compute the fft + + Notes + ----- + If you specify an n such that a must be zero-padded or truncated, the extra/removed values will be added/removed at high frequencies. One can thus resample a series to m points via Fourier interpolation by: a_resamp = irfft(rfft(a), m). - This is the inverse of rfft: - irfft(rfft(a), len(a)) == a - within numerical accuracy.""" + This is the inverse of rfft: irfft(rfft(a), len(a)) == a within numerical accuracy. + + """ a = asarray(a).astype(complex) if n is None: @@ -164,16 +228,34 @@ def irfft(a, n=None, axis=-1): def hfft(a, n=None, axis=-1): - """hfft(a, n=None, axis=-1) - ihfft(a, n=None, axis=-1) - + """ + Compute the fft of a signal which spectrum has Hermitian symmetry. + + Parameters + ---------- + a : array + input array + n : int + length of the hfft + axis : int + axis over which to compute the hfft + + Notes + ----- These are a pair analogous to rfft/irfft, but for the opposite case: here the signal is real in the frequency domain and has Hermite symmetry in the time domain. So here it's hermite_fft for which you must supply the length of the result if it is to be odd. ihfft(hfft(a), len(a)) == a - within numerical accuracy.""" + within numerical accuracy. + + See also + -------- + rfft + ihfft + + """ a = asarray(a).astype(complex) if n is None: @@ -182,16 +264,35 @@ def hfft(a, n=None, axis=-1): def ihfft(a, n=None, axis=-1): - """hfft(a, n=None, axis=-1) - ihfft(a, n=None, axis=-1) - + """ + Compute the inverse fft of a signal which spectrum has Hermitian + symmetry. + + Parameters + ---------- + a : array + input array + n : int + length of the ihfft + axis : int + axis over which to compute the ihfft + + Notes + ----- These are a pair analogous to rfft/irfft, but for the opposite case: here the signal is real in the frequency domain and has - Hermite symmetry in the time domain. So here it's hfft for which + Hermite symmetry in the time domain. So here it's hermite_fft for which you must supply the length of the result if it is to be odd. ihfft(hfft(a), len(a)) == a - within numerical accuracy.""" + within numerical accuracy. + + See also + -------- + rfft + hfft + + """ a = asarray(a).astype(float) if n is None: @@ -229,9 +330,53 @@ def _raw_fftnd(a, s=None, axes=None, function=fft): def fftn(a, s=None, axes=None): - """fftn(a, s=None, axes=None) + """ + Compute the N-dimensional Fast Fourier Transform. + + Parameters + ---------- + a : array_like + Input array. + s : sequence of ints + Shape of each axis of the input (s[0] refers to axis 0, s[1] to + axis 1, etc.). This corresponds to `n` for `fft(x, n)`. + Along any axis, if the given shape is smaller than that of the input, + the input is cropped. If it is larger, the input is padded with zeros. + axes : tuple of int + Axes over which to compute the FFT. + + Notes + ----- + Analogously to `fft`, the term for zero frequency in all axes is in the + low-order corner, while the term for the Nyquist frequency in all axes is + in the middle. - The n-dimensional fft of a. s is a sequence giving the shape of the input + If neither `s` nor `axes` is specified, the transform is taken along all + axes. If `s` is specified and `axes` is not, the last ``len(s)`` axes are + used. If `axes` is specified and `s` is not, the input shape along the + specified axes is used. If `s` and `axes` are both specified and are not + the same length, an exception is raised. + + """ + + return _raw_fftnd(a,s,axes,fft) + +def ifftn(a, s=None, axes=None): + """ + Compute the inverse of fftn. + + Parameters + ---------- + a : array + input array + s : sequence (int) + shape of the ifft + axis : int + axis over which to compute the ifft + + Notes + ----- + The n-dimensional ifft of a. s is a sequence giving the shape of the input an result along the transformed axes, as n for fft. Results are packed analogously to fft: the term for zero frequency in all axes is in the low-order corner, while the term for the Nyquist frequency in all axes is @@ -241,43 +386,77 @@ def fftn(a, s=None, axes=None): axes. If s is specified and axes is not, the last len(s) axes are used. If axes are specified and s is not, the input shape along the specified axes is used. If s and axes are both specified and are not the same - length, an exception is raised.""" - - return _raw_fftnd(a,s,axes,fft) - -def ifftn(a, s=None, axes=None): - """ifftn(a, s=None, axes=None) + length, an exception is raised. - The inverse of fftn.""" + """ return _raw_fftnd(a, s, axes, ifft) def fft2(a, s=None, axes=(-2,-1)): - """fft2(a, s=None, axes=(-2,-1)) + """ + Compute the 2d fft of an array. + + Parameters + ---------- + a : array + input array + s : sequence (int) + shape of the fft + axis : int + axis over which to compute the fft + + Notes + ----- + This is really just fftn with different default behavior. - The 2d fft of a. This is really just fftn with different default - behavior.""" + """ return _raw_fftnd(a,s,axes,fft) def ifft2(a, s=None, axes=(-2,-1)): - """ifft2(a, s=None, axes=(-2, -1)) + """ + Compute the inverse 2d fft of an array. - The inverse of fft2d. This is really just ifftn with different - default behavior.""" + Parameters + ---------- + a : array + input array + s : sequence (int) + shape of the ifft + axis : int + axis over which to compute the ifft + + Notes + ----- + This is really just ifftn with different default behavior. + + """ return _raw_fftnd(a, s, axes, ifft) def rfftn(a, s=None, axes=None): - """rfftn(a, s=None, axes=None) - - The n-dimensional discrete Fourier transform of a real array a. A real - transform as rfft is performed along the axis specified by the last + """ + Compute the n-dimensional fft of a real array. + + Parameters + ---------- + a : array (real) + input array + s : sequence (int) + shape of the fft + axis : int + axis over which to compute the fft + + Notes + ----- + A real transform as rfft is performed along the axis specified by the last element of axes, then complex transforms as fft are performed along the - other axes.""" + other axes. + + """ a = asarray(a).astype(float) s, axes = _cook_nd_args(a, s, axes) @@ -287,21 +466,48 @@ def rfftn(a, s=None, axes=None): return a def rfft2(a, s=None, axes=(-2,-1)): - """rfft2(a, s=None, axes=(-2,-1)) + """ + Compute the 2-dimensional fft of a real array. + + Parameters + ---------- + a : array (real) + input array + s : sequence (int) + shape of the fft + axis : int + axis over which to compute the fft + + Notes + ----- + The 2-D fft of the real valued array a. This is really just rfftn with + different default behavior. - The 2d fft of the real valued array a. This is really just rfftn with - different default behavior.""" + """ return rfftn(a, s, axes) def irfftn(a, s=None, axes=None): - """irfftn(a, s=None, axes=None) - - The inverse of rfftn. The transform implemented in ifft is - applied along all axes but the last, then the transform implemented in - irfft is performed along the last axis. As with - irfft, the length of the result along that axis must be - specified if it is to be odd.""" + """ + Compute the n-dimensional inverse fft of a real array. + + Parameters + ---------- + a : array (real) + input array + s : sequence (int) + shape of the inverse fft + axis : int + axis over which to compute the inverse fft + + Notes + ----- + The transform implemented in ifftn is applied along + all axes but the last, then the transform implemented in irfft is performed + along the last axis. As with irfft, the length of the result along that + axis must be specified if it is to be odd. + + """ a = asarray(a).astype(complex) s, axes = _cook_nd_args(a, s, axes, invreal=1) @@ -311,10 +517,23 @@ def irfftn(a, s=None, axes=None): return a def irfft2(a, s=None, axes=(-2,-1)): - """irfft2(a, s=None, axes=(-2, -1)) - - The inverse of rfft2. This is really just irfftn with - different default behavior.""" + """ + Compute the 2-dimensional inverse fft of a real array. + + Parameters + ---------- + a : array (real) + input array + s : sequence (int) + shape of the inverse fft + axis : int + axis over which to compute the inverse fft + + Notes + ----- + This is really irfftn with different default. + + """ return irfftn(a, s, axes) -- cgit v1.2.3