/* StarPU --- Runtime system for heterogeneous multicore architectures.
 *
 * Copyright (C) 2009-2022  Université de Bordeaux, CNRS (LaBRI UMR 5800), Inria
 *
 * StarPU is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or (at
 * your option) any later version.
 *
 * StarPU is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 *
 * See the GNU Lesser General Public License in COPYING.LGPL for more details.
 */

/*! \page FFTSupport FFT Support

StarPU provides <c>libstarpufft</c>, a library whose design is very similar to
both <c>fftw</c> and <c>cufft</c>, 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 be different by a negligible amount.

Different precisions are available, namely \c float, \c double and <c>long
double</c> precisions, with the following \c fftw naming conventions:

<ul>
<li>
double precision structures and functions are named e.g. starpufft_execute()
</li>
<li>
float precision structures and functions are named e.g. starpufftf_execute()
</li>
<li>
long double precision structures and functions are named e.g. starpufftl_execute()
</li>
</ul>

The documentation below is given with names for double precision, replace
<c>starpufft_</c> with <c>starpufftf_</c> or <c>starpufftl_</c> as appropriate.

Only complex numbers are supported at the moment.

The application has to call starpu_init() before calling <c>starpufft</c> functions.

Either main memory pointers or data handles can be provided.

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

All functions are defined in \ref API_FFT_Support.

Some examples illustrating the usage of FFT API are available in
the directory <c>starpufft/tests</c>.

\section FFTCompilation Compilation

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

\verbatim
$ pkg-config --cflags starpufft-1.4  # options for the compiler
$ pkg-config --libs starpufft-1.4    # options for the linker
\endverbatim

Also pass the option <c>--static</c> if the application is to be linked statically.

*/
