Common Parameters of the Trigonometric Transforms

Developer Reference for Intel® oneAPI Math Kernel Library for C

Download PDF

ID 766684

Date 7/13/2023

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-3DA88A75-AC3D-45F1-B647-7D020451D010

View Details

Common Parameters of the Trigonometric Transforms

This section provides description of array parameters that hold TT routine options: ipar, dpar and spar.

NOTE:

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 (oneMKL) 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.

NOTE:

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 5n/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 5n/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 5n/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 3n/2 array elements, which contain tabulated sine and cosine values. If tt_type=`MKL_STAGGERED2_SINE_TRANSFORM`, the transform uses all the 5n/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 3n/2 elements, which contain tabulated sine and cosine values. If tt_type=`MKL_STAGGERED2_COSINE_TRANSFORM`, the transform uses all the 5n/2 elements, which contain tabulated sine and cosine values.

NOTE:

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.

NOTE:

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/ .

warning:

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.

Product and Performance Information
Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex. Notice revision #20201201

Product and Performance Information

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

Notice revision #20201201

Parent topic: Trigonometric Transform Routines

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Developer Reference for Intel® oneAPI Math Kernel Library for C

Common Parameters of the Trigonometric Transforms

Caveat on Parameter Modifications