oneapi::mkl::sparse::omatconvert

oneapi::mkl::sparse::omatconvert#

行列ハンドル内のユーザーデータを、異なるスパース行列形式の新しいハンドル内のユーザーデータにアウトオブプレースで変換します。

説明#

注

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

oneapi::mkl::sparse::omatconvert ルーチンのセットを使用すると、入力行列として参照されるスパース形式のスパース行列を、出力行列である別の形式の別のスパース行列に変換できます。これらの API では、アウトオブプレースの変換のみがサポートされます。API でサポートされているスパース行列形式は、圧縮スパース行 (CSR) と座標リスト形式 (COO) のみです。入力行列と出力行列のスパース行列形式は異なっている必要があります。行列のコピーを実行する方法は、sparse::omatcopy API を参照してください。このコピーでは、コピー内の index_base を変更、および行列の転置をコピーする可能性があります。

変換プロセス全体は一連のステージに分解されます。各ステージは、1 つ omatconvert ルーチン呼び出しで構成され、ユーザーが指定するメモリー割り当ても含まれる場合があります。API は、最小限のデータが内部的に割り当てられ、必要なメモリー割り当ての大部分はユーザーが行うように設計されています。これは、変換プロセス中に必要な一時的なワークスペースと、出力行列のデータを格納するメモリーに適用されます。

出力行列のデータを割り当てに必要なサイズは、行数や列数など事前に判明しているパラメーターや、出力行列表現内のゼロ以外の要素数などの事前に不明であるパラメーターでは異なる場合があります。2 番目の状況に対処するため、実際の変換に入る前に出力行列内のゼロ以外の要素の数を計算する API が提供されています。

omatconvert アルゴリズムのステージを以下に示します (定義については、omatconvert API API とステージを参照してください)。

ステージ

説明

omatconvert_buffer_size

一時ワークスペースのサイズを返します。

omatconvert_analyze

出力スパース行列内のゼロ以外の値 (nnzOut) の数をカウントします。

omatconvert_get_nnz

出力スパース行列の計算された nnzOut カウントを返します。

omatconvert

入力行列から出力行列への変換を実行します。

変換プロセスの詳細な手順は次のとおりです:

  1. omatconvert ステージの前:

    • oneapi::mkl::sparse::set_<sparse_matrix_type>_data を使用して出力行列のハンドルを作成します。ここで、<sparse_matrix_type> は出力行列の形式を表します。

    • 出力行列のインデックスは、入力行列のインデックスとは異なる場合があります。

    • このステージでは、非ゼロ要素の数を 0 に設定でき、行列表現配列にダミー引数を使用できます (例: CSR の場合: rowptr、colind、および values)。

    • init_omatconvert_descr API を使用して omatconvert_descr_t オブジェクトを割り当てて初期化し、列挙タイプ omatconvert_alg enum で使用するアルゴリズムを決定します。一連の omatconvert API 呼び出し内でアルゴリズムを変更してはなりません。

  2. omatconvert_buffer_size ステージ:

    • これは、入力行列配列にアクセスする非ブロッキング API です。

    • omatconvert_buffer_size API 呼び出しは、一時ワークスペースのサイズを取得します。

    • 後続のステージで使用する一時ワークスペースを割り当てます。

  3. omatconvert_analyze ステージ:

    • これは、入力行列のスパースパターンと出力行列の既知のパラメーターにアクセスして解析する非ブロッキング非同期 API です。

    • 前のステージで割り当てられた一時ワークスペースを渡して omatconvert_analyze API を呼び出します。

    • 一時ワークスペース配列は、omatconvert_descr_t オブジェクトに格納されます。omatconvert_descr_t オブジェクトが有効でり、スパース行列変換に使用されている間は、ワークスペースを変更および解放ししてはなりません。

  4. omatconvert_get_nnz ステージ:

    • これは、omatconvert_analyze ステージから取得したゼロ以外のカウントをホスト上のユーザーに返すブロッキング API です。

    • omatconvert_get_nnz API を呼び出して、出力スパース行列に関連付けられた非ゼロのカウントを取得します。

    • 適切なサイズの出力スパース行列配列を割り当てます。

    • oneapi::mkl::sparse::set_<sparse_matrix_type>_data API を再度呼び出します。今回は、出力スパース行列の新しく割り当てられた行、列、およびデータ配列を使用します。この時点で、出力の 0/1 ベースのインデックスは変更してはならず、行列の行数と列数は、入力行列のサイズと数学的に一致している必要があります。

  5. omatconvert ステージ:

    • これは、スパース行列変換を実行して、ユーザー指定の出力行列配列を要求されたスパース形式で埋める非ブロッキング非同期 API です。

    • omatconvert API を呼び出します。

  6. omatconvert ステージの後 :

    • 別の変換に、omatconvert_descr_t オブジェクトを解放するか再利用します。

    • この API で使用するために割り当てられた一時ワークスペース配列を解放または再利用します。

API#

構文#

enum omatconvert_alg と変換アルゴリズム#

omataconvert_alg enum タイプは、oneMKL に実装された特定のアルゴリズムを使用する選択肢を提供します。enum は次のように定義されます。

