oneapi::mkl::sparse::omatadd#

一般スパース行列とスパース行列の加算を計算し、スパース行列を出力します。

説明 #

注

サポートされている <DATA_TYPE> と <INT_TYPE> データタイプと整数タイプの一覧については、Sparse BLAS でサポートされているデータと整数タイプを参照してください。また、スローされる可能性のある例外の詳細については、エラー処理を参照してください。

oneapi::mkl::sparse::omatadd ルーチンセットは、以下のように定義される一般スパース行列-スパース行列の加算を実行します

\[C = \alpha\cdot\text{op}(A) + \beta\cdot\text{op}(B)\]

ここで、\(A\)、\(B\)、および \(C\) は数学的に一貫したサイズを持つスパース行列であり、\(\text{op()}\) は行列修飾子です:

\[\begin{split}\text{op}(A) = \begin{cases} A,& \text{ oneapi::mkl::transpose::nontrans}\\ A^{T},& \text{ oneapi::mkl::transpose::trans}\\A^{H},& \text{ oneapi::mkl::transpose::conjtrans.} \end{cases}\end{split}\]

スパース行列は sparse::matrix_handle_t オブジェクトに格納されます。

出力行列 \(C\) は sparse::omatadd() の終了時にソートされていることは保証されませんが、後にソートが必要な場合にはヘルパー関数 sparse::sort_matrix() が提供されます。

入力行列 \(A\) と \(B\) は、これらの API で使用するのにソートする必要はありません。ただし、ユーザーが、事前に行列に対して sparse::sort_matrix() を呼び出すか、または sparse::set_matrix_property() API を使用して行列に sparse::property::sorted プロパティーを設定することによって、両方の入力行列がソートされていることを保証すると、omatadd API のパフォーマンスが大幅に向上する可能性があります。

\(C\) のスパースパターンとそのデータ配列のサイズは通常は事前に不明であるため、omatadd ルーチンは異なる API 名を持つ複数のステージに分割され、一時ワークスペースのサイズと結果の \(C\) データ配列のサイズを照会し、割り当てて、ルーチンに渡して埋めることができます。これにより、ユーザーはすべての \(C\) 行列データの割り当てを制御および所有できるようになります。ただし、sparse::matmat() API とは異なり、omatadd ルーチンは現在、浮動小数点値を含まないスパースパターンのみの加算をサポートしていません。sparse::omatadd() API セットは、以下に示す 2 つの軽量ステージと 2 つの計算コストの高いステージを含む 4 つの API に分かれています。

ステージ	説明
`omatadd_buffer_size`	一時ワークスペースのサイズを返します。
`omatadd_analyze`	出力スパース行列内のゼロ以外の値 (`nnzC`) の数をカウントします。
`omatadd_get_nnz`	出力スパース行列の計算された `nnzC` カウントを返します。
`omatadd`	スパースパターンと浮動小数点累積の和を、出力スパース行列のユーザー指定配列に実行します。

ステージ #

