1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19 """
20 Python bindings to the FFTW library.
21
22 Usage:
23
24 In order to use PyFFTW you should have a basic understanding of the
25 FFTW3 interface. For documentation about FFTW3 go to http://www.fftw.org
26 In order to achieve maximum performance FFTW3 requires a planning stage
27 where the actual FFT is created from an input and output array.
28 To perform the FFT between the input and output array the plan is then
29 executed. This interface is therefore significantly different from the
30 traditional A = fft(B) interface.
31 In contrast to the C-library PyFFTW utilizes the Plan class for planning.
32 To create a fftw plan one creates a Plan object using an input and output
33 array, and possible parameters. PyFFTW determines from the input and output
34 arrays the correct plan to create. To perform the FFT one can either
35 call the Plan directly or call the method execute() or pass the plan
36 to the execute function.
37
38
39 Example:
40 --------
41
42 #create arrays
43 >>>inputa = numpy.zeros((1024,3), dtype=complex)
44 >>>outputa = numpy.zeros((1024,3), dtype=complex)
45
46 # create a forward and backward fft plan
47 >>>fft = fftw3.Plan(inputa,outputa, direction='forward', flags=['measure'])
48 >>>ifft = fftw3.Plan(outputa, inputa, direction='backward', flags=['measure'])
49
50 #initialize the input array
51 >>>inputa[:] = 0
52 >>>inputa += exp(-x**2/2)
53
54 #perform a forward transformation
55 >>>fft() # alternatively fft.execute() or fftw.execute(fft)
56
57 # do some calculations with the output array
58 >>>outputa *= D
59
60 #perform a backward transformation
61 >>>ifft()
62
63 The planning functions expect aligned, contiguous input arrays of
64 any shape.
65 Currently strides are not implemented. The dtype has to either be complex
66 or double. If you want to perform ffts on single or longdouble precision
67 arrays use the appropriate fftw3f or fftw3l module. FFTW overwrites the
68 arrays in the planning process, thus, if you use planning strategies
69 other than 'estimate' the arrays are going to be overwritten and have to
70 be reinitialized.
71
72 *IMPORTANT*
73 -----------
74
75 Because the plan uses pointers to the data of the arrays you cannot
76 perform operations on the arrays that change the data pointer. Therefore
77
78 >>>a = zeros(1024, dtype=complex)
79 >>>p = plan(a,b)
80 >>>a = a+10
81 >>>p()
82
83 does not work, i.e. the a object references different memory, however
84 the Fourier transform will be performed on the original memory (the
85 plan actually contains a reference to the orgininal data (p.inarray),
86 otherwise this operation could even result in a python segfault).
87
88 Aligned memory:
89 ---------------
90
91 On many platforms using the SIMD units for part of the floating point
92 arithmetic significantly improves performance. FFTW can make use of the
93 SIMD operations, however the arrays have to be specifically aligned
94 in memory. PyFFTW provides a function which creates an numpy array
95 which is aligned to
96 a specified boundary. In most circumstances the default alignment to 16
97 byte boundary is what you want. Note that the same precautions as above
98 apply, i.e. creating an aligned array and then doing something like
99 a=a+1 will result in new memory allocated by python which might not
100 be aligned.
101
102 PyFFTW interface naming conventions:
103 ------------------------------------
104
105 All exposed fftw-functions do have the same names as the C-functions with the
106 leading fftw_ striped from the name.
107 Direct access to the C-functions is available by importing lib.lib, the usual
108 precautions for using C-functions from Python apply.
109
110 Advanced and Guru interface:
111 ----------------------------
112
113 Currently only the execute_dft function from the fftw guru and advanced
114 interface is exposed.
115 It is explicitly name guru_execute_dft. You should only use
116 these if you know what you're doing, as no checking is done on these functions.
117
118
119
120 Constants:
121
122 fftw_flags -- dictionary of possible flags for creating plans
123 fft_direction -- the direction of the fft (see the fftw documentation
124 for the mathematical meaning).
125 realfft_type -- a dictionary of possible types for real-to-real
126 transforms (see the fftw documentation for a
127 more detailed description).
128 """
129 __all__ = ["export_wisdom_to_file", "export_wisdom_to_string",
130 "import_wisdom_from_string", "import_wisdom_from_file",
131 "import_system_wisdom", "forget_wisdom", "AlignedArray",
132 "create_aligned_array", "execute", "guru_execute_dft",
133 "destroy_plan", "Plan", "fftw_flags", "fft_direction",
134 "realfft_type"]
135 from wisdom import export_wisdom_to_file, export_wisdom_to_string,\
136 import_wisdom_from_string, import_wisdom_from_file, \
137 import_system_wisdom, forget_wisdom
138
139 from planning import create_aligned_array,\
140 execute, guru_execute_dft, destroy_plan,\
141 Plan, fftw_flags, fft_direction, realfft_type, \
142 print_plan, fprint_plan
143