FFTW
for version 3.3.3, 25 November 2012
Matteo Frigo
Steven G. Johnson
This manual is for FFTW (version 3.3.3, 25 November 2012).
Copyright
c
2003 Matteo Frigo.
Copyright
c
2003 Massachusetts Institute of Technology.
Permission is granted to make and distribute verbatim copies of this manual
provided the copyright notice and this permission notice are preserved on all
copies.
Permission is granted to copy and distribute modified versions of this manual
under the conditions for verbatim copying, provided that the entire resulting
derived work is distributed under the terms of a permission notice identical to
this one.
Permission is granted to copy and distribute translations of this manual into
another language, under the above conditions for modified versions, except
that this permission notice may be stated in a translation approved by the Free
Software Foundation.
i
Table of Contents
1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2 Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1 Complex One-Dimensional DFTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2 Complex Multi-Dimensional DFTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3 One-Dimensional DFTs of Real Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.4 Multi-Dimensional DFTs of Real Data. . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.5 More DFTs of Real Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.5.1 The Halfcomplex-format DFT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.5.2 Real even/odd DFTs (cosine/sine transforms) . . . . . . . . . . . . 11
2.5.3 The Discrete Hartley Transform . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3 Other Important Topics. . . . . . . . . . . . . . . . . . . . . . . 15
3.1 SIMD alignment and fftw malloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.2 Multi-dimensional Array Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.2.1 Row-major Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.2.2 Column-major Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.2.3 Fixed-size Arrays in C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.2.4 Dynamic Arrays in C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2.5 Dynamic Arrays in C—The Wrong Way . . . . . . . . . . . . . . . . . . 17
3.3 Words of Wisdom—Saving Plans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.4 Caveats in Using Wisdom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4 FFTW Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.1 Data Types and Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.1.1 Complex numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.1.2 Precision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.1.3 Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.2 Using Plans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.3 Basic Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.3.1 Complex DFTs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.3.2 Planner Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.3.3 Real-data DFTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.3.4 Real-data DFT Array Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.3.5 Real-to-Real Transforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.3.6 Real-to-Real Transform Kinds . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.4 Advanced Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.4.1 Advanced Complex DFTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.4.2 Advanced Real-data DFTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.4.3 Advanced Real-to-real Transforms . . . . . . . . . . . . . . . . . . . . . . . . 33
4.5 Guru Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.5.1 Interleaved and split arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
ii FFTW 3.3.3
4.5.2 Guru vector and transform sizes . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.5.3 Guru Complex DFTs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.5.4 Guru Real-data DFTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.5.5 Guru Real-to-real Transforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.5.6 64-bit Guru Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.6 New-array Execute Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
4.7 Wisdom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.7.1 Wisdom Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.7.2 Wisdom Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.7.3 Forgetting Wisdom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.7.4 Wisdom Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.8 What FFTW Really Computes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.8.1 The 1d Discrete Fourier Transform (DFT) . . . . . . . . . . . . . . . . 42
4.8.2 The 1d Real-data DFT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.8.3 1d Real-even DFTs (DCTs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.8.4 1d Real-odd DFTs (DSTs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.8.5 1d Discrete Hartley Transforms (DHTs) . . . . . . . . . . . . . . . . . . 45
4.8.6 Multi-dimensional Transforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5 Multi-threaded FFTW . . . . . . . . . . . . . . . . . . . . . . . . 49
5.1 Installation and Supported Hardware/Software . . . . . . . . . . . . . . . . 49
5.2 Usage of Multi-threaded FFTW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
5.3 How Many Threads to Use? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
5.4 Thread safety . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
6 Distributed-memory FFTW with MPI . . . . . . 53
6.1 FFTW MPI Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
6.2 Linking and Initializing MPI FFTW. . . . . . . . . . . . . . . . . . . . . . . . . . . 54
6.3 2d MPI example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
6.4 MPI Data Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
6.4.1 Basic and advanced distribution interfaces . . . . . . . . . . . . . . . . 56
6.4.2 Load balancing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
6.4.3 Transposed distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
6.4.4 One-dimensional distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.5 Multi-dimensional MPI DFTs of Real Data . . . . . . . . . . . . . . . . . . . . 60
6.6 Other multi-dimensional Real-Data MPI Transforms . . . . . . . . . . . 62
6.7 FFTW MPI Transposes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
6.7.1 Basic distributed-transpose interface . . . . . . . . . . . . . . . . . . . . . . 63
6.7.2 Advanced distributed-transpose interface . . . . . . . . . . . . . . . . . 63
6.7.3 An improved replacement for MPI Alltoall . . . . . . . . . . . . . . . 64
6.8 FFTW MPI Wisdom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6.9 Avoiding MPI Deadlocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
6.10 FFTW MPI Performance Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
6.11 Combining MPI and Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
6.12 FFTW MPI Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
6.12.1 MPI Files and Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
6.12.2 MPI Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.12.3 Using MPI Plans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
iii
6.12.4 MPI Data Distribution Functions. . . . . . . . . . . . . . . . . . . . . . . . 69
6.12.5 MPI Plan Creation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
6.12.6 MPI Wisdom Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
6.13 FFTW MPI Fortran Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
7 Calling FFTW from Modern Fortran . . . . . . . . 77
7.1 Overview of Fortran interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
7.1.1 Extended and quadruple precision in Fortran . . . . . . . . . . . . . 78
7.2 Reversing array dimensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
7.3 FFTW Fortran type reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
7.4 Plan execution in Fortran . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
7.5 Allocating aligned memory in Fortran . . . . . . . . . . . . . . . . . . . . . . . . . 82
7.6 Accessing the wisdom API from Fortran . . . . . . . . . . . . . . . . . . . . . . . 83
7.6.1 Wisdom File Export/Import from Fortran . . . . . . . . . . . . . . . . 83
7.6.2 Wisdom String Export/Import from Fortran . . . . . . . . . . . . . . 84
7.6.3 Wisdom Generic Export/Import from Fortran . . . . . . . . . . . . 84
7.7 Defining an FFTW module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
8 Calling FFTW from Legacy Fortran . . . . . . . . . 87
8.1 Fortran-interface routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
8.2 FFTW Constants in Fortran . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
8.3 FFTW Execution in Fortran . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
8.4 Fortran Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
8.5 Wisdom of Fortran?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
9 Upgrading from FFTW version 2 . . . . . . . . . . . . 93
10 Installation and Customization . . . . . . . . . . . . . 97
10.1 Installation on Unix. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
10.2 Installation on non-Unix systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
10.3 Cycle Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
10.4 Generating your own code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
11 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
12 License and Copyright. . . . . . . . . . . . . . . . . . . . . . 105
13 Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
14 Library Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
