Developer Reference

Contents

descriptor<precision, domain>::set_value

Sets one configuration parameter with the specified configuration value. This routine belongs to the
oneapi::mkl::dft
namespace.

Description

This function sets one configuration parameter with the specified configuration value and throws an
std::runtime_exception
in the case that it fails. Each configuration parameter is a named constant, and the configuration value must have the corresponding type, which can be a named constant or a native type. The DPC++ configuration parameters have type
mkl::dft::config_param
. Each parameter
mkl::dft::config_param::<PARAMETER_NAME>
has the same meaning and possible values as the C interface’s
DFTI_<PARAMETER_NAME>
. Some of the options available in the C interface are not fully supported in the DPC++ interface yet. See the note below and the Intel® oneAPI Math Kernel Library Release Notes. For a full description of each parameter’s meaning and options, see Config Params.
  • An important difference in the configuration options for DPC++ FFT interface is the use of
    FWD_DISTANCE
    and
    BWD_DISTANCE
    instead of
    INPUT_DISTANCE
    and
    OUTPUT_DISTANCE
    . The
    FWD_DISTANCE
    describes the number of elements between different batched FFTs for the forward domain while
    BWD_DISTANCE
    describes the number of elements between different batched FFTs for the backward domain. This allows a committed descriptor to compute both forward and backward transforms without resetting the distance parameters. It is required for all R2C or C2R transforms to use
    FWD_DISTANCE
    and
    BWD_DISTANCE
    instead of
    INPUT_DISTANCE
    and
    OUTPUT_DISTANCE
    .
  • Padded strides are not currently supported in the DPC++ interface. When
    INPUT_STRIDE
    is greater than
    INPUT_DISTANCE
    , it is assumed that
    INPUT_STRIDE
    =
    INPUT_DISTANCE*NUMBER_OF_TRANSFORMS
    . For example, to compute three FFTs on arrays
    x
    ,
    y
    , and
    z
    , a dense data layout like [x1, y1, z1, x2, y2, z2, x3,…] (INPUT_DISTANCE=1, NUMBER_OF_TRANSFORMS=3, INPUT_STRIDE=3) is supported. A padded data layout like [x1, y1, z1, pad, x2, y2, z2, pad, x3,…] (INPUT_DISTANCE=1, NUMBER_OF_TRANSFORMS=3, INPUT_STRIDE=4) is not currently supported.
  • For
    COMPLEX_STORAGE
    , only the
    DFTI_COMPLEX_COMPLEX
    format is currently supported on CPU and GPU devices. Both
    DFTI_COMPLEX_COMPLEX
    and
    DFTI_REAL_REAL
    are supported on the host device.
  • In the case of a real forward domain, the only supported values on GPU devices for
    CONJUGATE_EVEN_STORAGE
    and
    PACKED_FORMAT
    are respectively
    DFTI_COMPLEX_COMPLEX
    and
    DFTI_CCE_FORMAT
    . These values are set by default and require the setting of the
    INPUT_STRIDE
    and
    OUTPUT_STRIDE
    parameters before calling commit. (While these default values differ from the current C interface defaults, the C default values will be brought into alignment with these default values following the full deprecation process of the current C default values. See the deprecation notice at DFTI_COMPLEX_STORAGE, DFTI_REAL_STORAGE, DFTI_CONJUGATE_EVEN_STORAGE.)
The set_value function cannot be used to change configuration parameters
mkl::dft::config_param::FORWARD_DOMAIN
,
mkl::dft::config_param::PRECISION
since these are a part of the template. Likewise,
mkl::dft::config_param::LENGTHS
is set with the constructor.
All calls to
set_value()
must be done before calls to
commit()
. This is because the handle may have been moved to an offloaded device after
commit()
.
Function calls needed to configure an FFT descriptor for a particular call to an FFT computation function are summarized in Configuring and Computing an FFT in C/C++.

API

Syntax
namespace oneapi::mkl::dft{ void descriptor<prec,dom>::set_value(config_param param, ...); }
Include Files
  • oneapi/mkl/dfti.hpp
Input Parameters
Name
Type
Description
param
mkl::dft::config_param
Configuration parameter
value
Depends on the configuration parameter
Configuration value

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.