Developer Reference

  • 0.9
  • 09/09/2020
  • Public Content
Contents

Common Parameters of the Trigonometric Transforms

This section provides description of array parameters that hold TT routine options:
ipar
,
dpar
and
spar
.
Initial values are assigned to the array parameters by the appropriate
?_init_trig_transform
and
?_commit_trig_transform
routines.
ipar
MKL_INT
array of size 128, holds integer data needed for Trigonometric Transform computations. Its elements are described in Table
"Elements of the ipar Array"
:
Elements of the ipar Array
Index
Description
0
Contains the size of the problem to solve. The
?_init_trig_transform
routine sets
ipar[0]
=
n
, and all subsequently called TT routines use
ipar[0]
as the size of the transform.
1
Contains error messaging options:
  • ipar[1]
    =-1 indicates that all error messages will be printed to the file
    MKL_Trig_Transforms_log.txt
    in the folder from which the routine is called. If the file does not exist, the routine tries to create it. If the attempt fails, the routine prints information that the file cannot be created to the standard output device.
  • ipar[1]
    =0 indicates that no error messages will be printed.
  • ipar[1]
    =1 (default) indicates that all error messages will be printed to the preconnected default output device (usually, screen).
In case of errors, each TT routine assigns a non-zero value to
stat
regardless of the
ipar[1]
setting.
2
Contains warning messaging options:
  • ipar[2]
    =-1 indicates that all warning messages will be printed to the file
    MKL_Trig_Transforms_log.txt
    in the directory from which the routine is called. If the file does not exist, the routine tries to create it. If the attempt fails, the routine prints information that the file cannot be created to the standard output device.
  • ipar[2]
    =0 indicates that no warning messages will be printed.
  • ipar[2]
    =1 (default) indicates that all warning messages will be printed to the preconnected default output device (usually, screen).