omatadd ステージの前
- 行、列、およびデータ配列のダミー引数を持つ sparse::set_<xyz>_data API を使用して、スパース行列の形式と出力の 0/1 ベースのインデックスを設定します。このステージでは、行列の行数と列数はゼロに設定するか、入力行列のサイズと数学的に一致させることができます。
- init_omatadd_descr API を使用して omatadd_descr_t オブジェクトを作成し、列挙タイプ omatadd_alg で使用するアルゴリズムを決定します。特定の入力引数と記述子のセットを使用して、異なる omatadd を呼び出す間はこの列挙タイプを変更してはなりません。
omatadd_buffer_size ステージ
- これは、入力行列配列にアクセスしない非ブロッキングのホスト API です。
- omatadd_buffer_size API を使用して、一時ワークスペースのサイズを取得します。
- 後続のステージで使用する一時ワークスペースを割り当てます。
omatadd_analyze ステージ
- これは、入力行列のスパースパターンにアクセスして解析する非ブロッキング非同期 API です。
- 前のステージで割り当てられた一時ワークスペースで omatadd_analyze API を使用します。
- 一時ワークスペース配列は、omatadd_descr_t オブジェクトに格納されます。スパース行列の加算に使用している間、または omatadd_descr_t オブジェクトが有効である間は、ワークスペースを変更および解放ししてはなりません。
omatadd_get_nnz ステージ
- このブロッキング API を使用して、\(C\) 行列内の非ゼロの数を取得します。
- \(C\) 行列の行、列、およびデータ配列を割り当てます。
- sparse::set_<xyz>_data API を再度呼び出します。今回は、\(C\) の新しく割り当てられた有効な配列を使用します。この時点で、出力の 0/1 ベースのインデックスは変更してはならず、行列の行数と列数は、演算の入力行列のサイズと数学的に一致している必要があります。
omatadd ステージ
- 非ブロッキングの非同期 omatadd API を呼び出して、スパースパターンと浮動小数点の累積を結合し、ユーザー指定の出力 \(C\) 行列配列に埋め込みます。
omatadd ステージの後
- release_omatadd_descr API を使用して omatadd_descr_t オブジェクトを解放します。別の加算演算で記述子を再利用するのは現在未定義の動作ですが、将来の oneMKL リリースで有効になる可能性があります。
- 一時的なワークスペース配列を解放するか、omatadd_descr_t オブジェクトが解放されている場合は、ワークスペースを他の目的で再利用できます。
- 後続の操作のため、\(C\) 行列ハンドルを解放または使用します。
- 他の oneMKL API の後続の呼び出しでソートされた出力が必要な場合は、出力行列配列をソートする sparse::sort_matrix() API を呼び出します。

スパース行列の加算のワークフローの例は、後述の oneMKL SYCL* の例で示されています。

API #

構文#

`enum omatadd_alg`#

omatadd_alg enum タイプは、oneMKL に実装された特定のアルゴリズムを使用する選択肢を提供します。現在、ユーザーが利用できるアルゴリズムは 1 つだけです。この enum は次のように定義されます。

namespace oneapi::mkl::sparse { 
    enum class omatadd_alg : std::int32_t { 
        default_alg = 0 }; 
}

`omatadd_descr_t` オブジェクト#

omatadd_descr_t は、omatadd API セットの呼び出し中の内部状態を保存するのに使用される、操作固有の不透明な記述子オブジェクトです。特定の記述子オブジェクトが API で使用されると、omatadd API へのすべての呼び出しが完了するまで、そのオブジェクトを変更したり free することはできません。ユーザーが指定する一時ワークスペースへのポインターは、以下で説明する omatadd API セット (omatadd_analyze) を通してこの記述子オブジェクトに格納されます。この記述子オブジェクトには、初期化関数と解放関数が関連付けられています。

namespace oneapi::mkl::sparse { 
    struct omatadd_descr; /* 不透明な omatconvert 操作記述子の前方宣言 */ 
    typedef omatadd_descr *omatadd_descr_t; /* omatconvert API で使用するユーザー向けタイプ */ 

    /* ホスト側/非ブロッキング */ 
    void init_omatadd_descr(sycl::queue &queue, 
                            omatadd_descr_t *p_descr); 

    /* 非同期/非ブロッキング */ 
    sycl::event release_omatadd_descr(sycl::queue &queue, 
                                      omatadd_descr_t descr, 
                                      const std::vector<sycl::event> &dependencies = {}); 
}

`omatadd` API#

