PUBLIC INTERFACE ~ PUBLIC DATA ~ PUBLIC ROUTINES ~ NAMELIST ~ DIAGNOSTIC FIELDS ~ ERROR MESSAGES ~ REFERENCES ~ NOTES

Module fft_mod

Contact:  Bruce Wyman
Reviewers: 
Change History: WebCVS Log

OVERVIEW

Performs simultaneous fast Fourier transforms (FFTs) between real grid space and complex Fourier space.

This routine computes multiple 1-dimensional FFTs and inverse FFTs. There are 2d and 3d versions between type real grid point space and type complex Fourier space. There are single (32-bit) and full (64-bit) versions.

On Cray and SGI systems, vendor-specific scientific library routines are used, otherwise a user may choose a NAG library version or stand-alone version using Temperton's FFT.

OTHER MODULES USED

platform_mod
     fms_mod
   fft99_mod

PUBLIC INTERFACE

fft_grid_to_fourier:
Given multiple sequences of real data values, this routine computes the complex Fourier transform for all sequences.
fft_fourier_to_grid:
Given multiple sequences of Fourier space transforms, this routine computes the inverse transform and returns the real data values for all sequences.
fft_init:
This routine must be called to initialize the size of a single transform and setup trigonometric constants.
fft_end:
This routine is called to unset the transform size and deallocate memory.

PUBLIC DATA

None.

PUBLIC ROUTINES

  1. fft_grid_to_fourier

    fourier = fft_grid_to_fourier ( grid )
    DESCRIPTION
    Given multiple sequences of real data values, this routine computes the complex Fourier transform for all sequences.


    INPUT
    grid    Multiple sequence of real data values. The first dimension must be n+1 (where n is the size of a single sequence).
       [real(R4_KIND), dimension(:,:)]
       [real(R8_KIND), dimension(:,:)]
       [real(R4_KIND), dimension(:,:,:)]
       [real(R8_KIND), dimension(:,:,:)]

    OUTPUT
    fourier    Multiple sequences of transformed data in complex Fourier space. The first dimension must equal n/2+1 (where n is the size of a single sequence). The remaining dimensions must be the same size as the input argument "grid".
       [complex(R4_KIND), dimension(lenc,size(grid,2))]
       [complex(R8_KIND), dimension(lenc,size(grid,2))]
       [complex(R4_KIND), dimension(lenc,size(grid,2),size(grid,3))]
       [complex(R8_KIND), dimension(lenc,size(grid,2),size(grid,3))]

    NOTE
    The complex Fourier components are passed in the following format. 
            fourier (1)     = cmplx ( a(0), b(0) )
        fourier (2)     = cmplx ( a(1), b(1) )
            :              :
            :              :
        fourier (n/2+1) = cmplx ( a(n/2), b(n/2) )
    where n = length of each real transform


  2. fft_fourier_to_grid

    grid = fft_fourier_to_grid ( fourier )
    DESCRIPTION
    Given multiple sequences of Fourier space transforms, this routine computes the inverse transform and returns the real data values for all sequences.


    INPUT
    fourier    Multiple sequence complex Fourier space transforms. The first dimension must equal n/2+1 (where n is the size of a single real data sequence).
       [real(R4_KIND), dimension(:,:)]
       [real(R8_KIND), dimension(:,:)]
       [real(R4_KIND), dimension(:,:,:)]
       [real(R8_KIND), dimension(:,:,:)]

    OUTPUT
    grid    Multiple sequence of real data values. The first dimension must be n+1 (where n is the size of a single sequence). The remaining dimensions must be the same size as the input argument "fourier".
       [complex(R4_KIND), dimension(leng1,size(fourier,2))]
       [complex(R8_KIND), dimension(leng1,size(fourier,2))]
       [complex(R4_KIND), dimension(leng1,size(fourier,2),size(fourier,3))]
       [complex(R8_KIND), dimension(leng1,size(fourier,2),size(fourier,3))]

  3. fft_init

    call fft_init ( n )
    DESCRIPTION
    This routine must be called once to initialize the size of a single transform. To change the size of the transform the routine fft_exit must be called before re-initialing with fft_init.


    INPUT
    n    The number of real values in a single sequence of data. The resulting transformed data will have n/2+1 pairs of complex values.
       [integer]

  4. fft_end

    call fft_end
    DESCRIPTION
    This routine is called to unset the transform size and deallocate memory. It can not be called unless fft_init has already been called. There are no arguments.


