starpu-max/doc/chapters/fft-support.texi

@c -*-texinfo-*-

@c This file is part of the StarPU Handbook.
@c Copyright (C) 2009--2011  Universit@'e de Bordeaux 1
@c Copyright (C) 2010, 2011, 2012, 2013  Centre National de la Recherche Scientifique
@c Copyright (C) 2011 Institut National de Recherche en Informatique et Automatique
@c See the file starpu.texi for copying conditions.

StarPU provides @code{libstarpufft}, a library whose design is very similar to
both fftw and cufft, the difference being that it takes benefit from both CPUs
and GPUs. It should however be noted that GPUs do not have the same precision as
CPUs, so the results may different by a negligible amount.

Different precisions are available, namely float, double and long
double precisions, with the following fftw naming conventions:

@enumerate
@item double precision structures and functions are named e.g. @code{starpufft_execute}
@item float precision structures and functions are named e.g. @code{starpufftf_execute}
@item long double precision structures and functions are named e.g. @code{starpufftl_execute}
@end enumerate

The documentation below is given with names for double precision, replace
@code{starpufft_} with @code{starpufftf_} or @code{starpufftl_} as appropriate.

Only complex numbers are supported at the moment.

The application has to call @code{starpu_init} before calling starpufft functions.

Either main memory pointers or data handles can be provided.

@enumerate
@item To provide main memory pointers, use @code{starpufft_start} or
@code{starpufft_execute}. Only one FFT can be performed at a time, because
StarPU will have to register the data on the fly. In the @code{starpufft_start}
case, @code{starpufft_cleanup} needs to be called to unregister the data.
@item To provide data handles (which is preferrable),
use @code{starpufft_start_handle} (preferred) or
@code{starpufft_execute_handle}. Several FFTs Several FFT tasks can be submitted
for a given plan, which permits e.g. to start a series of FFT with just one
plan. @code{starpufft_start_handle} is preferrable since it does not wait for
the task completion, and thus permits to enqueue a series of tasks.
@end enumerate

All functions are defined in @ref{FFT Support}.

@section Compilation

The flags required to compile or link against the FFT library are accessible
with the following commands:

@example
$ pkg-config --cflags starpufft-1.0  # options for the compiler
$ pkg-config --libs starpufft-1.0    # options for the linker
@end example

Also pass the @code{--static} option if the application is to be linked statically.