In case of warnings, the
stat
parameter will acquire a non-zero value regardless of the
ipar[2]
setting.
3 through 4
Reserved for future use.
5
Contains the type of the transform. The
?_init_trig_transform
routine sets
ipar[5]
=
tt_type
, and all subsequently called TT routines use
ipar[5]
as the type of the transform.
6
Contains the
stat
value returned by the last completed TT routine. Used to check that the previous call to a TT routine completed with
stat
=0.
7
Informs the
?_commit_trig_transform
routines whether to initialize data structures
dpar
(
spar
) and
handle
.
ipar[7]
=0 indicates that the routine should skip the initialization and only check correctness and consistency of the parameters. Otherwise, the routine initializes the data structures. The default value is 1.
The possibility to check correctness and consistency of input data without initializing data structures
dpar
,
spar
and
handle
enables avoiding performance losses in a repeated use of the same transform for different data vectors. Note that you can benefit from the opportunity that
ipar[7]
gives only if you are sure to have supplied proper tolerance value in the
dpar
or
spar
array. Otherwise, avoid tuning this parameter.
8
Contains message style options for TT routines.
Specifically, if
ipar[8]
is non-zero
, TT routines print the messages in C-style notations.
The default value is 1.
When specifying message style options, be aware that by default, numbering of elements
in C arrays starts at 0
.
For example,
"
parameter ipar[0]=3 should be an even integer
"
is a C-style message
.
The use of
ipar[8]
enables you to view messages in a more convenient style.
9
Specifies the number of OpenMP threads to run TT routines in the OpenMP environment of the
Intel® oneAPI Math Kernel Library
Poisson Solver. The default value is 1. You are highly recommended not to alter this value. See alsoCaveat on Parameter Modifications.
10
Specifies the mode of compatibility with FFTW. The default value is 0. Set the value to 1 to invoke compatibility with FFTW. In the latter case, results will not be normalized, because FFTW does not do this. It is highly recommended not to alter this value, but rather use real-to-real FFTW to MKL wrappers, described in FFTW to Intel® MKL Wrappers for FFTW 3.x. See also Caveat on Parameter Modifications.
11 through 127
Reserved for future use.
While you can declare the
ipar
array as
MKL_INT ipar[11]
, for future compatibility you should declare
ipar
as
MKL_INT ipar[128]
.
Arrays
dpar
and
spar
are the same except in the data precision:
dpar
double
array of size 5
n
/2+2, holds data needed for double-precision routines to perform TT computations. This array is initialized in the
d_init_trig_transform
and
d_commit_trig_transform
routines.
spar
float
array of size 5
n
/2+2, holds data needed for single-precision routines to perform TT computations. This array is initialized in the
s_init_trig_transform
and
s_commit_trig_transform
routines.
As
dpar
and
spar
have similar elements in respective positions, the elements are described together in Table
"Elements of the dpar and spar Arrays"
:
Elements of the dpar and spar Arrays
Index
Description
0
Contains the first absolute tolerance used by the appropriate
?_commit_trig_transform
routine. For a staggered cosine or a sine transform,
f[n]
should be equal to 0.0 and for a staggered sine or a sine transform,
f[0]
should be equal to 0.0. The
?_commit_trig_transform
routine checks whether absolute values of these parameters are below
dpar[0]*n
or
spar[0]*n
, depending on the routine precision. To suppress warnings resulting from tolerance checks, set
dpar[0]
or
spar[0]
to a sufficiently large number.
1
Reserved for future use.
2 through 5
n
/2+1
Contain tabulated values of trigonometric functions. Contents of the elements depend upon the type of transform
tt_type
, set up in the
?_commit_trig_transform
routine:
  • If
    tt_type
    =
    MKL_SINE_TRANSFORM
    , the transform uses only the first
    n
    /2 array elements, which contain tabulated sine values.
  • If
    tt_type
    =
    MKL_STAGGERED_SINE_TRANSFORM
    , the transform uses only the first 3
    n
    /2 array elements, which contain tabulated sine and cosine values.
  • If
    tt_type
    =
    MKL_STAGGERED2_SINE_TRANSFORM
    , the transform uses all the 5
    n
    /2 array elements, which contain tabulated sine and cosine values.
  • If
    tt_type
    =
    MKL_COSINE_TRANSFORM
    , the transform uses only the first
    n
    array elements, which contain tabulated cosine values.
  • If
    tt_type
    =
    MKL_STAGGERED_COSINE_TRANSFORM
    , the transform uses only the first 3
    n
    /2 elements, which contain tabulated sine and cosine values.
  • If
    tt_type
    =
    MKL_STAGGERED2_COSINE_TRANSFORM
    , the transform uses all the 5
    n
    /2 elements, which contain tabulated sine and cosine values.
To save memory, you can define the array size depending upon the type of transform.

Caveat on Parameter Modifications

Flexibility of the TT interface enables you to skip a call to the
?_init_trig_transform
routine and to initialize the basic data structures explicitly in your code. You may also need to modify the contents of
ipar
,
dpar
and
spar
arrays after initialization. When doing so, provide correct and consistent data in the arrays. Mistakenly altered arrays cause errors or wrong computation. You can perform a basic check for correctness and consistency of parameters by calling the
?_commit_trig_transform
routine; however, this does not ensure the correct result of a transform but only reduces the chance of errors or wrong results.
To supply correct and consistent parameters to TT routines, you should have considerable experience in using the TT interface and good understanding of elements that the
ipar
,
spar
and
dpar
arrays contain and dependencies between values of these elements.
However, in rare occurrences, even advanced users might fail to compute a transform using TT routines after the parameter modifications. In cases like these, refer for technical support at http://www.intel.com/software/products/support/ .
The only way that ensures proper computation of the Trigonometric Transforms is to follow a typical sequence of invoking the routines and not change the default set of parameters. So, avoid modifications of
ipar
,
dpar
and
spar
arrays unless a strong need arises.
Optimization Notice
Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.
Notice revision #20110804
This notice covers the following instruction sets: SSE2, SSE4.2, AVX2, AVX-512.

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804