Mercurial > hg > sv-dependency-builds

comparison src/fftw-3.3.3/doc/html/Overview-of-Fortran-interface.html @ 10:37bf6b4a2645

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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>Overview of Fortran interface - 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="Calling-FFTW-from-Modern-Fortran.html#Calling-FFTW-from-Modern-Fortran" title="Calling FFTW from Modern Fortran">
9 <link rel="prev" href="Calling-FFTW-from-Modern-Fortran.html#Calling-FFTW-from-Modern-Fortran" title="Calling FFTW from Modern Fortran">
10 <link rel="next" href="Reversing-array-dimensions.html#Reversing-array-dimensions" title="Reversing array dimensions">
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="Overview-of-Fortran-interface"></a>
50 <p>
51 Next:&nbsp;<a rel="next" accesskey="n" href="Reversing-array-dimensions.html#Reversing-array-dimensions">Reversing array dimensions</a>,
52 Previous:&nbsp;<a rel="previous" accesskey="p" href="Calling-FFTW-from-Modern-Fortran.html#Calling-FFTW-from-Modern-Fortran">Calling FFTW from Modern Fortran</a>,
53 Up:&nbsp;<a rel="up" accesskey="u" href="Calling-FFTW-from-Modern-Fortran.html#Calling-FFTW-from-Modern-Fortran">Calling FFTW from Modern Fortran</a>
54 <hr>
55 </div>
56
57 <h3 class="section">7.1 Overview of Fortran interface</h3>
58
59 <p>FFTW provides a file <code>fftw3.f03</code> that defines Fortran 2003
60 interfaces for all of its C routines, except for the MPI routines
61 described elsewhere, which can be found in the same directory as
62 <code>fftw3.h</code> (the C header file). In any Fortran subroutine where
63 you want to use FFTW functions, you should begin with:
64
65 <p><a name="index-iso_005fc_005fbinding-502"></a>
66 <pre class="example"> use, intrinsic :: iso_c_binding
67 include 'fftw3.f03'
68 </pre>
69 <p>This includes the interface definitions and the standard
70 <code>iso_c_binding</code> module (which defines the equivalents of C
71 types). You can also put the FFTW functions into a module if you
72 prefer (see <a href="Defining-an-FFTW-module.html#Defining-an-FFTW-module">Defining an FFTW module</a>).
73
74 <p>At this point, you can now call anything in the FFTW C interface
75 directly, almost exactly as in C other than minor changes in syntax.
76 For example:
77
78 <p><a name="index-fftw_005fplan_005fdft_005f2d-503"></a><a name="index-fftw_005fexecute_005fdft-504"></a><a name="index-fftw_005fdestroy_005fplan-505"></a>
79 <pre class="example"> type(C_PTR) :: plan
80 complex(C_DOUBLE_COMPLEX), dimension(1024,1000) :: in, out
81 plan = fftw_plan_dft_2d(1000,1024, in,out, FFTW_FORWARD,FFTW_ESTIMATE)
82 ...
83 call fftw_execute_dft(plan, in, out)
84 ...
85 call fftw_destroy_plan(plan)
86 </pre>
87 <p>A few important things to keep in mind are:
88
89 <ul>
90 <li><a name="index-fftw_005fcomplex-506"></a><a name="index-C_005fPTR-507"></a><a name="index-C_005fINT-508"></a><a name="index-C_005fDOUBLE-509"></a><a name="index-C_005fDOUBLE_005fCOMPLEX-510"></a>FFTW plans are <code>type(C_PTR)</code>. Other C types are mapped in the
91 obvious way via the <code>iso_c_binding</code> standard: <code>int</code> turns
92 into <code>integer(C_INT)</code>, <code>fftw_complex</code> turns into
93 <code>complex(C_DOUBLE_COMPLEX)</code>, <code>double</code> turns into
94 <code>real(C_DOUBLE)</code>, and so on. See <a href="FFTW-Fortran-type-reference.html#FFTW-Fortran-type-reference">FFTW Fortran type reference</a>.
95
96 <li>Functions in C become functions in Fortran if they have a return value,
97 and subroutines in Fortran otherwise.
98
99 <li>The ordering of the Fortran array dimensions must be <em>reversed</em>
100 when they are passed to the FFTW plan creation, thanks to differences
101 in array indexing conventions (see <a href="Multi_002ddimensional-Array-Format.html#Multi_002ddimensional-Array-Format">Multi-dimensional Array Format</a>). This is <em>unlike</em> the legacy Fortran interface
102 (see <a href="Fortran_002dinterface-routines.html#Fortran_002dinterface-routines">Fortran-interface routines</a>), which reversed the dimensions
103 for you. See <a href="Reversing-array-dimensions.html#Reversing-array-dimensions">Reversing array dimensions</a>.
104
105 <li><a name="index-alignment-511"></a><a name="index-SIMD-512"></a>Using ordinary Fortran array declarations like this works, but may
106 yield suboptimal performance because the data may not be not aligned
107 to exploit SIMD instructions on modern proessors (see <a href="SIMD-alignment-and-fftw_005fmalloc.html#SIMD-alignment-and-fftw_005fmalloc">SIMD alignment and fftw_malloc</a>). Better performance will often be obtained
108 by allocating with &lsquo;<samp><span class="samp">fftw_alloc</span></samp>&rsquo;. See <a href="Allocating-aligned-memory-in-Fortran.html#Allocating-aligned-memory-in-Fortran">Allocating aligned memory in Fortran</a>.
109
110 <li><a name="index-fftw_005fexecute-513"></a>Similar to the legacy Fortran interface (see <a href="FFTW-Execution-in-Fortran.html#FFTW-Execution-in-Fortran">FFTW Execution in Fortran</a>), we currently recommend <em>not</em> using <code>fftw_execute</code>
111 but rather using the more specialized functions like
112 <code>fftw_execute_dft</code> (see <a href="New_002darray-Execute-Functions.html#New_002darray-Execute-Functions">New-array Execute Functions</a>).
113 However, you should execute the plan on the <code>same arrays</code> as the
114 ones for which you created the plan, unless you are especially
115 careful. See <a href="Plan-execution-in-Fortran.html#Plan-execution-in-Fortran">Plan execution in Fortran</a>. To prevent
116 you from using <code>fftw_execute</code> by mistake, the <code>fftw3.f03</code>
117 file does not provide an <code>fftw_execute</code> interface declaration.
118
119 <li><a name="index-flags-514"></a>Multiple planner flags are combined with <code>ior</code> (equivalent to &lsquo;<samp><span class="samp">|</span></samp>&rsquo; in C). e.g. <code>FFTW_MEASURE | FFTW_DESTROY_INPUT</code> becomes <code>ior(FFTW_MEASURE, FFTW_DESTROY_INPUT)</code>. (You can also use &lsquo;<samp><span class="samp">+</span></samp>&rsquo; as long as you don't try to include a given flag more than once.)
120
121 </ul>
122
123 <ul class="menu">
124 <li><a accesskey="1" href="Extended-and-quadruple-precision-in-Fortran.html#Extended-and-quadruple-precision-in-Fortran">Extended and quadruple precision in Fortran</a>
125 </ul>
126
127 </body></html>
128