Mercurial > hg > sv-dependency-builds

annotate src/fftw-3.3.5/doc/html/Reversing-array-dimensions.html @ 83:ae30d91d2ffe

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