A newer version of this document is available. Customers should click here to go to the newest version.
Visible to Intel only — GUID: GUID-9620B20B-0707-4ADA-B60A-788C7679C6B0
Visible to Intel only — GUID: GUID-9620B20B-0707-4ADA-B60A-788C7679C6B0
create_error_handler
Creates the local VM Error Handler for a function.
Syntax
Buffer API:
namespace oneapi::mkl::vm {
error_handler<T> create_error_handler(
buffer<uint8_t,
1> & errarray,
int64_t length = 1,
uint8_t errstatus = status::not_defined,
T fixup = 0.0,
bool copysign = false )
}
USM API:
namespace oneapi::mkl::vm {
error_handler<T> create_error_handler(
uint8_t* errarray,
int64_t length = 1,
uint8_t errstatus = status::not_defined,
T fixup = 0.0,
bool copysign = false )
}
create_error_handler supports the following precisions and devices:
T |
Devices supported |
|---|---|
float |
CPU and GPU |
double |
CPU and GPU |
Description
The create_error_handler creates the local VM Error handler to be passed to VM functions which support error handling.
The local VM Error Handler supports three modes:
Single status mode: all errors happened during function execution are being written into one status value.
At the execution end the single value is either un-changed if no errors happened or contained accumulated (merged by bitwise OR) error statuses happened in function execution.
Set the array pointer to any status object and the length equals 1 to enable this mode.
Multiple status mode: error statuses are saved as an array by indices where they happen.
Notice that only error statuses are being written into the array, the success statuses are not to be written.
That means the array needs to be allocated and initialized by user before function execution.
To enable this mode allocate status array with the same size as argument and result vectors, set the errarray pointer to it and the length to the vector size.
Fixup mode: for all arguments which caused specific error status results to be overwritten by a user-defined value.
To enable this mode set desirable errstatus and fixup values. The fixup value is written to results for each argument which caused the errstatus error.
If the copysign is set to true then fixup value’s sign set to the same sign of the argument which caused the errstatus – a suitable option for symmetric math functions.
The following table lists the possible computational error values.
Status |
Description |
|---|---|
Successful Execution |
|
status::success |
VM function execution completed successfully |
status::not_defined |
VM status not defined |
Warnings |
|
status::accuracy_warning |
VM function execution completed successfully in a different accuracy mode |
Computational Errors |
|
status::errdom |
Values are out of a range of definition producing invalid (QNaN) result |
status::sing |
Values cause divide-by-zero (singularity) errors and produce and invalid (QNaN or Inf) result |
status::overflow |
An overflow happened during the calculation process |
status::underflow |
An underflow happened during the calculation process |
Notes:
You must allocate and initialize array errarray before calling VM functions in multiple status error handling mode.
The array should be large enough to contain n error codes, where n is the same as inputoutput vector size for the VM function.
If no arguments passed to the create_error_handler function, then the empty object is created with all of three error handling modes disabled.
In this case, the VM math functions set the global error status only.
Input Parameters
- errarray
-
Array to store error statuses (should be a buffer for buffer API).
- length
-
Length of the errarray. This is an optional argument, default value is 1.
- errcode
-
Error status to fixup results. This is an optional argument, default value is status::not_defined.
- fixup
-
Fixup value for results. This is an optional argument, default value is 0.0.
- copysign
-
Flag for setting the fixup value’s sign the same as the argument’s. This is an optional argument, default value false.
Output Parameters
- return value
-
Specifies the error handler object to be created.
Examples
The following examples are possible usage models (USM API).
Single status mode with create_error_handler():
error_handler<float> handler = vm::create_error_handler (st);
vm::sin(exec_queue, 1000, a, r, handler);
if ( st[0] & status::errdom)
{
std::cout << ”Errdom status returned” << std::endl;
}
Single status mode without create_error_handler():
vm::sin(exec_queue, 1000, a, r, {st });
std::cout << status << std::endl;
if ( st[0] & status::errdom)
{
std::cout << ”Errdom status returned” << std::endl;
}
The st contains either status::success or accumulated error statuses if computational errors occured in vm::erfinv.
Multiple status mode with create_error_handler():
error_handler<float> handler = vm::create_error_handler (st, 1000);
vm::inv(exec_queue, 1000, a, r, handler);
for(int i=0; i<1000; i++)
std::cout << st[i] << std::endl;
Multiple status mode without create_error_handler():
vm::inv(exec_queue, 1000, a, r, {st, 1000});
for(int i=0; i<1000; i++)
std::cout << st[i] << std::endl;
The st array contains all codes for computational errors that occur at the same vector indices i as the arguments that caused the errors.
Fixup status mode with create_error_handler():
float fixup = 1.0;
error_handler<float> handler = vm::create_error_handler (nullptr, 0, status::errdom, fixup, true);
vm::erfinv(exec_queue, 1000, a, r, handler);
Fixup status mode without create_error_handler():
float fixup = 1.0;
vm::erfinv(exec_queue, 1000, a, r, { nullptr, 0, status::errdom, fixup, true });
All results in r which computation generated status::errdom are replaced by fixup values.
In the example above all the erfinv function’s NAN results caused by greater than |1| arguments are replaced by 1.0 value with the same sign as the corresponding argument.
Mixed (Single and Fixup) status mode with create_error_handler():
float fixup = 1e38;
error_handler<float> handler = vm::create_error_handler (st, 1, status::overflow, fixup);
vm::exp(exec_queue, 1000, a, r, handler);
if ( st & status::underflow)
{
std::cout << ”Underflow status returned” << std::endl;
}
Mixed (Single and Fixup) status mode without create_error_handler():
float fixup = 1e38;
vm::exp(exec_queue, 1000, a, r, {st, 1, status::overflow, fixup});
if ( st & status::underflow)
{
std::cout << ”Underflow status returned” << std::endl;
}
Mixed (Multiple and Fixup) status mode with create_error_handler():
namespace oneapi::mkl::vm {
float fixup = 1.0;
error_handler<float> handler = vm::create_error_handler (st, 1000, status::errdom, fixup);
vm::acospi(exec_queue, 1000, a, r, handler);
for(int i=0; i<1000; i++)
std::cout << st[i] << std::endl;
Mixed (Multiple and Fixup) status mode without create_error_handler():
float fixup = 1.0;
vm::acospi(exec_queue, 1000, a, r,{ st, 1000, status::errdom, fixup});
for(int i=0; i<1000; i++)
std::cout << st[i] << std::endl;
The st array contains all codes for computational errors that occur at the same vector indices i as the arguments that caused the errors. Additionally, all results in r which computation generated status::errdom are replaced by fixup values.
No local error handling mode:
vm::pow(exec_queue, n, a, b, r);
uint8_t err = vm::get_status (exec_queue);
if (err & status::errdom)
{
std::cout << ”Errdom status returned” << std::endl;
}
if (err & status::sing)
{
std::cout << ”Singularity status returned” << std::endl;
}
Only global accumulated error status err is set.