Mercurial > hg > sv-dependency-builds

comparison src/fftw-3.3.8/doc/html/Reversing-array-dimensions.html @ 167:bd3cc4d1df30

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add FFTW 3.3.8 source, and a Linux build
author Chris Cannam <cannam@all-day-breakfast.com>
date Tue, 19 Nov 2019 14:52:55 +0000
parents
children
comparison
equal deleted inserted replaced
166:cbd6d7e562c7 167:bd3cc4d1df30
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html>
3 <!-- This manual is for FFTW
4 (version 3.3.8, 24 May 2018).
5
6 Copyright (C) 2003 Matteo Frigo.
7
8 Copyright (C) 2003 Massachusetts Institute of Technology.
9
10 Permission is granted to make and distribute verbatim copies of this
11 manual provided the copyright notice and this permission notice are
12 preserved on all copies.
13
14 Permission is granted to copy and distribute modified versions of this
15 manual under the conditions for verbatim copying, provided that the
16 entire resulting derived work is distributed under the terms of a
17 permission notice identical to this one.
18
19 Permission is granted to copy and distribute translations of this manual
20 into another language, under the above conditions for modified versions,
21 except that this permission notice may be stated in a translation
22 approved by the Free Software Foundation. -->
23 <!-- Created by GNU Texinfo 6.3, http://www.gnu.org/software/texinfo/ -->
24 <head>
25 <title>FFTW 3.3.8: Reversing array dimensions</title>
26
27 <meta name="description" content="FFTW 3.3.8: Reversing array dimensions">
28 <meta name="keywords" content="FFTW 3.3.8: Reversing array dimensions">
29 <meta name="resource-type" content="document">
30 <meta name="distribution" content="global">
31 <meta name="Generator" content="makeinfo">
32 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
33 <link href="index.html#Top" rel="start" title="Top">
34 <link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
35 <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
36 <link href="Calling-FFTW-from-Modern-Fortran.html#Calling-FFTW-from-Modern-Fortran" rel="up" title="Calling FFTW from Modern Fortran">
37 <link href="FFTW-Fortran-type-reference.html#FFTW-Fortran-type-reference" rel="next" title="FFTW Fortran type reference">
38 <link href="Extended-and-quadruple-precision-in-Fortran.html#Extended-and-quadruple-precision-in-Fortran" rel="prev" title="Extended and quadruple precision in Fortran">
39 <style type="text/css">
40 <!--
41 a.summary-letter {text-decoration: none}
42 blockquote.indentedblock {margin-right: 0em}
43 blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
44 blockquote.smallquotation {font-size: smaller}
45 div.display {margin-left: 3.2em}
46 div.example {margin-left: 3.2em}
47 div.lisp {margin-left: 3.2em}
48 div.smalldisplay {margin-left: 3.2em}
49 div.smallexample {margin-left: 3.2em}
50 div.smalllisp {margin-left: 3.2em}
51 kbd {font-style: oblique}
52 pre.display {font-family: inherit}
53 pre.format {font-family: inherit}
54 pre.menu-comment {font-family: serif}
55 pre.menu-preformatted {font-family: serif}
56 pre.smalldisplay {font-family: inherit; font-size: smaller}
57 pre.smallexample {font-size: smaller}
58 pre.smallformat {font-family: inherit; font-size: smaller}
59 pre.smalllisp {font-size: smaller}
60 span.nolinebreak {white-space: nowrap}
61 span.roman {font-family: initial; font-weight: normal}
62 span.sansserif {font-family: sans-serif; font-weight: normal}
63 ul.no-bullet {list-style: none}
64 -->
65 </style>
66
67
68 </head>
69
70 <body lang="en">
71 <a name="Reversing-array-dimensions"></a>
72 <div class="header">
73 <p>
74 Next: <a href="FFTW-Fortran-type-reference.html#FFTW-Fortran-type-reference" accesskey="n" rel="next">FFTW Fortran type reference</a>, Previous: <a href="Overview-of-Fortran-interface.html#Overview-of-Fortran-interface" accesskey="p" rel="prev">Overview of Fortran interface</a>, Up: <a href="Calling-FFTW-from-Modern-Fortran.html#Calling-FFTW-from-Modern-Fortran" accesskey="u" rel="up">Calling FFTW from Modern Fortran</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
75 </div>
76 <hr>
77 <a name="Reversing-array-dimensions-1"></a>
78 <h3 class="section">7.2 Reversing array dimensions</h3>
79
80 <a name="index-row_002dmajor-6"></a>
81 <a name="index-column_002dmajor-1"></a>
82 <p>A minor annoyance in calling FFTW from Fortran is that FFTW&rsquo;s array
83 dimensions are defined in the C convention (row-major order), while
84 Fortran&rsquo;s array dimensions are the opposite convention (column-major
85 order). See <a href="Multi_002ddimensional-Array-Format.html#Multi_002ddimensional-Array-Format">Multi-dimensional Array Format</a>. This is just a
86 bookkeeping difference, with no effect on performance. The only
87 consequence of this is that, whenever you create an FFTW plan for a
88 multi-dimensional transform, you must always <em>reverse the
89 ordering of the dimensions</em>.
90 </p>
91 <p>For example, consider the three-dimensional (L&nbsp;&times;&nbsp;M&nbsp;&times;&nbsp;N
92 ) arrays:
93 </p>
94 <div class="example">
95 <pre class="example"> complex(C_DOUBLE_COMPLEX), dimension(L,M,N) :: in, out
96 </pre></div>
97
98 <p>To plan a DFT for these arrays using <code>fftw_plan_dft_3d</code>, you could do:
99 </p>
100 <a name="index-fftw_005fplan_005fdft_005f3d-2"></a>
101 <div class="example">
102 <pre class="example"> plan = fftw_plan_dft_3d(N,M,L, in,out, FFTW_FORWARD,FFTW_ESTIMATE)
103 </pre></div>
104
105 <p>That is, from FFTW&rsquo;s perspective this is a N&nbsp;&times;&nbsp;M&nbsp;&times;&nbsp;L
106 array.
107 <em>No data transposition need occur</em>, as this is <em>only
108 notation</em>. Similarly, to use the more generic routine
109 <code>fftw_plan_dft</code> with the same arrays, you could do:
110 </p>
111 <div class="example">
112 <pre class="example"> integer(C_INT), dimension(3) :: n = [N,M,L]
113 plan = fftw_plan_dft_3d(3, n, in,out, FFTW_FORWARD,FFTW_ESTIMATE)
114 </pre></div>
115
116 <p>Note, by the way, that this is different from the legacy Fortran
117 interface (see <a href="Fortran_002dinterface-routines.html#Fortran_002dinterface-routines">Fortran-interface routines</a>), which automatically
118 reverses the order of the array dimension for you. Here, you are
119 calling the C interface directly, so there is no &ldquo;translation&rdquo; layer.
120 </p>
121 <a name="index-r2c_002fc2r-multi_002ddimensional-array-format-2"></a>
122 <p>An important thing to keep in mind is the implication of this for
123 multidimensional real-to-complex transforms (see <a href="Multi_002dDimensional-DFTs-of-Real-Data.html#Multi_002dDimensional-DFTs-of-Real-Data">Multi-Dimensional DFTs of Real Data</a>). In C, a multidimensional real-to-complex DFT
124 chops the last dimension roughly in half (N&nbsp;&times;&nbsp;M&nbsp;&times;&nbsp;L
125 real input
126 goes to N&nbsp;&times;&nbsp;M&nbsp;&times;&nbsp;L/2+1
127 complex output). In Fortran, because
128 the array dimension notation is reversed, the <em>first</em> dimension of
129 the complex data is chopped roughly in half. For example consider the
130 &lsquo;<samp>r2c</samp>&rsquo; transform of L&nbsp;&times;&nbsp;M&nbsp;&times;&nbsp;N
131 real input in Fortran:
132 </p>
133 <a name="index-fftw_005fplan_005fdft_005fr2c_005f3d-2"></a>
134 <a name="index-fftw_005fexecute_005fdft_005fr2c-1"></a>
135 <div class="example">
136 <pre class="example"> type(C_PTR) :: plan
137 real(C_DOUBLE), dimension(L,M,N) :: in
138 complex(C_DOUBLE_COMPLEX), dimension(L/2+1,M,N) :: out
139 plan = fftw_plan_dft_r2c_3d(N,M,L, in,out, FFTW_ESTIMATE)
140 ...
141 call fftw_execute_dft_r2c(plan, in, out)
142 </pre></div>
143
144 <a name="index-in_002dplace-9"></a>
145 <a name="index-padding-5"></a>
146 <p>Alternatively, for an in-place r2c transform, as described in the C
147 documentation we must <em>pad</em> the <em>first</em> dimension of the
148 real input with an extra two entries (which are ignored by FFTW) so as
149 to leave enough space for the complex output. The input is
150 <em>allocated</em> as a 2[L/2+1]&nbsp;&times;&nbsp;M&nbsp;&times;&nbsp;N
151 array, even though only
152 L&nbsp;&times;&nbsp;M&nbsp;&times;&nbsp;N
153 of it is actually used. In this example, we will
154 allocate the array as a pointer type, using &lsquo;<samp>fftw_alloc</samp>&rsquo; to
155 ensure aligned memory for maximum performance (see <a href="Allocating-aligned-memory-in-Fortran.html#Allocating-aligned-memory-in-Fortran">Allocating aligned memory in Fortran</a>); this also makes it easy to reference the
156 same memory as both a real array and a complex array.
157 </p>
158 <a name="index-fftw_005falloc_005fcomplex-4"></a>
159 <a name="index-c_005ff_005fpointer"></a>
160 <div class="example">
161 <pre class="example"> real(C_DOUBLE), pointer :: in(:,:,:)
162 complex(C_DOUBLE_COMPLEX), pointer :: out(:,:,:)
163 type(C_PTR) :: plan, data
164 data = fftw_alloc_complex(int((L/2+1) * M * N, C_SIZE_T))
165 call c_f_pointer(data, in, [2*(L/2+1),M,N])
166 call c_f_pointer(data, out, [L/2+1,M,N])
167 plan = fftw_plan_dft_r2c_3d(N,M,L, in,out, FFTW_ESTIMATE)
168 ...
169 call fftw_execute_dft_r2c(plan, in, out)
170 ...
171 call fftw_destroy_plan(plan)
172 call fftw_free(data)
173 </pre></div>
174
175 <hr>
176 <div class="header">
177 <p>
178 Next: <a href="FFTW-Fortran-type-reference.html#FFTW-Fortran-type-reference" accesskey="n" rel="next">FFTW Fortran type reference</a>, Previous: <a href="Overview-of-Fortran-interface.html#Overview-of-Fortran-interface" accesskey="p" rel="prev">Overview of Fortran interface</a>, Up: <a href="Calling-FFTW-from-Modern-Fortran.html#Calling-FFTW-from-Modern-Fortran" accesskey="u" rel="up">Calling FFTW from Modern Fortran</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
179 </div>
180
181
182
183 </body>
184 </html>