Developer Reference

Contents

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
Host
double
Host
std::complex<float>
Host
std::complex<double>
Host
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.

Product and Performance Information

1

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