Usage of Multi-threaded FFTW

Chris@19: Chris@19: Chris@19:

Chris@19: Next: How Many Threads to Use?, Chris@19: Previous: Installation and Supported Hardware/Software, Chris@19: Up: Multi-threaded FFTW Chris@19:

Chris@19:

5.2 Usage of Multi-threaded FFTW

Here, it is assumed that the reader is already familiar with the usage Chris@19: of the uniprocessor FFTW routines, described elsewhere in this manual. Chris@19: We only describe what one has to change in order to use the Chris@19: multi-threaded routines. Chris@19: Chris@19:

First, programs using the parallel complex transforms should be linked Chris@19: with -lfftw3_threads -lfftw3 -lm on Unix, or

-lfftw3_omp
Chris@19: -lfftw3 -lm

if you compiled with OpenMP. You will also need to link Chris@19: with whatever library is responsible for threads on your system Chris@19: (e.g. -lpthread on GNU/Linux) or include whatever compiler flag Chris@19: enables OpenMP (e.g. -fopenmp with gcc). Chris@19: Chris@19: Chris@19:

Second, before calling any FFTW routines, you should call the Chris@19: function: Chris@19: Chris@19:

Chris@19: This function, which need only be called once, performs any one-time Chris@19: initialization required to use threads on your system. It returns zero Chris@19: if there was some error (which should not happen under normal Chris@19: circumstances) and a non-zero value otherwise. Chris@19: Chris@19:

Third, before creating a plan that you want to parallelize, you should Chris@19: call: Chris@19: Chris@19:

Chris@19: The nthreads argument indicates the number of threads you want Chris@19: FFTW to use (or actually, the maximum number). All plans subsequently Chris@19: created with any planner routine will use that many threads. You can Chris@19: call fftw_plan_with_nthreads, create some plans, call Chris@19: fftw_plan_with_nthreads again with a different argument, and Chris@19: create some more plans for a new number of threads. Plans already created Chris@19: before a call to fftw_plan_with_nthreads are unaffected. If you Chris@19: pass an nthreads argument of 1 (the default), threads are Chris@19: disabled for subsequent plans. Chris@19: Chris@19:

With OpenMP, to configure FFTW to use all of the currently running Chris@19: OpenMP threads (set by omp_set_num_threads(nthreads) or by the Chris@19: OMP_NUM_THREADS environment variable), you can do: Chris@19: fftw_plan_with_nthreads(omp_get_max_threads()). (The ‘omp_’ Chris@19: OpenMP functions are declared via #include <omp.h>.) Chris@19: Chris@19:

Given a plan, you then execute it as usual with Chris@19: fftw_execute(plan), and the execution will use the number of Chris@19: threads specified when the plan was created. When done, you destroy Chris@19: it as usual with fftw_destroy_plan. As described in Chris@19: Thread safety, plan execution is thread-safe, but plan Chris@19: creation and destruction are not: you should create/destroy Chris@19: plans only from a single thread, but can safely execute multiple plans Chris@19: in parallel. Chris@19: Chris@19:

There is one additional routine: if you want to get rid of all memory Chris@19: and other resources allocated internally by FFTW, you can call: Chris@19: Chris@19:

Chris@19: which is much like the fftw_cleanup() function except that it Chris@19: also gets rid of threads-related data. You must not execute any Chris@19: previously created plans after calling this function. Chris@19: Chris@19:

We should also mention one other restriction: if you save wisdom from a Chris@19: program using the multi-threaded FFTW, that wisdom cannot be used Chris@19: by a program using only the single-threaded FFTW (i.e. not calling Chris@19: fftw_init_threads). See Words of Wisdom-Saving Plans. Chris@19: Chris@19: Chris@19: Chris@19: