comparison src/fftw-3.3.3/doc/html/MPI-Plan-Creation.html @ 10:37bf6b4a2645

Add FFTW3
author Chris Cannam
date Wed, 20 Mar 2013 15:35:50 +0000
parents
children
comparison
equal deleted inserted replaced
9:c0fb53affa76 10:37bf6b4a2645
1 <html lang="en">
2 <head>
3 <title>MPI Plan Creation - FFTW 3.3.3</title>
4 <meta http-equiv="Content-Type" content="text/html">
5 <meta name="description" content="FFTW 3.3.3">
6 <meta name="generator" content="makeinfo 4.13">
7 <link title="Top" rel="start" href="index.html#Top">
8 <link rel="up" href="FFTW-MPI-Reference.html#FFTW-MPI-Reference" title="FFTW MPI Reference">
9 <link rel="prev" href="MPI-Data-Distribution-Functions.html#MPI-Data-Distribution-Functions" title="MPI Data Distribution Functions">
10 <link rel="next" href="MPI-Wisdom-Communication.html#MPI-Wisdom-Communication" title="MPI Wisdom Communication">
11 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
12 <!--
13 This manual is for FFTW
14 (version 3.3.3, 25 November 2012).
15
16 Copyright (C) 2003 Matteo Frigo.
17
18 Copyright (C) 2003 Massachusetts Institute of Technology.
19
20 Permission is granted to make and distribute verbatim copies of
21 this manual provided the copyright notice and this permission
22 notice are preserved on all copies.
23
24 Permission is granted to copy and distribute modified versions of
25 this manual under the conditions for verbatim copying, provided
26 that the entire resulting derived work is distributed under the
27 terms of a permission notice identical to this one.
28
29 Permission is granted to copy and distribute translations of this
30 manual into another language, under the above conditions for
31 modified versions, except that this permission notice may be
32 stated in a translation approved by the Free Software Foundation.
33 -->
34 <meta http-equiv="Content-Style-Type" content="text/css">
35 <style type="text/css"><!--
36 pre.display { font-family:inherit }
37 pre.format { font-family:inherit }
38 pre.smalldisplay { font-family:inherit; font-size:smaller }
39 pre.smallformat { font-family:inherit; font-size:smaller }
40 pre.smallexample { font-size:smaller }
41 pre.smalllisp { font-size:smaller }
42 span.sc { font-variant:small-caps }
43 span.roman { font-family:serif; font-weight:normal; }
44 span.sansserif { font-family:sans-serif; font-weight:normal; }
45 --></style>
46 </head>
47 <body>
48 <div class="node">
49 <a name="MPI-Plan-Creation"></a>
50 <p>
51 Next:&nbsp;<a rel="next" accesskey="n" href="MPI-Wisdom-Communication.html#MPI-Wisdom-Communication">MPI Wisdom Communication</a>,
52 Previous:&nbsp;<a rel="previous" accesskey="p" href="MPI-Data-Distribution-Functions.html#MPI-Data-Distribution-Functions">MPI Data Distribution Functions</a>,
53 Up:&nbsp;<a rel="up" accesskey="u" href="FFTW-MPI-Reference.html#FFTW-MPI-Reference">FFTW MPI Reference</a>
54 <hr>
55 </div>
56
57 <h4 class="subsection">6.12.5 MPI Plan Creation</h4>
58
59 <h5 class="subsubheading">Complex-data MPI DFTs</h5>
60
61 <p>Plans for complex-data DFTs (see <a href="2d-MPI-example.html#g_t2d-MPI-example">2d MPI example</a>) are created by:
62
63 <p><a name="index-fftw_005fmpi_005fplan_005fdft_005f1d-461"></a><a name="index-fftw_005fmpi_005fplan_005fdft_005f2d-462"></a><a name="index-fftw_005fmpi_005fplan_005fdft_005f3d-463"></a><a name="index-fftw_005fmpi_005fplan_005fdft-464"></a><a name="index-fftw_005fmpi_005fplan_005fmany_005fdft-465"></a>
64 <pre class="example"> fftw_plan fftw_mpi_plan_dft_1d(ptrdiff_t n0, fftw_complex *in, fftw_complex *out,
65 MPI_Comm comm, int sign, unsigned flags);
66 fftw_plan fftw_mpi_plan_dft_2d(ptrdiff_t n0, ptrdiff_t n1,
67 fftw_complex *in, fftw_complex *out,
68 MPI_Comm comm, int sign, unsigned flags);
69 fftw_plan fftw_mpi_plan_dft_3d(ptrdiff_t n0, ptrdiff_t n1, ptrdiff_t n2,
70 fftw_complex *in, fftw_complex *out,
71 MPI_Comm comm, int sign, unsigned flags);
72 fftw_plan fftw_mpi_plan_dft(int rnk, const ptrdiff_t *n,
73 fftw_complex *in, fftw_complex *out,
74 MPI_Comm comm, int sign, unsigned flags);
75 fftw_plan fftw_mpi_plan_many_dft(int rnk, const ptrdiff_t *n,
76 ptrdiff_t howmany, ptrdiff_t block, ptrdiff_t tblock,
77 fftw_complex *in, fftw_complex *out,
78 MPI_Comm comm, int sign, unsigned flags);
79 </pre>
80 <p><a name="index-MPI-communicator-466"></a><a name="index-collective-function-467"></a>These are similar to their serial counterparts (see <a href="Complex-DFTs.html#Complex-DFTs">Complex DFTs</a>)
81 in specifying the dimensions, sign, and flags of the transform. The
82 <code>comm</code> argument gives an MPI communicator that specifies the set
83 of processes to participate in the transform; plan creation is a
84 collective function that must be called for all processes in the
85 communicator. The <code>in</code> and <code>out</code> pointers refer only to a
86 portion of the overall transform data (see <a href="MPI-Data-Distribution.html#MPI-Data-Distribution">MPI Data Distribution</a>)
87 as specified by the &lsquo;<samp><span class="samp">local_size</span></samp>&rsquo; functions in the previous
88 section. Unless <code>flags</code> contains <code>FFTW_ESTIMATE</code>, these
89 arrays are overwritten during plan creation as for the serial
90 interface. For multi-dimensional transforms, any dimensions <code>&gt;
91 1</code> are supported; for one-dimensional transforms, only composite
92 (non-prime) <code>n0</code> are currently supported (unlike the serial
93 FFTW). Requesting an unsupported transform size will yield a
94 <code>NULL</code> plan. (As in the serial interface, highly composite sizes
95 generally yield the best performance.)
96
97 <p><a name="index-advanced-interface-468"></a><a name="index-FFTW_005fMPI_005fDEFAULT_005fBLOCK-469"></a><a name="index-stride-470"></a>The advanced-interface <code>fftw_mpi_plan_many_dft</code> additionally
98 allows you to specify the block sizes for the first dimension
99 (<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
100 (<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
101 steps of the transform, and for the output if
102 <code>FFTW_TRANSPOSED_OUT</code> is specified in <code>flags</code>). These must
103 be the same block sizes as were passed to the corresponding
104 &lsquo;<samp><span class="samp">local_size</span></samp>&rsquo; function; you can pass <code>FFTW_MPI_DEFAULT_BLOCK</code>
105 to use FFTW's default block size as in the basic interface. Also, the
106 <code>howmany</code> parameter specifies that the transform is of contiguous
107 <code>howmany</code>-tuples rather than individual complex numbers; this
108 corresponds to the same parameter in the serial advanced interface
109 (see <a href="Advanced-Complex-DFTs.html#Advanced-Complex-DFTs">Advanced Complex DFTs</a>) with <code>stride = howmany</code> and
110 <code>dist = 1</code>.
111
112 <h5 class="subsubheading">MPI flags</h5>
113
114 <p>The <code>flags</code> can be any of those for the serial FFTW
115 (see <a href="Planner-Flags.html#Planner-Flags">Planner Flags</a>), and in addition may include one or more of
116 the following MPI-specific flags, which improve performance at the
117 cost of changing the output or input data formats.
118
119 <ul>
120 <li><a name="index-FFTW_005fMPI_005fSCRAMBLED_005fOUT-471"></a><a name="index-FFTW_005fMPI_005fSCRAMBLED_005fIN-472"></a><code>FFTW_MPI_SCRAMBLED_OUT</code>, <code>FFTW_MPI_SCRAMBLED_IN</code>: valid for
121 1d transforms only, these flags indicate that the output/input of the
122 transform are in an undocumented &ldquo;scrambled&rdquo; order. A forward
123 <code>FFTW_MPI_SCRAMBLED_OUT</code> transform can be inverted by a backward
124 <code>FFTW_MPI_SCRAMBLED_IN</code> (times the usual 1/<i>N</i> normalization).
125 See <a href="One_002ddimensional-distributions.html#One_002ddimensional-distributions">One-dimensional distributions</a>.
126
127 <li><a name="index-FFTW_005fMPI_005fTRANSPOSED_005fOUT-473"></a><a name="index-FFTW_005fMPI_005fTRANSPOSED_005fIN-474"></a><code>FFTW_MPI_TRANSPOSED_OUT</code>, <code>FFTW_MPI_TRANSPOSED_IN</code>: valid
128 for multidimensional (<code>rnk &gt; 1</code>) transforms only, these flags
129 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
130 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>.
131
132 </ul>
133
134 <h5 class="subsubheading">Real-data MPI DFTs</h5>
135
136 <p><a name="index-r2c-475"></a>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:
137
138 <p><a name="index-fftw_005fmpi_005fplan_005fdft_005fr2c_005f2d-476"></a><a name="index-fftw_005fmpi_005fplan_005fdft_005fr2c_005f2d-477"></a><a name="index-fftw_005fmpi_005fplan_005fdft_005fr2c_005f3d-478"></a><a name="index-fftw_005fmpi_005fplan_005fdft_005fr2c-479"></a><a name="index-fftw_005fmpi_005fplan_005fdft_005fc2r_005f2d-480"></a><a name="index-fftw_005fmpi_005fplan_005fdft_005fc2r_005f2d-481"></a><a name="index-fftw_005fmpi_005fplan_005fdft_005fc2r_005f3d-482"></a><a name="index-fftw_005fmpi_005fplan_005fdft_005fc2r-483"></a>
139 <pre class="example"> fftw_plan fftw_mpi_plan_dft_r2c_2d(ptrdiff_t n0, ptrdiff_t n1,
140 double *in, fftw_complex *out,
141 MPI_Comm comm, unsigned flags);
142 fftw_plan fftw_mpi_plan_dft_r2c_2d(ptrdiff_t n0, ptrdiff_t n1,
143 double *in, fftw_complex *out,
144 MPI_Comm comm, unsigned flags);
145 fftw_plan fftw_mpi_plan_dft_r2c_3d(ptrdiff_t n0, ptrdiff_t n1, ptrdiff_t n2,
146 double *in, fftw_complex *out,
147 MPI_Comm comm, unsigned flags);
148 fftw_plan fftw_mpi_plan_dft_r2c(int rnk, const ptrdiff_t *n,
149 double *in, fftw_complex *out,
150 MPI_Comm comm, unsigned flags);
151 fftw_plan fftw_mpi_plan_dft_c2r_2d(ptrdiff_t n0, ptrdiff_t n1,
152 fftw_complex *in, double *out,
153 MPI_Comm comm, unsigned flags);
154 fftw_plan fftw_mpi_plan_dft_c2r_2d(ptrdiff_t n0, ptrdiff_t n1,
155 fftw_complex *in, double *out,
156 MPI_Comm comm, unsigned flags);
157 fftw_plan fftw_mpi_plan_dft_c2r_3d(ptrdiff_t n0, ptrdiff_t n1, ptrdiff_t n2,
158 fftw_complex *in, double *out,
159 MPI_Comm comm, unsigned flags);
160 fftw_plan fftw_mpi_plan_dft_c2r(int rnk, const ptrdiff_t *n,
161 fftw_complex *in, double *out,
162 MPI_Comm comm, unsigned flags);
163 </pre>
164 <p>Similar to the serial interface (see <a href="Real_002ddata-DFTs.html#Real_002ddata-DFTs">Real-data DFTs</a>), these
165 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
166 data, representing the non-redundant half of the conjugate-symmetry
167 output of a real-input DFT (see <a href="Multi_002ddimensional-Transforms.html#Multi_002ddimensional-Transforms">Multi-dimensional Transforms</a>).
168 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)]
169
170 <p>array (much like the in-place serial r2c transforms, but here for
171 out-of-place transforms as well). Currently, only multi-dimensional
172 (<code>rnk &gt; 1</code>) r2c/c2r transforms are supported (requesting a plan
173 for <code>rnk = 1</code> will yield <code>NULL</code>). As explained above
174 (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
175 distribution of both the real and complex arrays is given by the
176 &lsquo;<samp><span class="samp">local_size</span></samp>&rsquo; function called for the dimensions of the
177 <em>complex</em> array. Similar to the other planning functions, the
178 input and output arrays are overwritten when the plan is created
179 except in <code>FFTW_ESTIMATE</code> mode.
180
181 <p>As for the complex DFTs above, there is an advance interface that
182 allows you to manually specify block sizes and to transform contiguous
183 <code>howmany</code>-tuples of real/complex numbers:
184
185 <p><a name="index-fftw_005fmpi_005fplan_005fmany_005fdft_005fr2c-484"></a><a name="index-fftw_005fmpi_005fplan_005fmany_005fdft_005fc2r-485"></a>
186 <pre class="example"> fftw_plan fftw_mpi_plan_many_dft_r2c
187 (int rnk, const ptrdiff_t *n, ptrdiff_t howmany,
188 ptrdiff_t iblock, ptrdiff_t oblock,
189 double *in, fftw_complex *out,
190 MPI_Comm comm, unsigned flags);
191 fftw_plan fftw_mpi_plan_many_dft_c2r
192 (int rnk, const ptrdiff_t *n, ptrdiff_t howmany,
193 ptrdiff_t iblock, ptrdiff_t oblock,
194 fftw_complex *in, double *out,
195 MPI_Comm comm, unsigned flags);
196 </pre>
197 <h5 class="subsubheading">MPI r2r transforms</h5>
198
199 <p><a name="index-r2r-486"></a>There are corresponding plan-creation routines for r2r
200 transforms (see <a href="More-DFTs-of-Real-Data.html#More-DFTs-of-Real-Data">More DFTs of Real Data</a>), currently supporting
201 multidimensional (<code>rnk &gt; 1</code>) transforms only (<code>rnk = 1</code> will
202 yield a <code>NULL</code> plan):
203
204 <pre class="example"> fftw_plan fftw_mpi_plan_r2r_2d(ptrdiff_t n0, ptrdiff_t n1,
205 double *in, double *out,
206 MPI_Comm comm,
207 fftw_r2r_kind kind0, fftw_r2r_kind kind1,
208 unsigned flags);
209 fftw_plan fftw_mpi_plan_r2r_3d(ptrdiff_t n0, ptrdiff_t n1, ptrdiff_t n2,
210 double *in, double *out,
211 MPI_Comm comm,
212 fftw_r2r_kind kind0, fftw_r2r_kind kind1, fftw_r2r_kind kind2,
213 unsigned flags);
214 fftw_plan fftw_mpi_plan_r2r(int rnk, const ptrdiff_t *n,
215 double *in, double *out,
216 MPI_Comm comm, const fftw_r2r_kind *kind,
217 unsigned flags);
218 fftw_plan fftw_mpi_plan_many_r2r(int rnk, const ptrdiff_t *n,
219 ptrdiff_t iblock, ptrdiff_t oblock,
220 double *in, double *out,
221 MPI_Comm comm, const fftw_r2r_kind *kind,
222 unsigned flags);
223 </pre>
224 <p>The parameters are much the same as for the complex DFTs above, except
225 that the arrays are of real numbers (and hence the outputs of the
226 &lsquo;<samp><span class="samp">local_size</span></samp>&rsquo; data-distribution functions should be interpreted as
227 counts of real rather than complex numbers). Also, the <code>kind</code>
228 parameters specify the r2r kinds along each dimension as for the
229 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>.
230
231 <h5 class="subsubheading">MPI transposition</h5>
232
233 <p><a name="index-transpose-487"></a>
234 FFTW also provides routines to plan a transpose of a distributed
235 <code>n0</code> by <code>n1</code> array of real numbers, or an array of
236 <code>howmany</code>-tuples of real numbers with specified block sizes
237 (see <a href="FFTW-MPI-Transposes.html#FFTW-MPI-Transposes">FFTW MPI Transposes</a>):
238
239 <p><a name="index-fftw_005fmpi_005fplan_005ftranspose-488"></a><a name="index-fftw_005fmpi_005fplan_005fmany_005ftranspose-489"></a>
240 <pre class="example"> fftw_plan fftw_mpi_plan_transpose(ptrdiff_t n0, ptrdiff_t n1,
241 double *in, double *out,
242 MPI_Comm comm, unsigned flags);
243 fftw_plan fftw_mpi_plan_many_transpose
244 (ptrdiff_t n0, ptrdiff_t n1, ptrdiff_t howmany,
245 ptrdiff_t block0, ptrdiff_t block1,
246 double *in, double *out, MPI_Comm comm, unsigned flags);
247 </pre>
248 <p><a name="index-new_002darray-execution-490"></a><a name="index-fftw_005fmpi_005fexecute_005fr2r-491"></a>These plans are used with the <code>fftw_mpi_execute_r2r</code> new-array
249 execute function (see <a href="Using-MPI-Plans.html#Using-MPI-Plans">Using MPI Plans</a>), since they count as (rank
250 zero) r2r plans from FFTW's perspective.
251
252 </body></html>
253