Mercurial > hg > sv-dependency-builds

annotate src/fftw-3.3.3/doc/html/FFTW-MPI-Fortran-Interface.html @ 83:ae30d91d2ffe

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Replace these with versions built using an older toolset (so as to avoid ABI compatibilities when linking on Ubuntu 14.04 for packaging purposes)
author Chris Cannam
date Fri, 07 Feb 2020 11:51:13 +0000
parents 37bf6b4a2645
children
rev   line source
Chris@10 1 <html lang="en">
Chris@10 2 <head>
Chris@10 3 <title>FFTW MPI Fortran Interface - FFTW 3.3.3</title>
Chris@10 4 <meta http-equiv="Content-Type" content="text/html">
Chris@10 5 <meta name="description" content="FFTW 3.3.3">
Chris@10 6 <meta name="generator" content="makeinfo 4.13">
Chris@10 7 <link title="Top" rel="start" href="index.html#Top">
Chris@10 8 <link rel="up" href="Distributed_002dmemory-FFTW-with-MPI.html#Distributed_002dmemory-FFTW-with-MPI" title="Distributed-memory FFTW with MPI">
Chris@10 9 <link rel="prev" href="FFTW-MPI-Reference.html#FFTW-MPI-Reference" title="FFTW MPI Reference">
Chris@10 10 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
Chris@10 11 <!--
Chris@10 12 This manual is for FFTW
Chris@10 13 (version 3.3.3, 25 November 2012).
Chris@10 14
Chris@10 15 Copyright (C) 2003 Matteo Frigo.
Chris@10 16
Chris@10 17 Copyright (C) 2003 Massachusetts Institute of Technology.
Chris@10 18
Chris@10 19 Permission is granted to make and distribute verbatim copies of
Chris@10 20 this manual provided the copyright notice and this permission
Chris@10 21 notice are preserved on all copies.
Chris@10 22
Chris@10 23 Permission is granted to copy and distribute modified versions of
Chris@10 24 this manual under the conditions for verbatim copying, provided
Chris@10 25 that the entire resulting derived work is distributed under the
Chris@10 26 terms of a permission notice identical to this one.
Chris@10 27
Chris@10 28 Permission is granted to copy and distribute translations of this
Chris@10 29 manual into another language, under the above conditions for
Chris@10 30 modified versions, except that this permission notice may be
Chris@10 31 stated in a translation approved by the Free Software Foundation.
Chris@10 32 -->
Chris@10 33 <meta http-equiv="Content-Style-Type" content="text/css">
Chris@10 34 <style type="text/css"><!--
Chris@10 35 pre.display { font-family:inherit }
Chris@10 36 pre.format { font-family:inherit }
Chris@10 37 pre.smalldisplay { font-family:inherit; font-size:smaller }
Chris@10 38 pre.smallformat { font-family:inherit; font-size:smaller }
Chris@10 39 pre.smallexample { font-size:smaller }
Chris@10 40 pre.smalllisp { font-size:smaller }
Chris@10 41 span.sc { font-variant:small-caps }
Chris@10 42 span.roman { font-family:serif; font-weight:normal; }
Chris@10 43 span.sansserif { font-family:sans-serif; font-weight:normal; }
Chris@10 44 --></style>
Chris@10 45 </head>
Chris@10 46 <body>
Chris@10 47 <div class="node">
Chris@10 48 <a name="FFTW-MPI-Fortran-Interface"></a>
Chris@10 49 <p>
Chris@10 50 Previous:&nbsp;<a rel="previous" accesskey="p" href="FFTW-MPI-Reference.html#FFTW-MPI-Reference">FFTW MPI Reference</a>,
Chris@10 51 Up:&nbsp;<a rel="up" accesskey="u" href="Distributed_002dmemory-FFTW-with-MPI.html#Distributed_002dmemory-FFTW-with-MPI">Distributed-memory FFTW with MPI</a>
Chris@10 52 <hr>
Chris@10 53 </div>
Chris@10 54
Chris@10 55 <h3 class="section">6.13 FFTW MPI Fortran Interface</h3>
Chris@10 56
Chris@10 57 <p><a name="index-Fortran-interface-494"></a>
Chris@10 58 <a name="index-iso_005fc_005fbinding-495"></a>The FFTW MPI interface is callable from modern Fortran compilers
Chris@10 59 supporting the Fortran 2003 <code>iso_c_binding</code> standard for calling
Chris@10 60 C functions. As described in <a href="Calling-FFTW-from-Modern-Fortran.html#Calling-FFTW-from-Modern-Fortran">Calling FFTW from Modern Fortran</a>,
Chris@10 61 this means that you can directly call FFTW's C interface from Fortran
Chris@10 62 with only minor changes in syntax. There are, however, a few things
Chris@10 63 specific to the MPI interface to keep in mind:
Chris@10 64
Chris@10 65 <ul>
Chris@10 66 <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
Chris@10 67 <code>use, intrinsic :: iso_c_binding</code> as before). The
Chris@10 68 <code>fftw3-mpi.f03</code> file includes <code>fftw3.f03</code>, so you should
Chris@10 69 <em>not</em> <code>include</code> them both yourself. (You will also want to
Chris@10 70 include the MPI header file, usually via <code>include 'mpif.h'</code> or
Chris@10 71 similar, although though this is not needed by <code>fftw3-mpi.f03</code>
Chris@10 72 <i>per se</i>.) (To use the &lsquo;<samp><span class="samp">fftwl_</span></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>.)
Chris@10 73
Chris@10 74 <li>Because of the different storage conventions between C and Fortran,
Chris@10 75 you reverse the order of your array dimensions when passing them to
Chris@10 76 FFTW (see <a href="Reversing-array-dimensions.html#Reversing-array-dimensions">Reversing array dimensions</a>). This is merely a
Chris@10 77 difference in notation and incurs no performance overhead. However,
Chris@10 78 it means that, whereas in C the <em>first</em> dimension is distributed,
Chris@10 79 in Fortran the <em>last</em> dimension of your array is distributed.
Chris@10 80
Chris@10 81 <li><a name="index-MPI-communicator-496"></a>In Fortran, communicators are stored as <code>integer</code> types; there is
Chris@10 82 no <code>MPI_Comm</code> type, nor is there any way to access a C
Chris@10 83 <code>MPI_Comm</code>. Fortunately, this is taken care of for you by the
Chris@10 84 FFTW Fortran interface: whenever the C interface expects an
Chris@10 85 <code>MPI_Comm</code> type, you should pass the Fortran communicator as an
Chris@10 86 <code>integer</code>.<a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a>
Chris@10 87
Chris@10 88 <li>Because you need to call the &lsquo;<samp><span class="samp">local_size</span></samp>&rsquo; function to find out
Chris@10 89 how much space to allocate, and this may be <em>larger</em> than the
Chris@10 90 local portion of the array (see <a href="MPI-Data-Distribution.html#MPI-Data-Distribution">MPI Data Distribution</a>), you should
Chris@10 91 <em>always</em> allocate your arrays dynamically using FFTW's allocation
Chris@10 92 routines as described in <a href="Allocating-aligned-memory-in-Fortran.html#Allocating-aligned-memory-in-Fortran">Allocating aligned memory in Fortran</a>.
Chris@10 93 (Coincidentally, this also provides the best performance by
Chris@10 94 guaranteeding proper data alignment.)
Chris@10 95
Chris@10 96 <li>Because all sizes in the MPI FFTW interface are declared as
Chris@10 97 <code>ptrdiff_t</code> in C, you should use <code>integer(C_INTPTR_T)</code> in
Chris@10 98 Fortran (see <a href="FFTW-Fortran-type-reference.html#FFTW-Fortran-type-reference">FFTW Fortran type reference</a>).
Chris@10 99
Chris@10 100 <li><a name="index-fftw_005fexecute_005fdft-497"></a><a name="index-fftw_005fmpi_005fexecute_005fdft-498"></a><a name="index-new_002darray-execution-499"></a>In Fortran, because of the language semantics, we generally recommend
Chris@10 101 using the new-array execute functions for all plans, even in the
Chris@10 102 common case where you are executing the plan on the same arrays for
Chris@10 103 which the plan was created (see <a href="Plan-execution-in-Fortran.html#Plan-execution-in-Fortran">Plan execution in Fortran</a>).
Chris@10 104 However, note that in the MPI interface these functions are changed:
Chris@10 105 <code>fftw_execute_dft</code> becomes <code>fftw_mpi_execute_dft</code>,
Chris@10 106 etcetera. See <a href="Using-MPI-Plans.html#Using-MPI-Plans">Using MPI Plans</a>.
Chris@10 107
Chris@10 108 </ul>
Chris@10 109
Chris@10 110 <p>For example, here is a Fortran code snippet to perform a distributed
Chris@10 111 L&nbsp;&times;&nbsp;M complex DFT in-place. (This assumes you have already
Chris@10 112 initialized MPI with <code>MPI_init</code> and have also performed
Chris@10 113 <code>call fftw_mpi_init</code>.)
Chris@10 114
Chris@10 115 <pre class="example"> use, intrinsic :: iso_c_binding
Chris@10 116 include 'fftw3-mpi.f03'
Chris@10 117 integer(C_INTPTR_T), parameter :: L = ...
Chris@10 118 integer(C_INTPTR_T), parameter :: M = ...
Chris@10 119 type(C_PTR) :: plan, cdata
Chris@10 120 complex(C_DOUBLE_COMPLEX), pointer :: data(:,:)
Chris@10 121 integer(C_INTPTR_T) :: i, j, alloc_local, local_M, local_j_offset
Chris@10 122
Chris@10 123 ! <span class="roman">get local data size and allocate (note dimension reversal)</span>
Chris@10 124 alloc_local = fftw_mpi_local_size_2d(M, L, MPI_COMM_WORLD, &amp;
Chris@10 125 local_M, local_j_offset)
Chris@10 126 cdata = fftw_alloc_complex(alloc_local)
Chris@10 127 call c_f_pointer(cdata, data, [L,local_M])
Chris@10 128
Chris@10 129 ! <span class="roman">create MPI plan for in-place forward DFT (note dimension reversal)</span>
Chris@10 130 plan = fftw_mpi_plan_dft_2d(M, L, data, data, MPI_COMM_WORLD, &amp;
Chris@10 131 FFTW_FORWARD, FFTW_MEASURE)
Chris@10 132
Chris@10 133 ! <span class="roman">initialize data to some function</span> my_function(i,j)
Chris@10 134 do j = 1, local_M
Chris@10 135 do i = 1, L
Chris@10 136 data(i, j) = my_function(i, j + local_j_offset)
Chris@10 137 end do
Chris@10 138 end do
Chris@10 139
Chris@10 140 ! <span class="roman">compute transform (as many times as desired)</span>
Chris@10 141 call fftw_mpi_execute_dft(plan, data, data)
Chris@10 142
Chris@10 143 call fftw_destroy_plan(plan)
Chris@10 144 call fftw_free(cdata)
Chris@10 145 </pre>
Chris@10 146 <p>Note that when we called <code>fftw_mpi_local_size_2d</code> and
Chris@10 147 <code>fftw_mpi_plan_dft_2d</code> with the dimensions in reversed order,
Chris@10 148 since a L&nbsp;&times;&nbsp;M Fortran array is viewed by FFTW in C as a
Chris@10 149 M&nbsp;&times;&nbsp;L array. This means that the array was distributed over
Chris@10 150 the <code>M</code> dimension, the local portion of which is a
Chris@10 151 L&nbsp;&times;&nbsp;local_M array in Fortran. (You must <em>not</em> use an
Chris@10 152 <code>allocate</code> statement to allocate an L&nbsp;&times;&nbsp;local_M array,
Chris@10 153 however; you must allocate <code>alloc_local</code> complex numbers, which
Chris@10 154 may be greater than <code>L * local_M</code>, in order to reserve space for
Chris@10 155 intermediate steps of the transform.) Finally, we mention that
Chris@10 156 because C's array indices are zero-based, the <code>local_j_offset</code>
Chris@10 157 argument can conveniently be interpreted as an offset in the 1-based
Chris@10 158 <code>j</code> index (rather than as a starting index as in C).
Chris@10 159
Chris@10 160 <p>If instead you had used the <code>ior(FFTW_MEASURE,
Chris@10 161 FFTW_MPI_TRANSPOSED_OUT)</code> flag, the output of the transform would be a
Chris@10 162 transposed M&nbsp;&times;&nbsp;local_L array, associated with the <em>same</em>
Chris@10 163 <code>cdata</code> allocation (since the transform is in-place), and which
Chris@10 164 you could declare with:
Chris@10 165
Chris@10 166 <pre class="example"> complex(C_DOUBLE_COMPLEX), pointer :: tdata(:,:)
Chris@10 167 ...
Chris@10 168 call c_f_pointer(cdata, tdata, [M,local_L])
Chris@10 169 </pre>
Chris@10 170 <p>where <code>local_L</code> would have been obtained by changing the
Chris@10 171 <code>fftw_mpi_local_size_2d</code> call to:
Chris@10 172
Chris@10 173 <pre class="example"> alloc_local = fftw_mpi_local_size_2d_transposed(M, L, MPI_COMM_WORLD, &amp;
Chris@10 174 local_M, local_j_offset, local_L, local_i_offset)
Chris@10 175 </pre>
Chris@10 176 <div class="footnote">
Chris@10 177 <hr>
Chris@10 178 <h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> Technically, this is because you aren't
Chris@10 179 actually calling the C functions directly. You are calling wrapper
Chris@10 180 functions that translate the communicator with <code>MPI_Comm_f2c</code>
Chris@10 181 before calling the ordinary C interface. This is all done
Chris@10 182 transparently, however, since the <code>fftw3-mpi.f03</code> interface file
Chris@10 183 renames the wrappers so that they are called in Fortran with the same
Chris@10 184 names as the C interface functions.</p>
Chris@10 185
Chris@10 186 <hr></div>
Chris@10 187
Chris@10 188 </body></html>
Chris@10 189