namespace oneapi::mkl::sparse { 
    enum class omataconvert_alg : std::int32_t { 
        default_alg = 0     /* 将来的にはさらに追加される可能性があります */ 
    }; 
}

すべての変換構成でサポートされているアルゴリズムのリストを示します。

変換タイプ

サポートされるアルゴリズム

アルゴリズムの説明

CSR -> COO

omatconvert_alg::default

CSR から COO への変換のデフォルト・アルゴリズム

COO -> CSR

omatconvert_alg::default

COO から CSR への変換のデフォルト・アルゴリズム重複する要素は圧縮されます。

omatconvert_descr_t オブジェクト#

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

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

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

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

omatconvert API とステージ#

namespace oneapi::mkl::sparse { 

    /* USM/sycl::buffer API の統合、ホスト側/非ブロッキング */ 
    void omatconvert_buffer_size( 
        sycl::queue &queue, 
        matrix_handle_t spMat_in, 
        matrix_handle_t spMat_out, 
        omatconvert_alg alg, 
        omatconvert_descr_t descr, 
        std::int64_t &sizeTempWorkspace); 

    /* sycl::buffer API、非同期/非ブロッキング */ 
    sycl::event omatconvert_analyze( 
        sycl::queue &queue, 
        matrix_handle_t spMat_in, 
        matrix_handle_t spMat_out, 
        omatconvert_alg alg, 
        omatconvert_descr_t descr, 
        void *tempWorkspace, 
        const std::vector<sycl::event> &dependencies = {}); 

    /* USM API、非同期/非ブロッキング */ 
    void omatconvert_analyze( 
        sycl::queue &queue, 
        matrix_handle_t spMat_in, 
        matrix_handle_t spMat_out, 
        omatconvert_alg alg, 
        omatconvert_descr_t descr, 
        sycl::buffer<std::uint8_t, 1> *tempWorkspace); 

    /* USM/sycl::buffer API の統合、同期/ブロッキング */ 
    void omatconvert_get_nnz( 
        sycl::queue &queue, 
        matrix_handle_t spMat_in, 
        matrix_handle_t spMat_out, 
        omatconvert_alg alg, 
        omatconvert_descr_t descr, 
        std::int64_t &nnzOut, 
        const std::vector<sycl::event> &dependencies = {}); 

    /* USM/sycl::buffer API の統合、非同期/非ブロッキング */ 
    sycl::event omatconvert( 
        sycl::queue &queue, 
        matrix_handle_t spMat_in, 
        matrix_handle_t spMat_out, 
        omatconvert_alg alg, 
        omatconvert_descr_t descr, 
        const std::vector<sycl::event> &dependencies = {}); 
}

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

  • oneapi/mkl/spblas.hpp

入力パラメーター#

queue

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

spMat_in

入力スパース行列およびその他の内部データを含むオブジェクトへのハンドル。oneapi::mkl::sparse::set_<sparse_matrix_type>_data ルーチンの 1 つを使用して作成されます。

注

<sparse_matrix_type> でサポートされているケースは、CPU と GPU デバイスの両方で csr と coo です。

spMat_out

出力スパース行列およびその他の内部データを含むオブジェクトへのハンドル。oneapi::mkl::sparse::set_<sparse_matrix_type>_data ルーチンの 1 つを使用して作成されます。入力ハンドルと出力ハンドルのスパース行列の次元は同じである必要があります。このステージでは、このハンドルの配列にデータを割り当てておく必要があります。

注

<sparse_matrix_type> でサポートされているケースは、CPU と GPU デバイスの両方で csr と coo です。spMat_out の <sparse_matrix_type> は、spMat_in と異なる必要があります。

alg

変換に使用するアルゴリズムを指定する omatconvert_alg enum利用可能なオプションについては上記を参照してください。

descr

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

tempWorkspace

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

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

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

dependencies

oneapi::mkl::sparse::omatconvert ルーチンが依存するイベントのリストを含む、std::vector<sycl::event> & タイプのベクトル。

出力パラメーター#

sizeTempWorkspace

omatconvert_analyze および omatconvert 呼び出しに割り当てる一時ワークスペース tempWorkspace のサイズ (バイト単位) を含む std::int64_t タイプの整数。このパラメーターは omatconvert_buffer_size API から取得されます。

nnzOut

出力行列配列を割り当てるために使用される、出力行列内の形式固有の非ゼロ数を含む std::int64_t タイプの整数。このパラメーターは omatconvert_get_nnz API から取得されます。

spMat_out

戻り時に、スパース行列のデータは、要求された <sparse_matrix_type> に従って入力されます。

戻り値#

sycl::event

omatconvert ルーチンの完了を待機したり、依存関係として追加される SYCL* イベント。

例#

SYCL バッファーまたは USM で oneapi::mkl::sparse::omatconvert を使用する例と関連する API の例は、oneMKL インストール・ディレクトリーの以下の場所にあります。

share/doc/mkl/examples/sycl/sparse_blas/source/csr2coo_omatconvert.cpp
share/doc/mkl/examples/sycl/sparse_blas/source/coo2csr_omatconvert_usm.cpp