namespace oneapi::mkl::sparse { 
    /* USM/sycl::buffer API の統合、ホスト側/非ブロッキング */ 
    void omatadd_buffer_size(sycl::queue &queue, 
                             transpose opA, 
                             transpose opB, 
                             matrix_handle_t A, /* oneMKL 入力スパース行列ハンドルe */ 
                             matrix_handle_t B, /* oneMKL 入力スパース行列ハンドル */ 
                             matrix_handle_t C, /* oneMKL 出力スパース行列ハンドル */ 
                             omatadd_alg alg, 
                             omatadd_descr_t descr, /* omatadd 操作記述子 */ 
                             std::int64_t &sizeTempWorkspace); /* 一時的なワークスペースのサイズ */ 

    /* sycl::buffer API、非同期/非ブロッキング */ 
    void omatadd_analyze(sycl::queue &queue, 
                         transpose opA, 
                         transpose opB, 
                         matrix_handle_t A, 
                         matrix_handle_t B, 
                         matrix_handle_t C, 
                         omatadd_alg alg, 
                         omatadd_descr_t descr, 
                         sycl::buffer<std::uint8_t, 1> *tempWorkspace); /* 一時的なワークスペース */ 

    /* USM API、非同期/非ブロッキング */ 
    sycl::event omatadd_analyze(sycl::queue &queue, 
                                transpose opA, 
                                transpose opB, 
                                matrix_handle_t A, 
                                matrix_handle_t B, 
                                matrix_handle_t C, 
                                omatadd_alg alg, 
                                omatadd_descr_t descr, 
                                void *tempWorkspace, /* 一時的なワークスペース */ 
                                const std::vector<sycl::event> &dependencies = {}); 

    /* USM/sycl::buffer API の統合、同期/ブロッキング */ 
    void omatadd_get_nnz(sycl::queue &queue, 
                         transpose opA, 
                         transpose opB, 
                         matrix_handle_t A, 
                         matrix_handle_t B, 
                         matrix_handle_t C, 
                         omatadd_alg alg, 
                         omatadd_descr_t descr, 
                         std::int64_t &nnzC, /* C 行列の非ゼロカウントが返される */ 
                         const std::vector<sycl::event> &dependencies = {}); 

    /* USM/sycl::buffer API の統合、非同期/非ブロッキング */ 
    sycl::event omatadd(sycl::queue &queue, 
                     transpose opA, 
                     transpose opB, 
                     const DATA_TYPE alpha, /* A スケーリング係数 */ 
                     matrix_handle_t A, 
                     const DATA_TYPE beta, /* B スケーリング係数 */ 
                     matrix_handle_t B, matrix_handle_t C, /* ユーザー配列が満たされました */ 
                     omatadd_alg alg, 
                     omatadd_descr_t descr, 
                     const std::vector<sycl::event> &dependencies = {}); 
}

インクルード・ファイル#

oneapi/mkl/spblas.hpp

API パラメーター#

入力パラメーター#

queue

SYCL* カーネルの実行に使用する SYCL* コマンドキューを指定します。

opA、opB

入力行列 \(A\) と \(B\) に対する演算 op() を、oneapi::mkl::transpose 列挙タイプとして指定します。opA と opB のすべての組み合わせがサポートされています。

alpha、beta

\(\text{op}(A)\) 行列と \(\text{op}(B)\) 行列をそれぞれスケールするスカラー \(\alpha\) と \(\beta\) を指定します。

A、B

加算される入力スパース行列の行列ハンドル。\(A\) と \(B\) は、omatadd への入力としてソートされている必要はありませんが、両方の行列で sparse::sort_matrix() API が呼び出された場合、またはソートされたユーザー入力を保証する sorted プロパティーを設定するため両方の行列で sparse::set_matrix_property() API が呼び出された場合、パフォーマンスが大幅に向上する可能性があります。\(A\) と \(B\) の順序は、API 呼び出し間で変更してはなりません。

注

現在、\(A\) と \(B\) では CSR 行列形式のみがサポートされています。

alg

操作に使用するアルゴリズムの選択を指定する omatadd_alg enum。与えられた入力と記述子のセットは、alg は API 呼び出し間で変更してはなりません。

descr

