Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 3/22/2024
Public

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

Document Table of Contents

vmlSetMode

Sets a new mode for VM functions according to the mode parameter and stores the previous VM mode to oldmode.

Syntax

oldmode = vmlSetMode( mode );

Include Files

  • mkl.h

Input Parameters

Name

Type

Description

mode

const MKL_UINT

Specifies the VM mode to be set.

Output Parameters

Name

Type

Description

oldmode

unsigned int

Specifies the former VM mode.

Description

The vmlSetMode function sets a new mode for VM functions according to the mode parameter and stores the previous VM mode to oldmode. The mode change has a global effect on all the VM functions within a thread.

NOTE:

You can override the global mode setting and change the mode for a given VM function call by using a respective vm[s,d]<Func> variant of the function.

The mode parameter is designed to control accuracy, handling of denormalized numbers, and error handling. Table "Values of the mode Parameter" lists values of the mode parameter. You can obtain all other possible values of the mode parameter from the mode parameter values by a using bitwise OR ( | ) operation to combine one value for accuracy, one value for handling of denormalized numbers, and one value for error control options. The default value of the mode parameter is VML_HA | VML_FTZDAZ_CURRENT | VML_ERRMODE_DEFAULT.

The VML_FTZDAZ_ON mode is specifically designed to improve the performance of computations that involve denormalized numbers at the cost of reasonable accuracy loss. This mode changes the numeric behavior of the functions: denormalized input values are treated as zeros (DAZ = denormals-are-zero) and denormalized results are flushed to zero (FTZ = flush-to-zero). Accuracy loss may occur if input and/or output values are close to denormal range.

Values of the mode Parameter
Value of mode Description
Accuracy Control
VML_HA high accuracy versions of VM functions
VML_LA low accuracy versions of VM functions
VML_EP enhanced performance accuracy versions of VM functions
Denormalized Numbers Handling Control
VML_FTZDAZ_ON Faster processing of denormalized inputs is enabled.
VML_FTZDAZ_OFF Faster processing of denormalized inputs is disabled.
VML_FTZDAZ_CURRENT Keep the current CPU settings for denormalized inputs.
Error Mode Control
VML_ERRMODE_IGNORE On computation error, VM Error status is updated, but otherwise no action is set. Cannot be combined with other VML_ERRMODE settings.
VML_ERRMODE_NOERR On computation error, VM Error status is not updated and no action is set. Cannot be combined with other VML_ERRMODE settings.
VML_ERRMODE_ERRNO On error, the errno variable is set.
VML_ERRMODE_STDERR On error, the error text information is written to stderr.
VML_ERRMODE_EXCEPT On error, an exception is raised.
VML_ERRMODE_CALLBACK On error, an additional error handler function is called.
VML_ERRMODE_DEFAULT On error, the errno variable is set, an exception is raised, and an additional error handler function is called.

Product and Performance Information

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

Notice revision #20201201

Examples

The following example shows how to set low accuracy, fast processing for denormalized numbers and stderr error mode:

ClassicC:

 

vmlSetMode( VML_LA ); 
vmlSetMode( VML_LA | VML_FTZDAZ_ON | VML_ERRMODE_STDERR );