Provided by: pdl_2.007-2build1_amd64 bug

NAME

       PDL::FFT - FFTs for PDL

DESCRIPTION

       !!!!!!!!!!!!!!!!!!!!!!!!!!WARNING!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!  As of PDL-2.006_04,
       the direction of the FFT/IFFT has been reversed to match the usage in the FFTW library and
       the convention in use generally.
       !!!!!!!!!!!!!!!!!!!!!!!!!!WARNING!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

       FFTs for PDL.  These work for arrays of any dimension, although ones with small prime
       factors are likely to be the quickest.  The forward FFT is unnormalized while the inverse
       FFT is normalized so that the IFFT of the FFT returns the original values.

       For historical reasons, these routines work in-place and do not recognize the in-place
       flag.  That should be fixed.

SYNOPSIS

               use PDL::FFT qw/:Func/;

               fft($real, $imag);
               ifft($real, $imag);
               realfft($real);
               realifft($real);

               fftnd($real,$imag);
               ifftnd($real,$imag);

               $kernel = kernctr($image,$smallk);
               fftconvolve($image,$kernel);

DATA TYPES

       The underlying C library upon which this module is based performs FFTs on both single
       precision and double precision floating point piddles.  Performing FFTs on integer data
       types is not reliable.  Consider the following FFT on piddles of type 'double':

               $r = pdl(0,1,0,1);
               $i = zeroes($r);
               fft($r,$i);
               print $r,$i;
               [2 0 -2 0] [0 0 0 0]

       But if $r and $i are unsigned short integers (ushorts):

               $r = pdl(ushort,0,1,0,1);
               $i = zeroes($r);
               fft($r,$i);
               print $r,$i;
               [2 0 65534 0] [0 0 0 0]

       This used to occur because PDL::PP converts the ushort piddles to floats or doubles,
       performs the FFT on them, and then converts them back to ushort, causing the overflow
       where the amplitude of the frequency should be -2.

       Therefore, if you pass in a piddle of integer datatype (byte, short, ushort, long) to any
       of the routines in PDL::FFT, your data will be promoted to a double-precision piddle.  If
       you pass in a float, the single-precision FFT will be performed.

FREQUENCIES

       For even-sized input arrays, the frequencies are packed like normal for FFTs (where N is
       the size of the array and D is the physical step size between elements):

        0, 1/ND, 2/ND, ..., (N/2-1)/ND, 1/2D, -(N/2-1)/ND, ..., -1/ND.

       which can easily be obtained (taking the Nyquist frequency to be positive) using

       "$kx = $real->xlinvals(-($N/2-1)/$N/$D,1/2/$D)->rotate(-($N/2 -1));"

       For odd-sized input arrays the Nyquist frequency is not directly acessible, and the
       frequencies are

        0, 1/ND, 2/ND, ..., (N/2-0.5)/ND, -(N/2-0.5)/ND, ..., -1/ND.

       which can easily be obtained using

       "$kx = $real->xlinvals(-($N/2-0.5)/$N/$D,($N/2-0.5)/$N/$D)->rotate(-($N-1)/2);"

ALTERNATIVE FFT PACKAGES

       Various other modules - such as PDL::FFTW and PDL::Slatec - contain FFT routines.
       However, unlike PDL::FFT, these modules are optional, and so may not be installed.

FUNCTIONS

   fft()
       Complex 1-D FFT of the "real" and "imag" arrays [inplace].

         Signature: ([o,nc]real(n); [o,nc]imag(n))

       fft($real,$imag);

   ifft()
       Complex inverse 1-D FFT of the "real" and "imag" arrays [inplace].

         Signature: ([o,nc]real(n); [o,nc]imag(n))

       ifft($real,$imag);

   realfft()
       One-dimensional FFT of real function [inplace].

       The real part of the transform ends up in the first half of the array and the imaginary
       part of the transform ends up in the second half of the array.

               realfft($real);

   realifft()
       Inverse of one-dimensional realfft routine [inplace].

               realifft($real);

   fftnd()
       N-dimensional FFT over all pdl dims of input (inplace)

               fftnd($real,$imag);

   ifftnd()
       N-dimensional inverse FFT over all pdl dims of input (inplace)

               ifftnd($real,$imag);

   fftconvolve()
       N-dimensional convolution with periodic boundaries (FFT method)

               $kernel = kernctr($image,$smallk);
               fftconvolve($image,$kernel);

       fftconvolve works inplace, and returns an error array in kernel as an accuracy check --
       all the values in it should be negligible.

       See also PDL::ImageND::convolveND, which performs speed-optimized convolution with a
       variety of boundary conditions.

       The sizes of the image and the kernel must be the same.  kernctr centres a small kernel to
       emulate the behaviour of the direct convolution routines.

       The speed cross-over between using straight convolution (PDL::Image2D::conv2d()) and these
       fft routines is for kernel sizes roughly 7x7.

   convmath
         Signature: ([o,nc]a(m); [o,nc]b(m))

       Internal routine doing maths for convolution

       convmath does not process bad values.  It will set the bad-value flag of all output
       piddles if the flag is set for any of the input piddles.

   cmul
         Signature: (ar(); ai(); br(); bi(); [o]cr(); [o]ci())

       Complex multiplication

       cmul does not process bad values.  It will set the bad-value flag of all output piddles if
       the flag is set for any of the input piddles.

   cdiv
         Signature: (ar(); ai(); br(); bi(); [o]cr(); [o]ci())

       Complex division

       cdiv does not process bad values.  It will set the bad-value flag of all output piddles if
       the flag is set for any of the input piddles.

BUGS

       Where the source is marked `FIX', could re-implement using phase-shift factors on the
       transforms and some real-space bookkeeping, to save some temporary space and redundant
       transforms.

AUTHOR

       This file copyright (C) 1997, 1998 R.J.R. Williams (rjrw@ast.leeds.ac.uk), Karl Glazebrook
       (kgb@aaoepp.aao.gov.au), Tuomas J. Lukka, (lukka@husc.harvard.edu).  All rights reserved.
       There is no warranty. You are allowed to redistribute this software / documentation under
       certain conditions. For details, see the file COPYING in the PDL distribution. If this
       file is separated from the PDL distribution, the copyright notice should be included in
       the file.