[SciPy-dev] fftpack2 for review

[Pearu Peterson]

On 4 Oct 2002, Travis Oliphant wrote:

> 
> I finally had some time to test fftpack2.  It looks really great and I'm
> happy to support including it.   I'll attach my test results at the end
> (with fftw and djbfft).
> 
> My only comment right now, is that I don't like doing away with the word
> fftshift.  This is a common command in MATLAB and is quite familiar.  I
> don't necessarily mind freqshift,
> 
> 
> > >   Also freqshift puts the Nyquist component at the end of the result
> > >   while fftshift puts it at the beginning of the result. This is for
> > >   the consistency among various functions in the fftpack module.
> 
> Is there a difference between freqshift and fftshift?  If so, then I am
> not satisfied.  I took great pains to ensure that fftshift works exactly
> the same way as in MATLAB.

To be honest, I used the docs of scipy.fftpack.fft as a basic reference
and followed that while implementing fftpack2. Until fftshift, everything
was consistent. Then it turned out that fftshift uses a different
convention than fft. Namely, according to scipy.fftpack.fft docs, the
corresponding frequencies of the fft result are given as
   [ 0, 1, 2, 3, 4, -3, -2, -1]
for n=8 case, for example. But fftshift assumed
   [ 0, 1, 2, 3, -4, -3, -2, -1]
Both cases are equivalent except when applying the definition of fftshift,
that is, how to order the frequencies of the fft result.
Now, in fftpack2 I just kept being consistent (as everything were 
documented already) and as a result, the results of fftpack2.freqshift and
fftshift (in scipy.fftpack and Matlab) had to differ by the location
of the Nyquist mode (that's also one of the hidden reasons why I
introduced a new name freqshift for fftshift; about the other reason, see
below).

I guess it would not be a good idea to have both freqshift and fftshift at
the same time (the latter behaving exactly as fftshift in MATLAB). 
Personally, I have no preference to either of them, it's just a
matter of choosing a convention and sticking to it.  But since you insist
MATLAB convention, I'll change the docs in fftpack2: basically, the
Nyquist mode will be corresponding to the smallest negative frequency
instead of the largest positive one.

> It is important that the common fft operations present a single
> interface to the user.  If we want to offer specialized functions that
> do not mess with the ordering but expect the user to know what they are
> doing, that is fine, as long as the default functions follow the basic
> pattern.

Ok.

> I think that the MATLAB convention should be followed here.

Ok. But I still think that "fftshift" is a misleading name, even
if MATLAB uses it. Often people forget that FFT is just an efficient 
algorithm for performing the Fourier matrix multiplication with a vector,
nothing more. And fftshift has nothing to do with this FFT algorithm.

I see the following solutions:
1) continue with a bad manner learned from Matlab and use fftshift
2) use a more appropriate name, I proposed freqshift (other suggestions
are welcome), and may be provide fftshift in MLab.py, for example.

On the other hand, I don't want that some function name will make somebody
unhappy. Right now I am just proposing this name change because it feels
right to me and it is the right time to make a choice, later it would be
too late. What do you think?

Pearu