FFTW¶
Usage
use FFTW;
or
import FFTW;
Submodules
FFT computations via key routines from FFTW (version 3).
This module defines Chapel wrappers for key 64bit
routines from FFTW (http://www.fftw.org), version 3. The routines
in this module exposes the simple FFTW interface. The full C API
may be accessed through the C_FFTW
submodule.
Over time, the intention is to expand these modules to support additional
routines, prioritizing based on requests and feedback from users.
To use this module:
Ensure that FFTW (version 3) is installed on your system. The current version of the Chapel module only supports double precision
real(64)
transforms. We do support using the FFTW compatible wrappers provided by the Intel Math Kernel Library (MKL) (see below for usage).Add
use FFTW;
to your Chapel code.Include the appropriate libraries in your compilation command.
For a standard FFTW installation, this may be as simple as including
lfftw3
when compiling. You may also need to use theI
andL
flags to specify the locations of the header and library files if these are in nonstandard locations.Intel MKL : To use the MKL FFTW wrappers, compile with
sisFFTW_MKL
to include thefftw3_mkl.h
header in addition to the usualfftw3.h
header file. You may also need to addI${MKLROOT}/include/fftw
to point the compiler to the location of these header files. Refer to the Intel MKL documentation for the appropriate libraries to include.
If you wish to run FFTW in a multithreaded mode:
Initialize FFTW for multithreaded support. You may do this by either setting the compiletime config parameter
autoInitFFTW_MT
to true or callinginit_FFTW_MT
.Set the number of threads for subsequent FFTW plans with
plan_with_nthreads
. If you initialized automatically, this module defaults to usinghere.maxTaskPar
. There is no limit on the number of times you can callplan_with_nthreads
.Link with the appropriate multithreaded FFTW libraries.
Note the both
init_FFTW_MT
andplan_with_nthreads
are multilocale aware and will automatically run on all locales. However, the FFTW plans created by this routine are not distributed.When all multithreaded usage is complete, call
cleanup_threads
.
As in standard FFTW usage, the flow is to:
Create plan(s) using the
plan_dft*
routines.Execute the plan(s) one or more times using
execute
.Destroy the plan(s) using
destroy_plan
.Cleanup, using
cleanup
(andcleanup_threads
if multithreaded).
Note that each of the Chapel plan_dft*
routines
support both inplace and outofplace versions of the
transforms, where the former versions use a single array for both
input and output, and the latter use two distinct arrays.
In future versions of this module, we anticipate improving the plan_dft*() interfaces to make better use of Chapel features and move further away from Cisms (like the overloaded role of flags and the use of Cbased types). Such features are expected to take advantage of Chapel’s support for default argument values and keywordbased argument passing. We are also thinking about changing the interface for the inplace routines to use array slicing rather than separate arguments for the array and domain.
 config param isFFTW_MKL = false¶
Set this to true if you are using the Intel MKL FFTW wrappers
 config param autoInitFFTW_MT = false¶
Set this config parameter to true to automatically initialize FFTW for thread support, and setup FFTW to generate multithreaded plans (with the number of threads equal to maxTaskPar in Chapel).
If you keep the default value of false, then call
init_FFTW_MT()
to initialize threadsupport for Chapel.Note that
plan_with_nthreads
can be called at any time and changes the number of threads used by plans created after the call.
 config param noFFTWsizeChecks = false¶
Controls executiontime array size checks in the FFTW
plan_dft
routines (set to true to disable checks).
 type fftw_plan = c_ptr(void)¶
An opaque type used to store and reuse FFTW plans across multiple routines.
 type FFTW_Flag = c_uint¶
Type alias for FFTW flags
 type FFTW_Direction = c_int¶
Type alias for FFT directions
 type FFTW_R2R = c_int¶
Type alias for FFTW R2R type
 proc plan_dft(input: [?Din] complex(128), ref output: [?Dout] complex(128), sign: FFTW_Direction, flags: FFTW_Flag): fftw_plan¶
Creates a plan for an outofplace complextocomplex DFT.
 Arguments
input : [] complex(128) – The input array, which can be of any rank
output : [] complex(128) – The output array, whose size and shape must match the input array’s
sign : FFTW_Direction –
FFTW_FORWARD
orFFTW_BACKWARD
flags : FFTW_Flag – the bitwiseor of any planningrigor or algorithmrestriction flags that should be used in creating the plan (e.g.,
FFTW_MEASURE

FFTW_PRESERVE_INPUT
)
 Returns
The
fftw_plan
representing the resulting plan
 proc plan_dft(ref arr: [] complex(128), sign: FFTW_Direction, flags: FFTW_Flag): fftw_plan
Creates a plan for an inplace complextocomplex DFT.
 Arguments
arr : [] complex(128) – The array to use as the inplace input/output array.
sign : FFTW_Direction –
FFTW_FORWARD
orFFTW_BACKWARD
flags : FFTW_Flag – the bitwiseor of any planningrigor or algorithmrestriction flags that should be used in creating the plan (e.g.,
FFTW_MEASURE

FFTW_PRESERVE_INPUT
)
 Returns
The
fftw_plan
representing the resulting plan
 proc plan_dft_r2c(input: [?Din] real(64), ref output: [?Dout] complex(128), flags: FFTW_Flag): fftw_plan¶
Create a plan for a realtocomplex, outofplace DFT.
 Arguments
input : [] real(64) – The input array, which can be of any rank
output : [] complex(128) – The output array, whose size and shape must match the input array’s, except for the leading dimension which should be n/2 + 1, where n is the size of the input array’s leading dimension. See the FFTW documentation for more information.
flags : FFTW_Flag – the bitwiseor of any planningrigor or algorithmrestriction flags that should be used in creating the plan (e.g.,
FFTW_MEASURE

FFTW_PRESERVE_INPUT
)
 Returns
The
fftw_plan
representing the resulting plan
 proc plan_dft_r2c(realDom: domain, ref arr: [?D] ?t, flags: FFTW_Flag): fftw_plan where t == real  t == complex
Create a plan for a realtocomplex, inplace DFT.
 Arguments
realDom : domain – Describes the indices of the ‘real’ view of the array
arr : [] T where T is of type real(64) or complex(128) –
The array to be used as the inplace input/output array. If passing in an array of real elements, the leading dimension of the array must be padded to store 2(n/2 + 1) elements, where n is the size of the corresponding dimension of realDom. If passing in an array of complex elements, the leading dimension should be (n/2 + 1). See the FFTW documentation for more information.
flags : FFTW_Flag – the bitwiseor of any planningrigor or algorithmrestriction flags that should be used in creating the plan (e.g.,
FFTW_MEASURE

FFTW_PRESERVE_INPUT
)
 Returns
The
fftw_plan
representing the resulting plan
 proc plan_dft_c2r(input: [?Din] complex(128), ref output: [?Dout] real(64), flags: FFTW_Flag): fftw_plan¶
Create a plan for a complextoreal, outofplace DFT.
 Arguments
input : [] complex(128) –
The input array, whose size and shape must match the output array’s, except for the leading dimension which should be n/2 + 1, where n is the size of the output array’s leading dimension. See the FFTW documentation for more information.
output : [] real(64) – The output array
flags : FFTW_Flag – the bitwiseor of any planningrigor or algorithmrestriction flags that should be used in creating the plan (e.g.,
FFTW_MEASURE

FFTW_PRESERVE_INPUT
)
 Returns
The
fftw_plan
representing the resulting plan
 proc plan_dft_c2r(realDom: domain, ref arr: [?D] ?t, flags: FFTW_Flag): fftw_plan where t == real  t == complex
Create a plan for a complextoreal, inplace DFT.
 Arguments
realDom : domain – Describes the indices of the ‘real’ view of the array
arr : [] T where T is of type real(64) or complex(128) –
The array to be used as the inplace input/output array. If passing in an array of real elements, the leading dimension of the array must be padded to store 2(n/2 + 1) elements, where n is the size of the corresponding dimension of realDom. If passing in an array of complex elements, the leading dimension should be (n/2 + 1). See the FFTW documentation for more information.
flags : FFTW_Flag – the bitwiseor of any planningrigor or algorithmrestriction flags that should be used in creating the plan (e.g.,
FFTW_MEASURE

FFTW_PRESERVE_INPUT
)
 Returns
The
fftw_plan
representing the resulting plan
 proc execute(const plan: fftw_plan)¶
Execute an FFTW plan.
 Arguments
plan : fftw_plan – The plan to execute, as computed by a plan_dft*() routine.
 proc destroy_plan(plan: fftw_plan)¶
Destroy an FFTW plan.
 Arguments
plan : fftw_plan – The plan to destroy
 proc cleanup()¶
Clean up FFTW overall.
 const FFTW_FORWARD: FFTW_Direction¶
Request a forward transform (i.e., use a negative exponent in the transform).
 const FFTW_BACKWARD: FFTW_Direction¶
Request a backward transform (i.e., use a positive exponent in the transform).
 const FFTW_ESTIMATE: FFTW_Flag¶
Specify that a simple heuristic should be used to pick a plan quickly. This will prevent the input/output arrays from being overwritten during planning.
 const FFTW_MEASURE: FFTW_Flag¶
Specify that FFTW should try and find an optimized plan by computing several FFTs and measuring their execution time. This can consume some time.
 const FFTW_PATIENT: FFTW_Flag¶
Specify that FFTW should expend a greater effort finding an optimized plan.
 const FFTW_EXHAUSTIVE: FFTW_Flag¶
Specify that FFTW should expend an even greater effort finding an optimized plan.
 const FFTW_WISDOM_ONLY: FFTW_Flag¶
This is a special planning mode that is useful for querying whether wisdom is available. When using it, the plan is only created when wisdom is available for the given problem; otherwise a null plan is returned. This can be combined with other flags to create a plan if the wisdom available was created in that mode (e.g.,
FFTW_WISDOM_ONLY

FFTW_PATIENT
). For more details on this flag and the previous four, refer to Section 4.3.2 of the FFTW manual
 const FFTW_DESTROY_INPUT: FFTW_Flag¶
Specify that an outofplace transform is permitted to overwrite its input array with arbitrary data. This permits more efficient algorithms to be used in some cases.
 const FFTW_PRESERVE_INPUT: FFTW_Flag¶
Specify that an outofplace transform cannot change its input array.
 const FFTW_UNALIGNED: FFTW_Flag¶
Specify that the algorithm may not impose any unusual alignment requirements on the input/output arrays. This flag should not be necessary for current Chapel use since the planner will automatically detect such cases. For more details on this flag and the previous two, refer to Section 4.3.2 of the FFTW manual.
 const FFTW_R2HC: FFTW_R2R¶
Use the halfcomplex form of array storage
 const FFTW_HC2R: FFTW_R2R¶
 const FFTW_DHT: FFTW_R2R¶
Discrete Hartley Transforms.
 const FFTW_REDFT00: FFTW_R2R¶
Specify the type of discrete cosine and discrete sine transforms to use.
 const FFTW_REDFT01: FFTW_R2R¶
 const FFTW_REDFT10: FFTW_R2R¶
 const FFTW_REDFT11: FFTW_R2R¶
 const FFTW_RODFT00: FFTW_R2R¶
 const FFTW_RODFT01: FFTW_R2R¶
 const FFTW_RODFT10: FFTW_R2R¶
 const FFTW_RODFT11: FFTW_R2R¶
 proc init_FFTW_MT()¶
Initialize the FFTW module to support multithreading. This has the effect of calling the FFTW C routine
fftw_init_threads()
on all locales, halting the Chapel program if any of the calls generate an error.
 proc plan_with_nthreads(nthreads: int = 0)¶
Register the number of threads to use for multithreaded FFTW plans on all locales. If fewer than one thread is requested, each locale will default to
here.maxTaskPar
threads. Note that this routine can be called multiple times, overwriting previous values. Arguments
nthreads : int – The number of threads to use.
 proc cleanup_threads()¶
Clean up the memory used by FFTW threads on all locales.