This file is indexed.

/usr/share/doc/libfftw3-doc/html/MPI-Plan-Creation.html is in libfftw3-doc 3.3.4-2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This manual is for FFTW
(version 3.3.4, 20 September 2013).

Copyright (C) 2003 Matteo Frigo.

Copyright (C) 2003 Massachusetts Institute of Technology.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation. -->
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>FFTW 3.3.4: MPI Plan Creation</title>

<meta name="description" content="FFTW 3.3.4: MPI Plan Creation">
<meta name="keywords" content="FFTW 3.3.4: MPI Plan Creation">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="FFTW-MPI-Reference.html#FFTW-MPI-Reference" rel="up" title="FFTW MPI Reference">
<link href="MPI-Wisdom-Communication.html#MPI-Wisdom-Communication" rel="next" title="MPI Wisdom Communication">
<link href="MPI-Data-Distribution-Functions.html#MPI-Data-Distribution-Functions" rel="prev" title="MPI Data Distribution Functions">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="MPI-Plan-Creation"></a>
<div class="header">
<p>
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>
</div>
<hr>
<a name="MPI-Plan-Creation-1"></a>
<h4 class="subsection">6.12.5 MPI Plan Creation</h4>

<a name="Complex_002ddata-MPI-DFTs"></a>
<h4 class="subsubheading">Complex-data MPI DFTs</h4>

<p>Plans for complex-data DFTs (see <a href="2d-MPI-example.html#g_t2d-MPI-example">2d MPI example</a>) are created by:
</p>
<a name="index-fftw_005fmpi_005fplan_005fdft_005f1d"></a>
<a name="index-fftw_005fmpi_005fplan_005fdft_005f2d-1"></a>
<a name="index-fftw_005fmpi_005fplan_005fdft_005f3d"></a>
<a name="index-fftw_005fmpi_005fplan_005fdft"></a>
<a name="index-fftw_005fmpi_005fplan_005fmany_005fdft"></a>
<div class="example">
<pre class="example">fftw_plan fftw_mpi_plan_dft_1d(ptrdiff_t n0, fftw_complex *in, fftw_complex *out,
                               MPI_Comm comm, int sign, unsigned flags);
fftw_plan fftw_mpi_plan_dft_2d(ptrdiff_t n0, ptrdiff_t n1,
                               fftw_complex *in, fftw_complex *out,
                               MPI_Comm comm, int sign, unsigned flags);
fftw_plan fftw_mpi_plan_dft_3d(ptrdiff_t n0, ptrdiff_t n1, ptrdiff_t n2,
                               fftw_complex *in, fftw_complex *out,
                               MPI_Comm comm, int sign, unsigned flags);
fftw_plan fftw_mpi_plan_dft(int rnk, const ptrdiff_t *n, 
                            fftw_complex *in, fftw_complex *out,
                            MPI_Comm comm, int sign, unsigned flags);
fftw_plan fftw_mpi_plan_many_dft(int rnk, const ptrdiff_t *n,
                                 ptrdiff_t howmany, ptrdiff_t block, ptrdiff_t tblock,
                                 fftw_complex *in, fftw_complex *out,
                                 MPI_Comm comm, int sign, unsigned flags);
</pre></div>

