.. default-domain:: chpl

.. module:: FFTW_MT
   :synopsis: Multi-threaded FFT computations via FFTW (version 3)

FFTW_MT
=======
**Usage**

.. code-block:: chapel

   use FFTW_MT;


Multi-threaded FFT computations via FFTW (version 3)

This module defines Chapel wrappers around key FFTW routines
supporting multithreaded execution.  It builds directly on the
:mod:`FFTW` module, inheriting all of its functionality, so refer to
that module for documentation on the transforms themselves.

To use this module:

1. Ensure that FFTW (version 3) is installed on your system with
   multi-threaded support enabled and that the header and library
   files (e.g., fftw3.h, libfftw3.*) are either installed in a
   standard system location or that your C compiler's environment
   variables are set up to find them (alternatively, the Chapel
   compiler's ``-I`` and ``-L`` flags can be used to specify these
   locations).

2. Add ``use FFTW_MT;`` to your Chapel code.

3. Compile and run your Chapel program as usual.


The steps to making multi-threaded FFTW calls are:

0. By default, the module will initialize itself to use
   ``here.maxTaskPar`` threads per locale when calling
   :proc:`plan_dft* <FFTW.plan_dft>` routines.  This
   auto-initialization can be disabled by setting
   :param:`autoInitFFTW_MT` to `false` at compile-time and calling
   :proc:`init_FFTW_MT` and :proc:`plan_with_nthreads` manually.  At
   any time during program execution, the number of threads to be
   used by FFTW can be changed by calling :proc:`plan_with_nthreads`
   with a new value.

1. Create, ...

2. execute, ...

3. ...and destroy plans as in single-threaded uses of :mod:`FFTW`.

4. Call :proc:`cleanup_threads` to release the memory used by FFTW's
   threads and :proc:`~FFTW.cleanup` as in single-threaded uses of
   :mod:`FFTW`.

Note that where the main :mod:`FFTW` module is a single-locale
module, this one is multi-locale in that, once it is initialized,
any locale can create and execute plans, though those plans will
only be valid on that locale.  Calls to :proc:`init_FFTW_MT`,
:proc:`plan_with_nthreads` and :proc:`cleanup_threads` will take
those actions across all locales.

.. data:: config param autoInitFFTW_MT = true

   
   By default, this module will call :proc:`init_FFTW_MT()` and
   :proc:`plan_with_nthreads()` as part of its initialization.
   Setting this to `false` at compile-time will disable this
   auto-initialization, requiring these calls to be made
   manually.
   

.. function:: proc init_FFTW_MT()

   
   Initialize the :mod:`FFTW_MT` module.  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.
   

.. function:: proc plan_with_nthreads(nthreads: int = 0)

   
   Register the number of threads to use for multi-threaded 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.
   
   :arg nthreads: The number of threads to use.
   :type nthreads: `int`
   

.. function:: proc cleanup_threads()

   
   Clean up the memory used by FFTW threads on all locales.