入力データ、操作固有の情報、およびユーザー指定の一時ワークスペースを格納する omatadd_descr_t 記述子オブジェクト。これは、sparse::init_omatadd_descr, sparse::release_omatadd_descr ルーチンを使用して作成および破棄されます。

p_descr

割り当てに使用される omatadd_descr_t 記述子オブジェクト descr へのポインター。

tempWorkspace

行列加算演算の一時ワークスペースとして使用される、sizeTempWorkspace バイトの SYCL* 対応コンテナー (sycl::buffer またはデバイスアクセス可能な USM ポインター)。ワークスペースは、omatadd マルチステージ呼び出し全体を通じて有効である必要があり、行列追加 API 呼び出し間または descr の有効期間中は変更してはなりません。

sycl::buffer 入力の場合、tempWorkspace は sycl::buffer<std::uint8_t> * タイプになります。

USM 入力の場合、tempWorkspace はデバイスからアクセス可能な void * ポインターです。この場合、最高のパフォーマンスを得るには USM メモリータイプには USM デバイスが推奨されますが、デバイスからアクセス可能であるため、USM 共有および USM ホスト割り当てもサポートされます。

dependencies

呼び出されるルーチンが依存するイベントのリストを含む、const std::vector<sycl::event> & タイプのベクトル。

入出力パラメーター#

C: omatadd 操作の入出力行列ハンドル。\(C\) 行列ハンドルに設定された 0 または 1 ベースのインデックス・パラメーターは、omatadd 操作への入力となります。スパース行列配列はユーザーによって割り当てられ、ユーザーが所有し、sparse::set_<xyz>_data ルーチンの 1 つを使用して行列ハンドルに格納されます。ライブラリーは、omataddomatadd 操作の一部としてデータを入力します。出力行列配列がソートされているかどうかは保証されません。

注

現在、\(C\) では CSR 行列形式のみがサポートされています。

注

ソートされた出力データが必要な場合は、最後の sparse::omatadd API 呼び出しの後に、sparse::sort_matrix() API を個別に呼び出します。

注

\(C\) 行列ハンドルまたは配列を、入力の \(A\) および \(B\) ハンドルまたはその配列のエイリアスである (つまり、「インプレース」加算演算を試行する) ことは、未定義の動作です。

出力パラメーター#

sizeTempWorkspace: ユーザーが omatadd 呼び出しに割り当てる一時ワークスペース tempWorkspace のサイズ (バイト単位) を含む std::int64_t タイプの整数。このパラメーターは omatadd_buffer_size API から取得されます。
nnzC: 出力 \(C\) 行列内の形式固有の非ゼロ数を含む std::int64_t タイプの整数。ユーザーが出力行列配列を割り当てて所有するために使用します。このパラメーターは omatadd_get_nnz API から取得されます。

該当する戻り値のタイプ#

sycl::event: 待機できる SYCL* イベント。USM API の場合、omatadd ルーチンの後続ステージの完了のため、依存関係として継承される必要があります。

例 #

SYCL* バッファーまたは USM で oneapi::mkl::sparse::omatadd を使用する方法の例は、oneMKL インストール・ディレクトリーの次の場所にあります。

share/doc/mkl/examples/sycl/sparse_blas/source/csr_omatadd.cpp

share/doc/mkl/examples/sycl/sparse_blas/source/csr_omatadd_usm.cpp

oneapi::mkl::sparse::omatadd

目次

oneapi::mkl::sparse::omatadd#

説明#

ステージ#

API#

構文#

enum omatadd_alg#

omatadd_descr_t オブジェクト#

omatadd API#

インクルード・ファイル#

API パラメーター#

入力パラメーター#

入出力パラメーター#

出力パラメーター#

該当する戻り値のタイプ#

例#

説明 #

ステージ #

API #

`enum omatadd_alg`#

`omatadd_descr_t` オブジェクト#

`omatadd` API#

例 #