comparison src/fftw-3.3.5/doc/html/MPI-Plan-Creation.html @ 127:7867fa7e1b6b

Current fftw source
author Chris Cannam <cannam@all-day-breakfast.com>
date Tue, 18 Oct 2016 13:40:26 +0100
parents
children
comparison
equal deleted inserted replaced
126:4a7071416412 127:7867fa7e1b6b
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: MPI Plan Creation</title>
26
27 <meta name="description" content="FFTW 3.3.5: MPI Plan Creation">
28 <meta name="keywords" content="FFTW 3.3.5: MPI Plan Creation">
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="FFTW-MPI-Reference.html#FFTW-MPI-Reference" rel="up" title="FFTW MPI Reference">
37 <link href="MPI-Wisdom-Communication.html#MPI-Wisdom-Communication" rel="next" title="MPI Wisdom Communication">
38 <link href="MPI-Data-Distribution-Functions.html#MPI-Data-Distribution-Functions" rel="prev" title="MPI Data Distribution Functions">
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="MPI-Plan-Creation"></a>
73 <div class="header">
74 <p>
75 Next: <a href="MPI-Wisdom-Communication.html#MPI-Wisdom-Communication" accesskey="n" rel="next">MPI Wisdom Communication</a>, Previous: <a href="MPI-Data-Distribution-Functions.html#MPI-Data-Distribution-Functions" accesskey="p" rel="prev">MPI Data Distribution Functions</a>, Up: <a href="FFTW-MPI-Reference.html#FFTW-MPI-Reference" accesskey="u" rel="up">FFTW MPI Reference</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="MPI-Plan-Creation-1"></a>
79 <h4 class="subsection">6.12.5 MPI Plan Creation</h4>
80
81 <a name="Complex_002ddata-MPI-DFTs"></a>
82 <h4 class="subsubheading">Complex-data MPI DFTs</h4>
83
84 <p>Plans for complex-data DFTs (see <a href="2d-MPI-example.html#g_t2d-MPI-example">2d MPI example</a>) are created by:
85 </p>
86 <a name="index-fftw_005fmpi_005fplan_005fdft_005f1d"></a>
87 <a name="index-fftw_005fmpi_005fplan_005fdft_005f2d-1"></a>
88 <a name="index-fftw_005fmpi_005fplan_005fdft_005f3d"></a>
89 <a name="index-fftw_005fmpi_005fplan_005fdft"></a>
90 <a name="index-fftw_005fmpi_005fplan_005fmany_005fdft"></a>
91 <div class="example">
92 <pre class="example">fftw_plan fftw_mpi_plan_dft_1d(ptrdiff_t n0, fftw_complex *in, fftw_complex *out,
93 MPI_Comm comm, int sign, unsigned flags);
94 fftw_plan fftw_mpi_plan_dft_2d(ptrdiff_t n0, ptrdiff_t n1,
95 fftw_complex *in, fftw_complex *out,
96 MPI_Comm comm, int sign, unsigned flags);
97 fftw_plan fftw_mpi_plan_dft_3d(ptrdiff_t n0, ptrdiff_t n1, ptrdiff_t n2,
98 fftw_complex *in, fftw_complex *out,
99 MPI_Comm comm, int sign, unsigned flags);
100 fftw_plan fftw_mpi_plan_dft(int rnk, const ptrdiff_t *n,
101 fftw_complex *in, fftw_complex *out,
102 MPI_Comm comm, int sign, unsigned flags);
103 fftw_plan fftw_mpi_plan_many_dft(int rnk, const ptrdiff_t *n,
104 ptrdiff_t howmany, ptrdiff_t block, ptrdiff_t tblock,
105 fftw_complex *in, fftw_complex *out,
106 MPI_Comm comm, int sign, unsigned flags);
107 </pre></div>
108
109 <a name="index-MPI-communicator-2"></a>
110 <a name="index-collective-function-4"></a>
111 <p>These are similar to their serial counterparts (see <a href="Complex-DFTs.html#Complex-DFTs">Complex DFTs</a>)
112 in specifying the dimensions, sign, and flags of the transform. The
113 <code>comm</code> argument gives an MPI communicator that specifies the set
114 of processes to participate in the transform; plan creation is a
115 collective function that must be called for all processes in the
116 communicator. The <code>in</code> and <code>out</code> pointers refer only to a
117 portion of the overall transform data (see <a href="MPI-Data-Distribution.html#MPI-Data-Distribution">MPI Data Distribution</a>)
118 as specified by the &lsquo;<samp>local_size</samp>&rsquo; functions in the previous
119 section. Unless <code>flags</code> contains <code>FFTW_ESTIMATE</code>, these
120 arrays are overwritten during plan creation as for the serial
121 interface. For multi-dimensional transforms, any dimensions <code>&gt;
122 1</code> are supported; for one-dimensional transforms, only composite
123 (non-prime) <code>n0</code> are currently supported (unlike the serial
124 FFTW). Requesting an unsupported transform size will yield a
125 <code>NULL</code> plan. (As in the serial interface, highly composite sizes
126 generally yield the best performance.)
127 </p>
128 <a name="index-advanced-interface-6"></a>
129 <a name="index-FFTW_005fMPI_005fDEFAULT_005fBLOCK-2"></a>
130 <a name="index-stride-3"></a>
131 <p>The advanced-interface <code>fftw_mpi_plan_many_dft</code> additionally
132 allows you to specify the block sizes for the first dimension
133 (<code>block</code>) of the n<sub>0</sub>&nbsp;&times;&nbsp;n<sub>1</sub>&nbsp;&times;&nbsp;n<sub>2</sub>&nbsp;&times;&nbsp;&hellip;&nbsp;&times;&nbsp;n<sub>d-1</sub> input data and the first dimension
134 (<code>tblock</code>) of the n<sub>1</sub>&nbsp;&times;&nbsp;n<sub>0</sub>&nbsp;&times;&nbsp;n<sub>2</sub>&nbsp;&times;&hellip;&times;&nbsp;n<sub>d-1</sub> transposed data (at intermediate
135 steps of the transform, and for the output if
136 <code>FFTW_TRANSPOSED_OUT</code> is specified in <code>flags</code>). These must
137 be the same block sizes as were passed to the corresponding
138 &lsquo;<samp>local_size</samp>&rsquo; function; you can pass <code>FFTW_MPI_DEFAULT_BLOCK</code>
139 to use FFTW&rsquo;s default block size as in the basic interface. Also, the
140 <code>howmany</code> parameter specifies that the transform is of contiguous
141 <code>howmany</code>-tuples rather than individual complex numbers; this
142 corresponds to the same parameter in the serial advanced interface
143 (see <a href="Advanced-Complex-DFTs.html#Advanced-Complex-DFTs">Advanced Complex DFTs</a>) with <code>stride = howmany</code> and
144 <code>dist = 1</code>.
145 </p>
146 <a name="MPI-flags"></a>
147 <h4 class="subsubheading">MPI flags</h4>
148
149 <p>The <code>flags</code> can be any of those for the serial FFTW
150 (see <a href="Planner-Flags.html#Planner-Flags">Planner Flags</a>), and in addition may include one or more of
151 the following MPI-specific flags, which improve performance at the
152 cost of changing the output or input data formats.
153 </p>
154 <ul>
155 <li> <a name="index-FFTW_005fMPI_005fSCRAMBLED_005fOUT-2"></a>
156 <a name="index-FFTW_005fMPI_005fSCRAMBLED_005fIN-2"></a>
157 <code>FFTW_MPI_SCRAMBLED_OUT</code>, <code>FFTW_MPI_SCRAMBLED_IN</code>: valid for
158 1d transforms only, these flags indicate that the output/input of the
159 transform are in an undocumented &ldquo;scrambled&rdquo; order. A forward
160 <code>FFTW_MPI_SCRAMBLED_OUT</code> transform can be inverted by a backward
161 <code>FFTW_MPI_SCRAMBLED_IN</code> (times the usual 1/<i>N</i> normalization).
162 See <a href="One_002ddimensional-distributions.html#One_002ddimensional-distributions">One-dimensional distributions</a>.
163
164 </li><li> <a name="index-FFTW_005fMPI_005fTRANSPOSED_005fOUT-2"></a>
165 <a name="index-FFTW_005fMPI_005fTRANSPOSED_005fIN-2"></a>
166 <code>FFTW_MPI_TRANSPOSED_OUT</code>, <code>FFTW_MPI_TRANSPOSED_IN</code>: valid
167 for multidimensional (<code>rnk &gt; 1</code>) transforms only, these flags
168 specify that the output or input of an n<sub>0</sub>&nbsp;&times;&nbsp;n<sub>1</sub>&nbsp;&times;&nbsp;n<sub>2</sub>&nbsp;&times;&nbsp;&hellip;&nbsp;&times;&nbsp;n<sub>d-1</sub> transform is
169 transposed to n<sub>1</sub>&nbsp;&times;&nbsp;n<sub>0</sub>&nbsp;&times;&nbsp;n<sub>2</sub>&nbsp;&times;&hellip;&times;&nbsp;n<sub>d-1</sub>. See <a href="Transposed-distributions.html#Transposed-distributions">Transposed distributions</a>.
170
171 </li></ul>
172
173 <a name="Real_002ddata-MPI-DFTs"></a>
174 <h4 class="subsubheading">Real-data MPI DFTs</h4>
175
176 <a name="index-r2c-4"></a>
177 <p>Plans for real-input/output (r2c/c2r) DFTs (see <a href="Multi_002ddimensional-MPI-DFTs-of-Real-Data.html#Multi_002ddimensional-MPI-DFTs-of-Real-Data">Multi-dimensional MPI DFTs of Real Data</a>) are created by:
178 </p>
179 <a name="index-fftw_005fmpi_005fplan_005fdft_005fr2c_005f2d"></a>
180 <a name="index-fftw_005fmpi_005fplan_005fdft_005fr2c_005f2d-1"></a>
181 <a name="index-fftw_005fmpi_005fplan_005fdft_005fr2c_005f3d"></a>
182 <a name="index-fftw_005fmpi_005fplan_005fdft_005fr2c"></a>
183 <a name="index-fftw_005fmpi_005fplan_005fdft_005fc2r_005f2d"></a>
184 <a name="index-fftw_005fmpi_005fplan_005fdft_005fc2r_005f2d-1"></a>
185 <a name="index-fftw_005fmpi_005fplan_005fdft_005fc2r_005f3d"></a>
186 <a name="index-fftw_005fmpi_005fplan_005fdft_005fc2r"></a>
187 <div class="example">
188 <pre class="example">fftw_plan fftw_mpi_plan_dft_r2c_2d(ptrdiff_t n0, ptrdiff_t n1,
189 double *in, fftw_complex *out,
190 MPI_Comm comm, unsigned flags);
191 fftw_plan fftw_mpi_plan_dft_r2c_2d(ptrdiff_t n0, ptrdiff_t n1,
192 double *in, fftw_complex *out,
193 MPI_Comm comm, unsigned flags);
194 fftw_plan fftw_mpi_plan_dft_r2c_3d(ptrdiff_t n0, ptrdiff_t n1, ptrdiff_t n2,
195 double *in, fftw_complex *out,
196 MPI_Comm comm, unsigned flags);
197 fftw_plan fftw_mpi_plan_dft_r2c(int rnk, const ptrdiff_t *n,
198 double *in, fftw_complex *out,
199 MPI_Comm comm, unsigned flags);
200 fftw_plan fftw_mpi_plan_dft_c2r_2d(ptrdiff_t n0, ptrdiff_t n1,
201 fftw_complex *in, double *out,
202 MPI_Comm comm, unsigned flags);
203 fftw_plan fftw_mpi_plan_dft_c2r_2d(ptrdiff_t n0, ptrdiff_t n1,
204 fftw_complex *in, double *out,
205 MPI_Comm comm, unsigned flags);
206 fftw_plan fftw_mpi_plan_dft_c2r_3d(ptrdiff_t n0, ptrdiff_t n1, ptrdiff_t n2,
207 fftw_complex *in, double *out,
208 MPI_Comm comm, unsigned flags);
209 fftw_plan fftw_mpi_plan_dft_c2r(int rnk, const ptrdiff_t *n,
210 fftw_complex *in, double *out,
211 MPI_Comm comm, unsigned flags);
212 </pre></div>
213
214 <p>Similar to the serial interface (see <a href="Real_002ddata-DFTs.html#Real_002ddata-DFTs">Real-data DFTs</a>), these
215 transform logically n<sub>0</sub>&nbsp;&times;&nbsp;n<sub>1</sub>&nbsp;&times;&nbsp;n<sub>2</sub>&nbsp;&times;&nbsp;&hellip;&nbsp;&times;&nbsp;n<sub>d-1</sub> real data to/from n<sub>0</sub>&nbsp;&times;&nbsp;n<sub>1</sub>&nbsp;&times;&nbsp;n<sub>2</sub>&nbsp;&times;&nbsp;&hellip;&nbsp;&times;&nbsp;(n<sub>d-1</sub>/2 + 1) complex
216 data, representing the non-redundant half of the conjugate-symmetry
217 output of a real-input DFT (see <a href="Multi_002ddimensional-Transforms.html#Multi_002ddimensional-Transforms">Multi-dimensional Transforms</a>).
218 However, the real array must be stored within a padded n<sub>0</sub>&nbsp;&times;&nbsp;n<sub>1</sub>&nbsp;&times;&nbsp;n<sub>2</sub>&nbsp;&times;&nbsp;&hellip;&nbsp;&times;&nbsp;[2&nbsp;(n<sub>d-1</sub>/2 + 1)]
219 array (much like the in-place serial r2c transforms, but here for
220 out-of-place transforms as well). Currently, only multi-dimensional
221 (<code>rnk &gt; 1</code>) r2c/c2r transforms are supported (requesting a plan
222 for <code>rnk = 1</code> will yield <code>NULL</code>). As explained above
223 (see <a href="Multi_002ddimensional-MPI-DFTs-of-Real-Data.html#Multi_002ddimensional-MPI-DFTs-of-Real-Data">Multi-dimensional MPI DFTs of Real Data</a>), the data
224 distribution of both the real and complex arrays is given by the
225 &lsquo;<samp>local_size</samp>&rsquo; function called for the dimensions of the
226 <em>complex</em> array. Similar to the other planning functions, the
227 input and output arrays are overwritten when the plan is created
228 except in <code>FFTW_ESTIMATE</code> mode.
229 </p>
230 <p>As for the complex DFTs above, there is an advance interface that
231 allows you to manually specify block sizes and to transform contiguous
232 <code>howmany</code>-tuples of real/complex numbers:
233 </p>
234 <a name="index-fftw_005fmpi_005fplan_005fmany_005fdft_005fr2c"></a>
235 <a name="index-fftw_005fmpi_005fplan_005fmany_005fdft_005fc2r"></a>
236 <div class="example">
237 <pre class="example">fftw_plan fftw_mpi_plan_many_dft_r2c
238 (int rnk, const ptrdiff_t *n, ptrdiff_t howmany,
239 ptrdiff_t iblock, ptrdiff_t oblock,
240 double *in, fftw_complex *out,
241 MPI_Comm comm, unsigned flags);
242 fftw_plan fftw_mpi_plan_many_dft_c2r
243 (int rnk, const ptrdiff_t *n, ptrdiff_t howmany,
244 ptrdiff_t iblock, ptrdiff_t oblock,
245 fftw_complex *in, double *out,
246 MPI_Comm comm, unsigned flags);
247 </pre></div>
248
249 <a name="MPI-r2r-transforms"></a>
250 <h4 class="subsubheading">MPI r2r transforms</h4>
251
252 <a name="index-r2r-4"></a>
253 <p>There are corresponding plan-creation routines for r2r
254 transforms (see <a href="More-DFTs-of-Real-Data.html#More-DFTs-of-Real-Data">More DFTs of Real Data</a>), currently supporting
255 multidimensional (<code>rnk &gt; 1</code>) transforms only (<code>rnk = 1</code> will
256 yield a <code>NULL</code> plan):
257 </p>
258 <div class="example">
259 <pre class="example">fftw_plan fftw_mpi_plan_r2r_2d(ptrdiff_t n0, ptrdiff_t n1,
260 double *in, double *out,
261 MPI_Comm comm,
262 fftw_r2r_kind kind0, fftw_r2r_kind kind1,
263 unsigned flags);
264 fftw_plan fftw_mpi_plan_r2r_3d(ptrdiff_t n0, ptrdiff_t n1, ptrdiff_t n2,
265 double *in, double *out,
266 MPI_Comm comm,
267 fftw_r2r_kind kind0, fftw_r2r_kind kind1, fftw_r2r_kind kind2,
268 unsigned flags);
269 fftw_plan fftw_mpi_plan_r2r(int rnk, const ptrdiff_t *n,
270 double *in, double *out,
271 MPI_Comm comm, const fftw_r2r_kind *kind,
272 unsigned flags);
273 fftw_plan fftw_mpi_plan_many_r2r(int rnk, const ptrdiff_t *n,
274 ptrdiff_t iblock, ptrdiff_t oblock,
275 double *in, double *out,
276 MPI_Comm comm, const fftw_r2r_kind *kind,
277 unsigned flags);
278 </pre></div>
279
280 <p>The parameters are much the same as for the complex DFTs above, except
281 that the arrays are of real numbers (and hence the outputs of the
282 &lsquo;<samp>local_size</samp>&rsquo; data-distribution functions should be interpreted as
283 counts of real rather than complex numbers). Also, the <code>kind</code>
284 parameters specify the r2r kinds along each dimension as for the
285 serial interface (see <a href="Real_002dto_002dReal-Transform-Kinds.html#Real_002dto_002dReal-Transform-Kinds">Real-to-Real Transform Kinds</a>). See <a href="Other-Multi_002ddimensional-Real_002ddata-MPI-Transforms.html#Other-Multi_002ddimensional-Real_002ddata-MPI-Transforms">Other Multi-dimensional Real-data MPI Transforms</a>.
286 </p>
287 <a name="MPI-transposition"></a>
288 <h4 class="subsubheading">MPI transposition</h4>
289 <a name="index-transpose-5"></a>
290
291 <p>FFTW also provides routines to plan a transpose of a distributed
292 <code>n0</code> by <code>n1</code> array of real numbers, or an array of
293 <code>howmany</code>-tuples of real numbers with specified block sizes
294 (see <a href="FFTW-MPI-Transposes.html#FFTW-MPI-Transposes">FFTW MPI Transposes</a>):
295 </p>
296 <a name="index-fftw_005fmpi_005fplan_005ftranspose-1"></a>
297 <a name="index-fftw_005fmpi_005fplan_005fmany_005ftranspose-1"></a>
298 <div class="example">
299 <pre class="example">fftw_plan fftw_mpi_plan_transpose(ptrdiff_t n0, ptrdiff_t n1,
300 double *in, double *out,
301 MPI_Comm comm, unsigned flags);
302 fftw_plan fftw_mpi_plan_many_transpose
303 (ptrdiff_t n0, ptrdiff_t n1, ptrdiff_t howmany,
304 ptrdiff_t block0, ptrdiff_t block1,
305 double *in, double *out, MPI_Comm comm, unsigned flags);
306 </pre></div>
307
308 <a name="index-new_002darray-execution-2"></a>
309 <a name="index-fftw_005fmpi_005fexecute_005fr2r-1"></a>
310 <p>These plans are used with the <code>fftw_mpi_execute_r2r</code> new-array
311 execute function (see <a href="Using-MPI-Plans.html#Using-MPI-Plans">Using MPI Plans</a>), since they count as (rank
312 zero) r2r plans from FFTW&rsquo;s perspective.
313 </p>
314 <hr>
315 <div class="header">
316 <p>
317 Next: <a href="MPI-Wisdom-Communication.html#MPI-Wisdom-Communication" accesskey="n" rel="next">MPI Wisdom Communication</a>, Previous: <a href="MPI-Data-Distribution-Functions.html#MPI-Data-Distribution-Functions" accesskey="p" rel="prev">MPI Data Distribution Functions</a>, Up: <a href="FFTW-MPI-Reference.html#FFTW-MPI-Reference" accesskey="u" rel="up">FFTW MPI Reference</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>
318 </div>
319
320
321
322 </body>
323 </html>