CreateDescriptor

Allocates memory for the descriptor data structure and preliminarily initializes it.

Syntax

Fortran:

Status = DftiCreateDescriptor( Desc_Handle, Precision, Forward_Domain, &

Dimension, Length )

status = DftiCreateDescriptor( &desc_handle, precision, forward_domain, dimension, length );

Include Files

The Fortran interface is specified in the mkl_dfti.f90 include file and the C interface is specified in the mkl_dfti.h include file.

Description

The function is declared in the mkl_dfti.h header file for the C interface and mkl_dfti.f90 header file for the Fortran interface. This function allocates memory for the descriptor data structure and instantiates it with all the default configuration settings with respect to the precision, domain, dimension, and length of the desired transform. The domain is understood to be the domain of the forward transform. Since memory is allocated dynamically, the result is actually a pointer to the created descriptor. This function is slightly different from the "initialization" function in more traditional software packages or libraries used for computing FFT. This function does not perform any significant computational work such as twiddle factors computation. The function DftiCommitDescriptor does this work after the function DftiSetValue has set values of all needed parameters.

The precision and (forward) domain are specified through named constants provided in the FFT interface for the configuration values. The choices for precision are DFTI_SINGLE and DFTI_DOUBLE; and the choices for (forward) domain are DFTI_COMPLEX and DFTI_REAL. See Table "Named Constant Configuration Values" for the complete table of named constants for configuration values.

Dimension is a simple positive integer indicating the dimension of the transform. Length is either a simple positive integer for one-dimensional transform, or an integer array (pointer in C) containing the positive integers corresponding to the length dimensions for multi-dimensional transform.

The function returns the zero status when completes successfully. See Status Checking Functions for more information on the returned status.

Interface and Prototype

 
! Fortran interface.
! Note that the body provided below only illustrates the list of different
! parameters and the types of dummy parameters. You can rely only on the function  
! name following keyword INTERFACE. For the precise definition of the 
! interface, see the include/mkl_dfti.f90 file in the Intel MKL directory.

  INTERFACE DftiCreateDescriptor

     FUNCTION some_actual_function_1d(desc, precision, domain, dim, length)
       INTEGER :: some_actual_function_1d
       ...
       INTEGER, INTENT(IN) :: length
     END FUNCTION some_actual_function_1d

     FUNCTION some_actual_function_md(desc, precision, domain, dim, lengths)
       INTEGER :: some_actual_function_md
       ...
       INTEGER, INTENT(IN), DIMENSION(*) :: lengths
     END FUNCTION some_actual_function_md

     ...

  END INTERFACE DftiCreateDescriptor

Note that the function is overloaded, because the actual parameter for the formal parameter length can be a scalar or a rank-one array.

The function is also overloaded with respect to the type of the precision parameter to provide an option of using a precision-specific function for the generic name. Using more specific functions can reduce the size of statically linked executable for the applications using only single-precision FFTs or only double-precision FFTs. To use this option, change statement "USE MKL_DFTI" in your program unit to either of the following:

USE MKL_DFTI, FORGET=>DFTI_SINGLE, DFTI_SINGLE=>DFTI_SINGLE_R

USE MKL_DFTI, FORGET=>DFTI_DOUBLE, DFTI_DOUBLE=>DFTI_DOUBLE_R

where the name "FORGET" can be replaced with any name that is not used in the program unit.

 
/* C prototype. 
 * Note that the preprocessor definition provided below only illustrates 
 * that the actual function called may be determined at compile time. 
 * You can rely only on the declaration of the function. 
 * For precise definition of the preprocessor macro, see the include/mkl_dfti.h
 * file in the Intel MKL directory.
 */
MKL_LONG DftiCreateDescriptor(DFTI_DESCRIPTOR_HANDLE * pHandle,
     enum DFTI_CONFIG_VALUE precision,
     enum DFTI_CONFIG_VALUE domain,
     MKL_LONG dimension, ... /* length(s) */ );
 
#define DftiCreateDescriptor(desc,prec,domain,dim,sizes) \
     ((prec)==DFTI_SINGLE && (dim)==1) ? \
     some_actual_function_s1d((desc),(domain),(MKL_LONG)(sizes)) : \
     ...

Variable length(s) is interpreted as a scalar (MKL_LONG) or an array (MKL_LONG*), depending on the value of parameter dimension. If the value of parameter precision is known at compile time, then the compiler may retain, at a certain level of optimization, only the call to the respective specific function, thereby reducing the size of the statically linked application. Avoid direct calls to the specific functions used in the preprocessor macro definition, because their interface may change in future releases of the library. If the use of the macro is undesirable, you can safely undefine it after inclusion of the Intel MKL FFT header file, as follows:

#include "mkl_dfti.h"
#undef DftiCreateDescriptor