README
1KISS FFT - A mixed-radix Fast Fourier Transform based up on the principle,
2"Keep It Simple, Stupid."
3
4 There are many great fft libraries already around. Kiss FFT is not trying
5to be better than any of them. It only attempts to be a reasonably efficient,
6moderately useful FFT that can use fixed or floating data types and can be
7incorporated into someone's C program in a few minutes with trivial licensing.
8
9USAGE:
10
11 The basic usage for 1-d complex FFT is:
12
13 #include "kiss_fft.h"
14
15 kiss_fft_cfg cfg = kiss_fft_alloc( nfft ,is_inverse_fft ,0,0 );
16
17 while ...
18
19 ... // put kth sample in cx_in[k].r and cx_in[k].i
20
21 kiss_fft( cfg , cx_in , cx_out );
22
23 ... // transformed. DC is in cx_out[0].r and cx_out[0].i
24
25 free(cfg);
26
27 Note: frequency-domain data is stored from dc up to 2pi.
28 so cx_out[0] is the dc bin of the FFT
29 and cx_out[nfft/2] is the Nyquist bin (if exists)
30
31 Declarations are in "kiss_fft.h", along with a brief description of the
32functions you'll need to use.
33
34Code definitions for 1d complex FFTs are in kiss_fft.c.
35
36You can do other cool stuff with the extras you'll find in tools/
37
38 * multi-dimensional FFTs
39 * real-optimized FFTs (returns the positive half-spectrum: (nfft/2+1) complex frequency bins)
40 * fast convolution FIR filtering (not available for fixed point)
41 * spectrum image creation
42
43The core fft and most tools/ code can be compiled to use float, double,
44 Q15 short or Q31 samples. The default is float.
45
46
47BACKGROUND:
48
49 I started coding this because I couldn't find a fixed point FFT that didn't
50use assembly code. I started with floating point numbers so I could get the
51theory straight before working on fixed point issues. In the end, I had a
52little bit of code that could be recompiled easily to do ffts with short, float
53or double (other types should be easy too).
54
55 Once I got my FFT working, I was curious about the speed compared to
56a well respected and highly optimized fft library. I don't want to criticize
57this great library, so let's call it FFT_BRANDX.
58During this process, I learned:
59
60 1. FFT_BRANDX has more than 100K lines of code. The core of kiss_fft is about 500 lines (cpx 1-d).
61 2. It took me an embarrassingly long time to get FFT_BRANDX working.
62 3. A simple program using FFT_BRANDX is 522KB. A similar program using kiss_fft is 18KB (without optimizing for size).
63 4. FFT_BRANDX is roughly twice as fast as KISS FFT in default mode.
64
65 It is wonderful that free, highly optimized libraries like FFT_BRANDX exist.
66But such libraries carry a huge burden of complexity necessary to extract every
67last bit of performance.
68
69 Sometimes simpler is better, even if it's not better.
70
71FREQUENTLY ASKED QUESTIONS:
72 Q: Can I use kissfft in a project with a ___ license?
73 A: Yes. See LICENSE below.
74
75 Q: Why don't I get the output I expect?
76 A: The two most common causes of this are
77 1) scaling : is there a constant multiplier between what you got and what you want?
78 2) mixed build environment -- all code must be compiled with same preprocessor
79 definitions for FIXED_POINT and kiss_fft_scalar
80
81 Q: Will you write/debug my code for me?
82 A: Probably not unless you pay me. I am happy to answer pointed and topical questions, but
83 I may refer you to a book, a forum, or some other resource.
84
85
86PERFORMANCE:
87 (on Athlon XP 2100+, with gcc 2.96, float data type)
88
89 Kiss performed 10000 1024-pt cpx ffts in .63 s of cpu time.
90 For comparison, it took md5sum twice as long to process the same amount of data.
91
92 Transforming 5 minutes of CD quality audio takes less than a second (nfft=1024).
93
94DO NOT:
95 ... use Kiss if you need the Fastest Fourier Transform in the World
96 ... ask me to add features that will bloat the code
97
98UNDER THE HOOD:
99
100 Kiss FFT uses a time decimation, mixed-radix, out-of-place FFT. If you give it an input buffer
101 and output buffer that are the same, a temporary buffer will be created to hold the data.
102
103 No static data is used. The core routines of kiss_fft are thread-safe (but not all of the tools directory).
104
105 No scaling is done for the floating point version (for speed).
106 Scaling is done both ways for the fixed-point version (for overflow prevention).
107
108 Optimized butterflies are used for factors 2,3,4, and 5.
109
110 The real (i.e. not complex) optimization code only works for even length ffts. It does two half-length
111 FFTs in parallel (packed into real&imag), and then combines them via twiddling. The result is
112 nfft/2+1 complex frequency bins from DC to Nyquist. If you don't know what this means, search the web.
113
114 The fast convolution filtering uses the overlap-scrap method, slightly
115 modified to put the scrap at the tail.
116
117LICENSE:
118 Revised BSD License, see COPYING for verbiage.
119 Basically, "free to use&change, give credit where due, no guarantees"
120 Note this license is compatible with GPL at one end of the spectrum and closed, commercial software at
121 the other end. See http://www.fsf.org/licensing/licenses
122
123 A commercial license is available which removes the requirement for attribution. Contact me for details.
124
125
126TODO:
127 *) Add real optimization for odd length FFTs
128 *) Document/revisit the input/output fft scaling
129 *) Make doc describing the overlap (tail) scrap fast convolution filtering in kiss_fastfir.c
130 *) Test all the ./tools/ code with fixed point (kiss_fastfir.c doesn't work, maybe others)
131
132AUTHOR:
133 Mark Borgerding
134 Mark@Borgerding.net
135
README.simd
1If you are reading this, it means you think you may be interested in using the SIMD extensions in kissfft
2to do 4 *separate* FFTs at once.
3
4Beware! Beyond here there be dragons!
5
6This API is not easy to use, is not well documented, and breaks the KISS principle.
7
8
9Still reading? Okay, you may get rewarded for your patience with a considerable speedup
10(2-3x) on intel x86 machines with SSE if you are willing to jump through some hoops.
11
12The basic idea is to use the packed 4 float __m128 data type as a scalar element.
13This means that the format is pretty convoluted. It performs 4 FFTs per fft call on signals A,B,C,D.
14
15For complex data, the data is interlaced as follows:
16rA0,rB0,rC0,rD0, iA0,iB0,iC0,iD0, rA1,rB1,rC1,rD1, iA1,iB1,iC1,iD1 ...
17where "rA0" is the real part of the zeroth sample for signal A
18
19Real-only data is laid out:
20rA0,rB0,rC0,rD0, rA1,rB1,rC1,rD1, ...
21
22Compile with gcc flags something like
23-O3 -mpreferred-stack-boundary=4 -DUSE_SIMD=1 -msse
24
25Be aware of SIMD alignment. This is the most likely cause of segfaults.
26The code within kissfft uses scratch variables on the stack.
27With SIMD, these must have addresses on 16 byte boundaries.
28Search on "SIMD alignment" for more info.
29
30
31
32Robin at Divide Concept was kind enough to share his code for formatting to/from the SIMD kissfft.
33I have not run it -- use it at your own risk. It appears to do 4xN and Nx4 transpositions
34(out of place).
35
36void SSETools::pack128(float* target, float* source, unsigned long size128)
37{
38 __m128* pDest = (__m128*)target;
39 __m128* pDestEnd = pDest+size128;
40 float* source0=source;
41 float* source1=source0+size128;
42 float* source2=source1+size128;
43 float* source3=source2+size128;
44
45 while(pDest<pDestEnd)
46 {
47 *pDest=_mm_set_ps(*source3,*source2,*source1,*source0);
48 source0++;
49 source1++;
50 source2++;
51 source3++;
52 pDest++;
53 }
54}
55
56void SSETools::unpack128(float* target, float* source, unsigned long size128)
57{
58
59 float* pSrc = source;
60 float* pSrcEnd = pSrc+size128*4;
61 float* target0=target;
62 float* target1=target0+size128;
63 float* target2=target1+size128;
64 float* target3=target2+size128;
65
66 while(pSrc<pSrcEnd)
67 {
68 *target0=pSrc[0];
69 *target1=pSrc[1];
70 *target2=pSrc[2];
71 *target3=pSrc[3];
72 target0++;
73 target1++;
74 target2++;
75 target3++;
76 pSrc+=4;
77 }
78}
79