cannam@127: @node Introduction, Tutorial, Top, Top cannam@127: @chapter Introduction cannam@127: This manual documents version @value{VERSION} of FFTW, the cannam@127: @emph{Fastest Fourier Transform in the West}. FFTW is a comprehensive cannam@127: collection of fast C routines for computing the discrete Fourier cannam@127: transform (DFT) and various special cases thereof. cannam@127: @cindex discrete Fourier transform cannam@127: @cindex DFT cannam@127: @itemize @bullet cannam@127: @item FFTW computes the DFT of complex data, real data, even- cannam@127: or odd-symmetric real data (these symmetric transforms are usually cannam@127: known as the discrete cosine or sine transform, respectively), and the cannam@127: discrete Hartley transform (DHT) of real data. cannam@127: cannam@127: @item The input data can have arbitrary length. cannam@127: FFTW employs @Onlogn{} algorithms for all lengths, including cannam@127: prime numbers. cannam@127: cannam@127: @item FFTW supports arbitrary multi-dimensional data. cannam@127: cannam@127: @item FFTW supports the SSE, SSE2, AVX, AVX2, AVX512, KCVI, Altivec, VSX, and cannam@127: NEON vector instruction sets. cannam@127: cannam@127: @item FFTW includes parallel (multi-threaded) transforms cannam@127: for shared-memory systems. cannam@127: @item Starting with version 3.3, FFTW includes distributed-memory parallel cannam@127: transforms using MPI. cannam@127: @end itemize cannam@127: cannam@127: We assume herein that you are familiar with the properties and uses of cannam@127: the DFT that are relevant to your application. Otherwise, see cannam@127: e.g. @cite{The Fast Fourier Transform and Its Applications} by E. O. Brigham cannam@127: (Prentice-Hall, Englewood Cliffs, NJ, 1988). cannam@127: @uref{http://www.fftw.org, Our web page} also has links to FFT-related cannam@127: information online. cannam@127: @cindex FFTW cannam@127: cannam@127: @c TODO: revise. We don't need to brag any longer cannam@127: @c cannam@127: @c FFTW is usually faster (and sometimes much faster) than all other cannam@127: @c freely-available Fourier transform programs found on the Net. It is cannam@127: @c competitive with (and often faster than) the FFT codes in Sun's cannam@127: @c Performance Library, IBM's ESSL library, HP's CXML library, and cannam@127: @c Intel's MKL library, which are targeted at specific machines. cannam@127: @c Moreover, FFTW's performance is @emph{portable}. Indeed, FFTW is cannam@127: @c unique in that it automatically adapts itself to your machine, your cannam@127: @c cache, the size of your memory, your number of registers, and all the cannam@127: @c other factors that normally make it impossible to optimize a program cannam@127: @c for more than one machine. An extensive comparison of FFTW's cannam@127: @c performance with that of other Fourier transform codes has been made, cannam@127: @c and the results are available on the Web at cannam@127: @c @uref{http://fftw.org/benchfft, the benchFFT home page}. cannam@127: @c @cindex benchmark cannam@127: @c @fpindex benchfft cannam@127: cannam@127: In order to use FFTW effectively, you need to learn one basic concept cannam@127: of FFTW's internal structure: FFTW does not use a fixed algorithm for cannam@127: computing the transform, but instead it adapts the DFT algorithm to cannam@127: details of the underlying hardware in order to maximize performance. cannam@127: Hence, the computation of the transform is split into two phases. cannam@127: First, FFTW's @dfn{planner} ``learns'' the fastest way to compute the cannam@127: transform on your machine. The planner cannam@127: @cindex planner cannam@127: produces a data structure called a @dfn{plan} that contains this cannam@127: @cindex plan cannam@127: information. Subsequently, the plan is @dfn{executed} cannam@127: @cindex execute cannam@127: to transform the array of input data as dictated by the plan. The cannam@127: plan can be reused as many times as needed. In typical cannam@127: high-performance applications, many transforms of the same size are cannam@127: computed and, consequently, a relatively expensive initialization of cannam@127: this sort is acceptable. On the other hand, if you need a single cannam@127: transform of a given size, the one-time cost of the planner becomes cannam@127: significant. For this case, FFTW provides fast planners based on cannam@127: heuristics or on previously computed plans. cannam@127: cannam@127: FFTW supports transforms of data with arbitrary length, rank, cannam@127: multiplicity, and a general memory layout. In simple cases, however, cannam@127: this generality may be unnecessary and confusing. Consequently, we cannam@127: organized the interface to FFTW into three levels of increasing cannam@127: generality. cannam@127: @itemize @bullet cannam@127: @item The @dfn{basic interface} computes a single cannam@127: transform of contiguous data. cannam@127: @item The @dfn{advanced interface} computes transforms cannam@127: of multiple or strided arrays. cannam@127: @item The @dfn{guru interface} supports the most general data cannam@127: layouts, multiplicities, and strides. cannam@127: @end itemize cannam@127: We expect that most users will be best served by the basic interface, cannam@127: whereas the guru interface requires careful attention to the cannam@127: documentation to avoid problems. cannam@127: @cindex basic interface cannam@127: @cindex advanced interface cannam@127: @cindex guru interface cannam@127: cannam@127: cannam@127: Besides the automatic performance adaptation performed by the planner, cannam@127: it is also possible for advanced users to customize FFTW manually. For cannam@127: example, if code space is a concern, we provide a tool that links only cannam@127: the subset of FFTW needed by your application. Conversely, you may need cannam@127: to extend FFTW because the standard distribution is not sufficient for cannam@127: your needs. For example, the standard FFTW distribution works most cannam@127: efficiently for arrays whose size can be factored into small primes cannam@127: (@math{2}, @math{3}, @math{5}, and @math{7}), and otherwise it uses a cannam@127: slower general-purpose routine. If you need efficient transforms of cannam@127: other sizes, you can use FFTW's code generator, which produces fast C cannam@127: programs (``codelets'') for any particular array size you may care cannam@127: about. cannam@127: @cindex code generator cannam@127: @cindex codelet cannam@127: For example, if you need transforms of size cannam@127: @ifinfo cannam@127: @math{513 = 19 x 3^3}, cannam@127: @end ifinfo cannam@127: @tex cannam@127: $513 = 19 \cdot 3^3$, cannam@127: @end tex cannam@127: @html cannam@127: 513 = 19*33, cannam@127: @end html cannam@127: you can customize FFTW to support the factor @math{19} efficiently. cannam@127: cannam@127: For more information regarding FFTW, see the paper, ``The Design and cannam@127: Implementation of FFTW3,'' by M. Frigo and S. G. Johnson, which was an cannam@127: invited paper in @cite{Proc. IEEE} @b{93} (2), p. 216 (2005). The cannam@127: code generator is described in the paper ``A fast Fourier transform cannam@127: compiler'', cannam@127: @cindex compiler cannam@127: by M. Frigo, in the @cite{Proceedings of the 1999 ACM SIGPLAN Conference cannam@127: on Programming Language Design and Implementation (PLDI), Atlanta, cannam@127: Georgia, May 1999}. These papers, along with the latest version of cannam@127: FFTW, the FAQ, benchmarks, and other links, are available at cannam@127: @uref{http://www.fftw.org, the FFTW home page}. cannam@127: cannam@127: The current version of FFTW incorporates many good ideas from the past cannam@127: thirty years of FFT literature. In one way or another, FFTW uses the cannam@127: Cooley-Tukey algorithm, the prime factor algorithm, Rader's algorithm cannam@127: for prime sizes, and a split-radix algorithm (with a cannam@127: ``conjugate-pair'' variation pointed out to us by Dan Bernstein). cannam@127: FFTW's code generator also produces new algorithms that we do not cannam@127: completely understand. cannam@127: @cindex algorithm cannam@127: The reader is referred to the cited papers for the appropriate cannam@127: references. cannam@127: cannam@127: The rest of this manual is organized as follows. We first discuss the cannam@127: sequential (single-processor) implementation. We start by describing cannam@127: the basic interface/features of FFTW in @ref{Tutorial}. cannam@127: Next, @ref{Other Important Topics} discusses data alignment cannam@127: (@pxref{SIMD alignment and fftw_malloc}), cannam@127: the storage scheme of multi-dimensional arrays cannam@127: (@pxref{Multi-dimensional Array Format}), and FFTW's mechanism for cannam@127: storing plans on disk (@pxref{Words of Wisdom-Saving Plans}). Next, cannam@127: @ref{FFTW Reference} provides comprehensive documentation of all cannam@127: FFTW's features. Parallel transforms are discussed in their own cannam@127: chapters: @ref{Multi-threaded FFTW} and @ref{Distributed-memory FFTW cannam@127: with MPI}. Fortran programmers can also use FFTW, as described in cannam@127: @ref{Calling FFTW from Legacy Fortran} and @ref{Calling FFTW from cannam@127: Modern Fortran}. @ref{Installation and Customization} explains how to cannam@127: install FFTW in your computer system and how to adapt FFTW to your cannam@127: needs. License and copyright information is given in @ref{License and cannam@127: Copyright}. Finally, we thank all the people who helped us in cannam@127: @ref{Acknowledgments}. cannam@127: