comparison src/fftw-3.3.8/doc/html/MPI-Plan-Creation.html @ 167:bd3cc4d1df30

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