<a name="index-MPI-communicator-2"></a>
<a name="index-collective-function-4"></a>
<p>These are similar to their serial counterparts (see <a href="Complex-DFTs.html#Complex-DFTs">Complex DFTs</a>)
in specifying the dimensions, sign, and flags of the transform.  The
<code>comm</code> argument gives an MPI communicator that specifies the set
of processes to participate in the transform; plan creation is a
collective function that must be called for all processes in the
communicator.  The <code>in</code> and <code>out</code> pointers refer only to a
portion of the overall transform data (see <a href="MPI-Data-Distribution.html#MPI-Data-Distribution">MPI Data Distribution</a>)
as specified by the &lsquo;<samp>local_size</samp>&rsquo; functions in the previous
section.  Unless <code>flags</code> contains <code>FFTW_ESTIMATE</code>, these
arrays are overwritten during plan creation as for the serial
interface.  For multi-dimensional transforms, any dimensions <code>&gt;
1</code> are supported; for one-dimensional transforms, only composite
(non-prime) <code>n0</code> are currently supported (unlike the serial
FFTW).  Requesting an unsupported transform size will yield a
<code>NULL</code> plan.  (As in the serial interface, highly composite sizes
generally yield the best performance.)
</p>
<a name="index-advanced-interface-6"></a>
<a name="index-FFTW_005fMPI_005fDEFAULT_005fBLOCK-2"></a>
<a name="index-stride-3"></a>
<p>The advanced-interface <code>fftw_mpi_plan_many_dft</code> additionally
allows you to specify the block sizes for the first dimension
(<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
(<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
steps of the transform, and for the output if
<code>FFTW_TRANSPOSED_OUT</code> is specified in <code>flags</code>).  These must
be the same block sizes as were passed to the corresponding
&lsquo;<samp>local_size</samp>&rsquo; function; you can pass <code>FFTW_MPI_DEFAULT_BLOCK</code>
to use FFTW&rsquo;s default block size as in the basic interface.  Also, the
<code>howmany</code> parameter specifies that the transform is of contiguous
<code>howmany</code>-tuples rather than individual complex numbers; this
corresponds to the same parameter in the serial advanced interface
(see <a href="Advanced-Complex-DFTs.html#Advanced-Complex-DFTs">Advanced Complex DFTs</a>) with <code>stride = howmany</code> and
<code>dist = 1</code>.
</p>
<a name="MPI-flags"></a>
<h4 class="subsubheading">MPI flags</h4>

<p>The <code>flags</code> can be any of those for the serial FFTW
(see <a href="Planner-Flags.html#Planner-Flags">Planner Flags</a>), and in addition may include one or more of
the following MPI-specific flags, which improve performance at the
cost of changing the output or input data formats.
</p>
<ul>
<li> <a name="index-FFTW_005fMPI_005fSCRAMBLED_005fOUT-2"></a>
<a name="index-FFTW_005fMPI_005fSCRAMBLED_005fIN-2"></a>
<code>FFTW_MPI_SCRAMBLED_OUT</code>, <code>FFTW_MPI_SCRAMBLED_IN</code>: valid for
1d transforms only, these flags indicate that the output/input of the
transform are in an undocumented &ldquo;scrambled&rdquo; order.  A forward
<code>FFTW_MPI_SCRAMBLED_OUT</code> transform can be inverted by a backward
<code>FFTW_MPI_SCRAMBLED_IN</code> (times the usual 1/<i>N</i> normalization).
See <a href="One_002ddimensional-distributions.html#One_002ddimensional-distributions">One-dimensional distributions</a>.

</li><li> <a name="index-FFTW_005fMPI_005fTRANSPOSED_005fOUT-2"></a>
<a name="index-FFTW_005fMPI_005fTRANSPOSED_005fIN-2"></a>
<code>FFTW_MPI_TRANSPOSED_OUT</code>, <code>FFTW_MPI_TRANSPOSED_IN</code>: valid
for multidimensional (<code>rnk &gt; 1</code>) transforms only, these flags
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
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>.

</li></ul>

<a name="Real_002ddata-MPI-DFTs"></a>
<h4 class="subsubheading">Real-data MPI DFTs</h4>

<a name="index-r2c-4"></a>
<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:
</p>
<a name="index-fftw_005fmpi_005fplan_005fdft_005fr2c_005f2d"></a>
<a name="index-fftw_005fmpi_005fplan_005fdft_005fr2c_005f2d-1"></a>
<a name="index-fftw_005fmpi_005fplan_005fdft_005fr2c_005f3d"></a>
<a name="index-fftw_005fmpi_005fplan_005fdft_005fr2c"></a>
<a name="index-fftw_005fmpi_005fplan_005fdft_005fc2r_005f2d"></a>
<a name="index-fftw_005fmpi_005fplan_005fdft_005fc2r_005f2d-1"></a>
<a name="index-fftw_005fmpi_005fplan_005fdft_005fc2r_005f3d"></a>
<a name="index-fftw_005fmpi_005fplan_005fdft_005fc2r"></a>
<div class="example">
<pre class="example">fftw_plan fftw_mpi_plan_dft_r2c_2d(ptrdiff_t n0, ptrdiff_t n1, 
                                   double *in, fftw_complex *out,
                                   MPI_Comm comm, unsigned flags);
fftw_plan fftw_mpi_plan_dft_r2c_2d(ptrdiff_t n0, ptrdiff_t n1, 
                                   double *in, fftw_complex *out,
                                   MPI_Comm comm, unsigned flags);
fftw_plan fftw_mpi_plan_dft_r2c_3d(ptrdiff_t n0, ptrdiff_t n1, ptrdiff_t n2,
                                   double *in, fftw_complex *out,
                                   MPI_Comm comm, unsigned flags);
fftw_plan fftw_mpi_plan_dft_r2c(int rnk, const ptrdiff_t *n,
                                double *in, fftw_complex *out,
                                MPI_Comm comm, unsigned flags);
fftw_plan fftw_mpi_plan_dft_c2r_2d(ptrdiff_t n0, ptrdiff_t n1, 
                                   fftw_complex *in, double *out,
                                   MPI_Comm comm, unsigned flags);
fftw_plan fftw_mpi_plan_dft_c2r_2d(ptrdiff_t n0, ptrdiff_t n1, 
                                   fftw_complex *in, double *out,
                                   MPI_Comm comm, unsigned flags);
fftw_plan fftw_mpi_plan_dft_c2r_3d(ptrdiff_t n0, ptrdiff_t n1, ptrdiff_t n2,
                                   fftw_complex *in, double *out,
                                   MPI_Comm comm, unsigned flags);
fftw_plan fftw_mpi_plan_dft_c2r(int rnk, const ptrdiff_t *n,
                                fftw_complex *in, double *out,
                                MPI_Comm comm, unsigned flags);
</pre></div>

<p>Similar to the serial interface (see <a href="Real_002ddata-DFTs.html#Real_002ddata-DFTs">Real-data DFTs</a>), these
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
data, representing the non-redundant half of the conjugate-symmetry
output of a real-input DFT (see <a href="Multi_002ddimensional-Transforms.html#Multi_002ddimensional-Transforms">Multi-dimensional Transforms</a>).
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)]
array (much like the in-place serial r2c transforms, but here for
out-of-place transforms as well). Currently, only multi-dimensional
(<code>rnk &gt; 1</code>) r2c/c2r transforms are supported (requesting a plan
for <code>rnk = 1</code> will yield <code>NULL</code>).  As explained above
(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
distribution of both the real and complex arrays is given by the
&lsquo;<samp>local_size</samp>&rsquo; function called for the dimensions of the
<em>complex</em> array.  Similar to the other planning functions, the
input and output arrays are overwritten when the plan is created
except in <code>FFTW_ESTIMATE</code> mode.
</p>
<p>As for the complex DFTs above, there is an advance interface that
allows you to manually specify block sizes and to transform contiguous
<code>howmany</code>-tuples of real/complex numbers:
</p>
<a name="index-fftw_005fmpi_005fplan_005fmany_005fdft_005fr2c"></a>
<a name="index-fftw_005fmpi_005fplan_005fmany_005fdft_005fc2r"></a>
<div class="example">
<pre class="example">fftw_plan fftw_mpi_plan_many_dft_r2c
              (int rnk, const ptrdiff_t *n, ptrdiff_t howmany,
               ptrdiff_t iblock, ptrdiff_t oblock,
               double *in, fftw_complex *out,
               MPI_Comm comm, unsigned flags);
fftw_plan fftw_mpi_plan_many_dft_c2r
              (int rnk, const ptrdiff_t *n, ptrdiff_t howmany,
               ptrdiff_t iblock, ptrdiff_t oblock,
               fftw_complex *in, double *out,
               MPI_Comm comm, unsigned flags);               
</pre></div>

<a name="MPI-r2r-transforms"></a>
<h4 class="subsubheading">MPI r2r transforms</h4>

<a name="index-r2r-4"></a>
<p>There are corresponding plan-creation routines for r2r
transforms (see <a href="More-DFTs-of-Real-Data.html#More-DFTs-of-Real-Data">More DFTs of Real Data</a>), currently supporting
multidimensional (<code>rnk &gt; 1</code>) transforms only (<code>rnk = 1</code> will
yield a <code>NULL</code> plan):
</p>
<div class="example">
<pre class="example">fftw_plan fftw_mpi_plan_r2r_2d(ptrdiff_t n0, ptrdiff_t n1,
                               double *in, double *out,
                               MPI_Comm comm,
                               fftw_r2r_kind kind0, fftw_r2r_kind kind1,
                               unsigned flags);
fftw_plan fftw_mpi_plan_r2r_3d(ptrdiff_t n0, ptrdiff_t n1, ptrdiff_t n2,
                               double *in, double *out,
                               MPI_Comm comm,
                               fftw_r2r_kind kind0, fftw_r2r_kind kind1, fftw_r2r_kind kind2,
                               unsigned flags);
fftw_plan fftw_mpi_plan_r2r(int rnk, const ptrdiff_t *n,
                            double *in, double *out,
                            MPI_Comm comm, const fftw_r2r_kind *kind, 
                            unsigned flags);
fftw_plan fftw_mpi_plan_many_r2r(int rnk, const ptrdiff_t *n,
                                 ptrdiff_t iblock, ptrdiff_t oblock,
                                 double *in, double *out,
                                 MPI_Comm comm, const fftw_r2r_kind *kind, 
                                 unsigned flags);
</pre></div>

<p>The parameters are much the same as for the complex DFTs above, except
that the arrays are of real numbers (and hence the outputs of the
&lsquo;<samp>local_size</samp>&rsquo; data-distribution functions should be interpreted as
counts of real rather than complex numbers).  Also, the <code>kind</code>
parameters specify the r2r kinds along each dimension as for the
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>.
</p>
<a name="MPI-transposition"></a>
<h4 class="subsubheading">MPI transposition</h4>
<a name="index-transpose-5"></a>

<p>FFTW also provides routines to plan a transpose of a distributed
<code>n0</code> by <code>n1</code> array of real numbers, or an array of
<code>howmany</code>-tuples of real numbers with specified block sizes
(see <a href="FFTW-MPI-Transposes.html#FFTW-MPI-Transposes">FFTW MPI Transposes</a>):
</p>
<a name="index-fftw_005fmpi_005fplan_005ftranspose-1"></a>
<a name="index-fftw_005fmpi_005fplan_005fmany_005ftranspose-1"></a>
<div class="example">
<pre class="example">fftw_plan fftw_mpi_plan_transpose(ptrdiff_t n0, ptrdiff_t n1,
                                  double *in, double *out,
                                  MPI_Comm comm, unsigned flags);
fftw_plan fftw_mpi_plan_many_transpose
                (ptrdiff_t n0, ptrdiff_t n1, ptrdiff_t howmany,
                 ptrdiff_t block0, ptrdiff_t block1,
                 double *in, double *out, MPI_Comm comm, unsigned flags);
</pre></div>

<a name="index-new_002darray-execution-2"></a>
<a name="index-fftw_005fmpi_005fexecute_005fr2r-1"></a>
<p>These plans are used with the <code>fftw_mpi_execute_r2r</code> new-array
execute function (see <a href="Using-MPI-Plans.html#Using-MPI-Plans">Using MPI Plans</a>), since they count as (rank
zero) r2r plans from FFTW&rsquo;s perspective.
</p>
<hr>
<div class="header">
<p>
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>
</div>



</body>
</html>