Mercurial > hg > sv-dependency-builds

comparison src/fftw-3.3.5/doc/html/FFTW-MPI-Fortran-Interface.html @ 42:2cd0e3b3e1fd

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Current fftw source
author Chris Cannam
date Tue, 18 Oct 2016 13:40:26 +0100
parents
children
comparison
equal deleted inserted replaced
41:481f5f8c5634 42:2cd0e3b3e1fd
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.5, 30 July 2016).
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 5.2, http://www.gnu.org/software/texinfo/ -->
24 <head>
25 <title>FFTW 3.3.5: FFTW MPI Fortran Interface</title>
26
27 <meta name="description" content="FFTW 3.3.5: FFTW MPI Fortran Interface">
28 <meta name="keywords" content="FFTW 3.3.5: FFTW MPI Fortran Interface">
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="Distributed_002dmemory-FFTW-with-MPI.html#Distributed_002dmemory-FFTW-with-MPI" rel="up" title="Distributed-memory FFTW with MPI">
37 <link href="Calling-FFTW-from-Modern-Fortran.html#Calling-FFTW-from-Modern-Fortran" rel="next" title="Calling FFTW from Modern Fortran">
38 <link href="MPI-Wisdom-Communication.html#MPI-Wisdom-Communication" rel="prev" title="MPI Wisdom Communication">
39 <style type="text/css">
40 <!--
41 a.summary-letter {text-decoration: none}
42 blockquote.smallquotation {font-size: smaller}
43 div.display {margin-left: 3.2em}
44 div.example {margin-left: 3.2em}
45 div.indentedblock {margin-left: 3.2em}
46 div.lisp {margin-left: 3.2em}
47 div.smalldisplay {margin-left: 3.2em}
48 div.smallexample {margin-left: 3.2em}
49 div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
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.nocodebreak {white-space:nowrap}
61 span.nolinebreak {white-space:nowrap}
62 span.roman {font-family:serif; font-weight:normal}
63 span.sansserif {font-family:sans-serif; font-weight:normal}
64 ul.no-bullet {list-style: none}
65 -->
66 </style>
67
68
69 </head>
70
71 <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
72 <a name="FFTW-MPI-Fortran-Interface"></a>
73 <div class="header">
74 <p>
75 Previous: <a href="FFTW-MPI-Reference.html#FFTW-MPI-Reference" accesskey="p" rel="prev">FFTW MPI Reference</a>, Up: <a href="Distributed_002dmemory-FFTW-with-MPI.html#Distributed_002dmemory-FFTW-with-MPI" accesskey="u" rel="up">Distributed-memory FFTW with MPI</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>
76 </div>
77 <hr>
78 <a name="FFTW-MPI-Fortran-Interface-1"></a>
79 <h3 class="section">6.13 FFTW MPI Fortran Interface</h3>
80 <a name="index-Fortran-interface-1"></a>
81
82 <a name="index-iso_005fc_005fbinding"></a>
83 <p>The FFTW MPI interface is callable from modern Fortran compilers
84 supporting the Fortran 2003 <code>iso_c_binding</code> standard for calling
85 C functions. As described in <a href="Calling-FFTW-from-Modern-Fortran.html#Calling-FFTW-from-Modern-Fortran">Calling FFTW from Modern Fortran</a>,
86 this means that you can directly call FFTW&rsquo;s C interface from Fortran
87 with only minor changes in syntax. There are, however, a few things
88 specific to the MPI interface to keep in mind:
89 </p>
90 <ul>
91 <li> Instead of including <code>fftw3.f03</code> as in <a href="Overview-of-Fortran-interface.html#Overview-of-Fortran-interface">Overview of Fortran interface</a>, you should <code>include 'fftw3-mpi.f03'</code> (after
92 <code>use, intrinsic :: iso_c_binding</code> as before). The
93 <code>fftw3-mpi.f03</code> file includes <code>fftw3.f03</code>, so you should
94 <em>not</em> <code>include</code> them both yourself. (You will also want to
95 include the MPI header file, usually via <code>include 'mpif.h'</code> or
96 similar, although though this is not needed by <code>fftw3-mpi.f03</code>
97 <i>per se</i>.) (To use the &lsquo;<samp>fftwl_</samp>&rsquo; <code>long double</code> extended-precision routines in supporting compilers, you should include <code>fftw3f-mpi.f03</code> in <em>addition</em> to <code>fftw3-mpi.f03</code>. See <a href="Extended-and-quadruple-precision-in-Fortran.html#Extended-and-quadruple-precision-in-Fortran">Extended and quadruple precision in Fortran</a>.)
98
99 </li><li> Because of the different storage conventions between C and Fortran,
100 you reverse the order of your array dimensions when passing them to
101 FFTW (see <a href="Reversing-array-dimensions.html#Reversing-array-dimensions">Reversing array dimensions</a>). This is merely a
102 difference in notation and incurs no performance overhead. However,
103 it means that, whereas in C the <em>first</em> dimension is distributed,
104 in Fortran the <em>last</em> dimension of your array is distributed.
105
106 </li><li> <a name="index-MPI-communicator-3"></a>
107 In Fortran, communicators are stored as <code>integer</code> types; there is
108 no <code>MPI_Comm</code> type, nor is there any way to access a C
109 <code>MPI_Comm</code>. Fortunately, this is taken care of for you by the
110 FFTW Fortran interface: whenever the C interface expects an
111 <code>MPI_Comm</code> type, you should pass the Fortran communicator as an
112 <code>integer</code>.<a name="DOCF8" href="#FOOT8"><sup>8</sup></a>
113
114 </li><li> Because you need to call the &lsquo;<samp>local_size</samp>&rsquo; function to find out
115 how much space to allocate, and this may be <em>larger</em> than the
116 local portion of the array (see <a href="MPI-Data-Distribution.html#MPI-Data-Distribution">MPI Data Distribution</a>), you should
117 <em>always</em> allocate your arrays dynamically using FFTW&rsquo;s allocation
118 routines as described in <a href="Allocating-aligned-memory-in-Fortran.html#Allocating-aligned-memory-in-Fortran">Allocating aligned memory in Fortran</a>.
119 (Coincidentally, this also provides the best performance by
120 guaranteeding proper data alignment.)
121
122 </li><li> Because all sizes in the MPI FFTW interface are declared as
123 <code>ptrdiff_t</code> in C, you should use <code>integer(C_INTPTR_T)</code> in
124 Fortran (see <a href="FFTW-Fortran-type-reference.html#FFTW-Fortran-type-reference">FFTW Fortran type reference</a>).
125
126 </li><li> <a name="index-fftw_005fexecute_005fdft-1"></a>
127 <a name="index-fftw_005fmpi_005fexecute_005fdft-1"></a>
128 <a name="index-new_002darray-execution-3"></a>
129 In Fortran, because of the language semantics, we generally recommend
130 using the new-array execute functions for all plans, even in the
131 common case where you are executing the plan on the same arrays for
132 which the plan was created (see <a href="Plan-execution-in-Fortran.html#Plan-execution-in-Fortran">Plan execution in Fortran</a>).
133 However, note that in the MPI interface these functions are changed:
134 <code>fftw_execute_dft</code> becomes <code>fftw_mpi_execute_dft</code>,
135 etcetera. See <a href="Using-MPI-Plans.html#Using-MPI-Plans">Using MPI Plans</a>.
136
137 </li></ul>
138
139 <p>For example, here is a Fortran code snippet to perform a distributed
140 L&nbsp;&times;&nbsp;M complex DFT in-place. (This assumes you have already
141 initialized MPI with <code>MPI_init</code> and have also performed
142 <code>call fftw_mpi_init</code>.)
143 </p>
144 <div class="example">
145 <pre class="example"> use, intrinsic :: iso_c_binding
146 include 'fftw3-mpi.f03'
147 integer(C_INTPTR_T), parameter :: L = ...
148 integer(C_INTPTR_T), parameter :: M = ...
149 type(C_PTR) :: plan, cdata
150 complex(C_DOUBLE_COMPLEX), pointer :: data(:,:)
151 integer(C_INTPTR_T) :: i, j, alloc_local, local_M, local_j_offset
152
153 ! <span class="roman">get local data size and allocate (note dimension reversal)</span>
154 alloc_local = fftw_mpi_local_size_2d(M, L, MPI_COMM_WORLD, &amp;
155 local_M, local_j_offset)
156 cdata = fftw_alloc_complex(alloc_local)
157 call c_f_pointer(cdata, data, [L,local_M])
158
159 ! <span class="roman">create MPI plan for in-place forward DFT (note dimension reversal)</span>
160 plan = fftw_mpi_plan_dft_2d(M, L, data, data, MPI_COMM_WORLD, &amp;
161 FFTW_FORWARD, FFTW_MEASURE)
162
163 ! <span class="roman">initialize data to some function</span> my_function(i,j)
164 do j = 1, local_M
165 do i = 1, L
166 data(i, j) = my_function(i, j + local_j_offset)
167 end do
168 end do
169
170 ! <span class="roman">compute transform (as many times as desired)</span>
171 call fftw_mpi_execute_dft(plan, data, data)
172
173 call fftw_destroy_plan(plan)
174 call fftw_free(cdata)
175 </pre></div>
176
177 <p>Note that when we called <code>fftw_mpi_local_size_2d</code> and
178 <code>fftw_mpi_plan_dft_2d</code> with the dimensions in reversed order,
179 since a L&nbsp;&times;&nbsp;M Fortran array is viewed by FFTW in C as a
180 M&nbsp;&times;&nbsp;L array. This means that the array was distributed over
181 the <code>M</code> dimension, the local portion of which is a
182 L&nbsp;&times;&nbsp;local_M array in Fortran. (You must <em>not</em> use an
183 <code>allocate</code> statement to allocate an L&nbsp;&times;&nbsp;local_M array,
184 however; you must allocate <code>alloc_local</code> complex numbers, which
185 may be greater than <code>L * local_M</code>, in order to reserve space for
186 intermediate steps of the transform.) Finally, we mention that
187 because C&rsquo;s array indices are zero-based, the <code>local_j_offset</code>
188 argument can conveniently be interpreted as an offset in the 1-based
189 <code>j</code> index (rather than as a starting index as in C).
190 </p>
191 <p>If instead you had used the <code>ior(FFTW_MEASURE,
192 FFTW_MPI_TRANSPOSED_OUT)</code> flag, the output of the transform would be a
193 transposed M&nbsp;&times;&nbsp;local_L array, associated with the <em>same</em>
194 <code>cdata</code> allocation (since the transform is in-place), and which
195 you could declare with:
196 </p>
197 <div class="example">
198 <pre class="example"> complex(C_DOUBLE_COMPLEX), pointer :: tdata(:,:)
199 ...
200 call c_f_pointer(cdata, tdata, [M,local_L])
201 </pre></div>
202
203 <p>where <code>local_L</code> would have been obtained by changing the
204 <code>fftw_mpi_local_size_2d</code> call to:
205 </p>
206 <div class="example">
207 <pre class="example"> alloc_local = fftw_mpi_local_size_2d_transposed(M, L, MPI_COMM_WORLD, &amp;
208 local_M, local_j_offset, local_L, local_i_offset)
209 </pre></div>
210 <div class="footnote">
211 <hr>
212 <h4 class="footnotes-heading">Footnotes</h4>
213
214 <h3><a name="FOOT8" href="#DOCF8">(8)</a></h3>
215 <p>Technically, this is because you aren&rsquo;t
216 actually calling the C functions directly. You are calling wrapper
217 functions that translate the communicator with <code>MPI_Comm_f2c</code>
218 before calling the ordinary C interface. This is all done
219 transparently, however, since the <code>fftw3-mpi.f03</code> interface file
220 renames the wrappers so that they are called in Fortran with the same
221 names as the C interface functions.</p>
222 </div>
223 <hr>
224 <div class="header">
225 <p>
226 Previous: <a href="FFTW-MPI-Reference.html#FFTW-MPI-Reference" accesskey="p" rel="prev">FFTW MPI Reference</a>, Up: <a href="Distributed_002dmemory-FFTW-with-MPI.html#Distributed_002dmemory-FFTW-with-MPI" accesskey="u" rel="up">Distributed-memory FFTW with MPI</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>
227 </div>
228
229
230
231 </body>
232 </html>