WebSVN - shark - Blame - Rev 1618 - /shark/branches/xen/ports/fftw/doc/fftw

Rev	Author	Line No.	Line
2	pj	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
		2	<HTML>
		3	<HEAD>
		4	<!-- This HTML file has been created by texi2html 1.52
		5	from fftw.texi on 18 May 1999 -->
		6
		7	<TITLE>FFTW - Calling FFTW from Fortran</TITLE>
		8	</HEAD>
		9	<BODY TEXT="#000000" BGCOLOR="#FFFFFF">
		10	Go to the <A HREF="fftw_1.html">first</A>, <A HREF="fftw_4.html">previous</A>, <A HREF="fftw_6.html">next</A>, <A HREF="fftw_10.html">last</A> section, <A HREF="fftw_toc.html">table of contents</A>.
		11	<P><HR><P>
		12
		13
		14	<H1><A NAME="SEC62">Calling FFTW from Fortran</A></H1>
		15
		16	<P>
		17	<A NAME="IDX290"></A>
		18	The standard FFTW libraries include special wrapper functions that allow
		19	Fortran programs to call FFTW subroutines. This chapter describes how
		20	those functions may be employed to use FFTW from Fortran. We assume
		21	here that the reader is already familiar with the usage of FFTW in C, as
		22	described elsewhere in this manual.
		23
		24
		25	<P>
		26	In general, it is not possible to call C functions directly from
		27	Fortran, due to Fortran's inability to pass arguments by value and also
		28	because Fortran compilers typically expect identifiers to be mangled
		29	<A NAME="IDX291"></A>
		30	somehow for linking. However, if C functions are written in a special
		31	way, they <EM>are</EM> callable from Fortran, and we have employed this
		32	technique to create Fortran-callable "wrapper" functions around the
		33	main FFTW routines. These wrapper functions are included in the FFTW
		34	libraries by default, unless a Fortran compiler isn't found on your
		35	system or <CODE>--disable-fortran</CODE> is included in the <CODE>configure</CODE>
		36	flags.
		37
		38
		39	<P>
		40	As a result, calling FFTW from Fortran requires little more than
		41	appending <SAMP>`<CODE>_f77</CODE>'</SAMP> to the function names and then linking
		42	normally with the FFTW libraries. There are a few wrinkles, however, as
		43	we shall discuss below.
		44
		45
		46
		47
		48	<H2><A NAME="SEC63">Wrapper Routines</A></H2>
		49
		50	<P>
		51	All of the uniprocessor and multi-threaded transform routines have
		52	Fortran-callable wrappers, except for the wisdom import/export functions
		53	(since it is not possible to exchange string and file arguments portably
		54	with Fortran). The name of the wrapper routine is the same as that of
		55	the corresponding C routine, but with <CODE>fftw/fftwnd/rfftw/rfftwnd</CODE>
		56	replaced by <CODE>fftw_f77/fftwnd_f77/rfftw_f77/rfftwnd_f77</CODE>. For
		57	example, in Fortran, instead of calling <CODE>fftw_one</CODE> you would call
		58	<CODE>fftw_f77_one</CODE>.<A NAME="DOCF8" HREF="fftw_foot.html#FOOT8">(8)</A>
		59	<A NAME="IDX292"></A>
		60	For the most part, all of the arguments to the functions are the same,
		61	with the following exceptions:
		62
		63
		64
		65	<UL>
		66
		67	<LI>
		68
		69	Any function that returns a value (e.g. <CODE>fftw_create_plan</CODE>) is
		70	converted into a subroutine. The return value is converted into an
		71	additional (first) parameter of the wrapper subroutine. (The reason for
		72	this is that some Fortran implementations seem to have trouble with C
		73	function return values.)
		74
		75	<LI>
		76
		77	<A NAME="IDX293"></A>
		78	When performing one-dimensional <CODE>FFTW_IN_PLACE</CODE> transforms, you
		79	don't have the option of passing <CODE>NULL</CODE> for the <CODE>out</CODE> argument
		80	(since there is no way to pass <CODE>NULL</CODE> from Fortran). Therefore,
		81	when performing such transforms, you <EM>must</EM> allocate and pass a
		82	contiguous scratch array of the same size as the transform. Note that
		83	for in-place multi-dimensional (<CODE>(r)fftwnd</CODE>) transforms, the
		84	<CODE>out</CODE> argument is ignored, so you can pass anything for that
		85	parameter.
		86
		87	<LI>
		88
		89	<A NAME="IDX294"></A>
		90	The wrapper routines expect multi-dimensional arrays to be in
		91	column-major order, which is the ordinary format of Fortran arrays.
		92	They do this transparently and costlessly simply by reversing the order
		93	of the dimensions passed to FFTW, but this has one important consequence
		94	for multi-dimensional real-complex transforms, discussed below.
		95
		96	<LI>
		97
		98	<CODE>plan</CODE> variables (what would be of type <CODE>fftw_plan</CODE>,
		99	<CODE>rfftwnd_plan</CODE>, etcetera, in C), must be declared as a type that is
		100	the same size as a pointer (address) on your machine. (Fortran has no
		101	generic pointer type.) The Fortran <CODE>integer</CODE> type is usually the
		102	same size as a pointer, but you need to be wary (especially on 64-bit
		103	machines). (You could also use <CODE>integer*4</CODE> on a 32-bit machine and
		104	<CODE>integer*8</CODE> on a 64-bit machine.) Ugh. (<CODE>g77</CODE> has a special
		105	type, <CODE>integer(kind=7)</CODE>, that is defined to be the same size as a
		106	pointer.)
		107
		108	</UL>
		109
		110	<P>
		111	<A NAME="IDX295"></A>
		112	In general, you should take care to use Fortran data types that
		113	correspond to (i.e. are the same size as) the C types used by FFTW. If
		114	your C and Fortran compilers are made by the same vendor, the
		115	correspondence is usually straightforward (i.e. <CODE>integer</CODE>
		116	corresponds to <CODE>int</CODE>, <CODE>real</CODE> corresponds to <CODE>float</CODE>,
		117	etcetera). Such simple correspondences are assumed in the examples
		118	below. The examples also assume that FFTW was compiled in
		119	double precision (the default).
		120
		121
		122
		123
		124	<H2><A NAME="SEC64">FFTW Constants in Fortran</A></H2>
		125
		126	<P>
		127	When creating plans in FFTW, a number of constants are used to specify
		128	options, such as <CODE>FFTW_FORWARD</CODE> or <CODE>FFTW_USE_WISDOM</CODE>. The
		129	same constants must be used with the wrapper routines, but of course the
		130	C header files where the constants are defined can't be incorporated
		131	directly into Fortran code.
		132
		133
		134	<P>
		135	Instead, we have placed Fortran equivalents of the FFTW constant
		136	definitions in the file <CODE>fortran/fftw_f77.i</CODE> of the FFTW package.
		137	If your Fortran compiler supports a preprocessor, you can use that to
		138	incorporate this file into your code whenever you need to call FFTW.
		139	Otherwise, you will have to paste the constant definitions in directly.
		140	They are:
		141
		142
		143
		144	<PRE>
		145	integer FFTW_FORWARD,FFTW_BACKWARD
		146	parameter (FFTW_FORWARD=-1,FFTW_BACKWARD=1)
		147
		148	integer FFTW_REAL_TO_COMPLEX,FFTW_COMPLEX_TO_REAL
		149	parameter (FFTW_REAL_TO_COMPLEX=-1,FFTW_COMPLEX_TO_REAL=1)
		150
		151	integer FFTW_ESTIMATE,FFTW_MEASURE
		152	parameter (FFTW_ESTIMATE=0,FFTW_MEASURE=1)
		153
		154	integer FFTW_OUT_OF_PLACE,FFTW_IN_PLACE,FFTW_USE_WISDOM
		155	parameter (FFTW_OUT_OF_PLACE=0)
		156	parameter (FFTW_IN_PLACE=8,FFTW_USE_WISDOM=16)
		157
		158	integer FFTW_THREADSAFE
		159	parameter (FFTW_THREADSAFE=128)
		160	</PRE>
		161
		162	<P>
		163	<A NAME="IDX296"></A>
		164	In C, you combine different flags (like <CODE>FFTW_USE_WISDOM</CODE> and
		165	<CODE>FFTW_MEASURE</CODE>) using the <SAMP>`<CODE>\|</CODE>'</SAMP> operator; in Fortran you
		166	should just use <SAMP>`<CODE>+</CODE>'</SAMP>.
		167
		168
		169
		170
		171	<H2><A NAME="SEC65">Fortran Examples</A></H2>
		172
		173	<P>
		174	In C you might have something like the following to transform a
		175	one-dimensional complex array:
		176
		177
		178
		179	<PRE>
		180	fftw_complex in[N], *out[N];
		181	fftw_plan plan;
		182
		183	plan = fftw_create_plan(N,FFTW_FORWARD,FFTW_ESTIMATE);
		184	fftw_one(plan,in,out);
		185	fftw_destroy_plan(plan);
		186	</PRE>
		187
		188	<P>
		189	In Fortran, you use the following to accomplish the same thing:
		190
		191
		192
		193	<PRE>
		194	double complex in, out
		195	dimension in(N), out(N)
		196	integer plan
		197
		198	call fftw_f77_create_plan(plan,N,FFTW_FORWARD,FFTW_ESTIMATE)
		199	call fftw_f77_one(plan,in,out)
		200	call fftw_f77_destroy_plan(plan)
		201	</PRE>
		202
		203	<P>
		204	<A NAME="IDX297"></A>
		205	<A NAME="IDX298"></A>
		206	<A NAME="IDX299"></A>
		207
		208
		209	<P>
		210	Notice how all routines are called as Fortran subroutines, and the plan
		211	is returned via the first argument to <CODE>fftw_f77_create_plan</CODE>. To
		212	do the same thing, but using 8 threads in parallel
		213	(see Section <A HREF="fftw_4.html#SEC48">Multi-threaded FFTW</A>), you would simply replace the call to
		214	<CODE>fftw_f77_one</CODE> with:
		215
		216
		217
		218	<PRE>
		219	call fftw_f77_threads_one(8,plan,in,out)
		220	</PRE>
		221
		222	<P>
		223	<A NAME="IDX300"></A>
		224
		225
		226	<P>
		227	To transform a three-dimensional array in-place with C, you might do:
		228
		229
		230
		231	<PRE>
		232	fftw_complex arr[L][M][N];
		233	fftwnd_plan plan;
		234	int n[3] = {L,M,N};
		235
		236	plan = fftwnd_create_plan(3,n,FFTW_FORWARD,
		237	FFTW_ESTIMATE \| FFTW_IN_PLACE);
		238	fftwnd_one(plan, arr, 0);
		239	fftwnd_destroy_plan(plan);
		240	</PRE>
		241
		242	<P>
		243	In Fortran, you would use this instead:
		244
		245
		246
		247	<PRE>
		248	double complex arr
		249	dimension arr(L,M,N)
		250	integer n
		251	dimension n(3)
		252	integer plan
		253
		254	n(1) = L
		255	n(2) = M
		256	n(3) = N
		257	call fftwnd_f77_create_plan(plan,3,n,FFTW_FORWARD,
		258	+ FFTW_ESTIMATE + FFTW_IN_PLACE)
		259	call fftwnd_f77_one(plan, arr, 0)
		260	call fftwnd_f77_destroy_plan(plan)
		261	</PRE>
		262
		263	<P>
		264	<A NAME="IDX301"></A>
		265	<A NAME="IDX302"></A>
		266	<A NAME="IDX303"></A>
		267
		268
		269	<P>
		270	Instead of calling <CODE>fftwnd_f77_create_plan(plan,3,n,...)</CODE>, we could
		271	also have called <CODE>fftw3d_f77_create_plan(plan,L,M,N,...)</CODE>.
		272	<A NAME="IDX304"></A>
		273
		274
		275	<P>
		276	Note that we pass the array dimensions in the "natural" order; also
		277	note that the last argument to <CODE>fftwnd_f77</CODE> is ignored since the
		278	transform is <CODE>FFTW_IN_PLACE</CODE>.
		279
		280
		281	<P>
		282	To transform a one-dimensional real array in Fortran, you might do:
		283
		284
		285
		286	<PRE>
		287	double precision in, out
		288	dimension in(N), out(N)
		289	integer plan
		290
		291	call rfftw_f77_create_plan(plan,N,FFTW_REAL_TO_COMPLEX,
		292	+ FFTW_ESTIMATE)
		293	call rfftw_f77_one(plan,in,out)
		294	call rfftw_f77_destroy_plan(plan)
		295	</PRE>
		296
		297	<P>
		298	<A NAME="IDX305"></A>
		299	<A NAME="IDX306"></A>
		300	<A NAME="IDX307"></A>
		301
		302
		303	<P>
		304	To transform a two-dimensional real array, out of place, you might use
		305	the following:
		306
		307
		308
		309	<PRE>
		310	double precision in
		311	double complex out
		312	dimension in(M,N), out(M/2 + 1, N)
		313	integer plan
		314
		315	call rfftw2d_f77_create_plan(plan,M,N,FFTW_REAL_TO_COMPLEX,
		316	+ FFTW_ESTIMATE)
		317	call rfftwnd_f77_one_real_to_complex(plan, in, out)
		318	call rfftwnd_f77_destroy_plan(plan)
		319	</PRE>
		320
		321	<P>
		322	<A NAME="IDX308"></A>
		323	<A NAME="IDX309"></A>
		324	<A NAME="IDX310"></A>
		325
		326
		327	<P>
		328	<B>Important:</B> Notice that it is the <EM>first</EM> dimension of the
		329	complex output array that is cut in half in Fortran, rather than the
		330	last dimension as in C. This is a consequence of the wrapper routines
		331	reversing the order of the array dimensions passed to FFTW so that the
		332	Fortran program can use its ordinary column-major order.
		333	<A NAME="IDX311"></A>
		334	<A NAME="IDX312"></A>
		335
		336
		337	<P><HR><P>
		338	Go to the <A HREF="fftw_1.html">first</A>, <A HREF="fftw_4.html">previous</A>, <A HREF="fftw_6.html">next</A>, <A HREF="fftw_10.html">last</A> section, <A HREF="fftw_toc.html">table of contents</A>.
		339	</BODY>
		340	</HTML>

Subversion Repositories shark

(root)/shark/branches/xen/ports/fftw/doc/fftw_5.htm - Rev 1618