IMOD Library libifft

The IMOD library libifft contains functions for performing 1-D, 2-D, and 3-D Fourier transforms, callable from C or Fortran. If IMOD is built with FFTW libraries, then the routines here are mostly wrappers to calls to FFTW, with some logic to handle thread number. Otherwise, the librayr contains FFT routines written by Lynn Ten Eyck, and wrapper routines written by David Agard, which were translated from Fortran to C by David Mastronarde.

In these routines, all dimensions being transformed must be even and their largest prime factors must be no larger than 19. All transforms are done in place and a normalization is applied in each case. The X dimension of the array must always be dimensioned to 2 more than the dimension of the real space image to allow space for an extra column of complex numbers. The sizes passed to the routines are always the real-space image sizes. Thus, in Fortran, an array would be dimensioned as:

     real*4 array(nx+2, ny)
or:
     complex array((nx+2)/2, ny)

There are no separate Fortran wrappers for these routines; their names are defined so that they can be called directly from Fortran. From C, include "cfft.h" to have the function name defined with an underscore on Unix-type systems and with capital letters on Windows. Pass all arguments by reference (as pointers), or use the odfftc, todfftc, and thrdfftc functions calls.

All functions exit with an error message to standard out if the image size is not allowed or the direction parameter is incorrect.

Header to include: cfft.h


void odfft(float *array, int *nxp, int *nyp, int *idirp)
void odfftc(float *array, int nx, int ny, int idir)
int usingFFTW(void)
int niceFFTlimit(void)
void cleanupFFTplans(void)
void todfft(float *array, int *nxp, int *nyp, int *idirp)
void todfftc(float *array, int nx, int ny, int idir)
void parallelTodfft(float *array, int nx, int ny, int idir, int numImages, int numThreads)
void thrdfft(float *array, float *brray, int *nxp, int *nyp, int *nzp, int *idirp)
void thrdfftc(float *array, float *brray, int nx, int ny, int nz, int idir)

void odfft(float *array, int *nxp, int *nyp, int *idirp)

Performs nyp 1-D FFT'S in place.  For real to complex or complex to real transforms, the data are organized as nyp lines of data of length nxp in the real space image, which must be contained in a float array whose X dimension is nxp + 2.  For complex to complex transforms, nxp is the number of complex elements in X, and the data must be in an array whose X dimension is 2 * nxp. The origin of the transform is at the first point on each line.  The direction of the transform is determined by idirp:
0 Forward  (Real --> Complex)     exp(-2PIirs)
1 Reverse  (Complex --> Real)     exp(+2PIirs)
-1 Forward  (Complex --> Complex)  exp(-2PIirs)
-2 Reverse  (Complex --> Complex)  exp(+2PIirs)
For Real/complex or Complex/real, only the unique portion of the transform is written to the array (positive frequencies).  For Complex/complex, the entire transform is written.  
Can be called from either C or Fortran by this name.

void odfftc(float *array, int nx, int ny, int idir)

Function to call odfft from C with arguments passed by value

int usingFFTW(void)

Returns 1 if FFTW is being used, 2 if Intel MKL is being used, or 0 if IMOD FFT library is being used

int niceFFTlimit(void)

Returns the highest desirable prime factor, 13 for FFTW/MKL and 5 for IMOD FFTs. For IMOD FFTs, the highest allowed prime factor is 19.

void cleanupFFTplans(void)

Destroys all plans for FFTs that have been saved in a ring buffer

void todfft(float *array, int *nxp, int *nyp, int *idirp)

Performs a two-dimensional FFT in place in array.  The data are organized as nyp rows of nxp values in the real space image, which must be contained in a float array whose X dimension is nxp + 2.  The direction of the transform is determined by idirp:
0        forward  transform :  exp(-2PIirs)
1 or -1  inverse transform  :  exp(+2PIirs)
The origin of the transform is at the first point.  The Y coordinate of the transform progresses from Y = 0 on the first line, to Y = (nyp - 1 ) / 2 on the middle line, then from -nyp / 2 on the next line up, to -1 on the last line.  
Can be called from either C or Fortran by this name.

void todfftc(float *array, int nx, int ny, int idir)

Function to call todfft from C with arguments passed by value

void parallelTodfft(float *array, int nx, int ny, int idir, int numImages, int numThreads)

Computes numImages 2-D FFTs in numThreads parallel threads from a stack of contiguous images in array, with real-space size nx, ny, padded by 2 floats as usual, in direction idir.  This function can be used only with Intel FFTs, which appear to be thread-safe.  It will exit with an error message otherwise; FFTW was found not to work and IMOD FFT's were not tested.  Test whether usingFFTW returns 2 before calling this routine.

void thrdfft(float *array, float *brray, int *nxp, int *nyp, int *nzp, int *idirp)

Performs a three-dimensional FFT in place on data in array. Data are organized as nzp slices each consisting of nyp rows of nxp values in the real-space image, which must be contained in a float array whose X dimension is nxp + 2.  brray is for working storage and must be dimensioned to at least (nxp + 2) * nzp when using IMOD FFT routines but is not needed with FFTW.  The direction of the transform is determined by idirp:
0         forward transform
1 or -1   inverse transform
The origin of the transform is at the first point.  The Y coordinate of the transform progresses from Y = 0 on the first line, to Y = (nyp - 1) / 2 on the middle line, then from -nyp / 2 on the next line up, to -1 on the last line.  Similarly the Z coordinate progresses from Z = 0 on the first slice to Z = (nzp - 1) / 2, then from -nzp / 2 to -1.  
Can be called from either C or Fortran by this name.

void thrdfftc(float *array, float *brray, int nx, int ny, int nz, int idir)

Function to call thrdfft from C with arguments passed by value