create_error_handler

Creates the local VM Error Handler for a function..

Syntax

Buffer API:

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:

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:

The following table lists the possible computational error values.

Values of the VM Status
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:

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():

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.