DATA SETS

None.

ERROR MESSAGES

Error in fft_grid_to_fourier
fft_init must be called
The initialization routine fft_init must be called before routines fft_grid_to_fourier.
Error in fft_grid_to_fourier
size of first dimension of input data is wrong
The real grid point field must have a first dimension equal to n+1 (where n is the size of each real transform). This message occurs when using the SGI/Cray fft.
Error in fft_grid_to_fourier
length of input data too small
The real grid point field must have a first dimension equal to n (where n is the size of each real transform). This message occurs when using the NAG or Temperton fft.
Error in fft_grid_to_fourier
float kind not supported for nag fft
32-bit real data is not supported when using the NAG fft. You may try modifying this part of the code by uncommenting the calls to the NAG library or less consider using the Temperton fft.
Error in fft_fourier_to_grid
fft_init must be called
The initialization routine fft_init must be called before routines fft_fourier_to_grid.
Error in fft_fourier_to_grid
size of first dimension of input data is wrong
The complex Fourier field must have a first dimension equal to n/2+1 (where n is the size of each real transform). This message occurs when using the SGI/Cray fft.
Error in fft_fourier_to_grid
length of input data too small
The complex Fourier field must have a first dimension greater than or equal to n/2+1 (where n is the size of each real transform). This message occurs when using the NAG or Temperton fft.
Error in fft_fourier_to_grid
float kind not supported for nag fft
float kind not supported for nag fft 32-bit real data is not supported when using the NAG fft. You may try modifying this part of the code by uncommenting the calls to the NAG library or less consider using the Temperton fft.
FATAL in fft_init
attempted to reinitialize fft
You must call fft_exit before calling fft_init for a second time.
Error in fft_end
attempt to un-initialize fft that has not been initialized
You can not call fft_end unless fft_init has been called.

REFERENCES

  1. For the SGI/Cray version refer to the manual pages for DZFFTM, ZDFFTM, SCFFTM, and CSFFTM.
  2. For the NAG version refer to the NAG documentation for routines C06FPF, C06FQF, and C06GQF.

COMPILER SPECIFICS

None.

PRECOMPILER OPTIONS

-D NAGFFT
-D NAGFFT On non-Cray/SGI machines, set to use the NAG library FFT routines. Otherwise the Temperton FFT is used by default.
-D test_fft
Provides source code for a simple test program. The program generates several sequences of real data. This data is transformed to Fourier space and back to real data, then compared to the original real data.

LOADER OPTIONS

On SGI machines the scientific library needs to be loaded by linking with: 

        -lscs

If using the NAG library, the following loader options (or something similar) may be necessary: 

        -L/usr/local/lib -lnag

TEST PROGRAM

None.

KNOWN BUGS

None.

NOTES

The routines are overloaded for 2d and 3d versions. The 2d versions copy data into 3d arrays then calls the 3d interface.

On SGI/Cray machines:

There are single (32-bit) and full (64-bit) versions. For Cray machines the single precision version does not apply.

On non-SGI/CRAY machines:

The NAG library option uses the "full" precision NAG routines (C06FPF,C06FQF,C06GQF). Users may have to specify a 64-bit real compiler option (e.g., -r8).

The stand-alone Temperton FFT option works for the real precision specified at compile time. If you compiled with single (32-bit) real precision then FFT's cannot be computed at full (64-bit) precision.

FUTURE PLANS

None.

top