create_error_handler#

関数のローカル VM エラーハンドラーを作成します。

構文

バッファー 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 は次の精度とデバイスをサポートしています。

T	デバイスサポート
`sycl::half`	GPU
`_Float16`	CPU
`float`	CPU および GPU
`double`	CPU および GPU

説明

create_error_handler は、エラー処理をサポートする VM 関数に渡されるローカル VM エラーハンドラーを作成します。

ローカル VM エラーハンドラは、次の 3 つのモードをサポートしています。

単一ステータスモード: 関数実行中に発生したすべてのエラーが 1 つのステータス値に書き込まれます。

実行終了時に、エラーが発生しなかった場合は値は変更されず、関数実行中に発生した累積された (ビット単位の OR で結合された) エラーステータスが含まれます。

このモードを有効にするには、配列ポインターを任意の status オブジェクトに設定し、長さを 1 に設定します。
複数ステータスモード: エラーステータスは、発生したインデックスによって配列として保存されます。

配列にはエラーステータスのみが書き込まれ、成功ステータスは書き込まれないことに注意してください。

関数を実行する前に、ユーザーが配列を割り当てて初期化する必要があります。

このモードを有効にするには、引数と結果ベクトルと同じサイズの status 配列を割り当て、エラー配列ポインターをその配列に設定し、長さをベクトルサイズに設定します。
修正モード: 特定のエラーステータスを引き起こしたすべての引数が、ユーザー定義の値によって上書きされます。

このモードを有効にするには、適切な errstatus と fixup 値を設定します。errstatus エラーの原因となった各引数の結果に、fixup 値が書き込まれます。

copysign が true に設定されている場合、fixup 値の符号は、errstatus の原因となった引数と同じ符号に設定されます。これは対称的な数学関数に適したオプションです。

次の表に、計算エラーの可能性がある値を示します。

状態	説明
実行成功
`status::success`	VM 関数の実行が正常に完了しました
`status::not_defined`	VM ステータスが定義されていません
警告
`status::accuracy_warning`	VM 関数の実行が異なる精度モードで正常に終了しました
計算エラー
`status::errdom`	値が定義の範囲外であるため、無効な結果 (QNaN) が生成されます
`status::sing`	値がゼロ除算 (特異点) エラーを引き起こし、無効な (QNaN または Inf) 結果を生成します
`status::overflow`	計算処理中にオーバーフローが発生しました
`status::underflow`	計算処理中にアンダーフローが発生しました

注:

複数ステータスエラー処理モードで VM 関数を呼び出す前に、配列 errarray を割り当てて初期化する必要があります。

配列は n 個のエラーコードを格納できる大きさが必要があります。ここで、n は VM 関数の入出力ベクトルのサイズと同じです。
create_error_handler 関数に引数が渡されない場合、3 つのエラー処理モードがすべて無効になった空のオブジェクトが作成されます。

この場合、VM 数学関数はグローバル・エラー・ステータスのみを設定します。

入力パラメーター

errarray: エラーステータスを格納する配列 (バッファー API の場合はバッファーが必要です)。
length: errarray の長さ。これはオプションの引数であり、デフォルト値は 1 です。
errcode: 結果を修正するエラーステータスこれはオプションの引数であり、デフォルト値は status::not_defined です。
fixup: 結果の fixup (修正) 値。これはオプションの引数であり、デフォルト値は 0.0 です。
copysign: fixup 値の符号を引数と同じにするフラグ。これはオプションの引数で、デフォルト値は false です。

出力パラメーター

return value: 作成するエラー・ハンドラー・オブジェクトを指定します。

例

次の例は、可能な使用モデル (USM API) です。

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; 
    }

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; 
    }

st には、vm::erfinv で計算エラーが発生した場合、status::success または累積されたエラーステータスのいずれかが含まれます。

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;

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;

st 配列には、エラーの原因となった引数と同じベクトルのインデックス i で発生する計算エラーのすべてのコードが含まれます。

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);

create_error_handler() を使用しないステータスモードを修正します。

float fixup = 1.0; 
    vm::erfinv(exec_queue, 1000, a, r, { nullptr, 0, status::errdom, fixup, true });

計算によってstatus::errdom が発生した r のすべての結果は、fixup 値に置き換えられます。

上記の例では、|1| より大きい引数によって発生した erfinv 関数の NAN 結果はすべて、対応する引数と同じ符号を持つ 1.0 値に置き換えられます。

create_error_handler() を使用した混合 (単一および Fixup) ステータスモード:

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; 
    }

create_error_handler() なしの混合 (単一および Fixup) ステータスモード:

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; 
    }

create_error_handler() を使用した混合 (複数と　Fixup) ステータスモード:

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;

create_error_handler() なしの混合 (複数と Fixup) ステータスモード:

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;

st 配列には、エラーの原因となった引数と同じベクトルのインデックス i で発生する計算エラーのすべてのコードが含まれます。さらに、計算によってstatus::errdom が発生した r のすべての結果は、fixup 値に置き換えられます。

ローカルエラー処理モードなし:

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; 
    }

グローバル累積エラーステータス err のみが設定されます。