oneAPI 仕様
リリース 1.0 リビジョン 3
日本語参考訳 Part 1 (1 – 311 ページ)
インテル コーポレーション
2020 年 11 月 23 日
注意事項:
1.

2.

この日本語マニュアルは、oneAPI のウェブサイト: https://spec.oneapi.com/versions/latest/versions.html (英語) で公開されている『oneAPI Specification Release 1.0-rev-2』の参考訳です。インテル社の許可を得て iSUS (IASoftware User Society) が翻訳版を作成した iSUS の著作物です。原文は Intel Corporation の Copyright であり、日本語参考訳版にも適用されます。
英語版と日本語版のページ番号は必ずしも同一ではありません。

目次
第 1 章 はじめに ........................................................................................................................................ 2
1.1
1.2
1.3
1.4

対象とする読者 ........................................................................................................................................................................ 2仕様の目標 ............................................................................................................................................................................... 3
定義 ............................................................................................................................................................................................ 3
寄稿のガイドライン ................................................................................................................................................................ 3
1.4.1 署名 ............................................................................................................................................................................. 3

第 2 章 ソフトウェア・アーキテクチャー ................................................................................................. 4
2.1 oneAPI プラットフォーム ..................................................................................................................................................... 5
2.2 API プログラミングの例 ....................................................................................................................................................... 6
2.3 ダイレクト・プログラミングの例 .......................................................................................................................................... 6

第 3 章 DPC++ .......................................................................................................................................... 8
3.1
3.2
3.3
3.4
3.5

概要 ............................................................................................................................................................................................ 8
API と言語の詳細 .................................................................................................................................................................10
オープンソース実装 .............................................................................................................................................................12
テスト .......................................................................................................................................................................................12
謝辞 ..........................................................................................................................................................................................12

第 4 章 oneDPL ..................................................................................................................................... 13
4.1 名前空間 .................................................................................................................................................................................13
4.2 サポートされる C++ 標準ライブラリー API とアルゴリズム .....................................................................................13
4.3 Parallel STL 拡張 ................................................................................................................................................................13
4.3.1 DPC++ 実行ポリシー ............................................................................................................................................13
4.3.2 バッファーラッパー ................................................................................................................................................16
4.4 oneDPL API 仕様.................................................................................................................................................................174.4.1 関数オブジェクト ....................................................................................................................................................17
4.4.2 イテレーター ............................................................................................................................................................17
4.4.3 並列アルゴリズム ...................................................................................................................................................22

第 5 章 oneDNN .................................................................................................................................... 25
5.1 概要 ..........................................................................................................................................................................................26
5.1.1 一般的な API の注意 .............................................................................................................................................28
5.1.2 エラー処理 ...............................................................................................................................................................28
5.1.3 名前空間 ...................................................................................................................................................................28
5.2 規則 ..........................................................................................................................................................................................28
5.2.1 変数 (Tensor) 名 ....................................................................................................................................................28
5.2.2 RNN 固有の表記 ....................................................................................................................................................30
5.3 実行モデル .............................................................................................................................................................................30
5.3.1 エンジン ...................................................................................................................................................................31
5.3.2 ストリーム ................................................................................................................................................................33
5.4 データモデル ..........................................................................................................................................................................34
iii

5.5

5.6
5.7
5.8

5.4.1 データ型....................................................................................................................................................................34
5.4.2 メモリー ....................................................................................................................................................................36
プリミティブ ...........................................................................................................................................................................54
5.5.1 共通定義 ...................................................................................................................................................................56
5.5.2 属性 ...........................................................................................................................................................................72
5.5.3 バッチ正規化 ...........................................................................................................................................................88
5.5.4 バイナリー ................................................................................................................................................................96
5.5.5 結合 (Concat) .........................................................................................................................................................99
5.5.6 畳み込みと逆畳み込み ....................................................................................................................................... 102
5.5.7 要素単位 ................................................................................................................................................................ 128
5.5.8 内積 ........................................................................................................................................................................ 135
5.5.9 レイヤーの正規化 ................................................................................................................................................ 144
5.5.10 LogSoftmax ..................................................................................................................................................... 152
5.5.11 ローカル応答の正規化 ................................................................................................................................... 156
5.5.12 行列の乗算 ......................................................................................................................................................... 162
5.5.13 プーリング .......................................................................................................................................................... 166
5.5.14 リオーダー .......................................................................................................................................................... 172
5.5.15 リサンプリング .................................................................................................................................................. 176
5.5.16 RNN ..................................................................................................................................................................... 183
5.5.17 シャッフル........................................................................................................................................................... 221
5.5.18 ソフトマックス .................................................................................................................................................. 225
5.5.19 累積 ...................................................................................................................................................................... 230
オープンソース実装 .......................................................................................................................................................... 232
実装の注意点 ...................................................................................................................................................................... 232
テスト .................................................................................................................................................................................... 232

第 6 章 oneCCL ................................................................................................................................... 233
6.1 概要 ....................................................................................................................................................................................... 233
6.2 名前空間 .............................................................................................................................................................................. 233
6.2.1 oneapi::ccl 名前空間 ......................................................................................................................................... 233
6.2.2 ccl 名前空間 ......................................................................................................................................................... 233
6.3 現在のバージョンの oneCCL 仕様 ............................................................................................................................... 234
6.4 定義 ....................................................................................................................................................................................... 234
6.4.1 oneCCL の概念 ................................................................................................................................................... 234
6.4.2 通信操作 ................................................................................................................................................................ 240
6.4.3 エラー処理 ............................................................................................................................................................ 252
6.5 プログラミング・モデル .................................................................................................................................................... 253
6.5.1 一般的なワークフロー ....................................................................................................................................... 253

第 7 章 レベルゼロ ............................................................................................................................... 255
7.1 API の詳細説明 .................................................................................................................................................................. 255

第 8 章 oneDAL ................................................................................................................................... 256
8.1 概要 ....................................................................................................................................................................................... 256
8.2 用語集 ................................................................................................................................................................................... 258
iv

8.3
8.4

8.5

8.6

8.7

8.8
8.9

8.2.1 マシンラーニング用語 ....................................................................................................................................... 258
8.2.2 oneDAL の用語 ................................................................................................................................................... 260
8.2.3 oneAPI の一般用語............................................................................................................................................ 262
数学表記 .............................................................................................................................................................................. 263
プログラミング・モデル .................................................................................................................................................... 263
8.4.1 エンドツーエンドの例 ........................................................................................................................................ 264
8.4.2 記述子 .................................................................................................................................................................... 265
8.4.3 操作 (Operation) ................................................................................................................................................ 267
8.4.4 計算モード ............................................................................................................................................................ 272
共通インターフェイス ........................................................................................................................................................ 273
8.5.1 現在のバージョンの oneDAL 仕様 ................................................................................................................ 273
8.5.2 ヘッダーファイル ................................................................................................................................................. 273
8.5.3 名前空間 ................................................................................................................................................................ 274
8.5.4 エラー処理 ............................................................................................................................................................ 274
8.5.5 共通型定義 ........................................................................................................................................................... 276
データ管理 ........................................................................................................................................................................... 278
8.6.1 主要な概念............................................................................................................................................................ 279
8.6.2 詳細 ........................................................................................................................................................................ 283
アルゴリズム ....................................................................................................................................................................... 309
8.7.1 クラスタリング ..................................................................................................................................................... 309
8.7.2 近傍法 (kNN)........................................................................................................................................................ 322
8.7.3 分解 ........................................................................................................................................................................ 330
付録 ....................................................................................................................................................................................... 339
8.8.1 k-d ツリー ............................................................................................................................................................. 339
文献目録 .............................................................................................................................................................................. 339v

oneAPI 仕様 リリース 1.0 リビジョン 3
oneAPI は、オープンで無料の標準化ベースのプログラミング・システムであり、アクセラレーターとハードウェア世代全体に渡る移植性とパフォーマンスを提供します。oneAPI は、並列アプリケーションを作成する言語とライブラリーで構成されます。
• DPC++: アクセラレーターとマルチプロセッサーをプログラミングする oneAPI のコア言語。DPCPP により、開発者はハードウェア・ターゲット (CPU および GPU、FPGA などのアクセラレーター) 全体でコードを再利用し、特定のアーキテクチャーに合わせてチューニングできます。
• oneDPL: C++ 標準ライブラリー、Parallel STL、および拡張 API を使用して oneAPI デバイスをプログラミ
ングする DPC++ 向けのライブラリーです。
• oneDNN: ディープラーニング・フレームワーク向けプリミティブのハイパフォーマンス実装です。
• oneCCL: 複数のデバイス間でディープラーニング・フレームワークをスケーリングする通信プリミティブです。
• レベルゼロ: oneAPI 言語およびライブラリーのシステム・インターフェイスです。
• oneDAL: データサイエンスを加速するアルゴリズムです。
• oneTBB: マルチプロセッサー上の複雑なアプリケーションでスレッドベースの並列処理を導入するライブ
ラリーです。
• oneVPL: ビデオ処理を加速するアルゴリズムです。
• oneMKL: 科学、工学、および金融アプリケーション向けのハイパフォーマンス数学ルーチンです。

目次

1

第1章
はじめに
oneAPI は、アクセラレーター・アーキテクチャー全体で同じ言語とプログラミング・モデルを提供することで、ソフトウェ
ア開発を簡素化します。この章では、プログラミング・モデルについて述べます。
並列アプリケーション開発は、システムによって提供される並列アルゴリズムを実装する API プログラミングと、プログラマーが並列アルゴリズムを作成するダイレクト・プログラミングの組み合わせです。
API プログラミングを行う場合、プログラマーはライブラリーを呼び出すことでプログラムのパフォーマンス上重要なコード領域を記述します。適切に定義され成熟した問題ドメインには、ライブラリーとしてパッケージ化されたハイパ
フォーマンス・ソリューションがあります。oneAPI は、最もよく使用されるデータ並列ドメイン向けの API セットを定義
し、oneAPI プラットフォームは、各種アクセラレーター向けのライブラリー実装を提供します。可能な限り、API は
BLAS などすでに確立された標準化をベースとしています。API プログラミング・モデルにより、プログラマーは最小限のコーディングとチューニングで、各種アクセラレーターのセット全体で高いパフォーマンスを達成できます。
一部の問題ドメインには標準化されたソリューションが存在しないか、ソリューションがライブラリーで容易に実装できない調整を必要とするため、API プログラミング・モデルにはあまり適していません。この場合、プログラマーはダイレ
クト・プログラミングにより並列アルゴリズムを明示的に記述する必要があります。oneAPI のプログラミング・モデルは、
データ並列処理に基づいており、各データ要素に対し同じ計算が実行されるためアプリケーションの並列性はデータのスケーリングに応じて向上します。プログラマーが並列処理を直接表現できるようにすることで、データ並列アルゴリズ
ムが並列アーキテクチャー向けに高い効率を持つアルゴリズムを生産的に作成することを可能にします。
データ並列アルゴリズムは、科学計算、人工知能、可視化など、計算量が非常に多い問題の解決に使用されます。データ
並列アルゴリズムは、マルチコア CPU、GPU、シストリック・アレイ、FPGA などさまざまなアーキテクチャー・セットに効率良くマッピングできます。

1.1

対象とする読者

この仕様の対象読者には、アプリケーション開発者、ミドルウェア開発者、システム・ソフトウェア・プロバイダー、および
ハードウェア・プロバイダーが含まれます。この仕様への貢献者として、アクセラレーター向けのソフトウェア・エコシス
テムの構築に参加いただけます。生産的でハイパフォーマンスなシステムでは、ソフトウェア・スタックのすべてのレベルでこの仕様を考慮する必要があります。この仕様書の利用者は、コンポーネントを oneAPI プラットフォームのアプリ
ケーションおよびシステム・ソフトウェアと相互に運用することが可能になります。

2

oneAPI 仕様 リリース 1.0 リビジョン 3

1.2

仕様の目標

oneAPI は以下を提供することを目標としています。
• ソースレベルの互換性: 再コンパイルとチューニングにより、oneAPI アプリケーションとミドルウェアを
oneAPI 準拠のプラットフォームに移植します。
• パフォーマンスの透過性: API と言語構造により、プログラマーはハードウェア間のマッピングを十分に制御することで、効率良いソリューションを作成できます。
• ソフトウェア・スタックの移植性: プラットフォーム・プロバイダーは、oneAPI レベルゼロ・インターフェイス
を実装することで、oneAPI ソフトウェア・スタックを移植できます。

1.3

定義

この仕様では、RFC 2119 (英語) で明示される、「すべきである」、「すべきではない」、「必須」などの定義を採用してい
ます。

1.4

寄稿のガイドライン

この仕様は、相互運用性と互換性を実現し、オープンで公正なプロセスで仕様を策定するため、標準化グループおよび
Khronos Group などの業界/学術イニシアチブと協力してきたインテル社の数十年にわたる継続的な取り組みの成果です。oneAPI はオープン仕様であり、皆さんの参加により良いものとなることを願っています。フィードバックは任意ですが、インテルがこの仕様にフィードバックを盛り込み、Khronos Group SYCL* 仕様を含む上位の標準化団体にフィードバックを送れるように、次の条件に基づいてフィードバックをお送りください。皆さんの oneAPI 仕様へのフィードバッ
クは、それぞれの提出ポリシーに基づく Khronos Group を含む他の標準化団体へのフィードバックの送信を妨げるものではありません。
oneAPI 仕様の GitHub* リポジトリー (英語) で投稿を開いて oneAPI 仕様の策定に貢献いただけます。

1.4.1 署名
フィードバックのすべての投稿に署名入りのタグを含めてください。署名入りのタグを含めることで、次のことに同意したことになります: (a) インテルにフィードバックをライセンス供与する権利があります。(b) インテルは、知的財産権またはライセンス義務に限定されない、いかなる種類の義務または制限なしに、独自の裁量でフィードバックを自由に使用、開示、複製、変更、ライセンス供与、または配布することがあります。(c) フィードバックは公開され、その記録は無期限に保持される場合があります。
上記に同意する場合、フィードバックのすべての投稿に含む次の行を記載する必要があります:
Signed-off-by: <本名> <メールアドレス>
例: Signed-off-by: Joe Smith joe.smith@email.com

1.2 仕様の目標

3第2章
ソフトウェア・アーキテクチャー
oneAPI は、さまざまなデータ並列アクセラレーター向けに共通のプログラミング・インターフェイスを提供します (以下の図を参照)。プログラマーは、API プログラミングとダイレクト・プログラミングの両方で DPC++ を利用します。
oneAPI プラットフォームの機能は、システム・ソフトウェアで oneAPI デバイスの一般抽象化を提供するレベルゼロ・
インターフェイスによって決定されます。

4

oneAPI 仕様 リリース 1.0 リビジョン 3

2.1

oneAPI プラットフォーム

oneAPI プラットフォームは、ホストとデバイスのコレクションで構成されます。ホストは通常マルチコア CPU であり、デバイスは 1 つ以上の GPU、FPGA、またはその他のアクセラレーターです。ホストとして機能するプロセッサーは、ソフ
トウェアによってターゲットデバイスとすることもできます。
各デバイスには関連付けられたコマンドキューがあります。oneAPI を採用するアプリケーションは、標準 C++ 実行セ
マンティクスに従ってホスト上で実行されます。関数オブジェクトをデバイス上で実行するには、アプリケーションは関数オブジェクトを含むコマンドグループをデバイスのキューに送信します。関数オブジェクトには、関連する変数と関数定義が含まれます。キューに送信された関数オブジェクトは、データ並列カーネルまたは単にカーネルと呼ばれます。
ホストで実行されるアプリケーションとデバイスで実行される関数は、メモリーを介して通信します。oneAPI は、デバイスの機能に応じてプラットフォーム全体でメモリーを共有するいくつかのメカニズムを定義しています。
メモリー共有メカニズム

説明

バッファー・オブジェクト

アプリケーションは、デバイスにデータを渡すためバッファー・オブジェクトを作成できます。バッファーはデータ配列です。コマンドグループは、デバイスの呼び出しでアクセスされるバッファーを特定するアクセサー・オブジェクトを定義します。oneAPI ラン
タイムは、デバイスで実行される関数がバッファー内のデータにアクセスできるようにします。バッファーアクセサーのメカニズムは、すべての oneAPI プラットフォームで利用できます。

統合アドレス指定

統合アドレス指定は、ホストとすべてのデバイスが統合アドレス空間を共有することを可能にします。統合アドレス空間のポインター値は、常にメモリー上の同じ場所を指します。

統合共有メモリー

統合共有メモリーを使用すると、バッファーやアクセサーを使用することなくポイン
ターを介してデータを共有できます。使用するデバイスの機能に応じて、この機能にはいくつかのレベルのサポートが提供されます。

スケジューラーは、コマンドグループをデバイスで実行するタイミングを決定します。コマンドグループを実行する準備ができたことを判断するため、次のメカニズムが採用されています。
• バッファーアクセサー方式を使用する場合、バッファーが定義され必要に応じてデバイスにコピーされると、コマンドグループの準備が整います。
• デバイスで順序付けされたキューが使用されると、キュー内の直前のコマンドグループが完了すると、次のコマンドグループの準備が整います。
• 統合共有メモリーを使用する場合、コマンドグループに関連するイベント・オブジェクトのセットを指定する必要があります。すべてのイベントが完了するとコマンドグループの準備が整います。
ホスト上のアプリケーションとデバイス上の関数は、実行を調整する機能を持つオブジェクトであるイベントを介して同期できます。バッファーアクセサーを使用する場合、アプリケーションとデバイスはホストアクセサー、バッファー・オブ
ジェクトの破棄、またはより高度なメカニズムを使用して同期することもできます。

2.1 oneAPI プラットフォーム

5

oneAPI 仕様 リリース 1.0 リビジョン 3

2.2

API プログラミングの例

API プログラミングでは、プログラマーがターゲットデバイスとメモリー通信方法を指定する必要があります。次の例では、oneMKL 行列乗算ルーチン (GEMM) を呼び出します。DPC++ で記述され、関係のないコードは省略されています。
GPU での計算を指定する gpu_selector で初期化されたキューを作成し、ホストで割り当てられたバッファーを保持するバッファーを定義します。標準の C++ の GEMM 呼び出しに、キューを指定するパラメーターを追加して、配列への参照を含むバッファー参照へ置き換えます。それ以外は、標準の GEMM C++ インターフェイスと同一です。
using namespace cl::sycl;// ホスト配列を宣言
double *A = new double[M*N];
double *B = new double[N*P];
double *C = new double[M*P];{// gpu_selector でデバイスキューを初期化
queue q{gpu_selector()};// ホストの配列にバインドされる行列の 1D バッファーを作成
buffer<double, 1> a{A, range<1>{M*N}};
buffer<double, 1> b{B, range<1>{N*P}};
buffer<double, 1> c{C, range<1>{M*P}};
mkl::transpose nT = mkl::transpose::nontrans;// 構文//
void gemm(queue &exec_queue, transpose transa, transpose transb,//
int64_t m, int64_t n, int64_t k, T alpha,//buffer<T,1> &a, int64_t lda,//
buffer<T,1> &b, int64_t ldb, T beta,//
buffer<T,1> &c, int64_t ldc);// call gemm
mkl::blas::gemm(q, nT, nT, M, P, N, 1.0, a, M, b, N, 0.0, c, M);}// ブロックを終了すると、バッファーのデストラクターは結果を配列 C に書き戻します

2.3

ダイレクト・プログラミングの例

ダイレクト・プログラミングでは、API プログラミングと同様に、ターゲットデバイスとメモリー通信方法を指定します。
さらに、計算を実行するコマンドグループを定義して送信する必要があります。次の例は、単純な並列行列乗算を示します。DPC++ で記述され、関係のないコードは省略されています。
コマンドグループを GPU で実行するため、gpu_selector で初期化されたキューを作成し、ホストで割り当てられた
バッファーを保持するバッファーを定義します。次に、コマンドグループをキューに送信して計算を実行します。コマンド
グループは、配列 A と B を読み取り、C に書き込むアクセサーを定義します。次に、C++ ラムダ関数を記述して、行列乗
算の 1 要素を計算する関数オブジェクトを作成します。関数オブジェクトを配列 A と B に対し並列に関数をマップする
parallel_for へのパラメーターとして指定します。カーネルのスコープを離れると、C を保持するバッファー・オブ
ジェクトのデストラクターがデータをホストの配列に書き戻します。
2.2 API プログラミングの例

6

oneAPI 仕様 リリース 1.0 リビジョン 3
using namespace cl::sycl;// ホストの配列を宣言
double *Ahost = new double [M*N];
double *Bhost = new double [N*P];
double *Chost = new double [M*P];{// gpu_selector でデバイスキューを初期化
queue q{gpu_selector()};// ホストの配列にバインドされる行列の 2D バッファーを作成
buffer<double, 2> a{Ahost, range<2>{M,N}};buffer<double, 2> b{Bhost, range<2>{N,P}};buffer<double, 2> c{Chost, range<2>{M,P}};// 行列 c=a*b を計算するコマンドグループをキューに送信
q.submit([&](handler &h){// A と B を読み取り、C に書き込み
auto A = a.get_access<access::mode::read>(h);auto B = b.get_access<access::mode::read>(h);auto C = c.get_access<access::mode::write>(h);int WidthA = a.get_range()[1];// カーネルを実行
h.parallel_for<class MatrixMult>(range<2>{M, P}, [=](id<2> index){
int row = index[0];int col = index[1];}// 配列 C の 1 つの要素の結果を計算
double sum = 0.0;
for (int i = 0; i < WidthA; i++) { sum += A[row][i] * B[i][col];C[index] = sum;

});

});
}
// ブロックを終了すると、バッファーのデストラクターは結果を配列 C に書き戻します

2.3 ダイレクト・プログラミングの例

7

第3章
DPC++
3.1

概要

oneAPI データ並列 C++ (DPC++) は、oneAPI のダイレクト・プログラミング言語と関連するダイレクト・プログラミン
グ API で構成されます。データ並列関数を定義してデバイスで起動するために必要な機能を提供します。この言語は次のコンポーネントで構成されています。
• C++。すべての DPC++ プログラムはまた、C++ プログラムでもあります。DPC++ 準拠の実装は、C++17 コ
ア言語 (ISO/IEC 14882:2017 のセクション 1-19) 以降の仕様をサポートする必要があります。C++ 標準(英語) を参照してください。
• SYCL*。DPC++ は Khronos Group の SYCL* 仕様をベースにしています。SYCL* 言語はデバイスにオフロードするデータ並列関数の定義を可能にし、オフロードされた関数を管理するランタイム API とクラスを定義します。
• DPC++ 言語拡張。DPC++ に準拠した実装は、指定された言語をサポートする必要があります。これには、
統合共有メモリー (USM)、順序付きキュー、およびリダクションが含まれます。一部の拡張機能は、拡張機能表に要約されるように、DPC++ 実装が特定クラスのデバイスをサポートする場合にのみ必要です。実装
では、実装に組込まれた明示的なサポートを通して、または oneAPI レベルゼロなどのデバイスクラスをサポートする下位のレイヤーを使用して、DPC++ デバイス型クエリーに対し「true」を返すハードウェアをターゲットにする場合、そのデバイスクラスをサポートします。DPC++ 実装は、実装がサポートするデバイス
クラスに必要なすべての拡張機能 (拡張機能表) の適合テストに合格する必要があります (SYCL* 拡張 (英語) を参照)。
この仕様では、少なくとも C++17 コア言語のサポートと DPC++ 拡張機能が必須です。言語のバージョンと機能カバ
レッジの要件は時間経過とともに進化し、特定バージョンの C++ と SYCL* が必須となりそれとともに拡張機能が追加されます。新しい C++ や SYCL* バージョンで要件がカバーされる場合、それに該当する DPC++ 拡張機能は不要になります。

8

oneAPI 仕様 リリース 1.0 リビジョン 3
表 1: DPC++ 拡張テーブル: SYCL* 1.2.1 以降の DPC++ 実装のサポート要件
機能

定義元

CPU

GPU

FPGA

Test1

アクセサーの簡略化

SYCL* 2020 暫定 (英語) 必須

必須

必須

利用不可3

bit_cast

SYCL* 2020 暫定 (英語) 必須

必須

必須

利用不可3

デダクション・ガイド

SYCL* 2020 暫定 (英語) 必須

必須

必須

利用不可3

デバイス固有のクエリー

SYCL* 2020 暫定 (英語) 必要なし4 必要なし4 必要なし4 利用不可3

拡張アトミックSYCL* 2020 暫定 (英語) 必須7

必須7

必要なし4 利用不可3

カーネル関数型属性

SYCL* 2020 暫定 (英語) 必須

必須

必須

利用不可3

インオーダー・キューSYCL* 2020 暫定 (英語) 必須

必須

必須

利用不可3

数学配列

SYCL* 2020 暫定 (英語) 必要なし4 必要なし4 必要なし4 利用不可3オプションのラムダ名

SYCL* 2020 暫定 (英語) 必須

必須

必須

利用不可3

キューのショートカット

SYCL* 2020 暫定 (英語) 必須

必須

必須

利用不可3

必須 work-group サイズ

SYCL* 2020 暫定 (英語) 必須

必須

必須

利用不可3

標準レイアウトの緩和

SYCL* 2020 暫定 (英語) 必須

必須

必須

利用不可3

統合共有メモリー

SYCL* 2020 暫定 (英語) 必須2

必須2

必須2

usm (英語)

アクセサー・プロパティー (英語)DPC++ 拡張

必須8

必須8

必須8

利用不可3

CXX 標準ライブラリー (英語)DPC++ 拡張

必須

必須

必要なし4 利用不可3

データ・フロー・パイプ (英語)DPC++ 拡張

必要なし

必要なし

必須

fpga_tests (英語)

キューに投入されたバリア (英語)DPC++ 拡張

必須

必須

必須

利用不可3

グループ・アルゴリズム (英語)DPC++ 拡張

必須

必須

必要なし4 利用不可3

グループマスク (英語)DPC++ 拡張

必要なし4 必要なし4 必要なし4 利用不可3

Parallel for ショートカット (英語)DPC++ 拡張

必須

必須

必須

利用不可3

メモリー・プロパティーの固定 (英語)DPC++ 拡張

必須

必須

必須

利用不可3

リダクション (英語)DPC++ 拡張

必須5

必須5

必要なし4 利用不可3

すべての引数を制限 (英語)DPC++ 拡張

必須

必須

必須

利用不可3

静的ローカルメモリーのクエリー (英語) DPC++ 拡張

必要なし4 必要なし4 必要なし4 利用不可3Sub-groups (英語)DPC++ 拡張

必須

必須

必要なし

sub_group (英語)

Sub-group アルゴリズム (英語)DPC++ 拡張

必須6

必須6

必要なし

sub_group (英語)

3.1 概要9oneAPI 仕様 リリース 1.0 リビジョン 3

3.2

API と言語の詳細

SYCL* 1.2.1 仕様 (英語) では、SYCL* API と言語について説明しています。SYCL* 上の DPC++ 拡張は、SYCL* 拡張(英語) リポジトリーに記述されています。拡張機能表に記載されているように、SYCL* 2020 暫定仕様 (英語) で定義さ
れ SYCL* 1.2.1 仕様 (英語) には含まれない一部の機能は DPC++ 拡張が必要であり、大部分の機能はこの仕様以前のバージョンで必須であった DPC++ 拡張機能を置き換えます。
SYCL* 2020 暫定仕様 (英語) (SYCL* 1.2.1 仕様 (英語) の上位) の必須機能は以下のとおりです。
• アクセサーの簡素化 - アクセサーのインターフェイスを簡素化し、一般的なコードの冗長性および通常のテンプレート引数を指定する必要性を排除します。SYCL* 2020 暫定仕様 (英語) の 4.7.6 節。
• bit_cast - sycl::bit_cast として C++20 (p0476r2) std::bit_castas をインクルードします。
SYCL* 2020 暫定仕様 (英語) の 3.8.2 節。
• 推論ガイド - C++ のクラス・テンプレート引数推論 (CTAD) を有効にして、一般的なコードパターンを簡素化しコードのレングスと冗長性を排除します。SYCL* 2020 暫定仕様 (英語) を通して配布されます。
• デバイス固有のクエリー - 特定のデバイスに関連付けられたカーネル・プロパティーのクエリー。SYCL*
2020 暫定仕様 (英語) の 4.12 節。
• 拡張アトミック – SYCL* メモリーモデルの微調整を含む C++20 std::atomic_ref との一致。
浮動小数型と省略演算子のサポート。SYCL* 2020 暫定仕様 (英語) の 4.17.3 節。追加のアトミック関連のクエリーは表 4.19 に定義されています。フェンスとバリアに関連するいくつかの変更は 4.17.1 節に反映されています (SYCL* 2020 暫定仕様 (英語) にも含まれます)。
• カーネル関数型の属性 - ラムダに適用可能な関数型の属性としてのカーネル属性の定義。いくつかのコア属性の定義。SYCL* 2020 暫定仕様 (英語) の 5.7 節。
• インオーダー・キュー - 一般的なコーディング・パターンを単純化するため、キューに単純なインオーダー・セ
マンティクスを定義します。SYCL* 2020 暫定仕様 (英語) の 4.6.5 節。
• 数学配列 - 連続した固定サイズのポータブルコンテナー。SYCL* 2020 暫定仕様 (英語) の 4.16.3 節。
• オプションのラムダ名 - カーネルを定義するラムダに手動で名前を付ける必要がなくなります。
コーディングを簡略化し、ライブラリーとの構成を可能にします。ラムダは、デバック時や sycl::program
オブジェクトとのインターフェイス時など、必要に応じて名前を付けることができます。SYCL* 2020 暫定仕様 (英語) の 4.14.2 節。
1

拡張テスト (英語) 内のテスト・ディレクトリー。
明示的な USM サポートの最小化。
3
利用できません。
4
今後必要となる可能性があります5
DPC++ の要件は、一次元のリダクション、単一リダクション変数のサポートです。
6
DPC++ の要件は、等価なグループ・アルゴリズムを持つ sub-group のアルゴリズムです。
7
DPC++ の要件には、汎用アドレス空間でのアトミックサポートは含まれません。
8
DPC++ の要件は、一般的なプロパティー・メカニズムに対するものであり、特定のプロパティーに対するものではありません。
2

3.2 API と言語の詳細

10

oneAPI 仕様 リリース 1.0 リビジョン 3• キューのショートカット - 追加のコマンドグループのスコープ内で、依存関係やアクセサーを作成する必要がないコードパターンを簡素化するため、カーネル呼び出し関数をキュークラスで直接定義します。いくつかの一般的なパターンで冗長性を軽減します。SYCL* 2020 暫定仕様 (英語) の 4.6.5 節。
• 必要なワークグループ・サイズ - カーネルに適用できる属性 (カーネルのラムダ定義を含む) を定義します。
これは、カーネルが特定のワークグループ・サイズでのみ使用されることを通知します。これは、追加のユー
ザー情報に基づいて最適化を可能にする最適化属性です。SYCL* 2020 暫定仕様 (英語) の 5.7 節。
• 標準レイアウトの緩和 - ホストとデバイスで共有されるデータが C++ 標準レイアウト型でなければならな
い要件をなくしました。レイアウトの互換性を確認するにはデバイス・コンパイラーが必要です。SYCL* 2020
暫定仕様 (英語) の 4.14.4 節。
• 統合共有メモリー (USM) - ポインターベースのメモリーアクセスと管理インターフェイスを定義します。可視的でホストとデバイス間で一貫したポインター値を持つ割り当てを行う機能を提供します。
異なるレベルのデバイスおよび実装サポートに対応し、各種 USM 機能レベルが定義されています。SYCL*
2020 暫定仕様 (英語) の 4.8 節。
拡張機能の概要を以下に示します。
• アクセサーのプロパティー - コンパイラーに可視的なコンパイル時アクセサーのプロパティー。
• CXX 標準ライブラリー - デバイスコードでの C および C++ 標準ライブラリーのサブセットを有効にします。
• データ・フロー・ パイプ - FPGA などの空間アーキテクチャー向けのアルゴリズムを記述する際に、一般的に使用されるメカニズムである「先入れ先出し (FIFO)」通信を DPC++ で有効にします。
• キューに投入されたバリア - 細粒度の依存関係を手動で管理せずに、キュー内で粗粒度で同期を行うことで、一般的なプログラミング・パターンの依存関係の管理と追跡を簡略化します。
• グループ・アルゴリズム - ブロードキャスト、レデュース、スキャンなど、ワーク項目のグループ全体で動作する集合操作を定義します。明示的にコードを記述する必要がない一般的なアルゴリズムを提供すること
で生産性を高め、デバイスとランタイムの組み合わせに対し最適化された実装を可能にします。
• グループマスク - グループからのワーク項目を表現する型と、投票と集計のように型を作成および操作する
集合操作を定義します。
• parallel for ショートカット - スカラー範囲でカーネルを呼び出すなど、一般的なパターンを簡素化します。
• メモリー・プロパティーの固定 - 一部の実装では、ホストとデバイス間のデータ移動を高速化するため、可能であればバッファーが特定のメモリーリソースを使用すべきことを示す最適化があります。
• リダクション - parallel_for の Nd-range 形式へのリダクション抽象化を提供します。明示的にコードを記述する必要がない一般的なリダクション・パターンを提供することで生産性を高めデバイス、ランタイ
ム、およびリダクション・プロパティーの組み合わせに対し最適化された実装を可能にします。

3.2 API と言語の詳細

11

oneAPI 仕様 リリース 1.0 リビジョン 3• すべての引数を制限 - カーネルに適用できる属性 (カーネルのラムダ定義など) を定義します。これにより、カーネルに引き渡される、もしくはカーネルによって取得されるポインター引数間にメモリーのエイリアスがないことを明示します。これは最適化属性であり、プログラマーがカーネル引数について、コンパイラーが推測または安全であると想定する以上のことを知っている場合に大きな影響をもたらす可能性があります。
• 静的ローカルメモリーのクエリー - コンパイラーによって使用されるローカルメモリー量と動的に利用できないメモリー量を紹介します。
• サブグループ - ワークグループ内のワーク項目グループを定義します。サブグループ内のワーク項目の同期は、ほかのサブグループ内のワーク項目から独立して行うことができ、サブグループはグループ内のワー
ク項目間の通信操作を発生させます。サブグループは通常、SIMD ハードウェアがある場所にマップされます。
• サブグループ・アルゴリズム - サブグループでのみ利用可能なサブグループ内のワーク項目全体の集合操作を定義します。また、サブグループの集合として、一般的な「グループ・アルゴリズム」の拡張アルゴリズムを有効にします。

3.3

オープンソース実装

オープンソース実装 (英語) は、LLVM ライセンスの下で利用できます。不完全な機能と既知の問題に関する詳細は、リリースノート (英語) (および導入ガイド (英語)） を参照してください。

3.4

テスト

DPC++ 実装は以下のテストにパスする必要があります。
1.

3.5

拡張機能表から実装された拡張機能用の拡張テスト (英語)。拡張機能表に示されるそれぞれの拡張機能に、拡張機能テスト (英語) ツリー内の対応するテストを含むディレクトリーがリストされています。

謝辞テクニカル・アドバイザリー・ボード (英語) による DPC++ と oneDPL への重要なフィードバック、および SYCL* 仕様の定義に協力いただいた Khronos SYCL* ワーキンググループに感謝いたします。

3.3 オープンソース実装

12

第4章
oneDPL
oneAPI DPC++ ライブラリー (oneDPL) は C++ 標準 (英語) で定義される機能を提供し、データ並列処理とデバイスオ
フロードをサポートする拡張機能と、データ並列アルゴリズムの実装を容易にする拡張機能を備えています。
このライブラリーは次のコンポーネントで構成されています。
• バッファーとデータ並列カーネルで使用できる C++ 標準 (英語) ライブラリーのサブセット。
• oneAPI デバイスで実行する実行ポリシーと関連 API で補完された Parallel STL アルゴリズム (「Parallel
STL 拡張」を参照)。
• 拡張機能: 有用であることは判明しているが、C++ または SYCL* 仕様にまだ含まれていないライブラリー・
クラスと関数の追加セット (個別の「oneDPL API 仕様」を参照)。

4.1

名前空間

oneDPL は、カーネル向けの標準 C++ ライブラリーのサブセットに名前空間 oneapi::std を使用し、Parallel STL
アルゴリズム、oneDPL 実行ポリシー、および拡張機能などのほかに、名前空間 oneapi::dpl を使用します。

4.2

サポートされる C++ 標準ライブラリー API とアルゴリズム

oneDPL は、DPC++ カーネルで使用する C++ 標準ライブラリー API のサブセットを定義します。これらの API は、一般的な CPU ベースのプラットフォームのコードと同様にカーネルでも使用できます。
(C++ 標準 (英語) で定義される) 実行ポリシーを受け入れるすべての C++ アルゴリズムに対し、 oneAPI は
oneapi::dpl::execution::device_policy を介して oneAPI デバイスで実行を可能にします。これらのアルゴ
リズムは、SYCL* バッファー (oneapi::dpl::begin/end を介した) および統合共有メモリー (USM) でデータを処理できる必要があります (「Parallel STL 拡張」を参照)。

4.3

Parallel STL 拡張

oneDPL は次の API によって Parallel STL を拡張します。

4.3.1 DPC++ 実行ポリシー
DPC++ 実行ポリシーは、アルゴリズムを実行する場所とその方法を指定します。

13

oneAPI 仕様 リリース 1.0 リビジョン 3// <oneapi/dpl/execution> で定義
namespace oneapi {namespace dpl {namespace execution {template <typename KernelName = /* ここでは未指定 */>class device_policy;
device_policy<> dpcpp_default;
template <typename KernelName = /* ここでは未指定 */>device_policy<KernelName>
make_device_policy( sycl::queue );template <typename KernelName = /* ここでは未指定 */>device_policy<KernelName>
make_device_policy( sycl::device );template <typename NewKernelName, typename OldKernelName>device_policy<NewKernelName>
make_device_policy( const device_policy<OldKernelName>& = dpcpp_default );}}}dpcpp_default は、デフォルトの DPC++ デバイスでアルゴリズムを実行するために事前定義された実行ポリシー・
オブジェクトです。
device_policy クラス
template <typename KernelName = /* ここでは未指定 */>class device_policy{
public:using kernel_name = KernelName;device_policy();
template <typename OtherName>device_policy( const device_policy<OtherName>& );explicit device_policy( sycl::queue );explicit device_policy( sycl::device );sycl::queue queue() const; operator
sycl::queue() const;};

device_policy 型 の オ ブ ジ ェ ク ト は 、 DPC++ 準 拠 の デ バ イ ス で ア ル ゴ リ ズ ム を 実 行 す る た め に 使 用 さ れ る
sycl::queue に関連付けられます。
KernelName テンプレート・パラメーターは、クラス・テンプレート内で kernel_name として別名化され、ポリシーが引き継がれるアルゴリズムによって実行される DPC++ カーネル名を明示します。
device_policy()

4.3 Parallel STL 拡張

14

oneAPI 仕様 リリース 1.0 リビジョン 3
デフォルトのデバイスセレクターで作成されたキューに関連するポリシー・オブジェクトを作成します。
template <typename OtherName>device_policy( const device_policy<OtherName>& policy )指定されたポリシーのカーネル名を新しいポリシーに定義された kernel_name に変更して、ポリシーと同じキューに関連付けられたポリシー・オブジェクトを作成します。
explicit device_policy( sycl::queue queue )指定されたキューに関連するポリシー・オブジェクトを作成します。
explicit device_policy( sycl::device device )特定のデバイスセレクター向けに作成されたキューに関連するポリシー・オブジェクトを作成します。
sycl::queue queue() const

ポリシーが関連付けられているキューを返します。
operator sycl::queue() const

ポリシーを暗黙的に sycl::queueobject へ変換することを許可します。
make_device_policy 関数
make_device_policy 関数テンプレートは、device_policy の作成を簡素化します。
template <typename KernelName = /* ここでは未指定 */>device_policy<KernelName>
make_device_policy( sycl::queue queue )キューに関連付けられたポリシー・オブジェクトを作成します。カーネル名はテンプレート引数として提供される可能性がありますが、それ以外では指定されません。
template <typename KernelName = /* ここでは未指定 */>device_policy<KernelName>
make_device_policy( sycl::device device )デバイス上でアルゴリズムを実行するポリシー・オブジェクトを作成します。カーネル名はテンプレート引数として提供される可能性がありますが、それ以外では指定されません。
template <typename NewKernelName, typename OldKernelName>device_policy<NewKernelName>
make_device_policy( const device_policy<OldKernelName>& policy = dpcpp_default )4.3 Parallel STL 拡張

15

oneAPI 仕様 リリース 1.0 リビジョン 3

テンプレート引数として提供された新しいカーネル名を使用して、ポリシーから構築されたポリシー・オブジェクトを返します。ポリシー・オブジェクトが指定されていない場合、新しいポリシーは dpcpp_default から作成されます。

4.3.2 バッファーラッパー// <oneapi/dpl/iterator> で定義
namespace oneapi {namespace dpl {template < typename T, typename AllocatorT, sycl::access::mode Mode >/* ここでは未指定 */ begin( sycl::buffer<T, /*dim=*/1, AllocatorT> buf,
sycl::mode_tag_t<Mode> tag = sycl::read_write );template < typename T, typename AllocatorT, sycl::access::mode Mode >/* ここでは未指定 */ begin( sycl::buffer<T, /*dim=*/1, AllocatorT> buf,
sycl::mode_tag_t<Mode> tag, sycl::property::noinit );template < typename T, typename AllocatorT >/* ここでは未指定 */ begin( sycl::buffer<T, /*dim=*/1, AllocatorT> buf,
sycl::property::noinit );template < typename T, typename AllocatorT, sycl::access::mode Mode >/* ここでは未指定 */ end( sycl::buffer<T, /*dim=*/1, AllocatorT> buf,
sycl::mode_tag_t<Mode> tag = sycl::read_write );template < typename T, typename AllocatorT, sycl::access::mode Mode >/* ここでは未指定 */ end( sycl::buffer<T, /*dim=*/1, AllocatorT> buf,
sycl::mode_tag_t<Mode> tag, sycl::property::noinit );template < typename T, typename AllocatorT >/* ここでは未指定 */ end( sycl::buffer<T, /*dim=*/1, AllocatorT> buf,
sycl::property::noinit );}}oneapi::dpl::begin および oneapi::dpl::end は、DPC++ バッファーを oneDPL アルゴリズムに渡すヘルパー関数です。これらの関数はバッファーを受け取り、次の要件を満たす未指定型のオブジェクトを返します。
• CopyConstructible、CopyAssignable、および比較可能な == と != 演算子。
• 次の式が有効です: a+n、a-n、a-b、ここで、a および b は型オブジェクトで、n は整数値です。
• begin または end 関数に渡されたバッファーを返す get_buffer() メソッドを提供します。
アルゴリズムを呼び出す場合、begin に渡すバッファーは end に渡すバッファーと同じでなければなりません。そうでない場合の動作は不定です。

4.3 Parallel STL 拡張

16

oneAPI 仕様 リリース 1.0 リビジョン 3
sycl::mode_tag_t と sycl::property::noinit パラメーターでは、アルゴリズムがバッファーにアクセスする際に使用するアクセスモードを指定できます。このモードはヒントとして機能し、アルゴリズムのセマンティクスに応じてオーバーライドできます。アルゴリズムを呼び出す際は、begin と end に同じアクセスモード引数を指定しなければなりません。そうでない場合の動作は不定です。
using namespace oneapi;
auto buf_begin = dpl::begin(buf, sycl::write_only);
auto buf_end_1 = dpl::end(buf, sycl::write_only);
auto buf_end_2 = dpl::end(buf, sycl::write_only, sycl::noinit);
dpl::fill(dpl::dpcpp_default, buf_begin, buf_end_1, 42); // 許可
dpl::fill(dpl::dpcpp_default, buf_begin, buf_end_2, 42); // 不許可

4.4

oneDPL API 仕様

oneDPL 拡張機能には、イテレーター、関数オブジェクト、および並列アルゴリズムが含まれます。

4.4.1 関数オブジェクト
oneDPL 関数オブジェクトは、名前空間 oneapi::dpl の <oneapi/dpl/functional> ヘッダーで定義されています。
namespace oneapi {namespace dpl {struct identity{
template <typename T>
constexpr T&&
operator()(T&& t) const noexcept;};}}

oneapi::dpl::identity クラスは ID 操作を実装します。関数オペレーターは型のインスタンスを受け取り、引数を変更することなく返します。

4.4.2 イテレーター
oneDPL イテレーターは、名前空間 oneapi::dpl の <oneapi/dpl/iterator> ヘッダーで定義されています。

4.4 oneDPL API 仕様

17

oneAPI 仕様 リリース 1.0 リビジョン 3
template <typename Integral>class counting_iterator{
public:using difference_type = /* ntegral と同じサイズの符号付き整数型 */;using value_type = Integral;using reference = Integral;counting_iterator();
explicit counting_iterator(Integral init);
reference operator*() const;
reference operator[](difference_type i) const;
difference_type operator-(const counting_iterator& it) const;
counting_iterator operator+(difference_type forward) const;
counting_iterator operator-(difference_type backward) const;
counting_iterator& operator+=(difference_type forward);
counting_iterator& operator-=(difference_type backward);
counting_iterator& operator++();
counting_iterator& operator--();
counting_iterator& operator++(int);
counting_iterator& operator--(int);
bool operator==(const counting_iterator& it) const;bool operator!=(const counting_iterator& it) const;bool operator<(const counting_iterator& it) const;bool operator>(const counting_iterator& it) const;bool operator<=(const counting_iterator& it) const;bool operator>=(const counting_iterator& it) const;};

counting_iterator は、整数カウンターに類似したランダム・アクセス・イテレーターのような型です。逆参照すると、
counting_iterator はカウンター値に等しい整数型の rvalue 値を提供します。逆参照操作によりカウンターを変更することはできません。counting_iterator の算術および比較オペレーターは、オペレーターに渡されたイテ
レーター・インスタンスのカウンターを表す整数型の値に適用されたように動作します。
class discard_iterator{
public:using difference_type = std::ptrdiff_t;
using value_type = /* ここでは未指定 */;using reference = /* ここでは未指定 */;discard_iterator();
explicit discard_iterator(difference_type init);
reference operator*() const;
reference operator[](difference_type) const;
difference_type operator-(const discard_iterator& it) const;
discard_iterator operator+(difference_type forward) const;
discard_iterator operator-(difference_type backward) const;(次のページへ続く)
4.4 oneDPL API 仕様

18

oneAPI 仕様 リリース 1.0 リビジョン 3(前のページの続き)
discard_iterator& operator+=(difference_type forward);
discard_iterator& operator-=(difference_type backward);
discard_iterator& operator++();
discard_iterator& operator--();
discard_iterator operator++(int);
discard_iterator operator--(int);
bool operator==(const discard_iterator& it) const;bool operator!=(const discard_iterator& it) const;bool operator<(const discard_iterator& it) const;bool operator>(const discard_iterator& it) const;};

discard_iterator は、ランダム・アクセス・イテレーターのような型であり、逆参照されると任意の値を割り当て可能な lvalue を提供します。割り当ては discard_iterator インスタンスには影響せず、書き込みは廃棄されます。
discard_iterator の算術および比較オペレーターは、イテレーター・インスタンスによって維持される整数カウン
ター値に適用されるように振る舞い、相互に相対的な位置を決定します。
template <typename SourceIterator, typename IndexMap>
class permutation_iterator{
public:using difference_type = typename std::iterator_traits<SourceIterator>::difference_type;using value_type = typename std::iterator_traits<SourceIterator>::value_type;using pointer = typename std::iterator_traits<SourceIterator>::pointer;using reference = typename std::iterator_traits<SourceIterator>::reference;
permutation_iterator(const SourceIterator& input1, const IndexMap& input2, std::size_t
index = 0);reference operator*() const;
reference operator[](difference_type i) const;
difference_type operator-(const permutation_iterator& it) const;
permutation_iterator operator+(difference_type forward) const;
permutation_iterator operator-(difference_type backward) const;
permutation_iterator& operator+=(difference_type forward);
permutation_iterator& operator-=(difference_type forward);
permutation_iterator& operator++();
permutation_iterator& operator--();
permutation_iterator operator++(int);
permutation_iterator operator--(int);
bool operator==(const permutation_iterator& it) const;bool operator!=(const permutation_iterator& it) const;bool operator<(const permutation_iterator& it) const;bool operator>(const permutation_iterator& it) const;bool operator<=(const permutation_iterator& it) const;bool operator>=(const permutation_iterator& it) const;};

4.4 oneDPL API 仕様

19

oneAPI 仕様 リリース 1.0 リビジョン 3

permutation_iterator は、ランダム・アクセス・イテレーターに類似した型であり、逆参照値セットはソース・イテ
レーターによって定義され、逆参照値セットに対する反復順序は、別のイテレーターまたは permutation_iterator
インデックスをソース・イテレーターのインデックスにマップするファンクターによって定義されます。
permutation_iterator の算術および比較オペレーターは、イテレーター・インスタンスによって維持される整数カ
ウンター値に適用されるように振る舞い、インデックス・マップ内の位置を決定します。
permutation_iterator::operator* は、呼び出されたインスタンスのカウンター値を使用して、インデックス・
マップにインデックスを付加します。マップ内の対応する値は、ソース・イテレーターによって定義される値セットのインデックスとして使用されます。lvalue はオペレーターの結果として返されます。
permutation_iterator::operator[] は、パラメーター i を使用してインデックス・マップにインデックスを付加します。マップ内の対応する値は、ソース・イテレーターによって定義される値セットのインデックスとして使用されます。lvalue はオペレーターの結果として返されます。
template <typename SourceIterator, typename IndexMap>
permutation_iterator<SourceIterator, IndexMap>
make_permutation_iterator(SourceIterator source, IndexMap map);

make_permutation_iterator は 、 ソ ー ス ・ イ テ レ ー タ ー と イ ン デ ッ ク ス ・ マ ッ プ を 使 用 し て 、permutation_iterator のインスタンスを構築して返します。
template <typename Iterator, typename UnaryFunc> class transform_iterator{
public:using difference_type = typename std::iterator_traits<Iterator>::difference_type;using reference = typename std::invoke_result<UnaryFunc,
typename std::iterator_traits<Iterator>::reference>::type;using value_type = typename std::remove_reference<reference>::type;using pointer = typename std::iterator_traits<Iterator>::pointer;transform_iterator(Iterator it, UnaryFunc unary_func);transform_iterator(const transform_iterator& input);transform_iterator& operator=(const transform_iterator& input);reference operator*() const;
reference operator[](difference_type i) const;
difference_type operator-(const transform_iterator& it) consttransform_iterator operator+(difference_type forward) const;
transform_iterator operator-(difference_type backward) const;
transform_iterator& operator+=(difference_type forward);transform_iterator& operator-=(difference_type backward);transform_iterator& operator++();
transform_iterator& operator--();
transform_iterator operator++(int);
transform_iterator operator--(int);(次のページへ続く)

4.4 oneDPL API 仕様

20

oneAPI 仕様 リリース 1.0 リビジョン 3(前のページの続き)bool operator==(const transform_iterator& it) const;bool operator!=(const transform_iterator& it) const;bool operator<(const transform_iterator& it) const;bool operator>(const transform_iterator& it) const;bool operator<=(const transform_iterator& it) const;bool operator>=(const transform_iterator& it) const;};

transform_iterator は、ランダム・アクセス・イテレーターに類似した型であり、逆参照セットは提供される単項関数とソース・イテレーターによって定義されます。逆参照されると、transform_iterator はソース・イテレーターの対応する要素に適用された単項関数の結果をもたらします。単項関数の結果に要素への参照が含まれない限り、逆参照操
作によってソース・イテレーターの要素を変更することはできません。transform_iterator の算術および比較オペ
レーターは、ソース・イテレーター自身に適用されるかのように動作します。
template <typename UnaryFunc, typename Iterator>transform_iterator<UnaryFunc, Iterator>
make_transform_iterator(Iterator, UnaryFunc);

make_transform_iterator は、ソース・イテレーターとインデックス・マップを使用して、transform_iteratorのインスタンスを構築して返します。
template <typename... Iterators>
class zip_iterator{
public:using difference_type = typename std::make_signed<std::size_t>::type;using value_type = std::tuple<typename std::iterator_traits<Iterators>::value_type...>;
using reference = /* 参照型のタプルを指定 */;using pointer = std::tuple<typename std::iterator_traits<Iterators>::pointer...>;
zip_iterator();
explicit zip_iterator(Iterators... args);
zip_iterator(const zip_iterator& input);
zip_iterator& operator=(const zip_iterator& input);reference operator*() const;
reference operator[](difference_type i) const;
difference_type operator-(const zip_iterator& it) const;
zip_iterator operator-(difference_type backward) const;
zip_iterator operator+(difference_type forward) const;
zip_iterator& operator+=(difference_type forward);
zip_iterator& operator-=(difference_type backward);
zip_iterator& operator++();
zip_iterator& operator--();
zip_iterator operator++(int);
zip_iterator operator--(int);(次のページへ続く)

4.4 oneDPL API 仕様

21

oneAPI 仕様 リリース 1.0 リビジョン 3(前のページの続き)bool operator==(const zip_iterator& it) const;bool operator!=(const zip_iterator& it) const;bool operator<(const zip_iterator& it) const;bool operator>(const zip_iterator& it) const;bool operator<=(const zip_iterator& it) const;bool operator>=(const zip_iterator& it) const;};

zip_iterator は、 1 つ 以上のイテレーターで定 義されたイテレーターに類似し た型です 。 逆参照することで
zip_iterator から返される値は、zip_iterator が定義されているソース・イテレーターを逆参照することで返される値のタプルです。zip_iterator の算術オペレーターは、操作が各イテレーターに適用されたかのように、
zip_iterator インスタンスのソース・イテレーターを更新します。
template <typename... Iterators>
zip_iterator<Iterators...>make_zip_iterator(Iterators...);

make_zip_iterator は、ソース・イテレーターのセットを使用して zip_iterator のインスタンスを構築して返します。

4.4.3 並列アルゴリズム
並列アルゴリズムは、名前空間 oneapi::dpl の <oneapi/dpl/algorithm> ヘッダーで定義されています。
template<typename Policy, typename InputKeyIt, typename InputValueIt,
typename OutputValueIt,
typename T = typename std::iterator_traits<InputValueIt>::value_type,typename BinaryPred =std::equal_to<typename std::iterator_traits<InputKeyIt>::value_type>,
typename BinaryOp =std::plus<typename std::iterator_traits<InputValueIt>::value_type>>
OutputValueIt
exclusive_scan_by_segment(Policy&& policy, InputKeyIt keys_first,
InputKeyIt keys_last, InputValueIt values_first, OutputValueIt values_result,T initial_value = 0,
BinaryPred binary_pred =std::equal_to<typename std::iterator_traits<InputKeyIt>::value_type>(),BinaryOp binary_op =std::plus<typename std::iterator_traits<InputValueIt>::value_type>());

oneapi::dpl::exclusive_scan_by_segment は、一連の値に binary_op 操作を適用することで、部分的なプ
リフィクス・スキャンを実行します。それぞれの部分スキャンは binary_pred プレディケートに従って、等しい値に関連付けられたキーによって決定される連続サブシーケンスに適用され、各スキャンの最初の要素は提供された初期値となります。戻り値は、結果シーケンスの終わりをターゲットにするイテレーターです。
省略された場合の初期値は、0 で初期化された InputValueIt イテレーター型の value_type インスタンスです。
キーの比較で BinaryPredcate が省略されている場合、std::equal_to のインスタンスと InputKeyIt イテレー
ター型の value_type が使用されます。最後に、値のサブシーケンス要素を組み合わせるため二項演算オペレーターが指定されていない場合は、InputValueIt イテレーター型の value_type を持つ std::plus のインスタンスが使用されます。

4.4 oneDPL API 仕様

22

oneAPI 仕様 リリース 1.0 リビジョン 3

template<typename Policy, typename InputKeyIt, typename InputValueIt,
typename OutputValueIt,
typename BinaryPredcate =std::equal_to<typename std::iterator_traits<InputKeyIt>::value_type,typename BinaryOp =std::plus<typename std::iterator_traits<InputValueIt>::value_type>>
OutputValueIt
inclusive_scan_by_segment(Policy&& policy, InputKeyIt keys_first,
InputKeyIt keys_last, InputValueIt values_first, OutputValueIt values_result
BinaryPred binary_pred =std::equal_to<typename std::iterator_traits<InputKeyIt>::value_type>(),BinaryOp binary_op =std::plus<typename std::iterator_traits<InputValueIt>::value_type>());

oneapi::dpl::inclusive_scan_by_segment は、一連の値に binary_op 操作を適用することで、部分的なプ
リフィクス・スキャンを実行します。それぞれの部分スキャンは binary_pred プレディケートに従って、等しい値に関連付けられたキーによって決定される連続したサブシーケンスに適用されます。戻り値は、結果シーケンスの終わりをターゲットにするイテレーターです。
キーの比較で BinaryPredcate が省略されている場合、std::equal_to のインスタンスと InputKeyIt イテ
レーター型の value_type が使用されます。値のサブシーケンス要素を組み合わせるため二項演算オペレーターが指定されていない場合は、InputValueIt イテレーター型の value_type を持つ std::plus のインスタンスが使用されます。
template<typename Policy, typename InputKeyIt, typename InputValueIt,
typename OutputKeyIt, typename OutputValueIt,
typename BinaryPredcate =std::equal_to<typename std::iterator_traits<InputKeyIt>::value_type,typename BinaryOp =std::plus<typename std::iterator_traits<InputValueIt>::value_type>>
std::pair<OutputKeyIt,OutputValueIt>
reduce_by_segment(Policy&& policy, InputKeyIt keys_first, InputKeyIt keys_last,
InputValueIt values_first, OutputKeyIt keys_result,
OutputValueIt values_result, BinaryPred binary_pred =std::equal_to<typename std::iterator_traits<InputKeyIt>::value_type>(),BinaryOp binary_op =std::plus<typename std::iterator_traits<InputValueIt>::value_type>());

oneapi::dpl::reduce_by_segment は値のシーケンスに対し部分的なリダクションを行います。それぞれのリダ
クションは、関連キーが binary_pred プレディケートと等しい値の連続するサブシーケンスに対し、binary_op 操
作を実行します。サブシーケンスごとに、等しいキーの最初が keys_result に格納され、計算されたリダクション値がvalues_result に格納されます。戻り値は、結果シーケンスの終わりを保持するイテレーターのペアです。
キーの比較で BinaryPredcate が省略されている場合、std::equal_to のインスタンスと InputKeyIt イテ
レーター型の value_type が使用されます。二項演算オペレーターが指定されていない場合、std::plus のインスタ
ンスと InputValueItiterator 型の value_type を使用して識別されたそれぞれのサブシーケンス値を結合します。

4.4 oneDPL API 仕様

23

oneAPI 仕様 リリース 1.0 リビジョン 3
template<typename Policy, typename InputIt1, typename InputIt2, typename OutputIt,
typename Comparator =std::less<typename std::iterator_traits<InputIt>::value_type>>
OutputIt
binary_search(Policy&& policy, InputIt1 start, InputIt1 end, InputIt2 value_first,
InputIt2 value_last, OutputIterator result,Comparator comp =std::less<typename std::iterator_traits<InputIt1>::value_type>());

oneapi::dpl::binary_search は、[value_first, value_last) のそれぞれの値の [start, end) のデ ー タ に 対 し て バ イ ナ リ ー 検 索 を 実 行 し ま す 。 検 索 さ れ た デ ー タ が 存 在 す る 場 合 、 [result, result +distance(value_first, value_last)) の対応する要素は true に設定され、それ以外は false に設定されます。
コンパレーターが指定されない場合、operator< を使用して検索値が検索対象範囲内の各要素よりも小さいか判断します。
template<typename Policy, typename InputIt1, typename InputIt2, typename OutputIt,
typename Comparator =std::less<typename std::iterator_traits<InputIt>::value_type>>
OutputIt
lower_bound(Policy&& policy, InputIt1 start, InputIt1 end,
InputIt2 value_first, InputIt2 value_last, OutputIterator result,Comparator comp =std::less<typename std::iterator_traits<InputIt1>::value_type>());

oneapi::dpl::lower_bound は、[value_first, value_last) のそれぞれの値の [start, end) のデー
タに対してバイナリー検索を実行し、コンパレーターで定義された順序に従って検索値を [start, end) に挿入可能な最小インデックスを見つけます。そして最小インデックスが、[result, result + distance(value_first,
value_last)) の対応する要素に割り当てられます。
コンパレーターが指定されない場合、operator< を使用して検索値が検索対象範囲内の各要素よりも小さいか判断します。
template<typename Policy, typename InputIt1, typename InputIt2, typename OutputIt,
typename Comparator =std::less<typename std::iterator_traits<InputIt>::value_type>>
OutputIt
upper_bound(Policy&& policy, InputIt1 start, InputIt1 end,
InputIt2 value_first, InputIt2 value_last, OutputIterator result,Comparator comp =std::less<typename std::iterator_traits<InputIt1>::value_type>());

oneapi::dpl::upper_bound は、[value_first, value_last) のそれぞれの値の [start, end) のデー
タに対してバイナリー検索を実行し、コンパレーターで定義された順序に従って検索値を [start, end) に挿入可能な最大インデックスを見つけます。そして最大インデックスが、[result, result + distance(value_first,
value_last)) の対応する要素に割り当てられます。
コンパレーターが指定されない場合、operator< を使用して検索値が検索対象範囲内の各要素よりも小さいか判断します。

4.4 oneDPL API 仕様

24

第5章
oneDNNoneAPI ディープ・ニューラル・ネットワーク・ライブラリー (oneDNN) は、ディープラーニング・アプリケーションとフレー
ムワーク向けのビルディング・ブロックを含むパフォーマンス・ライブラリーです。oneDNN は以下をサポートします。
• CNN プリミティブ (畳み込み、内積、プーリングなど)• RNN プリミティブ (LSTM、Vanilla、RNN、GRU)• 正規化 (LRN、バッチ、レイヤー)• 要素ごとの操作 (ReLU、Tanh、ELU、Abs など)• Softmax、Sum、Concat、Shuffle• 最適化されたデータレイアウト間との並べ替え• 8 ビット整数、16 ビット、32 ビット、そして bfloat16 浮動小数点データ型// Tensor の次元
int N, C, H, W;// ユーザーの DPC++ オブジェクト
sycl::device dev {sycl::gpu_selector {}}; // デバイス
sycl::context ctx {dev}; // コンテキスト
sycl::queue queue {dev}; // キュー
std::vector<sycl::event> dependencies; // 入力イベント依存関係// ソースfloat *buf_src = static_cast<float *>(sycl::malloc_device((N * C * H * W) * sizeof(float), dev, ctx));// 結果
float *buf_dst = static_cast<float *>(sycl::malloc_device((N * C * H * W) * sizeof(float), dev, ctx));// ユーザーの DPC++ GPU デバイスとコンテキストをカプセル化するエンジンを作成
dnnl::engine engine = dnnl::sycl_interop::make_engine(dev, ctx);// ユーザーの DPC++ GPU キューをカプセル化するストリームを作成
dnnl::stream stream = dnnl::sycl_interop::make_stream(engine, queue);(次のページへ続く)25

oneAPI 仕様 リリース 1.0 リビジョン 3(前のページの続き)// 基盤となるストレージとして buf_src と buf_dst を使用するメモリー・オブジェクトを作成
dnnl::memory mem_src({{N, C, H, W}, dnnl::memory::data_type::f32,
dnnl::memory::format_tag::nhwc}, engine, buf_src);
dnnl::memory mem_dst({{N, C, H, W}, dnnl::memory::data_type::f32,
dnnl::memory::format_tag::nhwc}, engine, buf_dst);// ReLU 要素ごとのプリミティブを作成
dnnl::eltwise_forward relu {{{dnnl::prop_kind::forward_inference, dnnl::algorithm::eltwise_relu,
mem_src.get_desc(), 0.f, 0.f}, engine}};// 入力依存関係を渡して、出力依存関係を取得するストリームで、ReLU プリミティブを実行
sycl::event event = dnnl::sycl_interop::execute(relu, stream,{{DNNL_ARG_SRC, mem_src}, {DNNL_ARG_DST, mem_dst}}, dependencies);

5.1

概要

この仕様は既存のオープンソース実装 (英語) をベースにしていますが、目標は移植可能な API のセットを定義することです。そのため、タイルやブロック化されたメモリー形式 (レイアウト) など実装固有の詳細を意図的に省略し、代わりにプレーンな多次元メモリー形式を記述することで、実装固有の不透過な最適化されたメモリー形式を定義します。
oneDNN の主な概念は、プリミティブ、エンジン、ストリーム、およびメモリー・オブジェクトです。

プリミティブ (dnnl::primitive) は、前方畳み込み、後方 LSTM 計算、データ交換操作など特定の計算をカプセル化するファンクター・オブジェクトです。単一のプリミティブは、前方畳み込みと後続の ReLU など、複雑な融合計算を表すことがあります。融合は、特にプリミティブ属性メカニズムを介して制御されます。
プリミティブと純粋関数の大きな違いは、プリミティブは入力パラメーターのサブセットとして特殊化できることです。
例えば、畳み込みプリミティブはテンソル形式のようなパラメーターを格納し、キャッシュ・ブロッキングなど他の依存関係があるパラメーターを事前計算できます。これにより、oneDNN プリミティブは要求された操作の実行に合わせて調整済みのコードを事前生成できます。oneDNN プログラミング・モデルは、同じプリミティブを再利用して計算を複数回実行することで、事前計算にかかる時間を償却することを前提にしています。

5.1 概要26

oneAPI 仕様 リリース 1.0 リビジョン 3
プリミティブには、計算中に一時ストレージとして利用できる可変メモリーバッファーが必要になることがあります。そのようなバッファーはスクラッチパッドと呼ばれ、プリミティブ・オブジェクト (オブジェクトはスレッドセーフでない) が所有することも、実行時にパラメーターにすることもできます。
プリミティブの作成はコストがかかる操作です。プリミティブは一度だけ作成し、複数回再利用すべきです。実装は、同じパラメーターを持つプリミティブをキャッシュすることで、プリミティブの作成コストを軽減することがあります。このような最適化はこの仕様ではカバーされません。
エンジン (dnnl::engine) は計算デバイス (CPU、システム内の特定の GPU カードなど) を抽象化します。ほとんどのプリミティブは、対応する特定のエンジンで計算を実行するために作成されます。唯一の例外は、2 つの異なるエンジン
間でデータを転送する可能性がある並べ替えプリミティブです。
ストリーム (dnnl::stream) は、特定のエンジンに関連付けられた実行コンテキストをカプセル化します。例えば、
DPC++ コマンドキューに対応します。
メモリー・オブジェクト (dnnl::memory) は、特定のエンジンに割り当てられたメモリーへのハンドル、テンソルの次元、
データ型、およびメモリー形式 (テンソル・インデックスが線形メモリー空間のオフセットにマップされる方法) をカプセ
ル化します。メモリー・オブジェクトは実行中プリミティブに渡されます。
抽象化レベルoneDNN には、最大限の柔軟性を提供するため、プリミティブとメモリー・オブジェクトの複数レベルを抽象化します。
ライブラリーは論理レベルで次の抽象化を提供します。
• メモリー記述子 (dnnl::memory::desc) は、テンソルの論理的な次元、データ型、およびデータをメモリーに配置する形式を定義します。特殊形式 (dnnl::memory::format_tag::any) は、実際の形式が後に定義されることを示します。
• 操作記述子 (サポートされるプリミティブごとに 1 つ) には、操作の最も基本的なプロパティーを記述します。
それらの計算で使用されるエンジンを指定する必要はありません。例えば、畳み込み記述子は、ソース、デスティネーション、重みテンソル、伝搬の種類 (データや重みに対する前方、後方)、およびその他の実装に依存しないパラメーターを記述します。
• プリミティブ記述子 (dnnl::primitive_desc_base が基本クラスであり、サポートされるそれぞれのプ
リミティブには固有のバージョンがある) は、操作記述子とプリミティブ間の抽象化レベルにあり、特定のプ
リミティブ実装を検査するために使用できます。例えば、クエリーを使用して予測されるメモリー形式を検査し、プリミティブを完全にインスタンス化することなく、メモリー形式の伝搬 (「メモリー形式伝搬」を参照) を実装します。

5.1 概要抽象化レベル

メモリー・オブジェクト

プリミティブ・オブジェクト

論理記述子

メモリー記述子

操作記述子

中間記述子

利用不可

プリミティブ記述子

実装

メモリー・オブジェクト

プリミティブ27

oneAPI 仕様 リリース 1.0 リビジョン 3

5.1.1 一般的な API の注意
oneDNN オブジェクトの動作には条件があります。
• メモリーと操作記述子はトリビアル型と同じように動作します。
• 他のすべてのオブジェクトは共有ポインターのように動作し、コピーは常にシャロ―です。
oneDNN オブジェクトは空にすることができ、その場合どのような用途にも有効ではありません。空のメモリー記述子は、
ゼロメモリー記述子と見なされ、メモリー記述子がないことを示すために使用できる点において特殊であると言えます。
空のオブジェクトはデフォルトのコンストラクターを使用して作成されますが、オブジェクト構築中のエラーによる可能性もあります (次の節を参照)。

5.1.2 エラー処理
すべての oneDNN 関数は、エラーが発生すると次の例外をスローします。
struct error: public 例外
例外クラス。
oneDNN オブジェクトを構築または返す大部分の oneDNN 関数には、ブール値 allow_empty パラメーターがあります。このパラメーターはデフォルトで false に設定されており、オブジェクトを構築できない場合、ライブラリーはエ
ラーを発生する代わりに、空のオブジェクト (メモリー記述子の場合はゼロオブジェクト) を返します。

5.1.3 名前空間
すべての oneDNN 関数とクラスは ::dnnl 名前空間にあります。コマンドキューやバッファーなどの DPC++ オブジェ
クトを受け入れるまたは返す関数は、::dnnl::sycl_interop 名前空間にあります。
さらに、oneDNN は ::oneapi::dnnl 名前空間を定義します。これは ::dnnl のエイリアスです。

5.2

規則

oneDNN 仕様は、変数の標準命名規則に依存します。ここでは、これらの規則について説明します。

5.2.1 変数 (Tensor) 名
ニューラル・ネットワーク・モデルは、次の式の操作で構成されます。
dst = f (src, weights)
dst と src は活性化テンソルであり、weights は学習可能なテンソルです。

5.2 規則28

oneAPI 仕様 リリース 1.0 リビジョン 3
従って、後方伝搬はそれぞれ src の重みに関連する勾配の計算で構成されます。
diff_src = dfsrc(diff_dst, src, weights, dst)および
diff_weights = dfweights(diff_dst, src, weights, dst)
oneDNN は、活性化と学習可能なテンソルの総称として、src、dst、および weights を使用しますが、一部の操作ではこれらのテンソルには広く知られている別名が存在する場合があります。例えば、畳み込み計算には bias と呼ばれる学習可能なテンソルがあります。使いやすくするため、oneDNN プリミティブでは初期化や他の関数でそのような名前を使用します。
oneDNN は、テンソルで一般に使用される次の表記を採用します。

5.2 規則

名前

意味

src

ソーステンソルdst

デスティネーション・テンソル

weights

重みテンソルbias

バイアステンソル (畳み込み、内積および他のプリミティブで使用)

scale_shift

スケールとシフトテンソル (バッチ正規化とレイヤー正規化プリミティブで使用)

workspace

順伝搬から逆伝搬への追加情報を移動するワークスペース・テンソル

scratchpad

中間結果を保存するために必要なテンポラリー・テンソル

diff_src

ソースに関連する勾配テンソル

diff_dst

デスティネーションに関連する勾配テンソル

diff_weights

重みに関連する勾配テンソル

diff_bias

バイアスに関連する勾配テンソル

diff_scale_shift

スケールとシフトに関連する勾配テンソル*_layer

RNN レイヤーデータまたは重みテンソル*_iter

RNN リカレントデータまたは重みテンソル

29

oneAPI 仕様 リリース 1.0 リビジョン 3

5.2.2 RNN 固有の表記
次の表記は、RNN プリミティブを説明する際に使用されます。

5.3

名前

セマンティクス·

行列乗算演算子*

要素ごとの乗算演算子

W

入力重み

U

リカレント重み

QT

転置

B

バイアス

h

隠された状態

a

中間値

x

入力

Qt

タイムスタンプ・インデックス

Ql

レイヤー・インデックス

activation

tanh、relu、logistic

c

セルの状態

c~

候補状態

i

入力ゲート

f

忘却ゲート

o

出力ゲート

u

更新ゲート

r

リセットゲート

実行モデル

プリミティブを実行するには、メモリー引数とストリームを dnnl::primitive::execute() メンバー関数に渡す必要があります。

5.3 実行モデル

30

oneAPI 仕様 リリース 1.0 リビジョン 3

プリミティブの計算は、プリミティブ (およびメモリー引数) が作成されたエンジンに対応する計算デバイスで実行され、ストリームのコンテキスト内で実行されます。

5.3.1 エンジン
エンジンは計算デバイス (CPU、システム内の特定の GPU カードなど) を抽象化します。ほとんどのプリミティブは、対応する特定のエンジンで計算を実行するために作成されます。唯一の例外は、2 つの異なるエンジン間でデータを転送する並べ替えプリミティブです。
エンジンは、DPC++ の sycl::device と sycl::context オブジェクトのペアに対応し、そこから構築できます。
または、oneDNN 自身が対応するオブジェクトを作成して所有することもできます。
struct dnnl::engine
実行エンジン。
パブリックタイプ
enum kindエンジンの種類。
値:
列挙子 any
不特定のエンジン。
列挙子 cpu
CPU エンジン。
列挙子 gpu
GPU エンジン。
パブリック関数engine()
空のエンジンを構築。空のエンジンはどの操作でも利用できません。

5.3 実行モデル

31

oneAPI 仕様 リリース 1.0 リビジョン 3
engine(kind akind, size_t index)
エンジンを構築。
パラメーター• akind: 構築するエンジンの種類。
• index: エンジンのインデックス。この種類のエンジンが get_count() で返す値よりも小さくする
必要があります。
kind get_kind() const
エンジンの種別を返します。
戻り値: エンジンの種別。
パブリック静的関数
size_t get_count(kind akind)
特定の種類のエンジンの数を返します。
戻り値: 特定の種類のエンジンの数。
パラメーター• akind: カウントするエンジンの種類。

engine dnnl::sycl_interop::make_engine(const&acontext)

cl::sycl::device&adevice,

const

cl::sycl::context

指定された SYCL* デバイスとコンテキスト・オブジェクトを使用して、エンジン・オブジェクトを作成します。
戻り値: 指定された acontext SYCL* コンテキスト内の adevice SYCL* デバイスのエンジン・オブジェクト。
パラメーター• adevice: SYCL* デバイス。
• acontext: SYCL* コンテキスト。
cl::sycl::device dnnl::sycl_interop::get_device(const engine &aengine)指定されたエンジン・オブジェクトの SYCL* デバイスを返します。
戻り値: aengine エンジン・オブジェクトの SYCL* デバイス・オブジェクト。
パラメーター• engine: エンジン・オブジェクト。
cl::sycl::context dnnl::sycl_interop::get_context(const engine &aengine)指定されたエンジン・オブジェクトの SYCL* コンテキストを返します。
戻り値: aengine エンジン・オブジェクトの SYCL* コンテキスト・オブジェクト。

5.3 実行モデル

32

oneAPI 仕様 リリース 1.0 リビジョン 3

パラメーター• engine: エンジン・オブジェクト。

5.3.2 ストリーム
ストリームは、特定のエンジンに関連付けられた実行コンテキストをカプセル化します。プリミティブが実行されると、
dnnl::primitive::execute() に渡されます。
ストリームは、DPC++ sycl::queue オブジェクトに対応しており、そこから構築できます。または、oneDNN 自身が対応するオブジェクトを作成して所有することもできます。ストリームは一時的なものと見なされ、これらの操作が DPC++
同期要件に違反しない限り作成および破棄できます。
DPC++ キューと同様に、ストリームはインオーダーでも、アウトオブオーダーでもかまいません (詳細については、
DPC++ 仕様の該当する節を参照してください)。目的とする動作は、dnnl::stream::flags 値を使用して指定します。DPC++ キューから作成されたストリームは、その動作を継承します。
struct dnnl::Stream
実行ストリーム。
パブリックタイプ
enum フラグ
ストリームフラグ。ビットごとの OR 演算子で組み合わせが可能です。
値:
列挙子 in_order
インオーダー実行。
列挙子 out_of_order
アウトオブオーダー実行。
列挙子 default_flags
デフォルトのストリーム設定。
パブリック関数stream()
空のストリームを構築。空のストリームはどの操作でも利用できません。
stream(const engine &aengine, flags aflags = flags::default_flags)指定されたエンジンのストリームを構築し、フラグによって動作を制御します。
パラメーター• aengine: ストリームを作成するエンジン。
• aflags: ストリームの動作を制御するフラグ。
stream &wait()
ストリームで実行されるすべてのプリミティブが終了するのを待機します。
5.3 実行モデル

33

oneAPI 仕様 リリース 1.0 リビジョン 3

戻り値: ストリーム自身。
stream dnnl::sycl_interop::make_stream(const engine &aengine,&aqueue)指定されたエンジンおよび SYCL キュー・オブジェクトのストリームを作成します。

cl::sycl::queue

戻り値: aqueue SYCL* キュー・オブジェクトを保持する aengine エンジン・オブジェクトのストリーム・オ
ブジェクト。
パラメーター• aengine: ストリームに使用するエンジン・オブジェクト。
• aqueue: ストリームに使用する SYCL* キュー。
cl::sycl::queue dnnl::sycl_interop::get_queue(const stream &astream)
指定されたストリーム・オブジェクトの SYCL* キューを返します。
戻り値: astream ストリーム・オブジェクトの基底となる SYCL* キュー。
パラメーター• astream: ストリーム・オブジェクト。

5.4

データモデルoneDNN のデータは、さまざまな型のデータを保持および表現し、各種形式 (レイアウト) で格納できるメモリー・オブジェクトにストアされます。

5.4.1 データ型
oneDNN は複数のデータ型をサポートします。oneDNN の基本型は 32 ビット IEEE 単精度浮動小数点データ型です。
これは、実装でサポートする必要がある唯一のデータ型です。以下で説明するデータ型はオプションです。
単精度浮動小数点データ型で動作するプリミティブは、同じデータ型の中間結果を生成し格納します。
また、単精度浮動小数点データ型の精度は十分であるため、精度が混在した計算の中間結果を保持するのに利用されます。例えば、要素全体のプリミティブと要素全体の後処理では、常に内部で単精度浮動小数点データ型が使用されます。
oneDNN は、次の列挙を使用してサポートするデータ型を参照します。
enum dnnl::memory::data_type
データ型仕様。

5.4 データモデル

34

oneAPI 仕様 リリース 1.0 リビジョン 3
値:
列挙子 undef
未定義データ型 (空のメモリー記述子に使用)。
列挙子 f16
16 ビット半精度浮動小数点 (英語)。
列挙子 bf16
非標準 16 ビット浮動小数点 (7 ビット仮数) (英語)。
列挙子 f32
32 ビット単精度浮動小数点 (英語)。
列挙子 s32
32 ビット符号付き整数。
列挙子 s88 ビット符号付き整数。
列挙子 u88 ビット符号なし整数。
oneDNN は、次のデータ型による訓練と推論をサポートします。
利用モデル

データ型

推論

dnnl::memory::data_type::f32,
dnnl::memory::data_type::bf16,
dnnl::memory::data_type::f16,
dnnl::memory::data_type::s8/dnnl::memory::data_type::u8

訓練

dnnl::memory::data_type::f32,
dnnl::memory::data_type::bf16

注: 低い精度で演算を行うと、深層学習モデルの実装の変更を考慮しなければならないことがあります。
それぞれのプリミティブには、精度要件に基づくデータ型のサポートに対し、個別の制限がある場合があります。プリミ
ティブがサポートするデータ型のリストは、仕様ガイドの関連する節に含まれています。
Bfloat16
注: この節では、可読性のためデータ型の名称を省略しています。例えば、dnnl::memory::data_type::f32 は、
f32 と表記されます。
Bfloat16 (bf16) は、IEEE 32 ビット単精度浮動小数点データ型 (f32) をベースとする 16 ビット浮動小数点データ型
です。
bf16 と f32 の指数部は 8 ビットです。ただし、f32 の仮数部は 23 ビットであるのに対し、bf16 では 7 ビットしかなく最上位ビットのみが保持されます。そのため、bf16 は f32 データ型に近い数値範囲の値をサポートしますが、精度は大幅に低下します。従って、bf16 は、f32 と IEEE 16 ビット半精度浮動小数点データ型 f16 の間に位置付けられます。
5 ビットの指数部と 10 ビットの仮数部を持つ f16 と比較すると、bf16 は範囲を広げて精度を下げています。

5.4 データモデル

35

oneAPI 仕様 リリース 1.0 リビジョン 3

bfloat16 データ型の詳細については、こちら (英語) をご覧ください。
f32 に対して bf16 を使用する利点は、メモリー使用量が減るためメモリー・アクセス・スループットが向上することです。
ワークフロー
f32 データ型と bf16 データ型を使用した訓練の実装の主な違いは、重みの更新処理方法です。f32 データ型では、重み勾配のデータ型は重み自体と同じです。oneDNN ではある程度の柔軟性を許容するため、これは必ずしも bf16 デー
タ型には当てはまりません。例えば、f32 ですべての重みのマスターコピーを保持して重みの勾配を計算し、結果をbf16 に変換することができます。
サポート
ほとんどのプリミティブでは、bf16 データ型のソースと重みテンソルをサポートできます。デスティネーション・テンソ
ルには、bf16 または f32 データ型のどちらかを指定できます。後者は、bfloat16 をサポートしない操作、またはより高い精度を必要とする操作に出力を供給するケースを対象としています。
Int8
推論計算のパフォーマンスを向上させるため、最近のワークでは高いスループットを実現する低精度で格納された活性化と重みを採用する計算が注目されています。Int8 による計算は、精度の低下 (ただし許容範囲で) と引き換えにさらに多くの計算を単一命令にパックできるため、高精度の型と比べパフォーマンスが向上します。
ワークフロー
量子化では、oneDNN がサポートする量子化モデルの種類を説明します。
サポート
oneDNN は、プリミティブの入力および出力メモリー・オブジェクトで int8 データ型の使用を指定できるようにすること
で、推論で int8 計算をサポートします。

5.4.2 メモリー
oneDNN のメモリーには 2 つのレベルの抽象化があります。
1.
2.

メモリー記述子 – エンジンに依存しないデータの論理記述 (次元数、次元サイズ、データ型、および形式)。
メモリー・オブジェクト – エンジン固有のオブジェクトは、メモリー記述子とストレージを組み合わせます。

5.4 データモデル

36

oneAPI 仕様 リリース 1.0 リビジョン 3

oneDNN ではテンソル次元を表す次のエイリアスを定義します。
using dnnl::memory::dim = int64_t次元サイズとインデックスを表す整数型。
using dnnl::memory::dims = std::vector<dim>
次元のベクトル。実装ではベクトル長を自由に制限できます。
メモリー形式
oneDNN メモリー形式では、多次元テンソルが 1 次元の線形メモリーアドレス空間に格納されます。また、oneDNN は
従来の多次元配列に対応するプレーンと、完全に不透過な最適化された 2 種類のメモリー形式の種類を指定します。
プレーンメモリー形式
プレーンメモリー形式は、次元配列とストライド配列を使用して多次元テンソルがメモリーにどのように配置されるか記述します。どちらのレングスもテンソルのランクに等しくなります。oneDNN では次元の順番が固定されており、プリ
ミティブよって各種次元が正規の解釈を持つことができます。例えば、CNN プリミティブでは、活性化テンソルの順番は、{N, C, ..., D, H, W} となり、N はミニバッチ (またはバッチサイズ) を表し、C はチャネルを表し、D、H、および W は、イメージの空間次元、深さ、高さ、および幅に相当します。空間次元は、最も外側から最も内側の順序で省略できます。例
えば、D が存在する場合 H を省略することはできず、W は常に省略することはできません。プリミティブごとの正規解釈が文書化されています。これは、ストライド配列が、異なる次元のメモリーに配置される順番を定義する重要な役割を持つことを意味します。さらに、ストライドは次元と一致している必要があります。
正確には、T をランク n のテンソルとし、δ をソートするストライド配列の順序とします。つまり、すべての 0 ≤ i 、j < nに対して δ(i) < δ(j) の場合、strides[j] ≥ strides[i] となります。そして、以下が成り立つ必要があります。
stides[i] ≥ strides[j] * dimensions[j](すべての 0 ≤ i、j < n に対し δ(i) < δ(j) の場合)
0 ≤ j < n に対して 0 ≤ ij < dimensions[j] となる座標 (i0, ..., in-1) を持つ要素では、メモリー内のオフ
セットは次のように求められます。

ここで、offset0 は親メモリーからのオフセットであり、dnnl::memory::desc::submemory_desc() を使用して作成されたサブメモリーのメモリー記述子に対してのみゼロ以外の値を持ちます。サブメモリーのメモリー記述子は、
親メモリー記述子からストライドを継承します。これにより、インプレースの結合操作を表現できます。
例えば、M x N 行列 A (M 行 x N 列) について考えてみます。A が転置して格納されるかどうかにかかわりなく、
dimensionsA = {M, N} で す 。 た だ し 、 転 置 さ れ な い 場 合 は stridesA = {LDA, 1} 、 転 置 さ れ る 場 合 は
stridesA = {1, LDA} です。ここで、LDA は A が転置されない場合は LDA ≥ N、転置される場合は LDA ≥ M です。
これはまた、メモリーに密に保存する必要がないことを示しています。
注: 上記の例は、oneDNN では行優先でデータが格納されていることを前提とすることを示しています。

5.4 データモデル

37

oneAPI 仕様 リリース 1.0 リビジョン 3
コード例:
int M, N;
dnnl::memory::dims dims {M, N}; // 次元は常に同じです// 非転置行列
dnnl::memory::dims strides_non_transposed {N, 1};
dnnl::memory::desc A_non_transposed {dims, dnnl::memory::data_type::f32,
strides_non_transposed};// 転置行列dnnl::memory::dims strides_transposed {1, M};
dnnl::memory::desc A_transposed {dims, dnnl::memory::data_type::f32, strides_transposed};

形式タグ
strides に加えて、oneDNN は dnnl::memory::format_tag 列挙型の名前付き format tags を提供します。
この型の列挙子は、密なプレーンレイアウトの strides の代わりに利用できます。
N 次元のメモリー形式の形式タグ名は、任意に並べ替え可能なアルファベットの最初の N 文字を使用します。この並べ替えにより、最大 6 次元のテンソル strides を計算できます。結果 strides には密ストレージを指定します。前述した命令法により次の同等性が成り立ちます。
stides[i] = strides[j] * dimensions[j](すべての 0 ≤ i、j < n − 1 に対して δ(i) + 1 = δ(j) の場合)
matrix の例では、転置されていない matrix には dnnl::memory::format_tag::ab を使用し、転置された
matrix には dnnl::memory::format_tag::ba を使用できます。
int M, N;
dnnl::memory::dims dims {M, N}; // 次元は常に同じです// 非転置行列
dnnl::memory::desc A_non_transposed {dims, dnnl::memory::data_type::f32,
dnnl::memory::format_tag::ab};// 転置行列dnnl::memory::desc A_transposed {dims, dnnl::memory::data_type::f32,
dnnl::memory::format_tag::ba};

注: この節では、可読性のためメモリー形式のタグ名を省略しています。例えば、dnnl::memory::format_tag::abcd
は abcd に省略されます。

5.4 データモデル

38

oneAPI 仕様 リリース 1.0 リビジョン 3
また、抽象化形式タグ名以外に oneDNN ではいくつかのエイリアスも提供します。CNN と RNN の例を示します。
• nchw は abcd のエイリアスです (前述の CNN 次元の正規順序付けを参照してください)。
• oihw は abcd のエイリアスです。
• nhwc は acdb のエイリアスです。
• tnc は abc のエイリアスです。
• ldio は abcd のエイリアスです。
• ldoi は abdc のエイリアスです。
最適化された形式 ‘any’
oneDNN がサポートする別種の形式は、strides または dimensions 配列で直接作成できない不透過な最適化されたメモリー形式です。最適化されたメモリー形式のメモリー記述子は、特定の操作記述子を作成する際に any を渡して対応するプリミティブ記述子を作成し、メモリー記述子を照会できます。プレーンメモリー形式のデータは、計算前に最適化されたデータ形式のデータとして再配置する必要があります。再配置のコストは高いため、最適化されたメモリー
形式は計算グラフを介して伝搬する必要があります。
最適化された形式では、特定のアーキテクチャーに最適なデータ配置を維持するため、パディング、ブロッキング、
お よ び そ の 他 の デ ー タ 変 換 が 使 用 さ れ ま す 。 こ れ は 、 dnnl::memory::desc::permute_axes() や
dnnl::memory::desc::submemory_desc() など典型的な操作が失敗する可能性があることを意味します。
デ ー タ を 保 存 す る メ モ リー 容 量 を 計 算 す る 際 に 次 元 サ イ ズ の 積 を 使 う こ とは 適 切 で は あ り ま せ ん 。 代 わ り に 、
dnnl::memory::desc::get_size() を使用します。
メモリー形式伝搬
メモリー形式の伝搬は、oneDNN を適切に使用する上で理解すべき概念の 1 つです。
畳み込みと内積プリミティブは、入力または出力プレースホルダー・メモリー形式 any を使用して作成する際にメモリー形式を選択します。選択されるメモリー形式は、ハードウェアや畳み込みパラメーターなどの状況に依存します。プ
レースホルダー any メモリー形式を使用することは、それらがあるほとんどのトポロジーで最も計算集約的な操作であるため、畳み込みに推奨されます。
要素ごと、LRN、バッチ正規化などのプリミティブは、順伝搬で前のレイヤーと同じメモリー形式を使用する必要がある
ため、複数の oneDNN プリミティブを介してメモリー形式を伝搬します。これにはコストが発生する可能性があり、計算集約型のプリミティブが必要としない限り避けるべき再配置を排除できます。パフォーマンス上の理由から、このようなプリミティブの逆計算には、対応する順計算と一致するメモリー形式が必要となります。つまり、逆計算プリミティブを初期化するには、dnnl::memory::format_tag::any メモリー形式タグを使用する必要があります。

5.4 データモデル

39

oneAPI 仕様 リリース 1.0 リビジョン 3
以下は、操作記述の初期化中にメモリー形式 any を使用する場合と、使用しない場合の簡単なサマリーです。
プリミティブの種類

順伝搬

計算集約型: (逆) 畳み込み、内積、RNN any を使用

逆伝搬

伝搬なし

any を使用利用不可

メモリー帯域幅の制限: プーリング、レ ソーステンソルには前のレ 勾配テンソルには any を使 利用不可
イヤーとバッチの正規化、ローカル応答 イヤーのメモリー形式を使用し、データテンソルには実正規化、要素ごと、シャッフル、ソフト
用し、デスティネーション・テ 際のメモリー形式を使用
マックス
ンソルには any 形式を使用
メモリー帯域幅の制限: 再配置、結合、合計、バイナリー

利用不可

利用不可

ソーステンソルには前のレイヤーのメモリー形式を使用し、デスティネーション・テ
ンソルには any 形式を使用

訓練ワークロードを実行する場合、順伝搬と逆伝搬の間に追加の形式同期が必要になります。これは、逆伝搬を実装するプリミティブの記述子コンストラクター hint_pd 引数によって実現されます。
API
enum dnnl::memory::format_tag
メモリー形式タグの仕様。
メモリー形式タグはさらに 2 つのカテゴリーに分類されます。
• ドメインにとらわれない、つまり特定のプリミティブのテンソルの使い方に依存しない名前。この名前は、a から f までの文字によって論理次元を表し、次元がメモリーに配置される順番を示します。
例えば、dnnl::memory::format_tag::ab は、2 番目の論理次元 (b として示される) が最内である、つまり、stride = 1 であり、最初の論理次元 (a) が配置される 2D テンソルを表すために使用されます。そして、 2 次元のサイズに等しいストライドでメモリーに出力されます。 一方、
dnnl::memory::format_tag::ba は同じテンソルの転置バージョンであり、最も外側の次元 (a)が最も内側になります。
• ドメイン固有の名前で、CNN などの特定のドメイン・コンテキストでのみ意味を持ちます。これらの名
前は、対応するドメインにとらわれないタグのエイリアスであり、利便性のため使用されます。例えば、
dnnl::memory::format_tag::nc は、２D CCN 活性化テンソルのメモリー形式を示します。ここで、チャネル次元は最内の次元であり、バッチ次元は最外の次元です。さらに、
dnnl::memory::format_tag::nc は dnnl::memory::format_tag::ab のエイリアスであり、CNN プリミティブの場合、活性化テンソルの論理次元がバッチ、チャネル、空間の順になります。
つまり、バッチは最初の論理次元 (a) に対応し、チャネルは 2 番目の次元 (b) に対応します。
次のドメイン固有表記は、メモリー形式タグに適用されます。
• 'n’ はミニバッチの次元を示します。
• 'c’ はチャネルの次元を示します。

5.4 データモデル

40

oneAPI 仕様 リリース 1.0 リビジョン 3• 複数のチャネル次元がある場合 (例えば畳み込み重みテンソル)、'i’ と 'o’ は、入力と出力チャネルの次元を示します。
• 'g’ は畳み込み重みのグループ次元を示します。
• 'd'、'h’ および 'w’ は、ぞれぞれ空間の深さ、高さ、そして幅を示します。
値:
列挙子 undef
未定義メモリー形式タグ。
列挙子 any
プレースホルダー・メモリー形式タグ。形式を自動的に選択するようにプリミティブに指示します。
列挙子 a
プレーン 1D テンソル。
列挙子 ab
プレーン 2D テンソル。
列挙子 ba
並べ替え 2D テンソル。
列挙子 abc
プレーン 3D テンソル。
列挙子 acb
並べ替え 3D テンソル。
列挙子 bac
並べ替え 3D テンソル。
列挙子 bca
並べ替え 3D テンソル。
列挙子 cba
並べ替え 3D テンソル。
列挙子 abcd
プレーン 4D テンソル。
列挙子 abdc
並べ替え 4D テンソル。
列挙子 acdb
並べ替え 4D テンソル。
列挙子 bacd
並べ替え 4D テンソル。
列挙子 bcda
並べ替え 4D テンソル。
列挙子 cdba
並べ替え 4D テンソル。
列挙子 dcab
並べ替え 4D テンソル。
列挙子 abcde
プレーン 5D テンソル。
列挙子 abdec
並べ替え 5D テンソル。

5.4 データモデル

41

oneAPI 仕様 リリース 1.0 リビジョン 3
列挙子 acbde
並べ替え 5D テンソル。
列挙子 acdeb
並べ替え 5D テンソル。
列挙子 bacde
並べ替え 5D テンソル。
列挙子 bcdea
並べ替え 5D テンソル。
列挙子 cdeba
並べ替え 5D テンソル。
列挙子 decab
並べ替え 5D テンソル。
列挙子 abcdef
プレーン 6D テンソル。
列挙子acbdef
プレーン 6D テンソル。
列挙子 defcab
プレーン 6D テンソル。
列挙子 x
1D テンソル、dnnl::memory::format_tag::a のエイリアス。
列挙子 nc2D CNN 活性化テンソル、dnnl::memory::format_tag::ab のエイリアス。
列挙子 cn2D CNN 活性化テンソル、dnnl::memory::format_tag::ba のエイリアス。
列挙子 tn2D RNN 統計テンソル、dnnl::memory::format_tag::ab のエイリアス。
列挙子 nt2D RNN 統計テンソル、dnnl::memory::format_tag::ba のエイリアス。
列挙子 ncw
3D CNN 活性化テンソル、dnnl::memory::format_tag::abc のエイリアス。
列挙子 nwc
3D CNN 活性化テンソル、dnnl::memory::format_tag::acb のエイリアス。
列挙子 nchw
4D CNN 活性化テンソル、dnnl::memory::format_tag::abcd のエイリアス。
列挙子 nhwc
4D CNN 活性化テンソル、dnnl::memory::format_tag::acdb のエイリアス。
列挙子 chwn
4D CNN 活性化テンソル、dnnl::memory::format_tag::bcda のエイリアス。
列挙子 ncdhw
5D CNN 活性化テンソル、dnnl::memory::format_tag::abcde のエイリアス。
列挙子 ndhwc
5D CNN 活性化テンソル、dnnl::memory::format_tag::acdeb のエイリアス。
列挙子 oi
2D CNN 重みテンソル、dnnl::memory::format_tag::ab のエイリアス。

5.4 データモデル

42

oneAPI 仕様 リリース 1.0 リビジョン 3
列挙子 io2D CNN 重みテンソル、dnnl::memory::format_tag::ba のエイリアス。
列挙子 oiw
3D CNN 重みテンソル、dnnl::memory::format_tag::abc のエイリアス。
列挙子 owi
3D CNN 重みテンソル、dnnl::memory::format_tag::acb のエイリアス。
列挙子 wio
3D CNN 重みテンソル、dnnl::memory::format_tag::cba のエイリアス。
列挙子 iwo
3D CNN 重みテンソル、dnnl::memory::format_tag::bca のエイリアス。
列挙子 oihw
4D CNN 重みテンソル、dnnl::memory::format_tag::abcd のエイリアス。
列挙子 hwio
4D CNN 重みテンソル、dnnl::memory::format_tag::cdba のエイリアス。
列挙子 ohwi
4D CNN 重みテンソル、dnnl::memory::format_tag::acdb のエイリアス。
列挙子 ihwo
4D CNN 重みテンソル、dnnl::memory::format_tag::bcda のエイリアス。
列挙子 iohw
4D CNN 重みテンソル、dnnl::memory::format_tag::bacd のエイリアス。
列挙子 oidhw
5D CNN 重みテンソル、dnnl::memory::format_tag::abcde のエイリアス。
列挙子 dhwio
5D CNN 重みテンソル、dnnl::memory::format_tag::cdeba のエイリアス。
列挙子 odhwi
5D CNN 重みテンソル、dnnl::memory::format_tag::acdeb のエイリアス。
列挙子 iodhw
5D CNN 重みテンソル、dnnl::memory::format_tag::bacde のエイリアス。
列挙子 idhwo
5D CNN 重みテンソル、dnnl::memory::format_tag::bcdea のエイリアス。
列挙子 goiw
4D CNN 重みテンソルとグループ、dnnl::memory::format_tag::abcd のエイリアス。
列挙子 wigo
4D CNN 重みテンソルとグループ、dnnl::memory::format_tag::dcab のエイリアス。
列挙子 goihw
5D CNN 重みテンソルとグループ、dnnl::memory::format_tag::abcde のエイリアス。
列挙子 hwigo
5D CNN 重みテンソルとグループ、dnnl::memory::format_tag::decab のエイリアス。
列挙子 giohw
5D CNN 重みテンソルとグループ、dnnl::memory::format_tag::acbde のエイリアス。
列挙子 goidhw
6D CNN 重みテンソルとグループ、dnnl::memory::format_tag::abcdef のエイリアス。
列挙子 giodhw
6D CNN 重みテンソルとグループ、dnnl::memory::format_tag::abcdef のエイリアス。

5.4 データモデル

43

oneAPI 仕様 リリース 1.0 リビジョン 3
列挙子 dhwigo
6D CNN 重みテンソルとグループ、dnnl::memory::format_tag::decab のエイリアス。
列挙子 tnc(seq_length、バッチ、入力、チャネル) 形式の 3D RNN データテンソル。
列挙子 ntc(バッチ、seq_length、入力、チャネル) 形式の 3D RNN データテンソル。
列挙子 ldnc(num_layers、num_directions、バッチ、ステート、チャネル) 形式の 4D RNN ステートテンソル。
列挙子 ldigo(num_layers、 num_directions 、 input_channels 、 num_gates、 output_channels) 形式 の 5D
RNN 重みテンソル。
• LSTM セルの場合、ゲート順序は、入力、忘却、候補、および出力ゲートです。
• GRU セルのゲート順序は、更新、リセットおよび出力ゲートとなります。
列挙子 ldgoi(num_layers、 num_directions 、 num_gates、 output_channels 、 input_channels) 形式 の 5D
RNN 重みテンソル。
• LSTM セルの場合、ゲート順序は、入力、忘却、候補、および出力ゲートです。
• GRU セルのゲート順序は、更新、リセットおよび出力ゲートとなります。
列挙子 ldio(num_layers、
num_directions、
num_channels_in_hidden_state、
num_channels_in_recurrent_projection) 形式の 4D LSTM 予測テンソル。
列挙子 ldoi(num_layers、
num_directions、
num_channels_in_recurrent_projection、
num_channels_in_hidden_state) 形式の 4D LSTM 予測テンソル。
列挙子 ldgo(num_layers、num_directions、num_gates、output_channels) 形式の4D RNN バイアステンソル。
• LSTM セルの場合、ゲート順序は、入力、忘却、候補、および出力ゲートです。
• GRU セルのゲート順序は、更新、リセットおよび出力ゲートとなります。
メモリー記述子とオブジェクト
記述子
メモリー記述子は、エンジンに依存しないデータの論理記述 (次元数、次元サイズ、データ型) であり、オプションでメモリー内の物理形式に関する情報を持ちます。この情報が不明である場合、形式タグを dnnl::memory::format_tag::anyに設定してメモリー記述子を作成できます。これにより、計算集約型のプリミティブが計算に最適な形式を選択できるようになります。形式が一致しない場合、ユーザーはデータを新しい形式に並べ替える必要があります。「メモリー形式伝搬」を参照してください。
メモリー記述子は、次元、メモリー形式タグ、またはストライドを指定して初期化できます。
ユーザーは、dnnl::memory::desc::get_size() 関数を使用してメモリー記述子に必要なメモリー量を照会できます。一般に、データサイズは次元にデータサイズを掛けただけでは計算することはできません。従って、コードの移植性を保持するにはこの関数を利用する必要があります。

5.4 データモデル

44

oneAPI 仕様 リリース 1.0 リビジョン 3
2 つのメモリー記述子は、等式演算子と不等式演算子を使用して比較できます。この比較は、データをユーザーのデータ形式からプリミティブのデータ形式に並べ替える必要性を確認する際に役立ちます。
次元が正である通常のメモリー記述子に加えて、oneDNN は 1 つ以上の次元がゼロに設定されたゼロボリューム・メモ
リー記述子をサポートします。これは、NumPy* 規則をサポートするために使用されます。ゼロボリューム・メモリーがプ
リミティブに渡されると、プリミティブはこのメモリーを計算に使用しません。以下に例を示します。
• 結合プリミティブは、結合次元/軸がゼロであるすべてのメモリー・オブジェクトを無視します。
• ミニバッチ次元がゼロのソース・メモリー・オブジェクトの順方向畳み込みでは、常にミニバッチ次元がゼロのデスティネーション・メモリー・オブジェクトを生成しますが、計算は実行しません。
• ただし、畳み込み次元がゼロの順方向畳み込みは不十分な定義であり、出力値に対する明確な定義がない
ため、ライブラリーはエラーを生成します。
ゼロボリューム・メモリーのデータハンドルはアクセスされることはありません。
APIstruct dnnl::memory::desc
メモリー記述子。
パブリック関数desc()ゼロ (空の) メモリー記述子を構築。このメモリー記述子は、引数がないことを明示します。
desc (const dims &adims,
allow_empty = false)
メモリー記述子を構築。

data_typeadata_type,format_tag

aformat_tag,bool

注: 次元の論理的な順序は abc... 形式タグに対応し、次元の物理的な意味はこのメモリーで動作するプリ
ミティブと操作コンテキストの両方に依存します。
パラメーター• adims: テンソルの次元。
• adata_type: データの精度/型。
• aformat_tag: メモリー形式タグ。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。
この場合、ゼロメモリー記述子が作成されます。このフラグはオプションでありデフォルトは falseです。
desc(const dims &adims, data_type
allow_empty = false)
ストライドによってメモリー記述子を構築。

adata_type,

const

dims

&strides,bool

注: 次元の論理的な順序は abc... 形式タグに対応し、次元の物理的な意味はこのメモリーで動作するプリ
ミティブと操作コンテキストの両方に依存します。

5.4 データモデル

45

oneAPI 仕様 リリース 1.0 リビジョン 3
パラメーター• adims: テンソルの次元。
• adata_type: データの精度/型。
• strides: 各次元のストライド。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。
この場合、ゼロメモリー記述子が作成されます。このフラグはオプションでありデフォルトは falseです。
desc submemory_desc(const dims &adims, const dims &offsets, bool allow_empty =false) const
このメモリー記述子で記述された領域内のメモリーを作成します。
戻り値: 領域のメモリー記述子。
パラメーター• adims: 領域のサイズ。
• offsets: それぞれの次元に含まれるメモリー・オブジェクトから領域へのオフセット。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、ゼロメモリー記述子が返されます。このフラグはオプションでありデフォルトは false です。
desc reshape(const dims &adims, bool allow_empty = false) const
既存の記述子を再形成してメモリー記述子を構築します。新しいメモリー記述子はデータ型を継承します。
この操作により、物理メモリー形式の変換が論理次元の変換に対応することが保証されます。変換が不可能である場合、allow_empty フラグに応じて関数は例外 (デフォルト) をスローするか、ゼロメモリー記述子を返します。
再形成操作は、次の基本操作の組み合わせとして説明できます。
i. サイズ 1 の次元を追加します。これは常に可能です。
ii. サイズ 1 の次元を削除します。
iii. 単一の次元を複数の次元に分割します。これは、すべてのテンソル次元の積が一定である場合にのみ可能です。
iv. 複数の連続する次元を単一の次元に結合します。これには、次元がメモリー内で密集し、対応する論
理次元と同じ順序である必要があります。
• ここで、「密集」とは次を意味します。
dim[i] の stride == (dim[i + 1] の stride) * dim[i + 1];• そして、「同じ順序」は次を意味します。
i < j で dim[j] の stride <= dim[i] の stride の場合のみ。
注: 最適化されたメモリー形式では、再形成が失敗することがあります。
戻り値: 新しい次元のメモリー記述子。

5.4 データモデル

46

oneAPI 仕様 リリース 1.0 リビジョン 3
パラメーター• adims: 新しい次元。次元の積は一定である必要があります。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、ゼロメモリー記述子が返されます。このフラグはオプションでありデフォルトは false です。
desc permute_axes(const std::vector<int> &permutation, bool allow_empty = false)
const
既存の軸を並べ替えてメモリー記述子を構築します。
メモリー記述子の論理部分と物理部分間の一貫性が維持されることで、物理メモリーのレイアウトが調整されます。新しいメモリー記述子はデータ型を継承します。
論理軸は次のように並べ替えられます。
for (i = 0; i < ndims(); i++)new_desc.dims()[permutation[i]] = dims()[i];例：
std::vector<int> permutation = {1, 0}; // 1 番目と 2 番目の軸を入れ替えます
dnnl::memory::desc in_md({2, 3}, data_type, memory::format_tag::ab);dnnl::memory::desc expect_out_md({3, 2}, data_type, memory::format_tag::ba);assert(in_md.permute_axes(permutation) == expect_out_md);

戻り値: 新しい次元のメモリー記述子。
パラメーター• permutation: 軸の入れ換え。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、ゼロメモリー記述子が返されます。このフラグはオプションでありデフォルトは false です。
memory::dims dims() const
メモリー記述子の次元を返します。データコピーが伴うため潜在的にコストが高くなります。
戻り値: 次元ベクトルのコピー。
memory::data_type data_type() const
メモリー記述子のデータ型を返します。
戻り値: データ型。
size_t get_size() const
メモリー記述子のサイズをバイト単位で返します。

5.4 データモデル

47

oneAPI 仕様 リリース 1.0 リビジョン 3

戻り値: このメモリー記述子によって記述されたメモリー・オブジェクトにメモリーバッファーを割り当てるバイ
ト数。
bool is_zero() const
メモリー記述子がゼロ (空) であるか確認します。
戻り値: メモリー記述子が空のメモリーを記述する場合は true、それ以外は false。
bool operator==(const desc &other) const
等式演算子。
戻り値: 他のメモリーが同じ形式タグ、次元、ストライドなどを持つかどうか。
パラメーター• other: 別のメモリー記述子。
bool operator!=(const desc &other) const
不等式演算子。
戻り値: 他のメモリーが異なるメモリーを記述しているかどうか。
パラメーター• other: 他のメモリー記述子。
オブジェクトメモリー・オブジェクトは、メモリー記述子とデータストレージ (データハンドル) を組み合わせます。USM では、データハ
ンド ルは void へ のポ イ ンターです。 データ ハ ンド ルは dnnl::memory::get_data_handle() で照会し 、
dnnl::memory::set_data_handle() で 設 定 で き ま す 。 SYCL* バ ッ フ ァ ー を 使 用 す る 場 合 、
dnnl::sycl_interop::get_buffer() で照会し、dnnl::sycl_interop::set_buffer() で設定できます。
また、 メモリー 記述子 とメ モリー・ オブジ ェク ト のベ ースと なる エン ジンは、 dnnl::memory::get_desc() とdnnl::memory::get_engine() で照会できます。
API
struct dnnl::memory
メモリー・オブジェクト。
メモリー・オブジェクトは、特定のエンジン、テンソルの次元、データ型、およびメモリー形式に割り当てられたメモ
リーバッファーへのハンドルをカプセル化します。これにより、テンソル・インデックスが線形メモリー空間のオフ
セットにマップされます。メモリー・オブジェクトは実行中プリミティブに渡されます。
パブリック関数
memory()デフォルト・コンストラクター。
空のメモリー・オブジェクトを構築します。これはパラメーターがないことを示すために使用されます。

5.4 データモデル

48

oneAPI 仕様 リリース 1.0 リビジョン 3

memory(const desc &md, const engine &aengine, void *handle)
メモリー・オブジェクトを構築。
ハンドルが DNNL_MEMORY_NONE と等しくない限り、構築されたメモリー・オブジェクトにはベースとなるバッ
ファーが設定されます。この場合、バッファーは dnnl::memory::set_data_handle() が呼び出される
ように初期化されます。
参照: memory::set_data_handle()
パラメーター• md: メモリー記述子。
• engine: データを保存するエンジン。
• handle: 使用するメモリーバッファーのハンドル。
– ユーザーが割り当てたバッファーへのポインター。この場合、ライブラリーはバッファーを所有しません。
– DNNL_MEMORY_ALLOCATE 特殊値。メモリー・オブジェクトにバッファーを割り当てるようライ
ブラリーに指示します。この場合、ライブラリーがバッファーを所有し、ベースとなるメモリー割り当ての種別は dnnl::sycl_interop::memory_kind::usm です。
– DNNL_MEMORY_NONE を使用して、ベースとなるバッファーなしの dnnl::memory を作成します。
memory(const desc &md, const engine &aengine)
メモリー・オブジェクトを構築。
メモリーのベースとなるバッファーはライブラリーによって割り当てられます。ベースとなるバッファーのメモ
リー割り当て種別は、dnnl::sycl_interop::memory_kind::usm です。
パラメーター• md: メモリー記述子。
• engine: データを保存するエンジン。
desc get_desc() const
関連するメモリー記述子を返します。
engine get_engine() const
関連するエンジンを返します。
void *get_data_handle() const
ベースとなるメモリーバッファーを返します。
CPU エンジン、または USM を使用する場合、これは割り当てられたメモリーへのポインターです。
void set_data_handle(void *handle, const stream &astream) const
ベースとなるメモリーバッファーを設定します。

5.4 データモデル

49

oneAPI 仕様 リリース 1.0 リビジョン 3
この関数は、メモリー・オブジェクトにゼロパディング領域が存在する場合、ハンドルで指定されたメモリーにゼロ値を書き込むことがあります。これには時間がかかることがあり、関数が呼び出されるたびに生じます。
操作は常にブロック化され、stream パラメーターはヒントとなります。
注: プログラムが実行中に定数値を保持するためにメモリーを使用していても (例えば、推論中に事前にパックされた重みなど)、関数はパディング領域が存在する場合はゼロを書き込みます。従って、handle パラメー
ターは const 修飾子を持つことができません。
パラメーター• handle: 使用するメモリーバッファー。CPU エンジン、または USM を使用する場合、メモリーバッ
ファーは実際のデータへのポインターです。少なくとも dnnl::memory::desc::get_size()
バイトが割り当てられている必要があります。
• astream: パディングを行うために使用するストリーム。
void set_data_handle(void *handle) const
ベースとなるメモリーバッファーを設定します。
詳 細 に つ い て は 、 dnnl::memory::set_data_handle(void *, const stream &) const のドキュメントを参照してください。
パラメーター• handle: 使用するメモリーバッファー。CPU エンジンでは、メモリーバッファーは実際のデータへのポインターです。少なくとも dnnl::memory::desc::get_size() バイトが割り当てられている必要があります。
template<typename T= void>
T *map_data() const
メモリー・オブジェクトをマップし、その内容のコピーを含むメモリーバッファーへのホストポインターを返します。
マッピングにより、ダイレクト・メモリー・アクセスをサポートしないエンジンのメモリーコンテンツを直接読み書きすることができます。
マッピングは排他的な操作であり、メモリー・オブジェクトは dnnl::memory::unmap_data() 呼び出しによってマッピングが解除されるまで、他の操作では利用できません。
注: メモリーを操作するプリミティブは、メモリーをマップする前に完了する必要があります。
dnnl::stream::wait() を使用して対応する実行ストリームを同期します。
注: map_data と unmap_data 関数は、デバッグとテスト用途に提供されており、パフォーマンスは最適でない可能性があります。
戻り値: マップされたメモリーへのポインター。

5.4 データモデル

50

oneAPI 仕様 リリース 1.0 リビジョン 3
テンプレート・パラメーター• T: 返すポインターのデータ型。
void unmap_data(void *mapped_ptr) const
メモリー・オブジェクトのマップを解除し、メモリーバッファーに加えられた変更を書き戻します。
注: map_data と unmap_data 関数は、デバッグとテスト用途に提供されており、パフォーマンスは最適でない可能性があります。
パラメーター• mapped_ptr: 以前に dnnl::memory::map_data() によって返されたポインター。
enum dnnl::sycl_interop::memory_kind
メモリー割り当て種別。
値:
列挙子 usm
USMメモリー割り当て種別。
列挙子 buffer
バッファーメモリー割り当て種別。
memory dnnl::sycl_interop::make_memory(const memory::desc &adesc, const engine&aengine, memory_kind akind, void *ahandle = DNNL_MEMORY_ALLOCATE)指定されたエンジンに対し、指定された記述子とメモリー割り当て種類のメモリー・オブジェクトを作成します。
注 : akind が
dnnl::sycl_interop::memory_kind::buffer で あ り 、 ハ ン ド ル が
DNNL_MEMORY_ALLOCATE または DNNL_MEMORY_NONE ではない場合、例外がスローされます。
戻り値: 同じメモリー割り当て種別で、aengine に接続されている adesc メモリー記述子によって記述されたメモリー・オブジェクト。
パラメーター• adesc: データを表現するメモリー記述子。
• aengine: データを保存するエンジン。
• akind: メモリー割り当て種別。
• ahandle: 使用するメモリーデータのハンドル。このパラメーターはオプションです。デフォルトでは、
ベースとなるメモリーバッファーは内部的に割り当てられ、そのメモリー割り当て種別は
dnnl::sycl_interop::memory_kind::usm であり、ライブラリーがバッファーを所有します。
ハンドルが提供されるとライブラリーはバッファーを所有しません。
memory dnnl::sycl_interop::make_memory(const memory::desc &adesc, const stream&astream, memory_kind akind, void *ahandle = DNNL_MEMORY_ALLOCATE)指定されたストリームに対し、指定された記述子とメモリー割り当て種類のメモリー・オブジェクトを作成します。

5.4 データモデル

51

oneAPI 仕様 リリース 1.0 リビジョン 3
注: akind が dnnl::sycl_interop::memory_kind::buffer であり、ハンドルがDNNL_MEMORY_ALLOCATE
または DNNL_MEMORY_NONE でない場合、例外がスローされます。
戻り値: 同じメモリー割り当て種別で、aengine で使用されている adesc メモリー記述子によって記述されたメモリー・オブジェクト。
パラメーター• adesc: データを表現するメモリー記述子。
• astream: データが使用されるストリーム・オブジェクト。
• akind: メモリー割り当て種別。
• ahandle: 使用するメモリーデータのハンドル。このパラメーターはオプションです。デフォルトでは、
ベースとなるメモリーバッファーは内部的に割り当てられ、そのメモリー割り当て種別は
dnnl::sycl_interop::memory_kind::usm であり、ライブラリーがバッファーを所有します。
ハンドルが提供されるとライブラリーはバッファーを所有しません。
template<typename T, int ndims>
memory dnnl::sycl_interop::make_memory(const memory::desc &adesc, const engine&aengine, cl::sycl::buffer<T, ndims> abuffer)指定された SYCL* バッファーを使用するメモリー・オブジェクトを作成します。
注: このメモリー・オブジェクトが作成されると、メモリー割り当て種別は暗黙的にdnnl::sycl_interop::memory_kind::buffer となります。
戻り値: adesc メモリー記述子によって記述され、aengine エンジンに接続された abuffer SYCL* バッ
ファーを保持するメモリー・オブジェクト。
テンプレート・パラメーター• T: 指定された SYCL* バッファーのデータ型。
• ndims: 指定された SYCL* バッファーの次元数。
パラメーター• adesc: 指定されたバッファー内のデータを記述するメモリー記述子。
• aengine: データを保存するエンジン。
• abuffer: SYCL* バッファー。
template<typename

T,

int

ndims>

memory dnnl::sycl_interop::make_memory(const memory::desc &adesc, const stream&as tream, cl::sycl::buffer<T, ndims> abuffer)指定された SYCL* バッファーを使用するメモリー・オブジェクトを作成します。
注: このメモリー・オブジェクトが作成されると、メモリー割り当て種別は暗黙的にdnnl::sycl_interop::memory_kind::buffer となります。
戻り値: adesc メモリー記述子によって記述され、astream ストリーム内で使用された abuffer SYCL*
バッファーを保持するメモリー・オブジェクト。

5.4 データモデル

52

oneAPI 仕様 リリース 1.0 リビジョン 3

テンプレート・パラメーター• T: 指定された SYCL* バッファーのデータ型。
• ndims: 指定された SYCL* バッファーの次元数。
パラメーター• adesc: 指定されたバッファー内のデータを記述するメモリー記述子。
• astream: データが使用されるストリーム・オブジェクト。
• abuffer: SYCL* バッファー。
memory_kind dnnl::sycl_interop::get_memory_kind(const memory &amemory)
指定されたメモリー・オブジェクトのメモリー割り当て種別を返します。
注: メモリー・オブジェクトのメモリー割り当て種別は、そのメモリー・オブジェクトの USM ハンドルや SYCL*
バッファーを設定することで存続期間中に変更できます。
戻り値: amemory メモリー・オブジェクトのメモリー割り当て種別。
パラメーター• amemory: メモリー・オブジェクト。
template<typename T, int ndims>
void dnnl::sycl_interop::set_buffer(memory &amemory, cl::sycl::buffer<T, ndims>
abuffer)
指定されたメモリー・オブジェクトのベースとなる SYCL* バッファーを設定します。
注 : メ モ リ ー ・ オ ブ ジ ェ ク ト の SYCL バ ッ フ ァ ー を 設 定 す る と 、 メ モ リ ー 割 り 当 て 種 別 は
dnnl::sycl_interop::memory_kind::buffer に変更されます。
テンプレート・パラメーター• T: 指定された SYCL* バッファーのデータ型。
• ndims: 指定された SYCL バッファーの次元数。
パラメーター• amemory: abuffer SYCL* バッファーに保存されるメモリー・オブジェクト。
• abuffer: amemory メモリー・オブジェクトに格納される SYCL* バッファー。
template<typenameT,
int
ndims>
void dnnl::sycl_interop::set_buffer(memory &amemory, cl::sycl::buffer<T, ndims>
abuffer, stream &astream)
指定されたストリーム内のメモリー・オブジェクトのベースとなる SYCL* バッファーを設定します。
テンプレート・パラメーター• T: 指定された SYCL* バッファーのデータ型。
• ndims: 指定された SYCL* バッファーの次元数。

5.4 データモデル

53

oneAPI 仕様 リリース 1.0 リビジョン 3
パラメーター• amemory: abuffer SYCL* バッファーに保存されるメモリー・オブジェクト。
• abuffer: amemory メモリー・オブジェクトに格納され、astream ストリームで使用される SYCL*
バッファー。
• astream: amemory メモリー・オブジェクトが使用されるストリーム・オブジェクト。
template<typename T, int ndims= 1>
cl::sycl::buffer<T, ndims> dnnl::sycl_interop::get_buffer(constmemory &amemory)
指定されたメモリー・オブジェクトのベースとなる SYCL バッファーを返します。
戻り値: amemory メモリー・オブジェクトのベースとなる、ndims 次元を持つ T 型の SYCL* バッファー。
テンプレート・パラメーター• T: 指定された SYCL* バッファーのデータ型。
• ndims: 指定されたバッファーの次元数。
パラメーター• amemory: メモリー・オブジェクト。
DNNL_MEMORY_NONE
メモリー・オブジェクトのベースとなるバッファーがないことを表す特殊なポインター値。
DNNL_MEMORY_ALLOCATE
ライブラリーがメモリー・オブジェクトのベースとなるバッファーを割り当てる必要があることを表す特殊なポ
インター値。

5.5

プリミティブプリミティブは、順方向畳み込み、逆方向 LSTM 計算、データ交換操作など特定の計算をカプセル化するファンク
ター・オブジェクトです。単一のプリミティブは、順方向畳み込みとそれに続く ReLU など、複雑な融合計算を表すことがあります。
プリミティブと純粋関数の大きな違いは、プリミティブは状態を格納できることです。
プリミティブ状態の一部は不変です。例えば、畳み込みプリミティブはテンソル形式のようなパラメーターを格納し、キャッシュ・ブロッキングなど他の依存関係があるパラメーターを事前計算できます。これにより、oneDNN プリミティ
ブは要求された操作の実行に合わせて調整済みのコードを事前生成できます。oneDNN プログラミング・モデルは、同じプリミティブを再利用して計算を複数回実行することで、事前計算にかかる時間を償却することを前提にしています。
プリミティブ状態の変更可能な部分は、スクラッチパッドと呼ばれます。これは、プリミティブが計算中にのみ一時ストレージとして使用できるメモリーバッファーです。スクラッチパッドは、プリミティブ・オブジェクト (オブジェクトはスレッ
ドセーフでない) が所有することも、実行時にパラメーターにすることもできます。
概念的には、oneDNN は、計算を抽象的なものから具体的なものまで記述できるいくつかのレイヤーを持ちます。

5.5 プリミティブ

54

oneAPI 仕様 リリース 1.0 リビジョン 3• 操作記述子 (サポートされるプリミティブごとに 1 つ) には、操作の最も基本的なプロパティーを記述します。
それらの計算で使用されるエンジンを指定する必要はありません。例えば、畳み込み記述子は、ソース、デスティネーション、重みテンソル、伝搬の種類 (データや重みに対する前方、後方)、およびその他の実装に依存しないパラメーターを記述します。形状はメモリー記述子 (dnnl::memory::desc) として記述されます。
• プリミティブ記述子は、操作記述子とプリミティブ間の抽象化レベルにあります。これらは、操作記述子とプリミティブ属性を組み合わせたものです。プリミティブ記述子を使用して、プリミティブ実装の詳細を照会できます。例えば、プリミティブをインスタンス化することなくクエリーによって予測されるメモリー形式を調査することで、メモリー形式の伝搬を実装できます。oneDNN には、同じ計算を実行するのに使用できる同一
プリミティブの複数の実装が含まれる場合があります。プリミティブ記述子は一方向の反復を許容し、複数の実装を検査できます。ライブラリーは、最も優先順位の高い実装から、最も優先度の低い実装の順に並べることが期待されるため、デフォルトで選択されたものを使用しても安全です。
• 最も具体的なプリミティブは、実行可能な実際の計算を具体化します。
API レベル:• プリミティブは、dnnl::primitive を基本クラスに持つ dnnl 名前空間のトップレベルのクラスとして表されます (例えば、dnnl::convolution_forward)。
• 操作記述子は desc 名前クラスで表され、対応するプリミティブ・クラス内で入れ子にされます (例えば、
dnnl::convolution_forward::desc)。dnnl::primitive_desc::next_impl() メンバー関数
は、実装を反復処理する方法を提供します。
• プリミティブ記述子は primitive_desc 名前クラスで表され、基本クラスとして
dnnl::primitive_desc_base を持つプリミティブ・クラス内で入れ子にされます(dnnl::rnn_primitive_desc_base から派生する RNN プリミティブを除く)。
例: dnnl::convolution_forward::primitive_desc。
namespace dnnl {struct something_forward : public primitive {struct desc {// プリミティブ固有のコンストラクター}
struct primitive_desc : public primitive_desc_base {// コンストラクターとプリミティブ固有のメモリー記述子のクエリー}};}

5.5 プリミティブ

55

oneAPI 仕様 リリース 1.0 リビジョン 3
プリミティブを作成する一連のアクションには次のものがあります。
1.

2.
3.

例えば、dnnl::convolution_forward::desc を使用して操作記述子を作成します。操作記述子には、プレースホルダー dnnl::memory::format_tag::any メモリー形式 (プリミティブがサポートする場合) を含むメモリー記述子を含めることができます。
操作記述子、エンジン、属性に基づいてプリミティブ記述子を作成します。
手順 2 で取得したプリミティブ記述子を基にプリミティブを作成します。

注: 厳密に言うと、すべてのプリミティブでこの手順を利用できるわけではありません。例えば、リオーダー・プリミティブには操作記述子がないため、手順 1 は必要ありません。

5.5.1 共通定義
ここでは、すべてもしくは複数のプリミティブで使用される一般的な型と定義を示します。
プリミティブの基本クラス
struct dnnl::primitive
すべての計算プリミティブのベースクラス。
dnnl::batch_normalization_backward、
dnnl::batch_normalization_forward、
dnnl::binary、
dnnl::concat、
dnnl::convolution_backward_data、
dnnl::convolution_backward_weights、
dnnl::convolution_forward、
dnnl::deconvolution_backward_data、
dnnl::deconvolution_backward_weights、
dnnl::deconvolution_forward 、 dnnl::eltwise_backward 、 dnnl::eltwise_forward 、
dnnl::gru_backward 、 dnnl::gru_forward 、 dnnl::inner_product_backward_data 、
dnnl::inner_product_backward_weights、
dnnl::inner_product_forward、
dnnl::layer_normalization_backward、
dnnl::layer_normalization_forward、
dnnl::lbr_gru_backward 、 dnnl::lbr_gru_forward 、 dnnl::logsoftmax_backward 、
dnnl::logsoftmax_forward、dnnl::lrn_backward、dnnl::lrn_forward、dnnl::lstm_backward、
dnnl::lstm_forward 、 dnnl::matmul 、 dnnl::pooling_backward 、 dnnl::pooling_forward 、
dnnl::reorder、dnnl::resampling_backward、
dnnl::resampling_forward、
dnnl::shuffle_backward、
dnnl::shuffle_forward、
dnnl::softmax_backward、
dnnl::softmax_forward、
dnnl::sum、dnnl::vanilla_rnn_backward、
dnnl::vanilla_rnn_forward によってサブクラス化されます。
パブリックタイプ
enum kindライブラリーでサポートされるプリミティブ種別。
値:
列挙子 undef
未定義のプリミティブ。
列挙子 reorder
リオーダー・プリミティブ。

5.5 プリミティブ

56

oneAPI 仕様 リリース 1.0 リビジョン 3
列挙子 shuffle
シャッフル・プリミティブ。
列挙子 concat(アウトオブプレース) テンソル結合プリミティブ。
列挙子 sum
総和プリミティブ。
列挙子 convolution
畳み込みプリミティブ。
列挙子 deconvolution
逆畳み込みプリミティブ。
列挙子 eltwise
要素ごとのプリミティブ。
列挙子 softmax
ソフトマックス・プリミティブ。
列挙子 pooling
プーリング・プリミティブ。
列挙子 lrn
LRN プリミティブ。
列挙子 batch_normalization
バッチ正規化プリミティブ。
列挙子 layer_normalization
レイヤー正規化プリミティブ。
列挙子 inner_product
内積プリミティブ。
列挙子 rnn
RNN プリミティブ。
列挙子 binary
ライブラリー・プリミティブ。
列挙子 logsoftmax
logsoftmax プリミティブ。
列挙子 matmul
matmul (行列乗算) プリミティブ。
列挙子 resampling
リサンプリング・プリミティブ。
パブリック関数primitive()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive(constprimitive_desc_base &pd)
プリミティブ記述子からプリミティブを構築します。
パラメーター• pd: プリミティブ記述子。

5.5 プリミティブ

57

oneAPI 仕様 リリース 1.0 リビジョン 3
kind get_kind() const
プリミティブの種別を返します。
戻り値: プリミティブの種別。
void execute(const stream &astream, const std::unordered_map<int, memory> &args)const指定されたストリーム内のプリミティブの計算を実行します。
引数は、<インデックス、メモリー・オブジェクト> のペアを含む引数マップを介して渡されます。インデックスは、
DNNL_ARG_SRC など DNNL_ARG_* 値のいずれかの必要があり、動的形状を使用しない限り、メモリーには
dnnl::primitive_desc_base::query_md(query::exec_arg_md, index) によって返されるメモリー記
述子と一致する必要があります (DNNL_RUNTIME_DIM_VAL を参照)。
パラメーター• astream: ストリーム・オブジェクト。ストリームはプリミティブと同じエンジンに属している必要があります。
• args: 引数マップ。
primitive &operator=(constprimitive &rhs)
代入演算子。
cl::sycl::event dnnl::sycl_interop::execute(const primitive &aprimitive, const stream &as tream, const
std::unordered_map<int, memory> &args, const std::vector<cl::sycl::event> &dependencies = {})指定されたストリーム内のプリミティブ・オブジェクトを使用して計算を実行します。
引数は、<インデックス、メモリー・オブジェクト> のペアを含む引数マップを介して渡されます。インデックスは、
DNNL_ARG_SRC など DNNL_ARG_* 値のいずれかの必要があり、動的形状を使用しない限り、メモリーには
dnnl::primitive_desc_base::query_md(query::exec_arg_md, index) によって返されるメモリー記
述子と一致する必要があります (DNNL_RUNTIME_DIM_VAL をディスクリプター)。
戻り値: 指定されたプリミティブ実行の SYCL イベント・オブジェクト。
パラメーター• aprimitive: 実行されるプリミティブ。
• astream: ストリーム・オブジェクト。ストリームはプリミティブと同じエンジンに属している必要があります。
• args: 引数マップ。
• dependencies: 実行が依存する SYCL* イベントのベクトル。
プリミティブ記述子の基本クラス
プリミティブ間で大きく異なるため、操作記述子に共通の基本クラスはありません。ただし、プリミティブ記述子には共通の基本クラスがあります。
struct dnnl::primitive_desc_base
すべてのプリミティブ記述子の基本クラス。

5.5 プリミティブ

58

oneAPI 仕様 リリース 1.0 リビジョン 3

dnnl::concat::primitive_desc 、 dnnl::primitive_desc 、 dnnl::reorder::primitive_desc 、
dnnl::sum::primitive_desc によってサブクラス化
パブリック関数primitive_desc_base()
デフォルト・コンストラクター。空のオブジェクトを生成します。
engine get_engine() const
プリミティブ記述子のエンジンを返します。
戻り値: プリミティブ記述子のエンジン。
const char *impl_info_str() const
実装名を返します。
戻り値: 実装名。
memory::dim query_s64(query what) const
memory::dim 値 (int64_t と同じ) を返します。
戻り値: 照会の結果。
パラメーター• what: 照会する値。

memory::desc query_md(query what, int idx = 0) const
メモリー記述子を返します。
注:
dnnl::primitive_desc_base::src_desc()
dnnl::primitive_desc_base::dst_desc() など便利なメソッドがあります。

や

戻り値: 要求されたメモリー記述子。
戻り値: プリミティブに種別やインデックス ・パラメーターがない場合は、ゼロメモリー記述子。
パラメーター• what: 照会するパラメーターの種別: dnnl::query::src_md や dnnl::query::dst_md など。
• idx: パラメーターのインデックス。例えば、畳み込みバイアスは、
what = dnnl::query::weights_md および idx = 1 で照会できます。

memory::desc src_desc(int idx) const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。

5.5 プリミティブ

59

oneAPI 仕様 リリース 1.0 リビジョン 3

戻り値: プリミティブにインデックス付きのソース・パラメーターがない場合は、ゼロメモリー記述子。
パラメーター• idx: ソース・インデックス。

memory::desc dst_desc(int idx) const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにインデックス pdx 付きのデスティネーション・パラメーターがない場合は、ゼロメモ
リー記述子。
パラメーター• idx: デスティネーション・インデックス。
memory::desc weights_desc(int idx) const
重みメモリー記述子を返します。
戻り値: 重みメモリー記述子。
戻り値: プリミティブにインデックス pdx 付きの重みパラメーターがない場合は、ゼロメモリー記述子。
パラメーター• idx: 重みインデックス。
memory::desc diff_src_desc(int idx) const
差分ソースメモリー記述子を返します。
戻り値: 差分ソースメモリー記述子。
戻り値: プリミティブにインデックス pdx 付きの差分ソース・パラメーターがない場合は、ゼロメモリー記述子。
パラメーター• idx: 差分ソース・インデックス。
memory::desc diff_dst_desc(int idx) const
差分デスティネーション・メモリー記述子を返します。
戻り値: 差分デスティネーション・メモリー記述子。
戻り値: プリミティブにインデックス pdx 付きの差分デスティネーション・パラメーターがない場合は、ゼロメ
モリー記述子。

5.5 プリミティブ

60

oneAPI 仕様 リリース 1.0 リビジョン 3

パラメーター• idx: 差分デスティネーション・インデックス。
memory::desc diff_weights_desc(int idx) const
差分重みメモリー記述子を返します。
戻り値: 差分重みメモリー記述子。
戻り値: プリミティブにインデックス pdx 付きの差分重みパラメーターがない場合は、ゼロメモリー記述子。
パラメーター• idx: 差分重みインデックス。
memory::desc src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc weights_desc() const
重みメモリー記述子を返します。
戻り値: 重みメモリー記述子。
戻り値: プリミティブに重みパラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_src_desc() const
差分ソースメモリー記述子を返します。
戻り値: 差分ソースメモリー記述子。
戻り値: プリミティブに差分ソースメモリーがない場合は、ゼロメモリー記述子。

memory::desc diff_dst_desc() const
差分デスティネーション・メモリー記述子を返します。
戻り値: 差分デスティネーション・メモリー記述子。
5.5 プリミティブ

61

oneAPI 仕様 リリース 1.0 リビジョン 3

戻り値: プリミティブに差分デスティネーション・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_weights_desc() const
差分重みメモリー記述子を返します。
戻り値: 差分重みメモリー記述子。
戻り値: プリミティブに差分重みパラメーターがない場合は、ゼロメモリー記述子。
memory::desc workspace_desc() const
ワークスペース・メモリー記述子を返します。
戻り値: ワークスペース・メモリー記述子。
戻り値: プリミティブがワークスペース・パラメーターを要求しない場合は、ゼロメモリー記述子。
memory::desc scratchpad_desc() const
スクラッチパッド・メモリー記述子を返します。
戻り値: スクラッチパッド・メモリー記述子。
戻り値: プリミティブがスクラッチパッド・パラメーターを要求しない場合は、ゼロメモリー記述子。
engine scratchpad_engine() const
スクラッチパッド・メモリーが配置されているエンジンを返します。
戻り値: スクラッチパッド・メモリーが配置されているエンジン。
primitive_attr get_primitive_attr() const
プリミティブ属性を返します。
戻り値: プリミティブ属性。
dnnl::primitive::kind get_kind() const
プリミティブ記述子の種別を返します。
戻り値: プリミティブ記述子の種別。
さらに、操作記述子を持つすべてのプリミティブの基本クラスを提供することから派生します。
struct dnnl::primitive_desc: public dnnl::primitive_desc_base
操作記述子を持ち、複数の実装に対して反復をサポートするすべてのプリミティブ記述子の基本クラス。
dnnl::batch_normalization_backward::primitive_desc、
dnnl::batch_normalization_forward::primitive_desc 、 dnnl::binary::primitive_desc 、
dnnl::convolution_backward_data::primitive_desc、
dnnl::convolution_backward_weights::primitive_desc、
5.5 プリミティブ

62

oneAPI 仕様 リリース 1.0 リビジョン 3
dnnl::convolution_forward::primitive_desc、
dnnl::deconvolution_backward_data::primitive_desc、
dnnl::deconvolution_backward_weights::primitive_desc、
dnnl::deconvolution_forward::primitive_desc、
dnnl::eltwise_backward::primitive_desc 、 dnnl::eltwise_forward::primitive_desc 、
dnnl::inner_product_backward_data::primitive_desc、
dnnl::inner_product_backward_weights::primitive_desc、
dnnl::inner_product_forward::primitive_desc、
dnnl::layer_normalization_backward::primitive_desc、
dnnl::layer_normalization_forward::primitive_desc、
dnnl::logsoftmax_backward::primitive_desc、
dnnl::logsoftmax_forward::primitive_desc 、 dnnl::lrn_backward::primitive_desc 、
dnnl::lrn_forward::primitive_desc、
dnnl::matmul::primitive_desc、
dnnl::pooling_backward::primitive_desc 、 dnnl::pooling_forward::primitive_desc 、
dnnl::resampling_backward::primitive_desc、
dnnl::resampling_forward::primitive_desc、
dnnl::rnn_primitive_desc_base、
dnnl::shuffle_backward::primitive_desc 、 dnnl::shuffle_forward::primitive_desc 、
dnnl::softmax_backward::primitive_desc 、 dnnl::softmax_forward::primitive_desc で サ
ブクラス化します。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
bool next_impl()
プリミティブ記述子イテレーターを次の実装に進めます。
戻り値: 成功した場合は true、最後の実装に達した場合は false。この場合、プリミティブ記述子は変更されません。
dnnl::reorder、dnnl::sum および dnnl::concat は、プリミティブ記述子を実装するため dnnl::primitive_desc
もサブクラス化します。
RNN プリミティブは、さらに dnnl::primitive_desc_base をサブクラス化して、頻繁に照会されるメモリー記述
子にユーティリティー関数を提供します。
struct dnnl::rnn_primitive_desc_base: public dnnl::primitive_desc
RNN プリミティブのプリミティブ記述子の基本クラス。
dnnl::gru_backward::primitive_desc、
dnnl::gru_forward::primitive_desc
dnnl::lbr_gru_backward::primitive_desc 、 dnnl::lbr_gru_forward::primitive_desc
dnnl::lstm_backward::primitive_desc、
dnnl::lstm_forward::primitive_desc
dnnl::vanilla_rnn_backward::primitive_desc
dnnl::vanilla_rnn_forward::primitive_desc でサブクラス化します。

5.5 プリミティブ

63

、
、
、
、

oneAPI 仕様 リリース 1.0 リビジョン 3
パブリック関数
rnn_primitive_desc_base()
デフォルト・コンストラクター。空のオブジェクトを生成します。
memory::desc src_layer_desc() const
ソース・レイヤー・メモリー記述子を返します。
戻り値: ソース・レイヤー・メモリー記述子。
memory::desc src_iter_desc() const
ソース反復メモリー記述子を返します。
戻り値: ソース反復メモリー記述子。
戻り値: プリミティブにソース反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc src_iter_c_desc() const
ソース・リカレント・セル状態メモリー記述子を返します。
戻り値: ソース・リカレント・セル状態メモリー記述子。
memory::desc weights_layer_desc() const
重みレイヤーメモリー記述子を返します。
戻り値: 重みレイヤーメモリー記述子。
memory::desc weights_iter_desc() const
重み反復メモリー記述子を返します。
戻り値: 重み反復メモリー記述子。
memory::desc weights_peephole_desc() const
重みピープホール・メモリー記述子を返します。
戻り値: 重みピープホール・メモリー記述子。
memory::desc weights_projection_desc() const
重みピープホール・メモリー記述子を返します。
戻り値: 重みピープホール・メモリー記述子。
memory::desc bias_desc() const
バイアスメモリー記述子を返します。
戻り値: バイアスメモリー記述子。
戻り値: プリミティブにバイアス・パラメーターがない場合は、ゼロメモリー記述子。

5.5 プリミティブ

64

oneAPI 仕様 リリース 1.0 リビジョン 3
memory::desc dst_layer_desc() const
デスティネーション・レイヤー・メモリー記述子を返します。
戻り値: デスティネーション・レイヤー・メモリー記述子。
memory::desc dst_iter_desc() const
デスティネーション反復メモリー記述子を返します。
戻り値: デスティネーション反復メモリー記述子。
戻り値: プリミティブにデスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_iter_c_desc() const
デスティネーション・リカレント・セル状態メモリー記述子を返します。
戻り値: デスティネーション・リカレント・セル状態メモリー記述子。
memory::desc diff_src_layer_desc() const
差分ソース・レイヤー・メモリー記述子を返します。
戻り値: 差分ソース・レイヤー・メモリー記述子。
memory::desc diff_src_iter_desc() const
差分ソース反復メモリー記述子を返します。
戻り値: 差分ソース反復メモリー記述子。
戻り値: プリミティブに差分ソース反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_src_iter_c_desc() const
差分ソース・リカレント・セルの状態メモリー記述子を返します。
戻り値: 差分ソース・リカレント・セルの状態メモリー記述子。
memory::desc diff_weights_layer_desc() const
差分重みレイヤーメモリー記述子を返します。
戻り値: 差分重みレイヤーメモリー記述子。
memory::desc diff_weights_iter_desc() const
差分重み反復メモリー記述子を返します。
戻り値: 差分重み反復メモリー記述子。
memory::desc diff_weights_peephole_desc() const
差分重みピープホール・メモリー記述子を返します。
戻り値: 差分重みピープホール・メモリー記述子。

5.5 プリミティブ

65

oneAPI 仕様 リリース 1.0 リビジョン 3

memory::desc diff_weights_projection_desc() const
差分重み予測メモリー記述子を返します。
戻り値: 差分重み予測メモリー記述子。
memory::desc diff_bias_desc() const
差分バイアスメモリー記述子を返します。
戻り値: 差分バイアスメモリー記述子。
戻り値: プリミティブに差分バイアス・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_layer_desc() const
差分デスティネーション・レイヤー・メモリー記述子を返します。
戻り値: 差分デスティネーション・レイヤー・メモリー記述子。
memory::desc diff_dst_iter_desc() const
差分デスティネーション反復メモリー記述子を返します。
戻り値: 差分デスティネーション反復メモリー記述子。
戻り値: プリミティブに差分デスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_iter_c_desc() const
差分デスティネーション・リカレント・セル状態メモリー記述子を返します。
戻り値: 差分デスティネーション・リカレント・セル状態メモリー記述子。
共通列挙子
enum dnnl::prop_kind
伝搬の種類。
値:
列挙子 undef
未定義の伝搬種別。
列挙子 forward_training
順方向データ伝搬 (訓練モード)このモードでは、プリミティブは後続の逆方向伝搬に必要な計算を実行します。
列挙子 forward_inference
順方向データ伝搬 (推論モード)このモードでは、プリミティブは推論に必要な計算だけを実行し、逆方向伝搬に必要な計算を省略します。
列挙子 forward_scoring
順方向データ伝搬、dnnl::prop_kind::forward_inference のエイリアス。
列挙子 forward
順方向データ伝搬、dnnl::prop_kind::forward_training のエイリアス。

5.5 プリミティブ

66

oneAPI 仕様 リリース 1.0 リビジョン 3
列挙子 backward
逆方向伝搬 (すべてのパラメーターに対し)。
列挙子 backward_data
逆方向データ伝搬。
列挙子 backward_weights
逆方向重み伝搬。
列挙子 backward_bias
逆方向バイアス伝搬。
enum dnnl::algorithm
アルゴリズムの種別。
値:
列挙子 undef
未定義のアルゴリズム。
列挙子 convolution_auto
直接または自動的に Winograd になるように選択された畳み込みアルゴリズム。
列挙子 convolution_direct
直接畳み込み。
列挙子 convolution_winograd
Winograd 畳み込み。
列挙子 deconvolution_direct
直接逆畳み込み。
列挙子 deconvolution_winograd
Winograd 逆畳み込み。
列挙子 eltwise_relu
要素ごと: 正規化線形関数 (ReLU)。
列挙子 eltwise_tanh
要素ごと: 双曲線正接関数 (tanh)。
列挙子 eltwise_elu
要素ごと: 指数線形関数 (ELU)。
列挙子 eltwise_square
要素ごと: square。
列挙子 eltwise_abs
要素ごと: abs。
列挙子 eltwise_sqrt
要素ごと: square root。
列挙子 eltwise_swish
要素ごと: swish (x ・ sigmoid(a ・ x))。
列挙子 eltwise_linear
要素ごと: linear。
列挙子 eltwise_bounded_relu
要素ごと: bounded_relu。
列挙子 eltwise_soft_relu
要素ごと: soft_relu。

5.5 プリミティブ

67

oneAPI 仕様 リリース 1.0 リビジョン 3
列挙子 eltwise_logistic
要素ごと: logistic。
列挙子 eltwise_exp
要素ごと: exponent。
列挙子 eltwise_gelu
要素ごと: gelu、dnnl::algorithm::eltwise_gelu_tanh のエイリアス。
列挙子 eltwise_gelu_tanh
要素ごと: tanh-based gelu。
列挙子 eltwise_gelu_erf
要素ごと: erf-based gelu。
列挙子 eltwise_log
要素ごと: natural logarithm。
列挙子 eltwise_clip
要素ごと: clip。
列挙子 eltwise_pow
要素ごと: pow。
列挙子 eltwise_round
要素ごと: round。
列挙子 eltwise_relu_use_dst_for_bwd
要素ごと: rectified linear unit (ReLU) (逆方向 dst)。
列挙子 eltwise_tanh_use_dst_for_bwd
要素ごと: hyperbolic tangent non-linearity (tanh) (逆方向 dst)。
列挙子 eltwise_elu_use_dst_for_bwd
要素ごと: exponential linear unit (ELU) (逆方向 dst)。
列挙子 eltwise_sqrt_use_dst_for_bwd
要素ごと: square root (逆方向 dst)。
列挙子 eltwise_logistic_use_dst_for_bwd
要素ごと: logistic (逆方向 dst)。
列挙子 eltwise_exp_use_dst_for_bwd
要素ごと: exponent (逆方向 dst)。
列挙子 lrn_across_channels
複数チャネル数のローカル応答正規化 (LRN)。
列挙子 lrn_within_channel
単一チャネルの LRN。
列挙子 pooling_max
最大プーリング。
列挙子 pooling_avg
パディングを除いた平均プーリング、dnnl::algorithm::pooling_avg_include_padding のエイリアス。
列挙子 pooling_avg_include_padding
パディング含む平均プーリング。
列挙子 pooling_avg_exclude_padding
パディングを除いた平均プーリング。
列挙子 vanilla_rnn
RNN セル。

5.5 プリミティブ

68

oneAPI 仕様 リリース 1.0 リビジョン 3
列挙子 vanilla_lstm
LSTM セル。
列挙子 vanilla_gru
GRU セル。
列挙子 lbr_gru
リセット前の線形 GRU セル。新しいメモリーゲートの計算方法は元の GRU とは異なります。
ct = tanh(Wc * xt +bcx +tt * (Uc * ℎt−1 + bcℎ ))LRB GRU は入力に 4 つのバイアステンソルを想定: [bu, br, bcx , bch]
列挙子 binary_add
バイナリー加算。
列挙子 binary_mul
バイナリー乗算。
列挙子 binary_max
バイナリー max。
列挙子 binary_min
バイナリー min。
列挙子 resampling_nearest
最近傍リサンプリング法。
列挙子 resampling_linear
線形 (双一次、三線形) リサンプリング法。
正規化プリミティブ・フラグ
enum dnnl::normalization_flags
正規化プリミティブのフラグ (「|」を介して組み合わせ可能)。
値:
列挙子 none
正規化フラグを使用しません指定されている場合、ライブラリーは訓練と推論の順方向伝搬で平均と分散を計算して、訓練の順方向伝搬で出力し、逆方向伝搬でそれぞれの導関数を計算します。
列挙子 use_global_stats
グローバル特性を使用します。指定されているとライブラリーは順方向伝搬の入力としてユーザーが提供する平均と分散を使用し、逆方向伝搬の導関数を計算しません。それ以外では、ライブラリーは訓練と推論の順伝搬で平均と分散を計算し、訓練の順伝搬でそれらを出力して逆方向伝搬でそれぞれの導関数を計算します。
列挙子 use_scale_shift
スケールとシフト・パラメーターを使用します。指定されていると、ユーザーは順方向伝搬の入力としてスケー
ルとシフトを渡すことが期待されます。dnnl::prop_kind::backward 型の逆方向伝搬では、ライブラリー
はそれらの導関数を計算します。指定されないと、スケールとシフト・パラメーターはライブラリーで使用されません。
列挙子 fuse_norm_relu
ReLU と正規化を融合します。訓練では、正規化にはワークスペースが逆方向伝搬を実装する必要があります。
推論にワークスペースは不要であり、その動作は正規化が post-op API を使用して ReLU と融合された場合と同じです。

5.5 プリミティブ

69

oneAPI 仕様 リリース 1.0 リビジョン 3
実行引数インデックス
DNNL_ARG_SRC_0
ソース引数 #0。
DNNL_ARG_SRC
単一ソースを持つプリミティブのソース引数における特殊ニーモニック。DNNL_ARG_SRC_0 のエイリアス。
DNNL_ARG_SRC_LAYER
RNN 入力ベクトルの特殊ニーモニック。DNNL_ARG_SRC_0 のエイリアス。
DNNL_ARG_FROM
リオーダーソース引数の特殊ニーモニック。DNNL_ARG_SRC_0 のエイリアス。
DNNL_ARG_SRC_1
ソース引数 #1。
DNNL_ARG_SRC_ITER
RNN 入力リカレント隠匿状態ベクトルの特殊ニーモニック。DNNL_ARG_SRC_1 のエイリアス。
DNNL_ARG_SRC_2
ソース引数 #2。
DNNL_ARG_SRC_ITER_C
RNN 入力リカレントセル状態ベクトルの特殊ニーモニック。DNNL_ARG_SRC_2 のエイリアス。
DNNL_ARG_DST_0
デスティネーション引数 #0。
DNNL_ARG_DST
単一デスティネーションを持つプリミティブのデスティネーション引数の特殊ニーモニック。
DNNL_ARG_TO
リオーダー・デスティネーション引数の特殊ニーモニック。DNNL_ARG_DST_0 のエイリアス。
DNNL_ARG_DST_LAYER
RNN 出力ベクトルの特殊ニーモニック。DNNL_ARG_DST_0 のエイリアス。
DNNL_ARG_DST_1
デスティネーション引数 #1。
DNNL_ARG_DST_ITER
RNN 入力リカレント隠匿状態ベクトルの特殊ニーモニック。DNNL_ARG_DST_1 のエイリアス。
DNNL_ARG_DST_2
デスティネーション引数 #2。
DNNL_ARG_DST_ITER_C
LSTM 出力リカレントセル状態ベクトルの特殊ニーモニック。DNNL_ARG_DST_2 のエイリアス。
DNNL_ARG_WEIGHTS_0
重み引数 #0。
DNNL_ARG_WEIGHTS
単一重み引数を持つプリミティブの特殊ニーモニック。DNNL_ARG_WEIGHTS_0 のエイリアス。
DNNL_ARG_SCALE_SHIFT
正規化プリミティブのスケールとシフト引数の特殊ニーモニック。
DNNL_ARG_WEIGHTS_LAYER
レイヤー入力に適用される RNN 重みの特殊ニーモニック。DNNL_ARG_WEIGHTS_0 のエイリアス。
DNNL_ARG_WEIGHTS_1
重み引数 #1。
DNNL_ARG_WEIGHTS_ITER
リカレント入力に適用される RNN 重みの特殊ニーモニック。DNNL_ARG_WEIGHTS_1 のエイリアス。
DNNL_ARG_BIAS
バイアステンソル引数。
DNNL_ARG_MEAN
平均値テンソル引数。
DNNL_ARG_VARIANCE
分散値テンソル引数。

5.5 プリミティブ

70

oneAPI 仕様 リリース 1.0 リビジョン 3
DNNL_ARG_WORKSPACE
ワークスペース・テンソル引数。ワークスペースは、順方向伝搬計算から逆方向伝搬計算に情報を渡すために使用されます。
DNNL_ARG_SCRATCHPAD
スクラッチパッド (一時ストレージ) テンソル引数。
DNNL_ARG_DIFF_SRC_0
ソース引数 #0 の勾配 (差分)。
DNNL_ARG_DIFF_SRC
単一重差分引数を持つプリミティブの特殊ニーモニック。
DNNL_ARG_DIFF_SRC_LAYER
RNN 入力ベクトルの勾配 (差分) の特殊ニーモニック。DNNL_ARG_DIFF_SRC_0 のエイリアス。
DNNL_ARG_DIFF_SRC_1
ソース引数 #1 の勾配 (差分)。
DNNL_ARG_DIFF_SRC_ITER
RNN 入力リカレント隠匿状態ベクトルの勾配 (差分) の特殊ニーモニック。DNNL_ARG_DIFF_SRC_1 のエイ
リアス。
DNNL_ARG_DIFF_SRC_2
ソース引数 #2 の勾配 (差分)。
DNNL_ARG_DIFF_SRC_ITER_C
RNN 入力リカレントセル状態ベクトルの勾配 (差分) の特殊ニーモニック。DNNL_ARG_DIFF_SRC_1 のエイ
リアス。
DNNL_ARG_DIFF_DST_0
デスティネーション引数 #0 の勾配 (差分)。
DNNL_ARG_DIFF_DST
単一差分デスティネーション引数を持つプリミティブの特殊ニーモニック。
DNNL_ARG_DIFF_DST_LAYER
RNN 出力ベクトルの勾配 (差分) の特殊ニーモニック。DNNL_ARG_DIFF_DST_0 のエイリアス。
DNNL_ARG_DIFF_DST_1
デスティネーション引数 #1 の勾配 (差分)。
DNNL_ARG_DIFF_DST_ITER
RNN 入力リカレント隠匿状態ベクトルの勾配 (差分) の特殊ニーモニック。DNNL_ARG_DIFF_DST_1 のエイ
リアス。
DNNL_ARG_DIFF_DST_2
デスティネーション引数 #2 の勾配 (差分)。
DNNL_ARG_DIFF_DST_ITER_C
RNN 入力リカレントセル状態ベクトルの勾配 (差分) の特殊ニーモニック。DNNL_ARG_DIFF_DST_2 のエイ
リアス。
DNNL_ARG_DIFF_WEIGHTS_0
重み引数 #0 の勾配 (差分)。
DNNL_ARG_DIFF_WEIGHTS
単一差分重み引数を持つプリミティブの特殊ニーモニック。
DNNL_ARG_DIFF_SCALE_SHIFT
正規化プリミティブのスケールとシフト差分引数の特殊ニーモニック。
DNNL_ARG_DIFF_WEIGHTS_LAYER
レイヤー入力に適用される RNN 重み差分の特殊ニーモニック。DNNL_ARG_DIFF_WEIGHTS_0 のエイリ
アス。
DNNL_ARG_DIFF_WEIGHTS_1
重み引数 #1 の勾配 (差分)。
DNNL_ARG_DIFF_WEIGHTS_ITER
リカレント入力に適用される RNN 重み差分の特殊ニーモニック。
DNNL_ARG_DIFF_BIAS
バイアステンソル引数の勾配 (差分)。

5.5 プリミティブ

71

oneAPI 仕様 リリース 1.0 リビジョン 3
DNNL_ARG_ATTR_OUTPUT_SCALES
実行時に適用される出力スケーリング係数。
DNNL_ARG_MULTIPLE_SRC
可変数のソース引数を受け取るプリミティブのソース引数の開始インデックス。
DNNL_ARG_MULTIPLE_DST
可変数のデスティネーション引数を生成するプリミティブのデスティネーション引数の開始インデックス。
DNNL_ARG_ATTR_ZERO_POINTS
実行時にゼロポイントが提供されます。
DNNL_RUNTIME_DIM_VAL
プリミティブ作成時の不明な次元のワイルドカード値。
DNNL_RUNTIME_SIZE_VAL
DNNL_RUNTIME_DIM_VAL に対 す る size_t。 例 え ば、 この 値 は次 元 また は ス トラ イ ド のい ずれ かが
DNNL_RUNTIME_DIM_VAL に等しい場合に dnnl::memory::desc::get_size() によって返されます。
DNNL_RUNTIME_F32_VAL
プリミティブ作成時の不明な浮動小数点値のワイルドカード値。
DNNL_RUNTIME_S32_VAL
プリミティブ作成時の不明な int32_t 値のワイルドカード値。

5.5.2 属性
プリミティブ記述子を作成する際に渡されるパラメーターは問題を指定します。エンジンは、プリミティブが実行される場所を指定します。操作記述子は、操作の種別、伝搬の種別、ソース、デスティネーション、およびその他のテンソル、ストライド (適用される場合) などを指定します。
属性ではプリミティブの追加プロパティーを指定します。ユーザーは使用する前にそれらを作成し、対応するセッターで必要な内容を設定する必要があります。属性はプリミティブ記述子の作成中にコピーされるため、ユーザーは作成直後に属性を変更または破棄できます。
変更しない場合、属性を空のまま維持することができ、これはデフォルト属性と同等となります。プリミティブ記述子のコンストラクターは、デフォルト・パラメーターとして空の属性を持っているため、必要な場合を除きユーザーは省略できます。
属性には、プリミティブの後に実行される計算である post-op を含めることもできます。
post-oppost-op は、プリミティブの後に追加される操作です。これは、属性メカニズムにより実装されます。複数の post-op
操作がある場合、追加された順番に実行されます。
post-op は、dnnl::post_ops と表記され、dnnl::primitive_attr::set_post_ops() 関数により属性にアタッチされると一度だけコピーされます。次に、属性を有効にするにはプリミティブ記述子作成関数に渡す必要があります。以下に例を示します。

5.5 プリミティブ

72

oneAPI 仕様 リリース 1.0 リビジョン 3
dnnl::post_ops po; // デフォルトの空の post-op
assert(po.len() == 0); // post-op はアタッチされていません
po.append_SOMETHING(params); // 特定の post-op を追加します
po.append_SOMETHING_ELSE(other_params); // さらに post-op を追加します// (!) post-op 操作が追加される順番が重要であることに注意してください！
assert(po.len() == 2);
dnnl::primitive_attr attr; // デフォルト属性
attr.set_post_ops(po); // post-op を属性にアタッチします// これ以降の po 変更は attr に格納されている値には影響しません
primitive::primitive_desc op_pd(params, attr); // attr で po を作成

注: 異なるプリミティブは異なる post-op をサポートします。さらに、サポートは実際のプリミティブの実装にも依存します。しかし、堅牢なコードはそれに応じてエラーを処理できるはずです。「属性に関連するエラー処理」を参照してください。
注: post-op は、操作対象のメモリー・オブジェクトのメモリー形式を変更することはありません。
post-op オブジェクトは、dnnl::post_ops::kind() 関数を使用して検査できます。この関数は post-op のイン
デックス (これは、dnnl::post_ops::len() が返す値より小さい必要があります) を取得して検査し、種別を返します。
サポート post-op
eltwise post-op (要素ごとの post-op)
eltwise post-op は 、 dnnl::post_ops::append_eltwise() 関 数 を 使 用 し て 追 加 さ れ ま す 。
dnnl::post_ops::kind() は、そのような post-op に対し dnnl::primitive::kind::eltwise を返します。
要素ごとの post-op は次の置換を行います。
置換前:

置換後:

Op(...) の中間結果は保持されません。

5.5 プリミティブ

73

oneAPI 仕様 リリース 1.0 リビジョン 3
scale 係数は、 int8 推論でのみサポートされます。それ以外では、scale は 1.0 である必要があります。
sum post-op (累積 post-op)
sum post-op は、プリミティブの結果を既存のデータと累積し、dnnl::post_ops::append_sum() 関数を使用して追加されます。dnnl::post_ops::kind() は、そのような post-op に対し dnnl::primitive::kind::sumを返します。
結果を累積する前に、既存の値に scale を掛けます。スケール・パラメーターは scale 係数で使用でき、int8 推論でのみサポートされており、結果と既存のデータサイズが異なる場合にのみ使用します。それ以外では、scale は 1.0 である必要があります。
さらに、sum post-op は、デスティネーション値を同じサイズの異なるデータ型として再解釈できます。例えば、8 ビッ
ト符号付きデータを符号なしとして再解釈、またはその逆に使用できます (値は共通範囲内にある必要があります)。
sum post-op は、次の置換を行います。
置換前:

置換後:

連鎖した post-op の例
post-op は、連続して追加することで連鎖させることができます。順番が重要であることに注意してください。post-op
は追加された順番で実行されます。
sum -> ReLU
このパターンは、ResNet ファミリーの CNN トポロジーでは一般的です。
dnnl::post_ops po;
po.append_sum(/* scale = */ 1.f);
po.append_eltwise(/* scale= */ 1.f,/* algorithm = */ dnnl::algorithm::eltwise_relu,/* neg slope = */ 0.f,/* ReLU では未使用 */ 0.f);
dnnl::primitive_attr attr;
attr.set_post_ops(po);convolution_forward::primitive_desc(conv_d, attr, engine);

5.5 プリミティブ

74

oneAPI 仕様 リリース 1.0 リビジョン 3
これにより次の計算が行われます。
dst[:] = ReLU(dst[:] + conv(src[:], weights[:])API
struct dnnl::post_ops
post-op。
post-op 操作はメインのプリミティブ計算後に実行される計算であり、プリミティブ属性を介してプリミティブにアタッチされます。
パブリック関数
post_ops()
post-op 操作の空のシーケンスを生成します。
int len() const
post-op のエントリー数を返します。
primitive::kind kind(int index) const
特定のインデックスを持つエントリーで post-op のプリミティブ種別を返します。
戻り値: 指定されたインデックスの post-op プリミティブの種別。
パラメーター• index: 種別を返す post-op のインデックス。
void
append_sum(float
scale
=
1.f,
memory::data_type
data_type=
memory::data_type::undef )累積 (sum post-op)を追加します。結果を累積する前に、既存の値に スケーリング係数 scale を掛けます。
この post-op の種別は dnnl::primitive::kind::sum です。
この機能により、畳み込みの結果がそれ以前に計算された活性化に累積される残余学習ブロックなどでパフォーマンスが向上する可能性があります。結果とそれ以前の活性化の論理スケーリング係数が異なる場合、
scale パラメーターを整数ベースの計算に使用できます。
累 積 が 唯 一 の post-op で あ る 最 も 単 純 な ケ ー ス で は 、 計 算 は dst[:] := op(...) で は な く 、dst[;] := scale * dst[:] + op(...) になります。
data_type が指定されている場合、元の dst テンソルは指定されたデータ型のテンソルとして再解釈されます。再解釈には、data_type と dst のデータ型は同じサイズである必要があります。結果として、計算はdst[:] <- op(...) ではなく、dst[:] <- scale * s_data_type(dst[:]) + op(...) になります。
注: この post-op はインプレースで実行され、デスティネーションのレイアウトは変更されません。

5.5 プリミティブ

75

oneAPI 仕様 リリース 1.0 リビジョン 3
パラメーター• scale: スケーリング係数。
• data_type: データ型。
void get_params_sum(int index, float &scale) const
累積 (sum) post-op のパラメーターを返します。
パラメーター• index: sum post-op のインデックス。
• scale: sum post-op のスケーリング係数。
void get_params_sum(int index, float &scale, memory::data_type &data_type) const
累積 (sum) post-op のパラメーターを返します。
パラメーター• index: sum post-op のインデックス。
• scale: sum post-op のスケーリング係数。
• data_type: sum post-op のデータ型。
void append_eltwise(float scale, algorithm aalgorithm, float alpha, float beta)
要素ごとの post-op を追加します。
この post-op の種別は dnnl::primitive::kind::eltwise です。
要素単位が唯一の post-op である最も単純なケースでは、計算は dst[:] := op(...) ではなく、
dst[;] := scale * eltwise_op ((...)) になります。ここで、eltwise_op は指定されたパラメー
ターで構成されます。
パラメーター• scale: スケーリング係数。
• aalgorithm: 要素ごとのアルゴリズム。
• alpha: 要素ごとのアルゴリズムのアルファ・パラメーター。
• beta: 要素ごとのアルゴリズムのベータ・パラメーター。
void get_params_eltwise(int index, float &scale, algorithm &aalgorithm, float&alpha, float &beta) const
要素ごとのポストアップ・パラメーターを返します。
パラメーター• index: post-op のインデックス。
• scale: 出力スケーリング係数。
• aalgorithm: 出力要素ごとのアルゴリズムの種類。
• alpha: 要素ごとのアルゴリズムの出力アルファ・パラメーター。
• beta: 要素ごとのアルゴリズムの出力ベータ・パラメーター。

5.5 プリミティブ

76

oneAPI 仕様 リリース 1.0 リビジョン 3
スクラッチパッド・モード
一部のプリミティブには、計算の実行中に一時バッファーを必要とするものがあります。例えば、システムのすべてのコ
アを利用するのに十分な独立したワークがない操作では、リダクション次元 (GEMM 表記の K 次元) で並列化を行う場
合があります。この場合、異なるスレッドがプライベートな一時バッファーで部分計算を行い、プライベートな結果がマージされ最終的な結果が生成されます。もう 1 つの例は、行列乗算 (GEMM) による畳み込みの実装です。GEMM を呼び出す前に、im2col 操作を使用してソース活性化を変換する必要があります。変換結果は一時バッファーに格納され、GEMM の入力として使用されます。
これら両方でプリミティブ計算が完了すると、一時バッファーは不要になります。oneDNN はスクラッチパッドなどのメ
モリーバッファーを参照します。
どちらのタイプの実装でも、独立したタスクが少ない場合に備えて、リダクションのため追加スペースが必要になることがあります。im2col 変換に必要なメモリー容量は、ソースイメージのサイズに重みの空間サイズを掛けたものに比例します。
リダクション・バッファーのサイズは、縮小するテンソルサイズ (例えば、重み逆方向の場合は diff_weights) にリダ
クション・グループ内のスレッド数 (上限はスレッドの総数) を掛けたものに比例します。
対照的に、他のプリミティブでは余分なスペースをほとんど使用しません。例えば、dnnl::sum プリミティブの実装の 1
つでは、すべての入力配列データへのポインターを格納する場合にのみ、一時スペースを必要とします (つまり、スクラッ
チパッドのサイズは n * sizeof(void *) です。n は被加数の数)。
oneDNN はスクラッチパッドを操作する 2 つのモードをサポートします。
enum dnnl::scratchpad_mode
スクラッチパッド・モード。
値:
列挙子 library
ライブラリーはスクラッチパッドの割り当てを管理します。この仕様で定義されていないメカニズムを使用して構成可能な実装固有のポリシーが複数存在することがあります。
列挙子 userユーザーは、スクラッチパッド・メモリーを照会して、プリミティブに提供することでスクラッチパッドの割り当てを管理します。このモードは、スクラッチパッド・バッファーが 2 つのプリミティブの実行によって同時に使用されない限りスレッドセーフです。
スクラッチパッド・モードは、dnnl::primitive_attr::set_scratchpad_mode() プリミティブ属性を使用して制御されます。
ユーザーがスクラッチパッド・メモリーをプリミティブに提供する場合、このメモリーはプリミティブが使用するエンジンと同じエンジンで作成する必要があります。
すべてのプリミティブは両方のスクラッチパッド・モードをサポートします。

5.5 プリミティブ

77

oneAPI 仕様 リリース 1.0 リビジョン 3
注: プリミティブは、デフォルトではスレッドセーフではありません。スクラッチパッドの実行をスレッドセーフにする唯一の方法は、dnnl::scratchpad_mode::user モードを使用して同時に実行される 2 つのプリミティブに同じ
スクラッチパッド・メモリーを渡さないことです。
例
スクラッチパッドを管理するライブラリー
上記に示すように、これはデフォルトの動作です。スクラッチパッドによりプリミティブが消費するメモリー量をユーザーが紹介する方法を示します。
// デフォルトの attr を使用するため、ライブラリーはスクラッチパッドを割り当てます
dnnl::primitive::primitive_desc op_pd(params, /* 他の引数 */);// スクラッチパッドによりプリミティブが保持するメモリー量を出力
std::cout << "primitive will use "<< op_pd.query_s64(dnnl::query::memory_consumption_s64)<< " bytes" << std::endl;// スクラッチパッドは内部にあるため、ユーザーに表示されるスクラッチパッドのメモリー記述子は空でなければなりません
auto zero_md = dnnl::memory::desc();

ユーザー管理のスクラッチパッド// 空 (デフォルト) の属性を作成
dnnl::primitive_attr attr;// デフォルトのスクラッチパッド・モードは library:assert(attr.get_scratchpad_mode() == dnnl::scratchpad_mode::library);// スクラッチパッド・モードを `user に設定
attr.set_scratchpad_mode(dnnl::scratchpad_mode::user);// カスタム属性でプリミティブ記述子を作成
dnnl::primitive::primitive_desc op_pd(op_d, attr, engine);// スクラッチパッド・メモリー記述子を照会
dnnl::memory::desc scratchpad_md = op_pd.scratchpad_desc();// この構成ではプリミティブはメモリーを消費しないことに注意
assert(op_pd.query_s64(dnnl::query::memory_consumption_s64) == 0);// プリミティブを作成
dnnl::primitive prim(op_pd);// ... コードを記述 ...

(次のページへ続く)

5.5 プリミティブ

78

oneAPI 仕様 リリース 1.0 リビジョン 3(前のページの続き)// スクラッチパッド・メモリーを作成// 注: プリミティブにスクラッチパッドが必要ない場合、scratchpad_md.get_size() は 0 を返します。
// この場合、scratchpad_ptr == nullptr を使用しても問題ありません。
void *scratchpad_ptr = user_memory_manager::allocate(scratchpad_md.get_size());// 注: このエンジンは、複数のプリミティブのエンジンである必要があります
dnnl::memory scratchpad(scratchpad_md, engine, scratchpad_ptr);// プリミティブへスクラッチパッド・メモリーを渡します
prim.execute(stream, { /* 他の引数 */,{DNNL_ARG_SCRATCHPAD, scratchpad}});量子化
プリミティブは、量子化を必要とする低精度の計算をサポートする場合があります。
量子化モードライブラリーが想定する主な量子化モデルを次に示します。
xf32[:] = scalef32 · (xint8[:] - 0x int8 )ここで、scaleｆ32 は事前に判明しているスケーリング係数であり、[:] は配列への式を要素ごとに適用することを示します。通常、スケーリング係数を計算する処理はキャリブレーションと呼ばれます。ライブラリーは、実行時に動的にスケール係数を計算することはできません。そのため、このモデルは静的量子化モデルと呼ばれることがあります。静的量子化モデルをサポートする理由は、パフォーマンスを向上のためです。動的量子化を使用するには、次の処理を行います。
1.
2.
3.

dnnl::memory::data_type::s32 のように、高い精度で結果を計算します。
最小値や最大値などの特性を検出して、スケール係数を導きます。
低い精度のデータ型に再量子化します。

oneDNN は固定のゼロポジションを想定します。ほとんどのプリミティブでは、実際のゼロ値は量子化されたゼロ値にマップされます。つまり、0xint8 = 0 です。例えば、これは畳み込みと逆畳み込みおよび内積が現在サポートしている唯一のモデルです。RNN プリミティブは、シフトされたゼロのサポートが制限されています。
このセクションの残りでは、0xint8 = 0 です。
例: 畳み込み量子化のワークフロー
バイアスなしの畳み込みを考えてみます。テンソルは次のように表現されます。

ここで、srcf32、weightsf32、dstf32 は計算されておらず、ワーク全体が int8 テンソルになります。前述のように、すべてのスケール係数 (scale_{src}、scale_{weights}、scale_{dst}) は判明しています。

5.5 プリミティブ

79

oneAPI 仕様 リリース 1.0 リビジョン 3
したがって、ここでのタスクは dstint8 テンソルを計算することです。数学的には次のように計算します。
dstint8[:]= f32_to_int8(output_scale · convf32(srcint8, weightsint8))
説明:•• convf32 は、int8 データ型でソースと重みを取得し、結果を int32 データ型で計算する通常の畳み込みです(int32 は計算中のオーバーフローを回避するために使用されます)。
• f32_to_s8() は、値が int8 データ型の範囲外にある場合、f32 値を飽和状態で s8 に変換します。
操作を実行するためすべてのテンソルの正確なスケール係数を知る必要はありません。output_scale のみ知っていれば十分です。ライブラリーはこれを利用します。ユーザーは 1 つの追加パラメーターのみを畳み込みプリミティブに渡す必要があります (以下の「出力スケーリング属性」を参照してください)。
チャネルごとのスケーリング
プリミティブは、量子化テンソルの複数スケールのサポートが制限されていることがあります。最も一般的な使い方は、
重み出力チャネルごとのスケーリング係数をサポートする畳み込みと逆畳み込みプリミティブです。実際の畳み込み計
算では、異なる出力チャネルに異なるスケーリングを行う必要があります。
以下にスケールを示します。

ここで、weights’ スケーリング係数は oc 依存であることに注意してください。
dstint8 を計算するには、以下を行う必要があります。
dstint8(n, oc, oℎ, ow) = f32_to_int8(output_scale(oc)·convs32(srcint8, weightsint8)|(n,oc,oℎ,ow))
説明:

ユーザーは、それぞれに量子化された重みを用意する必要があります。そのため、oneDNN ではチャネルごとのスケーリングを行う並べ替えが提供されています。
weightsint8(oc, ic, kℎ, kw) = f32_to_int8(output_scale(oc) · weightsf32(oc, ic, kℎ, kw))

5.5 プリミティブ

80

oneAPI 仕様 リリース 1.0 リビジョン 3
説明:

出力スケーリング属性
oneDNN では、ほとんどのプリミティブのスケーリング係数を設定するため dnnl::primitive_attr::set_output_scales()を提供します。
ソース (と重み) テンソルが int8 データ型でない場合、プリミティブは出力スケールをサポートしないことがあります。
つまり、単精度浮動小数点データ型で動作する畳み込みは、出力結果がスケールしない場合があるということです。
最も単純なケースとして、共通のスケールが 1 つのみである場合、属性は操作の動作を次のように置換します。
置換前:
dst[:] = Op(...)
置換後:
dst[:]= scale · Op(...)
1 つまたは複数の次元ごとのスケールをサポートするため、ユーザーは適切なマスクを設定する必要があります。
プリミティブのデスティネーションが、D0 × ...× Dn−1 テンソルで、di 次元ごとの出力スケールが必要であるとします(ここでは 0 ≤ di < n)。
であり、スケール数はである必要があります。
�

スケーリングは単精度浮動小数点データ型 (dnnl::memory::data_type::f32) で行われます。保存する前に、必要に応じて結果は飽和したデスティネーションのデータ型に変換されます。丸めはハードウェアの設定に従って行われます。
例 1: 出力チャネルとグループごとのスケーリングによる重みの量子化// 重み次元
const int G, OC, IC, KH, KW;// プレーン形式のオリジナルの f32 重み
dnnl::memory::desc wei_plain_f32_md({G, OC/G, IC/G, KH, KW},
dnnl::memory::data_type::f32,
dnnl::memory::format_tag::hwigo);// dims// オリジナルの f32 データ// プレーンメモリー形式(次のページへ続く)

5.5 プリミティブ

81

oneAPI 仕様 リリース 1.0 リビジョン 3(前のページの続き)// 量子化された重みのスケーリング係数// 各グループと出力チャンネルで固有のスケール。
std::vector<float> wei_scales(G * OC/G) = { /* 値 */ };// int8 畳み込みプリミティブ記述子
dnnl::convolution_forward::primitive_desc conv_pd(/* 次の例を参照 */);// 畳み込み重みメモリー記述子を照会
dnnl::memory::desc wei_conv_s8_md = conv_pd.weights_desc();// 逆スケールを準備// (f32 = scale * int8 --> int8 = 1/scale * f32)
std::vector<float> inv_wei_scales(wei_scales.size());
for (size_t i = 0; i < wei_scales.size(); ++i)
inv_wei_scales[i] = 1.f / wei_scales[i];// リオーダーの属性を準備
dnnl::primitive_attr attr;
const int mask = 0| (1 << 0)// dim #0 の G 次元ごとのスケール| (1 << 1);// dim #1 の OC 次元ごとのスケール
attr.set_output_scales(mask, inv_wei_scales);// 実行するリオーダーを作成:// wei_s8(g, oc, ic, kh, kw) <- 1/scale(g, oc) * wei_f32(g, oc, ic, kh, kw)// データ形式の変換を含む。
auto wei_reorder_pd = dnnl::reorder::primitive_desc(
wei_plain_f32_md, engine, // ソース
wei_conv_s8_md, engine, // デスティネーション,attr);
auto wei_reorder = dnnl::reorder(wei_reorder_pd);

例 2: 出力チャネルごとの量子化を使用したグループによる畳み込み
この例は、前述の例 (理想的には最初の例) を補完するものです。出力ごとのチャネルのスケーリングにより、int8 畳み込みを行うことを想定します。
const float src_scale; // src_f32[:] = src_scale * src_s8[:]
const float dst_scale; // dst_f32[:] = dst_scale * dst_s8[:]// 量子化された重みのスケーリング係数 (上記で宣言)// 各グループと出力チャンネルで固有のスケール。
std::vector<float> wei_scales(G * OC/G) = {...};// 畳み込み src、weights、および dst メモリー記述子、// メモリー形式タグ = any を使用して、畳み込み実装が適切な// メモリー形式を選択できるようにします。

(次のページへ続く)

5.5 プリミティブ

82

oneAPI 仕様 リリース 1.0 リビジョン 3(前のページの続き)
dnnl::memory::desc src_conv_s8_any_md({BATCH, IC, IH, IW},
dnnl::memory::data_type::s8,// 次元// オリジナルの s8 データ

dnnl::memory::format_tag::any // 畳み込みを選択);
dnnl::memory::desc wei_conv_s8_any_md({G, OC/G, IC/G, KH, KW},// 次元

dnnl::memory::data_type::s8,// オリジナルの s8 データ

dnnl::memory::format_tag::any);// 畳み込みを選択

dnnl::memory::desc dst_conv_s8_any_md(...);// 同上// 操作の記述子を作成
dnnl::convolution_forward::desc conv_d(
dnnl::prop_kind::forward_inference,
dnnl::algorithm::convolution_direct,
src_conv_s8_any_md,// 重要なことは、
wei_conv_s8_any_md,//

s8 で計算が必要である

dst_conv_s8_any_md,// ことを指定することですstrides, padding_l, padding_r, dnnl::padding_kind::zero);// 畳み込みの属性を準備
dnnl::primitive_attr attr;
const int mask = 0| (1 << 1);// dst テンソル用の dim #1 次元である OC 次元ごとのスケール
出力スケールと post-op の相互作用// (BATCH, OC, OH, OW)
//
0
1
2
3
一般に、post-op
は出力スケールとは独立しています。出力スケールは最初に結果に適用され、その後 post-op が有
std::vector<float> conv_output_scales(G * OC/G);
効になります。
for (int g_oc = 0; G * OC/G; ++g_oc)
conv_output_scales[g_oc] = src_scale * wei_scales(g_oc) / dst_scale;

これは、ライブラリーに渡されるスケーリング係数に影響します。tanh
post-op を使用する畳み込みを考えてみます。
attr.set_output_scales(mask, conv_output_scales);// スケーリング係数を使用して、畳み込みプリミティブ記述子を作成します
auto conv_pd = dnnl::convolution_forward::primitive_desc(
conv_d,// 一般的な (カスタマイズされていない) 操作記述子• 畳み込み出力スケールは
conv_output_scale = scalesrc ・ scaleweights であり、scaledst によ
attr,// 属性には出力スケーリングが含まれます
る除算はありません。
engine);• また、tanh post-op スケールはに設定されています。

エラー処理に関連する属性
属性は対応するプリミティブ記述子とは別に作成されるため、整合性チェックは遅延します。ユーザーは必要な構成の属性を適切に設定できます。ただし、設定した属性でプリミティブ記述子を作成しようとすると、その構成をサポートする
プリミティブ実装が存在しないことがあります。その場合、ライブラリーは dnnl::error 例外をスローします。

5.5 プリミティブ

83

oneAPI 仕様 リリース 1.0 リビジョン 3APIstruct dnnl::primitive_attr
プリミティブの属性。
パブリック関数primitive_attr()
デフォルト (空) のプリミティブ属性を構築します。
scratchpad_mode get_scratchpad_mode() const
スクラッチパッド・モードを返します。
void set_scratchpad_mode(scratchpad_mode mode)
スクラッチパッド・モードを設定します。
パラメーター• mode: 指定されたスクラッチパッド・モード。
void get_output_scales(int &mask, std::vector<float> &scales) const
出力スケーリング係数の対応するマスクと値を返します。
パラメーター• mask: 出力テンソル次元とスケールベクトル間の対応を定義するスケーリング係数に対応するマスク。設定される i 番目のビットは、その次元の各インデックス専用の出力スケーリング係数が使用されることを意味します。マスク値 0 は、出力テンソル全体で共通の出力スケーリング係数となります。
• scales: 出力スケーリング係数のベクトル。
void set_output_scales(int mask, const std::vector<float> &scales)
出力スケーリング係数の対応するマスクと値を設定します。
使用例:
int mb = 32, oc = 32,
oh = 14, ow = 14; // 畳み込み出力パラメーター// 出力チャンネルごとに固有な出力スケール
vector<float> scales = { ...};
int oc_dim = 1; // mb_dim = 0, channel_dim = 1, height_dim = 2, ...
// 畳み込み記述子を作成
dnnl::convolution::desc conv_d;
dnnl::primitive_attr attr;
attr.set_output_scales(attr, oc, 1 << oc_dim, scales);
dnnl::primitive_desc conv_pd(conv_d, attr, engine);

5.5 プリミティブ

84

oneAPI 仕様 リリース 1.0 リビジョン 3
注: 次元の順番は、要素がメモリー上でどのように配置されているかに依存しません。以下に例を示します。
• ２D CNN 活性化テンソルの場合、順番は常に (n, c) です。
• 4D CNN 活性化テンソルの場合、順番は常に (n, c, h, w) です。
• 5D CNN 重みテンソルの場合、順番は常に (g, oc, ic, kh, kw) です。
パラメーター• mask: 出力テンソル次元と scales ベクトル間の対応を定義します。設定される i 番目のビットは、その次元の各インデックス専用のスケーリング係数が使用されることを意味します。マスク値を 0 に設定すると、出力テンソル全体で共通の出力スケーリング係数となります。
• scales: 出力スケーリング係数の定数ベクトル。呼び出し時点でスケーリング係数が判明している
場合、次の式が成り立つ必要があります。

違反は属性を使用してプリミティブ記述子を作成する時にのみ検出できます。呼び出し時にスケーリング
係数が不明である場合、ベクトルには単一の DNNL_RUNTIME_F32_VAL 値が含まれている必要があり、出力スケーリング係数は実行時にインデックス DNNL_ARG_ATTR_OUTPUT_SCALES の引数として渡される必要があります。
void get_scales(int arg, int &mask, std::vector<float> &scales) const
指定されたメモリー引数のスケーリング係数に対応するマスクと値を返します。
パラメーター• arg: primitive::execute() 呼び出しに渡されるパラメーター引数インデックス。
• mask: 出力テンソル次元と scales ベクトル間の対応を定義するスケーリング係数に対応するマスク。設定される i 番目のビットは、その次元の各インデックス専用のスケーリング係数が使用されることを意味します。マスク値を 0 に設定すると、出力テンソル全体で共通の出力スケーリング係
数となります。
• scales: スケーリング係数の出力ベクトル。
void set_scales(int arg, int mask, const std::vector<float> &scales)
特定のメモリー引数のプリミティブ操作のスケーリング係数を設定します。
参照: dnnl::primitive_attr::set_output_scales
パラメーター• arg: primitive::execute() 呼び出しに渡されるパラメーター引数インデックス。
• mask: テンソル次元と scales ベクトル間の対応を定義するスケーリング係数に対応するマスク。
設定される i 番目のビットは、その次元の各インデックス専用のスケーリング係数が使用されることを意味します。マスク値を 0 に設定すると、出力テンソル全体で共通の出力スケーリング係数となります。

5.5 プリミティブ

85

oneAPI 仕様 リリース 1.0 リビジョン 3• scales: スケーリング係数の定数ベクトル。次の式が成り立つ必要があります。

void get_zero_points(int arg, int &mask,
const
ゼロポイントに対応するマスクと値を返します。

std::vector<int32_t>&zero_points)

パラメーター• arg: primitive::execute() 呼び出しに渡されるパラメーター引数インデックス。
• mask: 出力テンソル次元と zero_points ベクトル間の対応を定義するゼロポイントに対応するマスク。設定される i 番目のビットは、その次元の各インデックス専用のゼロポイントが使用されることを意味します。マスク値を 0 に設定すると、出力テンソル全体で共通のゼロポイントとなります。
• zero_points: ゼロポイントの出力ベクトル。
void set_zero_points(int arg, int mask, const std::vector<int32_t> &zero_points)指定されたメモリー引数のプリミティブ操作にゼロポイントを設定します。
参照: dnnl::primitive_attr::set_output_scales
パラメーター• arg: primitive::execute() 呼び出しに渡されるパラメーター引数インデックス。
• mask: テンソル次元とゼロポイント・ベクトル間の対応を定義するゼロポイントに対応するマスク。
設定される i 番目のビットは、その次元の各インデックス専用のゼロポイントが使用されることを意味します。マスク値を 0 に設定すると、出力テンソル全体で共通のゼロポイントとなります。
• zero_points: ゼロポイントの定数ベクトル。呼び出し時点でゼロポイントが判明している場合、次の式が成り立つ必要があります。

呼び出し時にゼロポイントが不明である場合、ベクトルには単一の DNNL_RUNTIME_F32_VAL 値が含まれている必要があり、ゼロポイントは実行時にインデックス DNNL_ARG_ATTR_ZERO_POINTS の引数として渡される必要があります。
const post_ops get_post_ops() const
set_post_ops() を介して設定された post-op を返します。
戻り値: post-op。
void set_post_ops(const post_ops ops)
post-op を設定します。
注: post-op がターゲット・プリミティブによってサポートされているか確認する方法はありません。エラーは、
プリミティブ記述子のコンストラクターによって報告されます。

5.5 プリミティブ

86

oneAPI 仕様 リリース 1.0 リビジョン 3

パラメーター• ops: post-op のコピー元になる post-op オブジェクト。
void set_rnn_data_qparams(float scale, float shift)
RNN データテンソルの量子化スケールとシフト・パラメーターを設定します。
パフォーマンスの観点から、低い精度の RNN プリミティブ構成では、入力活性化に符号なし 8 ビット整数
データ型を使用する必要があります。scale と shift パラメーターは、浮動小数点データを符号なしの整数型に量子化する際に使用され、属性によって RNN プリミティブに渡す必要があります。
量子化式は scale * (data + shift) です。
使用例:// RNN パラメーター
int l = 2, t = 2, mb = 32, sic = 32, slc = 32, dic = 32, dlc = 32;// 活性化量子化パラメーター
float scale = 2.0f, shift = 0.5f;
primitive_attr attr;// 活性化 int8 量子化の scale と shift を設定します。
attr.set_rnn_data_qparams(scale, shift);// rnn op_desc を作成して構成します
vanilla_rnn_forward::desc rnn_d(/* arguments */);
vanilla_rnn_forward::primitive_desc rnn_d(rnn_d, attr, engine);

注: 量子化 scale と shift は、src_layer、src_iter、dst_iter、および dst_layer では一般的です。
パラメーター• scale: データをスケールする値。
• shift: データをシフトする値。
void set_rnn_weights_qparams(int mask, const std::vector<float> &scales)
RNN 重みテンソルの量子化スケーリング係数を設定します。低い精度の RNN プリミティブ構成では、入力の重みが符号付き 8 ビット整数データ型であることを想定します。スケーリング係数は、浮動小数点データを符
号付き整数型に量子化する際に使用され、属性によって RNN プリミティブに渡す必要があります。
注: 次元の順番は、常にネイティブであり実際のレイアウトには依存しません。例えば、5 次元の重みには、常に(l, d, i, g, o) の論理的な次元の順番があります。
注: 量子化スケールは、weights_layer と weights_iteration では一般的です。

5.5 プリミティブ

87

oneAPI 仕様 リリース 1.0 リビジョン 3
パラメーター• mask: 出力テンソル次元と scales ベクトル間の対応を定義するスケーリング係数に対応するマスク。設定される i 番目のビットは、その次元の各インデックス専用のスケーリング係数を使用する必要があることを意味します。マスク値を 0 に設定すると、出力テンソル全体で共通の出力スケー
リング係数となります。
• scales: 出力スケーリング係数の定数ベクトル。次の式が成り立つ必要があります。

違反は、属性を使用してプリミティブ記述子を作成する場合にのみ検出できます。

5.5.3 バッチ正規化
バッチ正規化プリミティブは、次元数が 2 以上のテンソルに対して順方向または逆方法のバッチ正規化操作を実行します。変数名は標準規則に従います。
バッチ正規化操作は、次の式で定義されます。高次元と低次元のケースでは、一般化が容易な 2D 空間データの式のみを示します。
プリミティブのさまざまな振る舞いは、dnnl::batch_normalization_forward::desc::desc() などの操作
記述子の初期化関数に渡されるフラグ・パラメーターで制御できます。複数のフラグはビットごとの OR 演算子 (|) を使用して組み合わせることができます。
前方 (順方向)説明:• γ(ｃ) と β(c) は、チャネルのオプションの scale と shift です (use_scaleshift フラグで制御)、• μ(c) と δ2() は、チャネルの平均と分散であり (use_global_stats フラグで設定)、• ε は数値の安定性を向上させる定数です。
平均と分散は実行時に計算されるか、ユーザーによって提供されます。平均と分散を実行時に計算する場合、次の式が使用されます。

γ(ｃ) と β(c) テンソルは学習可能であると見なされます。

5.5 プリミティブ

88

oneAPI 仕様 リリース 1.0 リビジョン 3
訓練モードでは、プリミティブはオプションであり、結果にゼロの負の勾配が適用された ReLU 活性化との融合もサポートされます (fuse_norm_relu フラグを参照)。
注

バッチ正規化プリミティブは、母平均と分散を計算しますが、移動平均と分散の計算には一般に使用されるサンプ
ルやバイアスがないバージョンは計算されません。* バッチ正規化プリミティブによって計算された平均と分散を使用して、移動平均と分散 μ ˆi と δ ˆ2 (i は反復回数) は、次のように計算できます。

順方向訓練と順方向推論の違い• 平均と分散が実行時に計算される場合 (つまり use_global_stats が設定されていない場合)、それらは伝 搬 種 別 forward_training の 出 力 と な り ( 逆 伝 搬 で 必 要 と な り ま す ) 、 伝 搬 種 別
forward_inference には提供されません。
• バ ッ チ 正 規 化 が ReLU 融 合 で 作 成 さ れ る (fuse_norm_relu が 設 定 さ れ る ) 場 合 、 伝 搬 種 別 がforward_training であると、プリミティブは追加出力として workspace メモリーを生成します。このメモリーは逆伝搬を計算する際に必要です。プリミティブが伝搬種別 forward_inference で実行されると、ワークスペースは生成されません。この動作は、post-op として ReLU を使用したバッチ正規化プリミティ
ブを作成するのと同様です (以下のセクションを参照)。
逆方向 (後方)逆伝搬は、diff_dst(n, c, ℎ , w)、src(n, c, ℎ , w)、 μ (c)、 δ 2(c)、 γ (c)*、および β (c)* に基づいて、
diff_src(n, c, ℎ, w)、diff_γ(c)*、および diff_β(c)* を計算します。
アスタリスク (*) で示さ れるテンソルは、 プリミティブが γ (c) および β (c) を使用するように構成されてい る(use_scaleshiftis が設定されている) 場合にのみ使用されます。

5.5 プリミティブ

89

oneAPI 仕様 リリース 1.0 リビジョン 3
実行引数
フラグと伝搬の種別に応じて、バッチ正規化プリミティブには異なる入力 (In) と出力 (Out) が必要です。以下に要約します。
forward_infer

efnocreward_trainin gbackward

backward_data

In: src
Out: dst

In: src
Out: dst、μ、δ2

In: diff_dst、src、μ、δ2
Out: diff_src

backward と同じ

use_global_stats In: src、μ、δ2
Out: dst

In: src、μ、δ2
Out: dst

In: diff_dst、src、μ、δ2
Out: diff_src

backward と同じ

use_scaleshift

In: src、γ、βOut: dst、μ、δ2

In: diff_dst、src、μ、δ2、 未サポート
γ、βOut: diff_src、diff_γ、
diff_βIn: src、μ、δ2、γ、βOut: dst

In: diff_dst、src、μ、δ2、 未サポート
γ、βOut: diff_src, diff_γ、
diff_βnone

In: src、γ、βOut: dst

use_global_stats In: src、μ、δ2、γ、β| use_scaleshift Out: dst

flags |
fuse_norm_relu

In: flags と同じ
In: flags と同じ
Out: flags と同じ Out: flags、workspaceと同じ

In: flags、workspace と同じ
Out: flags と同じ

flags に
use_scaleshift が含
まれない場合、backwardと同じ
それ以外は未サポート

実行時に入力と出力は、次の表で示す実行引数インデックスにマップする必要があります。
プリミティブの入力/出力

実行引数インデックス

Src

DNNL_ARG_SRC

γ、βDNNL_ARG_SCALE_SHIFT

mean (μ)

DNNL_ARG_MEAN

variance (δ)

DNNL_ARG_VARIANCE

Dst
workspace

DNNL_ARG_DST

diff_dst

DNNL_ARG_DIFF_DST

diff_src

DNNL_ARG_DIFF_SRC

diff_γ、diff_β

DNNL_ARG_DIFF_SCALE_SHIFTDNNL_ARG_WORKSPACE

操作の詳細
1.

2.

順伝搬の場合、平均と分散は実行時に計算 (プリミティブの出力として) されるか、ユーザーによって提供されます (入力として)。ユーザーが提供する場合、use_global_stats フラグを設定する必要があります。逆伝搬の場合、平均と分散は常に入力パラメーターとなります。
src と dst のメモリー形式とデータ型は同一であると想定され、API ではデータとして参照されます(dnnl::batch_normalization_forward::desc::desc() の data_desc を参照)。
diff_src と diff_dst にも同じことが当てはまります。対応するメモリー記述子は
diff_data_desc と呼ばれます。

5.5 プリミティブ

90

oneAPI 仕様 リリース 1.0 リビジョン 33.

4.

順方向と逆方向の両方でインプレース操作がサポートされ、src は順方向伝搬の入力および出力として使用でき、diff_dst は逆伝搬の入力および出力として使用できます。インプレースの場合、元のデータは上書きされます。ただし、逆伝搬では元の src が必要であるため、対応する順伝搬をインプレースで実行してはなりません。
前述のように、バッチ正規化プリミティブは、訓練モードでも ReLU 活性化と融合できます。この場合、順方向伝搬では、プリミティブに 1 つの追加出力と workspace があり、逆方向伝搬に渡される必要があります。

サポートされるデータ型
操作は次のデータ型の組み合わせをサポートします。
注: この節では、可読性のためデータ型の名称を省略しています。例えば、dnnl::memory::data_type::f32 は、
f32 に省略されます。
伝搬

ソース/デスティネーション

順方向/逆方向
順方向

f32、bf16
f16

順方向

s8

平均/分散/スケールシフト
f32
f32
f32

データ表現
ソース、デスティネーション、およびそれらの勾配
他の CNN プリミティブと同様に、バッチ正規化プリミティブでは、データが N × C × SPn × · · · × SP0 テンソルであることを想定します。バッチ正規化プリミティブは次のメモリー形式に最適化されています。
空間

論理テンソル

0D

NC

メモリー形式向けに最適化された実装
nc(ab)

1D

NCW

ncw (abc)、nwc(acb)、最適化済み

2D

NCHW

nchw (abcd)、nhwc(acdb)、最適化済み

3D

NCDHW

ncdhw (abcde)、ndhwc(acdeb)、最適化済み

ここでいう最適化とは、前述の計算集約型プリミティブによって選択された形式を意味します。
統計テンソル
平均 (μ) と分散 (δ2) は、異なるサイズの 1D テンソルです。対応するメモリー・オブジェクトの形式は x (a) である
必要があります。
使用する場合、スケール (γ) とシフト (β) は、形状 2 × C の単一 2D テンソルに結合されます。
対応するメモリー・オブジェクトの形式は nc(ab) である必要があります。

5.5 プリミティブ

91

oneAPI 仕様 リリース 1.0 リビジョン 3
post-op と属性
伝搬
順方向

型
post-op

操作

説明

要素ごと

要素ごとの操作を出力に適用します。

注: post-op として ReLU を使用しても、逆伝搬を正しく計算するために必要な出力はワークスペースに生成されません。そのため、訓練には fuse_norm_relu フラグを使用する必要があります。
API
struct dnnl::batch_normalization_forward: public dnnl::primitive
バッチ正規化順伝搬プリミティブ。
パブリック関数
batch_normalization_forward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
batch_normalization_forward(constprimitive_desc &pd)
バッチ正規化順伝搬プリミティブを構築します。
パラメーター• pd: バッチ正規化順伝搬プリミティブのプリミティブ記述子。
struct desc
バッチの正規化順伝搬プリミティブの記述子。
パブリック関数desc(prop_kind aprop_kind, const memory::desc
normalization_flags flags)
順伝搬向けのバッチ正規化記述子を構築します。

&data_desc,

float

epsilon,

注: インプレース操作がサポートされ、dst は src と同じメモリーを参照できます。
パラメーター• aprop_kind: 伝搬の種類。可能な値は、dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• data_desc: ソースとデスティネーション・メモリー記述子。
• epsilon: バッチ正規化イプシロン・パラメーター。
• flags: バッチ正規化フラグ (dnnl::normalization_flags)。
struct primitive_desc: public dnnl::primitive_desc
バッチ正規化順伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。

5.5 プリミティブ

92

oneAPI 仕様 リリース 1.0 リビジョン 3
primitive_desc(const desc &adesc, const engine &aengine,
false)
バッチの正規化順伝搬プリミティブのプリミティブ記述子を構築します。

bool

allow_empty=

パラメーター• adesc: バッチ正規化順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine, bool allow_empty = false)
バッチ正規化順伝搬プリミティブのプリミティブ記述子を構築します。

&attr,

const

engine

パラメーター• adesc: バッチ正規化順伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc weights_desc() const
重みメモリー記述子を返します。
戻り値: 重みメモリー記述子。
戻り値: プリミティブに重みパラメーターがない場合は、ゼロメモリー記述子。
memory::desc workspace_desc() const
ワークスペース・メモリー記述子を返します。
戻り値: ワークスペース・メモリー記述子。

5.5 プリミティブ

93

oneAPI 仕様 リリース 1.0 リビジョン 3
戻り値: プリミティブがワークスペース・パラメーターを要求しない場合は、ゼロメモリー記述子。
memory::desc mean_desc() const
平均メモリー記述子を返します。
戻り値: 平均のメモリー記述子。
memory::desc mean_desc()const
分散のメモリー記述子を返します。
戻り値: 分散のメモリー記述子。
struct dnnl::batch_normalization_backward: public dnnl::primitive
バッチ正規化逆方向伝搬プリミティブ。
パブリック関数
batch_normalization_backward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
batch_normalization_backward(const primitive_desc &pd)
バッチ正規化逆方向伝搬プリミティブを構築します。
パラメーター• pd: バッチ正規化逆方向伝搬プリミティブのプリミティブ記述子。
struct desc
バッチ正規化逆方向伝搬プリミティブの記述子。
パブリック関数desc(prop_kind
aprop_kind,
const
memory::desc&diff_data_desc,
memory::desc &data_desc, float epsilon, normalization_flags flags)
逆方向伝搬向けのバッチ正規化記述子を構築します。

const

パラメーター• aprop_kind: 伝搬の種類。可能な値は、dnnl::prop_kind::backward_data とdnnl::prop_kind::backward (この場合、すべてのパラメーターの差分が計算されます)。
• diff_data_desc: 差分ソースと差分デスティネーションのメモリー記述子。
• data_desc: ソースメモリー記述子。
• epsilon: バッチ正規化イプシロン・パラメーター。
• flags: バッチ正規化フラグ (dnnl::normalization_flags)。
struct primitive_desc: public dnnl::primitive_desc
バッチ正規化逆方向伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。

5.5 プリミティブ

94

oneAPI 仕様 リリース 1.0 リビジョン 3
primitive_desc(const
desc&adesc,const
engine&aengine,
const
batch_normalization_forward::primitive_desc &hint_fwd_pd, bool al- low_empty =false)
バッチ正規化逆伝搬プリミティブのプリミティブ記述子を構築します。
パラメーター• adesc: バッチ正規化逆伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• hint_fwd_pd: バッチ正規化順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr &attr, const engine&aengine, const batch_normalization_forward::primitive_desc &hint_fwd_pd, bool
allow_empty = false)
バッチ正規化逆伝搬プリミティブのプリミティブ記述子を構築します。
パラメーター• adesc: バッチ正規化逆伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• hint_fwd_pd: バッチ正規化順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc weights_desc() const
重みメモリー記述子を返します。
戻り値: 重みメモリー記述子。
戻り値: プリミティブに重みパラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。

5.5 プリミティブ

95

oneAPI 仕様 リリース 1.0 リビジョン 3

memory::desc diff_src_desc() const
差分ソースメモリー記述子を返します。
戻り値: 差分ソースメモリー記述子。
戻り値: プリミティブに差分ソースメモリーがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_desc() const
差分デスティネーション・メモリー記述子を返します。
戻り値: 差分デスティネーション・メモリー記述子。
戻り値: プリミティブに差分デスティネーション・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_weights_desc() const
差分重みメモリー記述子を返します。
戻り値: 差分重みメモリー記述子。
戻り値: プリミティブに差分重みパラメーターがない場合は、ゼロメモリー記述子。
memory::desc mean_desc() const
平均メモリー記述子を返します。
戻り値: 平均メモリー記述子。
memory::desc mean_desc() const
分散のメモリー記述子を返します。
戻り値: 分散のメモリー記述子。
memory::desc workspace_desc() const
ワークスペース・メモリー記述子を返します。
戻り値: ワークスペース・メモリー記述子。
戻り値: プリミティブがワークスペース・パラメーターを要求しない場合は、ゼロメモリー記述子。

5.5.4 バイナリー
バイナリー・プリミティブは、テンソル src0 と src1 間のバイナリー要素ごとの演算結果を計算します。

ここで、5.5 プリミティブと op は加算、乗算、最大、最小などの演算子です。変数名は標準規則に従います。

96

oneAPI 仕様 リリース 1.0 リビジョン 3
順方向と逆方向
バイナリー・プリミティブには、順方向と逆方向の伝搬の概念がありません。
実行引数実行時に入力と出力は、次の表で示す実行引数インデックスにマップする必要があります。
プリミティブの入力/出力
src0

実行引数インデックス
DNNL_ARG_SRC_0

src1

DNNL_ARG_SRC_1

dst

DNNL_ARG_DST

操作の詳細• バイナリー・プリミティブでは、すべてのソースとデスティネーション・テンソルの次元は同一でなければなりません。
• バイナリー・プリミティブは、src1 の暗黙のブロードキャストをサポートします。これは、特定の次元の値が1 である場合、この値を使用して次元の src0 のそれぞれのポイントで計算操作を行うことを意味します。
• dst メモリー形式は、明示的に指定することも、dnnl::memory::format_tag::any (推奨) を使用して指定することもできます。この場合、プリミティブは src0 テンソルの形式をベースに最も適切なメモリー形式を取得できます。
• デスティネーション・メモリー記述子は、src0 メモリー記述子と完全に一致する必要があります。
• バイナリー・プリミティブはインプレース操作をサポートし、src0 テンソルをデスティネーションとして使用できます。この場合、データは上書きされます。
post-op と属性
次の属性をサポートする必要があります。
型

操作

説明

制限事項

属性

scales指定されたスケール係数で対応する
入力テンソルをスケールします。

対応するテンソルのデータ型は整数です。テンソルごとに 1 つのスケールのみが許されます。
入力テンソルのみ。

post-opsum

演算結果を上書きせずに、デスティ
ネーション・テンソルに加算します。

post-op の要素ごとに先行する必要があります。

post-op

要素ごと

要素ごとの操作を適用します。

サポートされるデータ型
ソースとデスティネーション・テンソルには、dnnl::memory::data_type::f32、dnnl::memory::data_type::bf16、dnnl::memory::data_type::s8 または dnnl::memory::data_type::u8 データ型があります。
データ表現
バイナリー・プリミティブは任意のデータテンソルで機能します。テンソルの次元については特別な意味はありません。
5.5 プリミティブ

97

oneAPI 仕様 リリース 1.0 リビジョン 3APIstruct dnnl::binary: public dnnl::primitive
要素ごとのバイナリー操作プリミティブ。
パブリック関数binary()デフォルト・コンストラクター。空のオブジェクトを生成します。
binary(const primitive_desc &pd)
要素ごとのバイナリー操作プリミティブを作成します。
パラメーター• pd: 要素ごとのバイナリー操作プリミティブのプリミティブ記述子。
struct desc
要素ごとのバイナリー操作プリミティブの記述子。
パブリック関数desc(algorithm aalgorithm, const memory::desc &src0, const memory::desc &src1,
const memory::desc &dst)
要素ごとのバイナリー操作プリミティブの記述子を作成します。
パラメーター• aalgorithm: 要素ごとのアルゴリズム。
• src0: ソーステンソル #0 のメモリー記述子。
• src1: ソーステンソル #1 のメモリー記述子。
• dst: デスティネーション・テンソルのメモリー記述子。
struct primitive_desc: public dnnl::primitive_desc
要素ごとのバイナリー操作プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const desc &adesc, const engine &aengine,
false)
要素ごとのバイナリー操作プリミティブのプリミティブ記述子を構築します。

bool

allow_empty=

パラメーター• adesc: 要素ごとのバイナリー操作プリミティブの記述子。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine, bool allow_empty = false)
要素ごとのバイナリー操作プリミティブのプリミティブ記述子を作成します。

5.5 プリミティブ&attr,

const

engine98

oneAPI 仕様 リリース 1.0 リビジョン 3

パラメーター• adesc: 要素ごとのバイナリー操作プリミティブの記述子。
• aengine: 使用するエンジン。
• attr: 使用するプリミティブ属性。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_desc(int idx = 0) const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにインデックス付きのソース・パラメーターがない場合は、ゼロメモリー記述子。
パラメーター• idx: ソース・インデックス。
memory::desc src0_desc() const
ソース #0 のメモリー記述子を返します。
memory::desc src1_desc() const
ソース #1 のメモリー記述子を返します。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。

5.5.5 結合 (Concat)
データを任意の次元で結合するプリミティブです。
結合プリミティブは、concat_dimension (ここでは C として示されます) 上で N テンソルを結合し、次にように定義さ
れます。

説明:
• c = C1 + ...+ Ci−1 + c′
• ou̅̅̅ は最外のインデックス (結合軸の左側)

5.5 プリミティブ

99

oneAPI 仕様 リリース 1.0 リビジョン 3• in̅ は最内のインデックス (結合軸の右)
変数名は標準規則に従います。
順方向と逆方向
結合プリミティブには、順方向と逆方向の伝搬の概念がありません。結合操作の逆伝搬は、単純な単位元操作です。
実行引数
実行時に入力と出力は、次の表で示す実行引数インデックスにマップする必要があります。
プリミティブの入力/出力
src

実行引数インデックス
DNNL_ARG_MULTIPLE_SRC

dst

DNNL_ARG_DST

操作の詳細
1.
2.

dst メモリー形式は、ユーザーが指定することも、プリミティブによって取得することもできます。推奨される方法は、プリミティブが最も適切な形式を選択できるようにすることです。
結合プリミティブでは、concat_dimension を除いて、すべてのソースとデスティネーション・テンソルが同一形状でなければなりません。concat_dimension のデスティネーション次元は、ソースのconcat_dimension 次元の合計と等しい必要があります (例えば、C = ∑i Ci )。暗黙のブロードキャ
ストはサポートされません。

サポートされるデータ型
結合プリミティブは、ソーステンソルとデスティネーション・テンソルの任意のデータ型をサポートします。ただし、すべてのソーステンソルは同一のデータ型である必要があります (デスティネーション・テンソルのデータ型とは必ずしも一致する必要はありません)。
データ表現
結合プリミティブは、関連する論理次元に対し特別な意味は持ちません。
post-op と属性
結合プリミティブは post-op や属性をサポートしません。
API
struct dnnl::concat: public dnnl::primitive
テンソル結合 (concat) プリミティブ。
パブリック関数
concat()
デフォルト・コンストラクター。空のオブジェクトを生成します。
concat(const primitive_desc &pd)
結合プリミティブを構築します。

5.5 プリミティブ

100

oneAPI 仕様 リリース 1.0 リビジョン 3
パラメーター• pd: 結合プリミティブのプリミティブ記述子。
struct primitive_desc: public dnnl::primitive_desc_base
結合プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const
memory::desc
&dst,
int
concat_dimension,
const
std::vector<memory::desc> &srcs, const engine &aengine, const primitive_attr&attr = primitive_attr())
要素ごとのアウトオブプレース結合プリミティブのプリミティブ記述子を作成します。
パラメーター• dst: デスティネーション・メモリー記述子。
• concat_dimension: ソーステンソルは、このインデックスを使用して次元全体で結合されます。
次元の順番はメモリー形式に依存しないことに注意してください。
• srcs: ソースメモリー記述子のベクトル。
• aengine: 操作を行うエンジン。
• attr: 使用するプリミティブ属性 (オプション)。
primitive_desc(int concat_dimension, const std::vector<memory::desc>
const en- gine &aengine, constprimitive_attr &attr = primitive_attr())
要素ごとのアウトオブプレース結合プリミティブのプリミティブ記述子を作成します。

&srcs,

このバージョンでは、デスティネーション・メモリー記述子が自動的に取得されます。
パラメーター• concat_dimension: ソーステンソルは、このインデックスを使用して次元全体で結合されます。次元の順番はメモリー形式に依存しないことに注意してください。
• srcs: ソースメモリー記述子のベクトル。
• aengine: 操作を行うエンジン。
• attr: 使用するプリミティブ属性 (オプション)。
memory::desc src_desc(int idx = 0) const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにインデックス付きのソース・パラメーターがない場合は、ゼロメモリー記述子。
パラメーター• idx: ソース・インデックス。

5.5 プリミティブ

101

oneAPI 仕様 リリース 1.0 リビジョン 3
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。

5.5.6 畳み込みと逆畳み込み
畳み込みおよび逆畳み込みプリミティブは、バイアス付きの 1D、２D、または 3D 空間データに対するバッチ畳み込みまたは逆畳み込み操作の順方向、逆方向、もしくは重み更新を計算します。
操作は次の式で定義されます。高次元と低次元のケースでは、一般化するのが簡単な 2D 空間データの式のみを示します。変数名は標準規則に従います。
前方 (順方向)src、weights および dst をそれぞれ N x IC x IH x IW、OC x IC x KH x KW および N x OC x OH x OWテンソルとします。バイアスを OC 要素を持つ 1D テンソルであるとします。
さらに、残りの畳み込みパラメーターを次のようにします。
パラメーター

深さ
PDL

高さ
PHL

幅
PWL

コメント

パディング: バック、ボトム、
およにライト

PDR

PHR

PWR

API では、padding_r は対応するパディングのベクトルを示します(_r は右を表します)。

ストライド

SD

SH

SW

ストライドのない畳み込みは、ストライド・パラメーターを 1 に設定して定義できます。

膨張

DD

DH

DW

非膨張畳み込みは、膨張パラメーターを 0 に設定して定義できます。

パディング: フロント、トップ、およびレフト

API では、padding_l は対応するパディングのベクトルを示します(_l は左を表します)。

次の式は、oneDNN における畳み込みの計算方法を示します。説明を簡単にするためいくつかのタイプに分類できます
が、実際には畳み込みタイプを組み合わせます。
式をさらに単純にするため、iℎ < 0 もしくは iℎ ≥ IH、または iw < 0 もしくは iw ≥ IW の場合、src(n, ic, iℎ,iw) = 0 と仮定します。
通常の畳み込み

5.5 プリミティブ

102

oneAPI 仕様 リリース 1.0 リビジョン 3

説明:

グループとの畳み込み
oneDNN は、畳み込みテンソルを表すメモリー・オブジェクトに個別のグループ次元を追加し、グループを使用した 2D
畳み込みの重みを G × OCG × ICG × KH × KW の 5D テンソルとして表します。

説明:

OCG

= ICG = 1 の場合、深さごとの畳み込みとも呼ばれます。

膨張を伴う畳み込み

逆畳み込み (転置畳み込み)

逆畳み込み (フラクショナル・ストライド畳み込み、または転置畳み込みとも呼ばれます) は、畳み込みの前方パスと後方パスを入れ替えることで定義できます。言い換えると、重みが畳み込みを定義していることに注意してください。直接畳み込みであるか転置畳み込みであるかは、順方向と逆方向パスの計算方法によって決定されます。

5.5 プリミティブ

103

oneAPI 仕様 リリース 1.0 リビジョン 3
順方向訓練と順方向推論の違い
forward_training と forward_inference 伝搬の種類に違いはありません。
後方 (逆方向)
逆方向伝搬は、diff_dst と重みに基づいて diff_src を計算します。
重みの更新では、diff_dst と src に基づいて diff_weights と diff_bias が計算されます。
注: 最適化されたメモリー形式の src と weights は、順方向伝搬、逆方向伝搬、および重みの更新で異なることがあ
ります。
実行引数
実行時に入力と出力は、次の表で示す実行引数インデックスにマップする必要があります。
プリミティブの入力/出力
src

実行引数インデックス
DNNL_ARG_SRC

weights

DNNL_ARG_WEIGHTSbias

DNNL_ARG_BIAS

dst

DNNL_ARG_DST

diff_src

DNNL_ARG_DIFF_SRC

diff_weights

DNNL_ARG_DIFF_WEIGHTS

diff_bias

DNNL_ARG_DIFF_BIAS

diff_dst

DNNL_ARG_DIFF_DST

操作の詳細
なし。
サポートされるデータ型
畳み込みプリミティブは、ソース、デスティネーション、および重みメモリー・オブジェクトのデータ型で次の組み合わせをサポートします。
注: この節では、可読性のためデータ型の名称を省略しています。例えば、dnnl::memory::data_type::f32 は、
f32 に省略されます。
伝搬
順方向/逆方向

ソース
f32

重み
f32

デスティネーション
f32

バイアス
f32

順方向

f16

f16

f16

f16

順方向

u8、s8
bf16

s8

u8、s8、s32、f32

u8、s8、s32、f32

bf16

f32、bf16

f32、bf16
bf16

bf16

f32、bf16
bf16

f32、bf16

bf16

f32、bf16

順方向
逆方向
重み更新

5.5 プリミティブ

104

oneAPI 仕様 リリース 1.0 リビジョン 3
データ表現
他の CNN プリミティブと同様に、畳み込みプリミティブは次のテンソルを想定します。
空間

ソース/デスティネーション

重み

1D

N × C × W

[G × ] OC × IC × KW

2D

N × C × H × W[G ×] OC × IC × KH × KW

3D

N × C × D × H × W[G ×] OC × IC × KD × KH × KW

データのメモリー形式とメモリー・オブジェクトの重みは、畳み込みプリミティブのパフォーマンスには重要です。
oneDNN プログラミング・モデルは、畳み込みはプレースホルダー・メモリー形式タグ any をサポートするプリミティブの 1 つであり、プリミティブのパラメーターに基づいてデータとメモリー・オブジェクト形式を定義できます。any を使用
する場合、最初に畳み込みプリミティブ記述子を作成してから、実際のデータと重みメモリー・オブジェクト形式を照会する必要があります。
畳み込みプリミティブは、明示的に指定されたメモリー形式によって作成できますが、パフォーマンスは最適ではない可能性があります。
次の表は、畳み込みプリミティブが最適化されるプレーンメモリー形式の組み合わせを示します。
空間

畳み込みタイプ

1D、2D、3D

データ/重み論理テンソル
any

メモリー形式に最適化された実装
最適化済み

1D

f32、bf16

NCW/OIW、GOIW

ncw (abc)/oiw (abc)、goiw (abcd)

1D
1D

f32、bf16
int8

NCW/OIW、GOIW
NCW/OIWnwc (acb)/wio (cba)、wigo(dcab)
nwc(acb)/wio(cba)

2D

f32、bf16

NCHW/OIHW、GOIHW

nchw (abcd)/oihw (abcd)、goihw (abcde)

2D

NCHW/OIHW、GOIHW

nhwc (acdb)/hwio (cdba)、hwigo(decab)

2D

f32、bf16
int8

NCHW/OIHW、GOIHW

nhwc (acdb)/hwio (cdba)、hwigo(decab)

3D

f32、bf16

NCDHW/OIDHW、GOIDHW

ncdhw (abcde)/oidhw (abcde)、goidhw (abcdef)

3D

f32、bf16
int8

NCDHW/OIDHW、GOIDHW
NCDHW/OIDHW

ndhwc (acdeb)/dhwio (cdeba)、dhwigo(defcab)
ndhwc (acdeb)/dhwio (cdeba)

3D

5.5 プリミティブ

105

oneAPI 仕様 リリース 1.0 リビジョン 3
post-op と属性
post-op と属性を使用すると、出力スケールをプリミティブの結果に適用し、プリミティブの後に特定の操作を結合することで畳み込みプリミティブの動作を変更できます。次の属性と post-op がサポートされます。
伝搬

型

操作

説明

制限事項

順方向

属性

出力スケール

与えられたスケーリング係数で畳み込みの結果をスケールし int8 畳み込みのみます

順方向

post-op

要素ごと

結果に要素ごとの操作を適用します

順方向

post-opSum

演算結果を上書きせずに、デスティネーション・テンソルに加算します

プリミティブは、実行時のスケールを介した動的な量子化をサポートします。プリミティブ記述子を作成する時点でスケールが不明である場合、ユーザーは実際のスケールではなく DNNL_RUNTIME_F32_VAL ワイルドカード値に設定された出力スケールで属性を構成できます。その場合、ユーザーは、実行時に引数 DNNL_ARG_ATTR_OUTPUT_SCALESを指定して追加の入力メモリー・オブジェクトとしてスケールを提供する必要があります。
注: ライブラリーは、訓練の post-op の仕様を妨げるものではありませんが、すべての post-op が訓練に適している
わけではありません。たえとば、ゼロ以外の負の勾配パラメーターで ReLU を post-op として使用しても、逆伝搬を正しく計算するために必要な出力ワークスペースは作成されません。従って、状況によっては訓練に個別の畳み込
みプリミティブと要素ごとのプリミティブを使用する必要があります。
次の post-op チェーンがライブラリーでサポートされる必要があります。
畳み込みタイプ

サポートされる post-op シーケンス

f32 と bf16 畳み込み

要素ごと、sum、sum -> 要素ごと

int8 畳み込み

要素ごと、sum、sum -> 要素ごと、要素ごと -> sum

属性と post-op が、次の順番で有効になります。
• 出力スケール属性、• post-op、アタッチされた順番。
属性と post-op 適用中の操作は、単精度浮動小数点データ型で実行されます。実際のデスティネーション・データ型への変換は、保存の直前に行われます。
例1
次の疑似コードについて考えてみます。

5.5 プリミティブ

106

oneAPI 仕様 リリース 1.0 リビジョン 3
attribute attr;
attr.set_output_scale(alpha);
attr.set_post_ops({{ sum={scale=beta} },{ eltwise={scale=gamma, type=tanh, alpha=ignore, beta=ignored }});convolution_forward(src, weights, dst, attr)

次の式が導き出されます。

例2
次に疑似コードを示します。
attribute attr;
attr.set_output_scale(alpha);
attr.set_post_ops({{ eltwise={scale=gamma, type=relu, alpha=eta, beta=ignored }{ sum={scale=beta} },});convolution_forward(src, weights, dst, attr)

次の式が導き出されます。

アルゴリズムoneDNN の実装では、ユーザーが選択可能ないくつかの異なるアルゴリズムを使用して畳み込みプリミティブを実装できます。
• Direct (dnnl::algorithm::convolution_direct)。畳み込み操作は、SIMD 命令によって直接計算されます。これには、ワークスペースを必要とする暗黙的な GEMM 公式も含まれます。
• Winograd (dnnl::algorithm::convolution_winograd)。このアルゴリズムは、精度の低下とメ
モリー操作が増加することを犠牲にして、畳み込みの計算の複雑性を軽減します。実装は、Fast Algorithms
for Convolutional Neural Networks by A. Lavin and S. Gray (英語) に基づいています。Winograd ア
ルゴリズムは、高いパフォーマンスをもたらしますが、特定の形状でのみ利用できます。さらに、Winograd
は int8 と f32 データ型のみをサポートします。
• Auto (dnnl::algorithm::convolution_auto)。この場合、ライブラリーはテンソルの形状と利用可能な論理プロセッサー数を考慮したヒューリスティックに基づいて、最適なアルゴリズムを自動的に選択します。
API
struct dnnl::convolution_forward: public dnnl::primitive
畳み込み順伝搬プリミティブ。

5.5 プリミティブ

107

oneAPI 仕様 リリース 1.0 リビジョン 3
パブリック関数
convolution_forward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
concat(const primitive_desc &pd)
畳み込み順伝搬プリミティブを構築します。
パラメーター• pd: 畳み込み順伝搬プリミティブのプリミティブ記述子。
struct desc
畳み順伝搬プリミティブの記述子。
パブリック関数desc(prop_kind aprop_kind, algorithm aalgorithm, const memory::desc &src_desc,
const
memory::desc&weights_desc,
const
memory::desc&bias_desc,
const
memory::desc &dst_desc, constmemory::dims &strides, constmemory::dims &padding_l,constmem- ory::dims &padding_r)
バイアス付き畳み込み順伝搬プリミティブの記述子を構築します。
配列の strides、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テン
ソルの場合)、および幅の順です。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• aalgorithm: 畳み込みアルゴリズム。可能な値は、dnnl::algorithm::convolution_direct、dnnl::algorithm::convolution_winograd、および dnnl::algorithm::convolution_autoです。
• src_desc: ソースメモリー記述子。
• weights_desc: 重みメモリー記述子。
• bias_desc: バイアスメモリー記述子。ゼロメモリー記述子を渡すとバイアスが無効になります。
• dst_desc: デスティネーション・メモリー記述子。
• strides: 各空間次元のストライド。
• padding_l: 各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル。
• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
desc(prop_kind aprop_kind, algorithm aalgorithm, constmemory::desc &src_desc,
constmemory::desc&weights_desc,
constmemory::desc&dst_desc,
constmemory::dims &strides, constmemory::dims &padding_l, constmemory::dims&padding_r)
バイアスなし畳み込み順伝搬プリミティブの記述子を構築します。

5.5 プリミティブ

108

oneAPI 仕様 リリース 1.0 リビジョン 3
配列の strides、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テン
ソルの場合)、および幅の順です。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• aalgorithm: 畳み込みアルゴリズム。可能な値は、dnnl::algorithm::convolution_direct、dnnl::algorithm::convolution_winograd、および dnnl::algorithm::convolution_autoです。
• src_desc: ソースメモリー記述子。
• weights_desc: 重みメモリー記述子。
• dst_desc: デスティネーション・メモリー記述子。
• strides: 各空間次元のストライド。
• padding_l: 各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル。
• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
desc(prop_kind aprop_kind, algorithm aalgorithm, const memory::desc &src_desc,
const
memory::desc&weights_desc,
const
memory::desc&bias_desc,
const
memory::desc &dst_desc, const memory::dims &strides, const memory::dims &dilates,
const mem- ory::dims &padding_l, constmemory::dims &padding_r)
バイアス付き拡張畳み込み順伝搬プリミティブの記述子を構築します。
配列の strides、dilates、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テンソルの場合)、および幅の順です。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• aalgorithm: 畳み込みアルゴリズム。可能な値は、dnnl::algorithm::convolution_direct、dnnl::algorithm::convolution_winograd、および dnnl::algorithm::convolution_autoです。
• src_desc: ソースメモリー記述子。
• weights_desc: 重みメモリー記述子。
• bias_desc: バイアスメモリー記述子。ゼロメモリー記述子を渡すとバイアスが無効になります。
• dst_desc: デスティネーション・メモリー記述子。
• strides: 各空間次元のストライド。
• dilates: 各空間次元の拡張。ゼロ値は、対応する次元に拡張がないことを意味します。

5.5 プリミティブ

109

oneAPI 仕様 リリース 1.0 リビジョン 3• padding_l: 各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル。
• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
desc(prop_kind aprop_kind, algorithm aalgorithm, constmemory::desc &src_desc,
constmemory::desc&weights_desc,
constmemory::desc&dst_desc,
constmemory::dims &strides, const memory::dims &dilates, const memory::dims&padding_l, const memory::dims &padding_r)
バイアスなし拡張畳み込み順伝搬プリミティブの記述子を構築します。
配列の strides、dilates、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テンソルの場合)、および幅の順です。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• aalgorithm: 畳み込みアルゴリズム。可能な値は、dnnl::algorithm::convolution_direct、dnnl::algorithm::convolution_winograd、および dnnl::algorithm::convolution_autoです。
• src_desc: ソースメモリー記述子。
• weights_desc: 重みメモリー記述子。
• dst_desc: デスティネーション・メモリー記述子。
• strides: 各空間次元のストライド。
• dilates: 各空間次元の拡張。ゼロ値は、対応する次元に拡張がないことを意味します。
• padding_l: 各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル。
• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
struct primitive_desc: public dnnl::primitive_desc
畳み込み順伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const desc &adesc, const engine &aengine,
false)
畳み込み順伝搬プリミティブのプリミティブ記述子を構築します。

bool

allow_empty=

パラメーター• adesc: 畳み順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。

5.5 プリミティブ

110

oneAPI 仕様 リリース 1.0 リビジョン 3• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine, bool allow_empty = false)
畳み順伝搬プリミティブのプリミティブ記述子を構築します。

&attr,

const

engine

パラメーター• adesc: 畳み順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• attr: 使用するプリミティブ属性。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc weights_desc() const
重みメモリー記述子を返します。
戻り値: 重みメモリー記述子。
戻り値: プリミティブに重みパラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc workspace_desc() const
バイアスメモリー記述子を返します。
戻り値: バイアスメモリー記述子。
戻り値: プリミティブにバイアス・パラメーターがない場合は、ゼロメモリー記述子。
struct dnnl::convolution_backward_data: public dnnl::primitive
畳み込み逆伝搬プリミティブ。
パブリック関数
convolution_backward_data()

5.5 プリミティブ

111

oneAPI 仕様 リリース 1.0 リビジョン 3
デフォルト・コンストラクター。空のオブジェクトを生成します。
convolution_backward_data(const primitive_desc &pd)
畳み込み逆伝搬プリミティブを構築します。
パラメーター• pd: 畳み込み逆伝搬プリミティブのプリミティブ記述子。
struct desc
畳み込み逆伝搬プリミティブの記述子。
パブリック関数desc(algorithm aalgorithm, const memory::desc &diff_src_desc, const memory::desc&weights_desc, const memory::desc &diff_dst_desc, const memory::dims &strides,
constmemory::dims &padding_l, constmemory::dims &padding_r)
畳み込み逆伝搬プリミティブの記述子を構築します。
配列の strides、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テン
ソルの場合)、および幅の順です。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aalgorithm: 畳み込みアルゴリズム。可能な値は、dnnl::algorithm::convolution_direct、dnnl::algorithm::convolution_winograd、および dnnl::algorithm::convolution_autoです。
• diff_src_desc: 差分ソースメモリー記述子。
• weights_desc: 重みメモリー記述子。
• diff_dst_desc: 差分デスティネーション・メモリー記述子。
• strides: 各空間次元のストライド。
• padding_l: 各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル。
• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
desc(algorithm aalgorithm, const memory::desc &diff_src_desc, const memory::desc&weights_desc, const memory::desc &diff_dst_desc, const memory::dims &strides,
const memory::dims &dilates, const memory::dims &padding_l, const memory::dims&padding_r)
拡張畳み込み逆伝搬プリミティブの記述子を構築します。
配列の strides、dilates、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テンソルの場合)、および幅の順です。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。

5.5 プリミティブ

112

oneAPI 仕様 リリース 1.0 リビジョン 3

パラメーター• aalgorithm: 畳み込みアルゴリズム。可能な値は、dnnl::algorithm::convolution_direct、dnnl::algorithm::convolution_winograd、および dnnl::algorithm::convolution_autoです。
• diff_src_desc: 差分ソースメモリー記述子。
• weights_desc: 重みメモリー記述子。
• diff_dst_desc: 差分デスティネーション・メモリー記述子。
• strides: 各空間次元のストライド。
• dilates: 各空間次元の拡張。ゼロ値は、対応する次元に拡張がないことを意味します。
• padding_l: 各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル。
• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
struct primitive_desc: public dnnl::primitive_desc
畳み込み逆伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const desc &adesc, const engine &aengine, const
tion_forward::primitive_desc &hint_fwd_pd, bool allow_empty = false)
畳み込み逆伝搬プリミティブのプリミティブ記述子を構築します。

convolu-

パラメーター• adesc: 畳み込み逆伝搬プリミティブの記述子。
• aengine: 操作を行うエンジン。
• hint_fwd_pd: 畳み込み順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine,
const
convolution_forward::primitive_desc
allow_empty = false)
畳み込み逆伝搬プリミティブのプリミティブ記述子を構築します。

&attr, const&hint_fwd_pd,

enginebool

パラメーター• adesc: 畳み込み逆伝搬プリミティブの記述子。
• aengine: 操作を行うエンジン。
• attr: 使用するプリミティブ属性。
• hint_fwd_pd: 畳み込み順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
5.5 プリミティブ

113

oneAPI 仕様 リリース 1.0 リビジョン 3

memory::desc diff_src_desc() const
差分ソースメモリー記述子を返します。
戻り値: 差分ソースメモリー記述子。
戻り値: プリミティブに差分ソースメモリーがない場合は、ゼロメモリー記述子。
memory::desc weights_desc() const
重みメモリー記述子を返します。
戻り値: 重みメモリー記述子。
戻り値: プリミティブに重みパラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_desc() const
差分デスティネーション・メモリー記述子を返します。
戻り値: 差分デスティネーション・メモリー記述子。
戻り値: プリミティブに差分デスティネーション・パラメーターがない場合は、ゼロメモリー記述子。
struct dnnl::convolution_backward_weights: publicdnnl::primitive
畳み込み重み勾配プリミティブ。
パブリック関数
convolution_backward_weights()
デフォルト・コンストラクター。空のオブジェクトを生成します。
convolution_backward_weights(const primitive_desc &pd)
畳み込み重み勾配プリミティブを構築します。
パラメーター• pd: 畳み込み重み勾配プリミティブのプリミティブ記述子。
struct desc
畳み込み重み勾配プリミティブの記述子。
パブリック関数desc(algorithm aalgorithm, const memory::desc &src_desc, const memory::desc&diff_weights_desc, const memory::desc &diff_bias_desc, const memory::desc&diff_dst_desc, const memory::dims &strides, const memory::dims &padding_l,constmemory::dims &padding_r)
バイアス付き畳み込み重み勾配プリミティブの記述子を構築します。
配列の strides、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テン
ソルの場合)、および幅の順です。

5.5 プリミティブ

114

oneAPI 仕様 リリース 1.0 リビジョン 3

注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aalgorithm: 畳み込みアルゴリズム。可能な値は、dnnl::algorithm::convolution_direct、dnnl::algorithm::convolution_winograd、および dnnl::algorithm::convolution_autoです。
• src_desc: ソースメモリー記述子。
• diff_weights_desc: 差分重みメモリー記述子。
• diff_bias_desc: 差分バイアスメモリー記述子。ゼロメモリー記述子を渡すとバイアスが無効になります。
• diff_dst_desc: 差分デスティネーション・メモリー記述子。
• strides: 各空間次元のストライド。
• padding_l:各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル。
• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
desc(algorithm aalgorithm, const memory::desc &src_desc, const memory::desc&diff_weights_desc,
const
memory::desc&diff_dst_desc,
const
memory::dims&strides, constmemory::dims &padding_l, constmemory::dims &padding_r)
バイアスなし畳み込み重み勾配プリミティブの記述子を構築します。
配列の strides、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テン
ソルの場合)、および幅の順です。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aalgorithm: 畳み込みアルゴリズム。可能な値は、dnnl::algorithm::convolution_direct、dnnl::algorithm::convolution_winograd、および dnnl::algorithm::convolution_autoです。
• src_desc: ソースメモリー記述子。
• diff_weights_desc: 差分重みメモリー記述子。
• diff_dst_desc: 差分デスティネーション・メモリー記述子。
• strides: 各空間次元のストライド。
• padding_l: 各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル。
• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
desc(algorithm aalgorithm, const memory::desc &src_desc, const memory::desc&diff_weights_desc, const memory::desc &diff_bias_desc, const memory::desc&diff_dst_desc, const memory::dims &strides, const memory::dims &dilates, const
memory::dims &padding_l, constmemory::dims &padding_r)
バイアス付き拡張畳み込み重み勾配プリミティブの記述子を構築します。

5.5 プリミティブ

115

oneAPI 仕様 リリース 1.0 リビジョン 3

配列の strides、dilates、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テンソルの場合)、および幅の順です。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aalgorithm: 畳み込みアルゴリズム。可能な値は、dnnl::algorithm::convolution_direct、dnnl::algorithm::convolution_winograd、および dnnl::algorithm::convolution_autoです。
• src_desc: ソースメモリー記述子。
• diff_weights_desc: 差分重みメモリー記述子。
• diff_bias_desc: 差分バイアスメモリー記述子。ゼロメモリー記述子を渡すとバイアスが無効になります。
• diff_dst_desc: 差分デスティネーション・メモリー記述子。
• strides: 各空間次元のストライド。
• dilates: 各空間次元の拡張。ゼロ値は、対応する次元に拡張がないことを意味します。
• padding_l: 各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル。
• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
desc(algorithm aalgorithm, const memory::desc &src_desc, const memory::desc&diff_weights_desc,
const
memory::desc&diff_dst_desc,
const
memory::dims&strides, const memory::dims &dilates, const memory::dims &padding_l, const
memory::dims &padding_r)
バイアスなし拡張畳み込み重み勾配プリミティブの記述子を構築します。
配列の strides、dilates、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テンソルの場合)、および幅の順です。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aalgorithm: 畳み込みアルゴリズム。可能な値は、dnnl::algorithm::convolution_direct、dnnl::algorithm::convolution_winograd、および dnnl::algorithm::convolution_autoです。
• src_desc: ソースメモリー記述子。
• diff_weights_desc: 差分重みメモリー記述子。
• diff_dst_desc: 差分デスティネーション・メモリー記述子。
• strides: 各空間次元のストライド。
• dilates: 各空間次元の拡張。ゼロ値は、対応する次元に拡張がないことを意味します。
• padding_l: 各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル。
5.5 プリミティブ

116

oneAPI 仕様 リリース 1.0 リビジョン 3• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
struct primitive_desc: publicdnnl::primitive_desc
畳み込み重み勾配プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const desc &adesc, const engine &aengine, const
tion_forward::primitive_desc &hint_fwd_pd, bool allow_empty = false)
畳み込み重み勾配プリミティブのプリミティブ記述子を構築します。

convolu-

パラメーター• adesc: 畳み込み重み勾配プリミティブの記述子。
• aengine: 使用するエンジン。
• hint_fwd_pd: 畳み込み順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine,
const
convolution_forward::primitive_desc
allow_empty = false)
畳み込み重み勾配プリミティブのプリミティブ記述子を構築します。

&attr, const&hint_fwd_pd,

enginebool

パラメーター• adesc: 畳み込み重み勾配プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• hint_fwd_pd: 畳み込み順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_weights_desc() const
差分重みメモリー記述子を返します。
戻り値: 差分重みメモリー記述子。

5.5 プリミティブ

117

oneAPI 仕様 リリース 1.0 リビジョン 3
戻り値: プリミティブに差分重みパラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_desc() const
差分デスティネーション・メモリー記述子を返します。
戻り値: 差分デスティネーション・メモリー記述子。
戻り値: プリミティブに差分デスティネーション・メモリーがない場合は、ゼロメモリー記述子。
memory::desc diff_bias_desc() const
差分バイアスメモリー記述子を返します。
戻り値: 差分バイアスメモリー記述子。
戻り値: プリミティブに差分バイアス・パラメーターがない場合は、ゼロメモリー記述子。
struct dnnl::deconvolution_forward: public dnnl::primitive
逆畳み込み順伝搬プリミティブ。
パブリック関数deconvolution_forward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
deconvolution_forward(const primitive_desc &pd)
逆畳み込み順伝搬プリミティブを構築します。
パラメーター• pd: 逆畳み込み順伝搬プリミティブのプリミティブ記述子。
struct desc
逆畳み順伝搬プリミティブの記述子。
パブリック関数desc(prop_kind aprop_kind, algorithm aalgorithm, const memory::desc &src_desc,
const
memory::desc&weights_desc,
const
memory::desc&bias_desc,
const
memory::desc &dst_desc, constmemory::dims &strides, constmemory::dims &padding_l,constmem- ory::dims &padding_r)
バイアス付き逆畳み込み順伝搬プリミティブの記述子を構築します。
配列の strides、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テン
ソルの場合)、および幅の順です。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
5.5 プリミティブ

118

oneAPI 仕様 リリース 1.0 リビジョン 3• aalgorithm: 逆畳み込みアルゴリズム dnnl::algorithm::deconvolution_direct とdnnl::algorithm::deconvolution_winograd。
• src_desc: ソースメモリー記述子。
• weights_desc: 重みメモリー記述子。
• bias_desc: バイアスメモリー記述子。ゼロメモリー記述子を渡すとバイアスが無効になります。
• dst_desc: デスティネーション・メモリー記述子。
• strides: 空間次元のストライドのベクトル。
• padding_l: 各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル 。
• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
desc(prop_kind aprop_kind, algorithm aalgorithm, constmemory::desc &src_desc,
constmemory::desc&weights_desc,
constmemory::desc&dst_desc,
constmemory::dims &strides, constmemory::dims &padding_l, constmemory::dims&padding_r)
バイアスなし逆畳み込み順伝搬プリミティブの記述子を構築します。
配列の strides、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テン
ソルの場合)、および幅の順です。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• aalgorithm: 逆畳み込みアルゴリズム dnnl::algorithm::deconvolution_direct とdnnl::algorithm::deconvolution_winograd。
• src_desc: ソースメモリー記述子。
• weights_desc: 重みメモリー記述子。
• dst_desc: デスティネーション・メモリー記述子。
• strides: 空間次元のストライドのベクトル。
• padding_l: 各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル。
• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
desc(prop_kind aprop_kind, algorithm aalgorithm, const memory::desc &src_desc,
const
memory::desc&weights_desc,
const
memory::desc&bias_desc,
const
memory::desc &dst_desc, const memory::dims &strides, const memory::dims &dilates,
const mem- ory::dims &padding_l, constmemory::dims &padding_r)
バイアス付き拡張逆畳み込み順伝搬プリミティブの記述子を構築します。
配列の strides、dilates、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テンソルの場合)、および幅の順です。

5.5 プリミティブ

119

oneAPI 仕様 リリース 1.0 リビジョン 3
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• aalgorithm: 逆畳み込みアルゴリズム dnnl::algorithm::deconvolution_direct とdnnl::algorithm::deconvolution_winograd。
• src_desc: ソースメモリー記述子。
• weights_desc: 重みメモリー記述子。
• bias_desc: バイアスメモリー記述子。ゼロメモリー記述子を渡すとバイアスが無効になります。
• dst_desc: デスティネーション・メモリー記述子。
• strides: 空間次元のストライドのベクトル。
• dilates: 各空間次元の拡張。ゼロ値は、対応する次元に拡張がないことを意味します。
• padding_l: 各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル。
• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
desc(prop_kind aprop_kind, algorithm aalgorithm, constmemory::desc &src_desc,
constmemory::desc&weights_desc,
constmemory::desc&dst_desc,
constmemory::dims &strides, const memory::dims &dilates, const memory::dims&padding_l, const memory::dims &padding_r)
バイアスなし拡張逆畳み込み順伝搬プリミティブの記述子を構築します。
配列の strides、dilates、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テンソルの場合)、および幅の順です。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• aalgorithm: 逆畳み込みアルゴリズム dnnl::algorithm::deconvolution_direct とdnnl::algorithm::deconvolution_winograd。
• src_desc: ソースメモリー記述子。
• weights_desc: 重みメモリー記述子。
• dst_desc: デスティネーション・メモリー記述子。
• strides: 空間次元のストライドのベクトル。
• dilates: 各空間次元の拡張。ゼロ値は、対応する次元に拡張がないことを意味します。
• padding_l: 各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル。
• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。

5.5 プリミティブ

120

oneAPI 仕様 リリース 1.0 リビジョン 3
struct primitive_desc: public dnnl::primitive_desc
逆畳み込み順伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const desc &adesc, const engine &aengine,
false)
逆畳み込み順伝搬プリミティブのプリミティブ記述子を構築します。

bool

allow_empty=

パラメーター• adesc: 逆畳み順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine, bool allow_empty = false)
逆畳み順伝搬プリミティブのプリミティブ記述子を構築します。

&attr,

const

engine

パラメーター• adesc: 逆畳み順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• attr: 使用するプリミティブ属性。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc weights_desc() const
重みメモリー記述子を返します。
戻り値: 重みメモリー記述子。
戻り値: プリミティブに重みパラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。

5.5 プリミティブ

121

oneAPI 仕様 リリース 1.0 リビジョン 3
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc workspace_desc() const
バイアスメモリー記述子を返します。
戻り値: バイアスメモリー記述子。
戻り値: プリミティブにバイアス・パラメーターがない場合は、ゼロメモリー記述子。
struct dnnl::deconvolution_backward_data: public dnnl::primitive
逆畳み込み逆伝搬プリミティブ。
パブリック関数deconvolution_backward_data()
デフォルト・コンストラクター。空のオブジェクトを生成します。
deconvolution_backward_data(const primitive_desc &pd)
逆畳み込み逆伝搬プリミティブを構築します。
パラメーター• pd: 逆畳み込み逆伝搬プリミティブのプリミティブ記述子。
struct desc
逆畳み込み逆伝搬プリミティブの記述子。
パブリック関数desc(algorithm aalgorithm, const memory::desc &diff_src_desc, const memory::desc&weights_desc, const memory::desc &diff_dst_desc, const memory::dims &strides,
constmemory::dims &padding_l, constmemory::dims &padding_r)
逆畳み込み逆伝搬プリミティブの記述子を構築します。
配列の strides、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テン
ソルの場合)、および幅の順です。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aalgorithm: 逆 畳 み 込 み ア ル ゴ リ ズ ム (dnnl::algorithm::convolution_direct 、
dnnl::algorithm::convolution_winograd)。
• diff_src_desc: 差分ソースメモリー記述子。
• weights_desc: 重みメモリー記述子。
• diff_dst_desc: 差分デスティネーション・メモリー記述子。
• strides: 各空間次元のストライド。
• padding_l: 各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル。

5.5 プリミティブ

122

oneAPI 仕様 リリース 1.0 リビジョン 3• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
desc(algorithm aalgorithm, const memory::desc &diff_src_desc, const memory::desc&weights_desc, const memory::desc &diff_dst_desc, const memory::dims &strides,
const memory::dims &dilates, const memory::dims &padding_l, const memory::dims&padding_r)
拡張逆畳み込み逆伝搬プリミティブの記述子を構築します。
配列の strides、dilates、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テンソルの場合)、および幅の順です。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aalgorithm: 逆 畳 み 込 み ア ル ゴ リ ズ ム (dnnl::algorithm::convolution_direct 、
dnnl::algorithm::convolution_winograd)。
• diff_src_desc: 差分ソースメモリー記述子。
• weights_desc: 重みメモリー記述子。
• diff_dst_desc: 差分デスティネーション・メモリー記述子。
• strides: 各空間次元のストライド。
• dilates: 各空間次元の拡張。ゼロ値は、対応する次元に拡張がないことを意味します。
• padding_l: 各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル。
• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
struct primitive_desc: public dnnl::primitive_desc
逆畳み込み逆伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const
desc&adesc,const
engine&aengine,
const
deconvolution_forward::primitive_desc &hint_fwd_pd, bool allow_empty = false)
逆畳み込み逆伝搬プリミティブのプリミティブ記述子を構築します。
パラメーター• adesc: 逆畳み込み逆伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• hint_fwd_pd: 逆畳み込み順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。

5.5 プリミティブ

123

oneAPI 仕様 リリース 1.0 リビジョン 3
primitive_desc(const desc &adesc, const primitive_attr &attr, const engine&aengine, const deconvolution_forward::primitive_desc &hint_fwd_pd, bool allow_empty = false)
逆畳み込み逆伝搬プリミティブのプリミティブ記述子を構築します。
パラメーター• adesc: 逆畳み込み逆伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• hint_fwd_pd: 逆畳み込み順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc diff_src_desc() const
差分ソースメモリー記述子を返します。
戻り値: 差分ソースメモリー記述子。
戻り値: プリミティブに差分ソースメモリーがない場合は、ゼロメモリー記述子。
memory::desc weights_desc() const
重みメモリー記述子を返します。
戻り値: 重みメモリー記述子。
戻り値: プリミティブに重みパラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_desc() const
差分デスティネーション・メモリー記述子を返します。
戻り値: 差分デスティネーション・メモリー記述子。
戻り値: プリミティブに差分デスティネーション・メモリーがない場合は、ゼロメモリー記述子。
struct dnnl::deconvolution_backward_weights: public dnnl::primitive
逆畳み込み重み勾配プリミティブ。
パブリック関数deconvolution_backward_weights()
デフォルト・コンストラクター。空のオブジェクトを生成します。
deconvolution_backward_weights(const primitive_desc &pd)
逆畳み込み重み勾配プリミティブを構築します。
パラメーター• pd: 逆畳み込み重み勾配プリミティブのプリミティブ記述子。

5.5 プリミティブ

124

oneAPI 仕様 リリース 1.0 リビジョン 3

struct desc
逆畳み込み重み勾配プリミティブの記述子。
パブリック関数desc(algorithm aalgorithm, const memory::desc &src_desc, const memory::desc&diff_weights_desc, const memory::desc &diff_bias_desc, const memory::desc&diff_dst_desc, const memory::dims &strides, const memory::dims &padding_l,constmemory::dims &padding_r)
バイアス付き逆畳み込み重み勾配プリミティブの記述子を構築します。
配列の strides、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テン
ソルの場合)、および幅の順です。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aalgorithm: 逆畳み込みアルゴリズム。設定可能な値は、dnnl::algorithm::deconvolution_directと dnnl::algorithm::deconvolution_winograd です。
• src_desc: ソースメモリー記述子。
• diff_weights_desc: 差分重みメモリー記述子。
• diff_bias_desc: 差分バイアスメモリー記述子。ゼロメモリー記述子を渡すとバイアスが無効になります。
• diff_dst_desc: 差分デスティネーション・メモリー記述子。
• strides: 各空間次元のストライド。
• padding_l: 空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベクト
ル。
• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
desc(algorithm aalgorithm, const memory::desc &src_desc, const memory::desc&diff_weights_desc,
const
memory::desc&diff_dst_desc,
const
memory::dims&strides, constmemory::dims &padding_l, constmemory::dims &padding_r)
バイアスなし逆畳み込み重み勾配プリミティブの記述子を構築します。
配列の strides、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テン
ソルの場合)、および幅の順です。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aalgorithm: 逆畳み込みアルゴリズム。設定可能な値は、dnnl::algorithm::deconvolution_directと dnnl::algorithm::deconvolution_winograd です。
• src_desc: ソースメモリー記述子。
• diff_weights_desc: 差分重みメモリー記述子。

5.5 プリミティブ

125

oneAPI 仕様 リリース 1.0 リビジョン 3• diff_dst_desc: 差分デスティネーション・メモリー記述子。
• strides: 各空間次元のストライド。
• padding_l: 各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル。
• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
desc(algorithm aalgorithm, const memory::desc &src_desc, const memory::desc&diff_weights_desc, const memory::desc &diff_bias_desc, const memory::desc&diff_dst_desc, const memory::dims &strides, const memory::dims &dilates, const
memory::dims &padding_l, constmemory::dims &padding_r)
バイアス付き拡張逆畳み込み重み勾配プリミティブの記述子を構築します。
配列の strides、dilates、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テンソルの場合)、および幅の順です。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aalgorithm: 逆畳み込みアルゴリズム。設定可能な値は、dnnl::algorithm::deconvolution_directと dnnl::algorithm::deconvolution_winograd です。
• src_desc: ソースメモリー記述子。
• diff_weights_desc: 差分重みメモリー記述子。
• diff_bias_desc: 差分バイアスメモリー記述子。ゼロメモリー記述子を渡すとバイアスが無効になります。
• diff_dst_desc: 差分デスティネーション・メモリー記述子。
• strides: 各空間次元のストライド。
• dilates: 各空間次元の拡張。ゼロ値は、対応する次元に拡張がないことを意味します。
• padding_l: 各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル。
• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
desc(algorithm aalgorithm, const memory::desc &src_desc, const memory::desc&diff_weights_desc,
const
memory::desc&diff_dst_desc,
const
memory::dims&strides, const memory::dims &dilates, const memory::dims &padding_l, const
memory::dims &padding_r)
バイアスなし拡張逆畳み込み重み勾配プリミティブの記述子を構築します。
配列の strides、dilates、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テンソルの場合)、および幅の順です。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。

5.5 プリミティブ

126

oneAPI 仕様 リリース 1.0 リビジョン 3
パラメーター• aalgorithm: 逆畳み込みアルゴリズム。設定可能な値は、dnnl::algorithm::deconvolution_directと dnnl::algorithm::deconvolution_winograd です。
• src_desc: ソースメモリー記述子。
• diff_weights_desc: 差分重みメモリー記述子。
• diff_dst_desc: 差分デスティネーション・メモリー記述子。
• strides: 各空間次元のストライド。
• dilates: 各空間次元の拡張。ゼロ値は、対応する次元に拡張がないことを意味します。
• padding_l: 各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル。
• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
struct primitive_desc: public dnnl::primitive_desc
逆畳み込み重み勾配プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const
desc&adesc,const
engine&aengine,
const
deconvolution_forward::primitive_desc &hint_fwd_pd, bool allow_empty = false)
逆畳み込み重み更新プリミティブのプリミティブ記述子を構築します。
パラメーター• adesc: 逆畳み込み重み勾配プリミティブの記述子。
• aengine: 使用するエンジン。
• hint_fwd_pd: 逆畳み込み順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr &attr, const engine&aengine, const deconvolution_forward::primitive_desc &hint_fwd_pd, bool allow_empty = false)
逆畳み込み重み更新プリミティブのプリミティブ記述子を構築します。
パラメーター• adesc: 逆畳み込み重み勾配プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• hint_fwd_pd: 逆畳み込み順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。

5.5 プリミティブ

127

oneAPI 仕様 リリース 1.0 リビジョン 3
memory::desc src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_weights_desc() const
差分重みメモリー記述子を返します。
戻り値: 差分重みメモリー記述子。
戻り値: プリミティブに差分重みパラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_desc() const
差分デスティネーション・メモリー記述子を返します。
戻り値: 差分デスティネーション・メモリー記述子。
戻り値: プリミティブに差分デスティネーション・メモリーがない場合は、ゼロメモリー記述子。
memory::desc diff_bias_desc() const
差分バイアスメモリー記述子を返します。
戻り値: 差分バイアスメモリー記述子。
戻り値: プリミティブに差分バイアス・パラメーターがない場合は、ゼロメモリー記述子。

5.5.7 要素単位
要素単位のプリミティブは、テンソルのすべての要素に操作を適用します。変数名は標準規則に従います。

(

5.5 プリミティブ)

128

oneAPI 仕様 リリース 1.0 リビジョン 3
前方 (順方向)
次の順方向操作をサポートしています。ここで s と d は、それぞれ src と dst、tensor 値を示します。
要素全体のアルゴリズム

順方向式

eltwise_abs

eltwise_bounded_relu

eltwise_clip

eltwise_elu、eltwise_elu_use_dst_for_bwd
eltwise_exp、eltwise_exp_use_dst_for_bwd

d = eseltwise_gelu_erf
eltwise_gelu_tanh

eltwise_lineard = αs + β

eltwise_log

d = loge s

eltwise_logistic、
eltwise_logistic_use_dst_for_bwd
eltwise_pow

d = αsβ

eltwise_relu、eltwise_relu_use_dst_for_bwd
eltwise_roundd = round(s)eltwise_soft_relu

d = loge (1 + es)

eltwise_sqrt、eltwise_sqrt_use_dst_for_bwd
eltwise_squared = s2

eltwise_swish
eltwise_tanh、eltwise_tanh_use_dst_for_bwd

5.5 プリミティブ

d = tanh s

129

oneAPI 仕様 リリース 1.0 リビジョン 3
後方 (逆方向)
逆伝搬は diff_dst(𝑠̅) と src(𝑠̅) をベースに diff_src(𝑠̅) を計算します。ただし、一部の操作では順伝搬で生成された dst(𝑠̅) メモリーを使用した計算をサポートします。入力メモリーとしてデスティネーションをサポートする操作の一覧と対応する式に関しては前述の表を参照してください。
次の逆方向操作をサポートしています。ここで、 s、d、ds および dd は、それぞれ src、dst、diff_src、および
diff_dst テンソル値を示します。

5.5 プリミティブ

130

oneAPI 仕様 リリース 1.0 リビジョン 3
順方向訓練と順方向推論の違い#dnnl_forward_training と #dnnl_forward_inference 伝搬の種類に違いはありません。
実行引数実行時に入力と出力は、次の表で示す実行引数インデックスにマップする必要があります。
プリミティブの入力/出力
src

実行引数インデックス
DNNL_ARG_SRC

dst

DNNL_ARG_DST

diff_src

DNNL_ARG_DIFF_SRC

diff_dst

DNNL_ARG_DIFF_DST

操作の詳細
1.

2.

3.

4.

dnnl::eltwise_forward::desc::desc() および dnnl::eltwise_backward::desc::desc() コンス
トラクターは、パラメーター α と β の両方を受け取ります。これらのパラメーターは、アルゴリズムで使用されない
場合は無視されます。
src と dst のメモリー形式とデータ型は同一であると想定され、API では data として示されます (例えば、dnnl::eltwise_forward::desc::desc() には data_desc 引数があります)。同じことが
diff_src と diff_dst にも当てはまります。対応するメモリー記述子は diff_data_desc として表示されます。
順方向と逆方向の両方でインプレース操作がサポートされ、src は順方向伝搬の入力および出力として使用でき、diff_dst は逆伝搬の入力および出力として使用できます。インプレースの場合、元のデータは上書きされます。ただし、逆伝搬では一部のアルゴリズムが元の src を必要とするため、対応する順伝
搬をそれらのアルゴリズムのインプレースで実行してはなりません。逆伝搬で dst を使用するアルゴリズ
ムは、インプレースで安全に実行できます。
一部の操作では、パフォーマンス向上のため src(𝑠̅) ではなく dst(𝑠̅) に基づいて計算を行うと利点が得られることがあります。

注: 入力としてデスティネーション・メモリーをサポートする操作では、逆方向伝搬を計算する際に src の代わりにdst を使用できます。これにより、パフォーマンスの最適化が可能になります (以下のヒントを参照)。
サポートされるデータ型
要素ごとのプリミティブは次のデータ型の組み合わせをサポートする必要があります。
注: この節では、可読性のためデータ型の名称を省略しています。例えば、dnnl::memory::data_type::f32 は、
f32 に省略されます。
伝搬

ソース/デスティネーション

順方向/逆方向
順方向

f32、bf16
f16

順方向

s32/s8/u8

5.5 プリミティブ

中間データ型
f32
f16
f32

131

oneAPI 仕様 リリース 1.0 リビジョン 3
中間データ型は、入力値が最初に中間データ型に変換されてから演算が適用され、最後に結果が出力データ型に変換
されます。
データ表現
要素ごとのプリミティブは任意のデータテンソルで機能します。論理的な次元については特別な意味はありません。
post-op と属性
要素ごとのプリミティブは post-op や属性をサポートする必要がありません。
APIstruct dnnl::eltwise_forward: public dnnl::primitive
要素ごとの単項演算順伝搬プリミティブ。
パブリック関数
eltwise_forward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
eltwise_forward(const primitive_desc &pd)
要素ごとの順伝搬プリミティブを構築します。
パラメーター• pd: 要素ごとの順伝搬プリミティブのプリミティブ記述子。
struct desc
要素ごとの順伝搬プリミティブの記述子。
パブリック関数desc(prop_kind aprop_kind, algorithm aalgorithm, constmemory::desc &data_desc,
float alpha = 0, float beta = 0)
要素ごとの順伝搬プリミティブの記述子を構築します。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• aalgorithm: 要素ごとのアルゴリズムの種類。
• data_desc: ソースとデスティネーション・メモリー記述子。
• alpha: 要素ごとの操作のアルファ・パラメーター。具体的な意味はアルゴリズムごとに異なります。
• beta: 要素ごとの操作のベータ・パラメーター。具体的な意味はアルゴリズムごとに異なります。
struct primitive_desc: public dnnl::primitive_desc
要素ごとの順伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。

5.5 プリミティブ

132

oneAPI 仕様 リリース 1.0 リビジョン 3
primitive_desc(const desc &adesc, const engine &aengine,
false)
要素ごとの順伝搬プリミティブのプリミティブ記述子を構築します。
パラメーターbool

allow_empty=• adesc: 要素ごとの順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine, bool allow_empty = false)
要素ごとの順伝搬プリミティブのプリミティブ記述子を構築します。

&attr,

const

engine

パラメーター• adesc: 要素ごとの順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• attr: 使用するプリミティブ属性。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。
struct dnnl::eltwise_backward: public dnnl::primitive
要素ごとの単項操作の逆伝搬プリミティブ。
参照: eltwise_forward
パブリック関数
eltwise_backward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
eltwise_backward(const primitive_desc &pd)
要素ごとの逆伝搬プリミティブを構築します。

5.5 プリミティブ

133

oneAPI 仕様 リリース 1.0 リビジョン 3
パラメーター• pd: 要素ごとの逆伝搬プリミティブのプリミティブ記述子。
struct desc
要素ごとの逆伝搬プリミティブの記述子。
パブリック関数desc(algorithm
aalgorithm,
const
memory::desc&diff_data_desc,
memory::desc &data_desc, float alpha = 0, float beta = 0)
要素ごとの逆伝搬プリミティブの記述子を構築します。

const

パラメーター• aalgorithm: 要素ごとのアルゴリズムの種類。
• diff_data_desc: 差分ソースとデスティネーション・メモリー記述子。
• data_desc: ソースメモリー記述子。
• alpha: 要素ごとの操作のアルファ・パラメーター。具体的な意味はアルゴリズムごとに異なります。
• beta: 要素ごとの操作のベータ・パラメーター。具体的な意味はアルゴリズムごとに異なります。
struct primitive_desc: public dnnl::primitive_desc_base
要素ごとの逆伝搬プリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const
desc&adesc,const
engine&aengine,
eltwise_forward::primitive_desc &hint_fwd_pd, bool allow_empty = false)
要素ごとの逆伝搬プリミティブのプリミティブ記述子を構築します。

const

パラメーター• adesc: 要素ごとの逆伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• hint_fwd_pd: 要素ごとの順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr &attr, const engine&aengine, const eltwise_forward::primitive_desc &hint_fwd_pd, bool allow_empty =false)
要素ごとの逆伝搬プリミティブのプリミティブ記述子を構築します。
パラメーター• adesc: 要素ごとの逆伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。

5.5 プリミティブ

134

oneAPI 仕様 リリース 1.0 リビジョン 3• hint_fwd_pd: 要素ごとの順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_src_desc() const
差分ソースメモリー記述子を返します。
戻り値: 差分ソースメモリー記述子。
戻り値: プリミティブに差分ソースメモリーがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_desc() const
差分デスティネーション・メモリー記述子を返します。
戻り値: 差分デスティネーション・メモリー記述子。
戻り値: プリミティブに差分デスティネーション・メモリーがない場合は、ゼロメモリー記述子。

5.5.8 内積
内積プリミティブ (全結合レイヤーと呼ばれることもあります) は、ミニバッチ内の活性化をベクトルとして扱い、2D テ
ンソルを出力する重み 2D テンソルを使用して、その積を計算します。
順方向 (前方)src、weights、bias、および dst を、それぞれ N x IC、OC x IC、OC、および N x OC テンソルとします。変数名は標準規則に従います。次の式で表すことができます。

src テンソルと weights テンソルが空間次元を持つ場合、それらは 2D に平坦化されます。例えば、それらが 4D N x
IC′x IH x IW および OC x IC′x KH x KW テンソルである場合、上記の式は IC = IC′- IH - IW で適用できます。
この場合、src テンソルと weights テンソルは、等しい空間次元を持つ必要があります (例えば、4D テンソルの場合
は KH = IH と KW = IW)。

5.5 プリミティブ

135

oneAPI 仕様 リリース 1.0 リビジョン 3
順方向訓練と順方向推論の違い
forward_training と forward_inference 伝搬の種類に違いはありません。
後方 (逆方向)
逆方向伝搬は、diff_dst と重みに基づいて diff_src を計算します。
重みの更新では、diff_dst と src に基づいて diff_weights と diff_bias が計算されます。
注: 最適化されたメモリー形式の src と weights は、順方向伝搬、逆方向伝搬、および重みの更新で異なることがあ
ります。
実行引数
実行時に入力と出力は、次の表で示す実行引数インデックスにマップする必要があります。
プリミティブの入力/出力
src

実行引数インデックス
DNNL_ARG_SRC

weights

DNNL_ARG_WEIGHTSbias

DNNL_ARG_BIAS

dst

DNNL_ARG_DST

diff_src

DNNL_ARG_DIFF_SRC

diff_weights

DNNL_ARG_DIFF_WEIGHTS

diff_bias

DNNL_ARG_DIFF_BIAS

diff_dst

DNNL_ARG_DIFF_DST

操作の詳細
なし。
サポートされるデータ型
内積プリミティブは、ソース、デスティネーション、重み、およびバイアスのデータ型で次の組み合わせをサポートします。
注: この節では、可読性のためデータ型の名称を省略しています。例えば、dnnl::memory::data_type::f32 は、
f32 に省略されます。
伝搬
順方向/逆方向

ソース
f32

重み
f32

デスティネーション
f32

バイアス
f32

順方向

f16

f16

f16

f16

順方向

u8、s8
bf16

s8

u8、s8、s32、f32

u8、s8、s32、f32

bf16

f32、bf16

f32、bf16
bf16

bf16

f32、bf16
bf16

f32、bf16

bf16

f32、bf16

順方向
逆方向
重み更新

5.5 プリミティブ

136

oneAPI 仕様 リリース 1.0 リビジョン 3
データ表現
他の CNN プリミティブと同様に、内積プリミティブは次のテンソルを想定します。
空間

ソース

デスティネーション重み

1D

N × C × W

N × C

OC × IC × KW

2D

N × C × H × W

N × C

OC × IC × KH × KW

3D

N × C × D × H × W

N × C

OC × IC × KD × KH × KW

データのメモリー形式とメモリー・オブジェクトの重みは、内積プリミティブのパフォーマンスには重要です。oneDNN
プログラミング・モデルは、内積プリミティブはプレースホルダー形式の any をサポートし、プリミティブ・パラメーターに基づいてメモリー・オブジェクト形式を定義できる数少ないプリミティブの 1 つです。any を使用する場合、最初に内積プリミティブ記述子を作成してから、実際のデータと重みメモリー・オブジェクト形式を照会する必要があります。
次の表は、内積プリミティブが最適化されるプレーンメモリー形式の組み合わせを示します。デスティネーション・テンソ
ル (常に N × C) では、メモリー形式は常に nc(ab) です。
空間0D

ソース/重み論理テンソル
NC/OI

メモリー形式向けに最適化された実装
nc(ab)/oi(ab)

0D

NC/OI

nc(ab)/io(ba)1D

NCW/OIWncw (abc)/oiw (abc)

1D

NCW/OIWnwc(acb)/wio(cba)

2D

NCHW/OIHW

nchw (abcd)/oihw (abcd)

2D

NCHW/OIHW

nhwc(acdb)/hwio(cdba)

3D

NCDHW/OIDHW

ncdhw (abcde)/oidhw (abcde)

3D

NCDHW/OIDHW

ndhwc(acdeb)/dhwio(cdeba)

post-op と属性
次の post-op 操作が内積プリミティブでサポートされる必要があります。
伝搬

型

操作

説明

制限事項

順方向

属性

出力
スケール

与えられたスケール係数で内積の結果をスケールしますint8 内積のみ

順方向

post-op

要素ごと

結果に要素ごとの演算を適用します

順方向

post-opSum

演算結果を上書きせずに、デスティネーション・テンソルに
加算します

API
struct dnnl::inner_product_forward: public dnnl::primitive
内積順伝搬プリミティブ。

5.5 プリミティブ

137

oneAPI 仕様 リリース 1.0 リビジョン 3
パブリック関数
inner_product_forward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
eltwise_forward(const primitive_desc &pd)
内積順伝搬プリミティブを構築します。
パラメーター• pd: 内積順伝搬プリミティブのプリミティブ記述子。
struct desc
内積順伝搬プリミティブの記述子。
パブリック関数desc(prop_kind aprop_kind, const memory::desc &src_desc, const memory::desc&weights_desc, constmemory::desc &bias_desc, constmemory::desc &dst_desc)
バイアス付き内積順伝搬プリミティブの記述子を構築します。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• src_desc: ソースのメモリー記述子。
• weights_desc: 差分重みメモリー記述子。
• bias_desc: 差分バイアスのメモリー記述子。
• dst_desc: 差分デスティネーションのメモリー記述子。
desc(prop_kind aprop_kind, const memory::desc&weights_desc, constmemory::desc &dst_desc)
バイアスなし内積順伝搬プリミティブの記述子を構築します。

&src_desc,

const

memory::desc

注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• src_desc: ソースのメモリー記述子。
• weights_desc: 差分重みメモリー記述子。
• dst_desc: デスティネーションのメモリー記述子。
struct primitive_desc: public dnnl::primitive_desc
内積順伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。

5.5 プリミティブ

138

oneAPI 仕様 リリース 1.0 リビジョン 3

primitive_desc(const desc &adesc, const engine
false)
内積順伝搬プリミティブのプリミティブ記述子を構築します。

&aengine,boolallow_empty=

パラメーター• adesc: 内積順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine, bool allow_empty = false)
内積順伝搬プリミティブのプリミティブ記述子を構築します。

&attr,

const

engine

パラメーター• adesc: 内積順伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_desc()const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc weights_desc() const
重みメモリー記述子を返します。
戻り値: 重みメモリー記述子。
戻り値: プリミティブに重みパラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc workspace_desc() const
バイアスメモリー記述子を返します。
戻り値: バイアスメモリー記述子。

5.5 プリミティブ

139

oneAPI 仕様 リリース 1.0 リビジョン 3

戻り値: プリミティブにバイアス・パラメーターがない場合は、ゼロメモリー記述子。
struct dnnl::inner_product_backward_data: public dnnl::primitive
内積逆伝搬プリミティブ。
パブリック関数
inner_product_backward_data()
デフォルト・コンストラクター。空のオブジェクトを生成します。
inner_product_backward_data(const primitive_desc &pd)
内積逆伝搬プリミティブを構築します。
パラメーター• pd: 内積逆伝搬プリミティブのプリミティブ記述子。
struct desc
内積逆伝搬プリミティブの記述子。
パブリック関数desc(const memory::desc &diff_src_desc, const memory::desc &weights_desc, const
memory::desc &diff_dst_desc)
内積逆伝搬プリミティブの記述子を構築します。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• diff_src_desc: 差分ソースのメモリー記述子。
• weights_desc: 重みのメモリー記述子。
• diff_dst_desc: 差分デスティネーションのメモリー記述子。
struct primitive_desc: public dnnl::primitive_desc
内積逆伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const
desc&adesc,const
engine&aengine,
const
inner_product_forward::primitive_desc &hint_fwd_pd, bool allow_empty = false)
内積逆伝搬プリミティブのプリミティブ記述子を構築します。
パラメーター• adesc: 内積逆伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• hint_fwd_pd: 内積順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定する
ヒントとして利用されます。

5.5 プリミティブ

140

oneAPI 仕様 リリース 1.0 リビジョン 3• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine,
const
inner_product_forward::primitive_desc
allow_empty = false)
内積逆伝搬プリミティブのプリミティブ記述子を構築します。

&attr, const engine&hint_fwd_pd,bool

パラメーター• adesc: 内積逆伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• hint_fwd_pd: 内積順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定する
ヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc diff_src_desc() const
差分ソースメモリー記述子を返します。
戻り値: 差分ソースメモリー記述子。
戻り値: プリミティブに差分ソースメモリーがない場合は、ゼロメモリー記述子。
memory::desc weights_desc() const
重みメモリー記述子を返します。
戻り値: 重みメモリー記述子。
戻り値: プリミティブに重みパラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_desc() const
差分デスティネーション・メモリー記述子を返します。
戻り値: 差分デスティネーション・メモリー記述子。
戻り値: プリミティブに差分デスティネーション・メモリーがない場合は、ゼロメモリー記述子。
struct dnnl::inner_product_backward_weights: public dnnl::primitive
内積重み勾配プリミティブ。
パブリック関数
inner_product_backward_weights()
デフォルト・コンストラクター。空のオブジェクトを生成します。
inner_product_backward_weights(const primitive_desc &pd)
内積重み勾配プリミティブを構築します。

5.5 プリミティブ

141

oneAPI 仕様 リリース 1.0 リビジョン 3
パラメーター• pd: 内積重み勾配プリミティブのプリミティブ記述子。
struct desc
内積重み勾配プリミティブの記述子。
パブリック関数desc(const memory::desc &src_desc, const memory::desc &diff_weights_desc, const
memory::desc &diff_bias_desc, constmemory::desc &diff_dst_desc)
バイアス付き内積重み更新プリミティブの記述子を構築します。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• src_desc: ソースのメモリー記述子。
• diff_weights_desc: 差分重みメモリー記述子。
• diff_bias_desc: 差分バイアスのメモリー記述子。
• diff_dst_desc: 差分デスティネーションのメモリー記述子。
desc(const memory::desc &src_desc, const memory::desc &diff_weights_desc, const
memory::desc &diff_dst_desc)
バイアスなし内積重み更新プリミティブの記述子を構築します。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• src_desc: ソースのメモリー記述子。
• diff_weights_desc: 差分重みメモリー記述子。
• diff_dst_desc: デスティネーション差分のメモリー記述子。
struct primitive_desc: public dnnl::primitive_desc
内積重み勾配プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const
desc&adesc,const
engine&aengine,
const
inner_product_forward::primitive_desc &hint_fwd_pd, bool allow_empty = false)
内積重み更新プリミティブのプリミティブ記述子を構築します。
パラメーター• adesc: 内積重み勾配プリミティブの記述子。
• aengine: 使用するエンジン。
• hint_fwd_pd: 内積順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定する
ヒントとして利用されます。

5.5 プリミティブ

142

oneAPI 仕様 リリース 1.0 リビジョン 3• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine,
const
inner_product_forward::primitive_desc
allow_empty = false)
内積重み更新プリミティブのプリミティブ記述子を構築します。

&attr, const engine&hint_fwd_pd,bool

パラメーター• adesc: 内積重み勾配プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• hint_fwd_pd: 内積順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定する
ヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_weights_desc() const
差分重みメモリー記述子を返します。
戻り値: 差分重みメモリー記述子。
戻り値: プリミティブに差分重みパラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_desc() const
差分デスティネーション・メモリー記述子を返します。
戻り値: 差分デスティネーション・メモリー記述子。
戻り値: プリミティブに差分デスティネーション・メモリーがない場合は、ゼロメモリー記述子。
memory::desc diff_bias_desc() const
差分バイアスメモリー記述子を返します。
戻り値: 差分バイアスメモリー記述子。
戻り値: プリミティブに差分バイアス・パラメーターがない場合は、ゼロメモリー記述子。

5.5 プリミティブ

143

oneAPI 仕様 リリース 1.0 リビジョン 3

5.5.9 レイヤーの正規化
レイヤーの正規化プリミティブは、2D - 5D データテンソルで順方向または逆方向のレイヤー正規化操作を実行します。
レイヤーの正規化操作は、データテンソルの最後の論路軸に対して正規化を行います (次の式で定義されます)。ここでは 3D データの式を示しますが、これは高次元のケースでは一般化が容易であるためです。変数名は標準規則に従います。
前方 (順方向)説明:• γ(c)、β(c) は、チャネルのオプションのスケールとシフトです (use_scaleshift フラグを参照)、• μ(t, n)、σ2(t, n) は平均と分散 (use_global_stats フラグを参照)、および• ε は数値の安定性を向上させる定数です。
平均と分散は実行時に計算されるか、ユーザーによって提供されます。平均と分散を実行時に計算する場合、次の式が使用されます。

γ(ｃ) と β(c) テンソルは学習可能であると見なされます。
順方向訓練と順方向推論の違い
平 均 と 分 散 が 実 行 時 に 計 算 さ れ る (use_global_stats が 設 定 さ れ て い な い ) 場 合 、 そ れ ら は 伝 搬 種 別
forward_training の出力になります (逆伝搬中に必要となるため)。平均と分散のデータレイアウトは、統計用のメ
モリー記述子を渡すことで (例えば、dnnl::layer_normalization_forward::desc::desc() で stat_descを渡す) レイヤー正規化記述子の初期化中に指定する必要があります。平均と分散は、伝搬種別
forward_inference では公開されていません。
逆方向 (後方)逆伝搬は、diff_dst(t, n, c)、src(t, n, c)、 μ (t, n)、 σ 2(t, n)、 γ (c)*、および β (c)* に基づいて、
diff_src(t, n, c)、diff_γ(c)*、および diff_β(c)* を計算します。
アスタリスク (*) で示されるテンソルは、プリミティブが γ (c) および β (c) を使用するように構成されている(use_scaleshiftis が設定されている) 場合にのみ使用されます。

5.5 プリミティブ

144

oneAPI 仕様 リリース 1.0 リビジョン 3
実行引数
フラグと伝搬の種別に応じて、レイヤー正規化プリミティブには異なる入力 (In) と出力 (Out) が必要です。以下に要約
します。

none

forward_infer

efnocreward_trainin gbackward

In: src
Out: dst

In: src
Out: dst、μ、δ2

In: diff_dst、src、μ、δ2
Out: diff_src

backward と同じ

In: src、μ、δ2
Out: dst

In: diff_dst、src、μ、δ2
Out: diff_src

backward と同じ

In: src、γ、βOut: dst、μ、δ2

In: diff_dst、src、

未サポート

use_global_stats In: src、μ、δ2
Out: dst
use_scaleshift
In: src、γ、βOut: dst

backward_data

μ、δ2、γ、βOut: diff_src、diff_γ、diff_β

use_global_stats In: src、μ、δ2、γ、β In: src、μ、δ2、γ、β| use_scaleshift
Out: dst
Out: dst

In: diff_dst、src、μ、δ2、γ、β
未サポート
Out: diff_src、diff_γ、diff_β

実行時に入力と出力は、次の表で示す実行引数インデックスにマップする必要があります。
プリミティブの入力/出力
src

実行引数インデックス
DNNL_ARG_SRC

γ、βDNNL_ARG_SCALE_SHIFT

mean(μ)DNNL_ARG_MEAN

variance(δ)
dst

DNNL_ARG_VARIANCE

diff_dst

DNNL_ARG_DIFF_DST

diff_src

DNNL_ARG_DIFF_SRC

diff_γ、diff_β

DNNL_ARG_DIFF_SCALE_SHIFTDNNL_ARG_DST

操作の詳細
1.

2.

3.

4.

プリミティブのさまざまな振る舞いは、操作記述子の初期化関数(dnnl::layer_normalization_forward::desc::desc()) などに渡されるフラグ・パラメー
ターによって部分的に制御できます。複数のフラグはビットごとの OR 演算子 (|) を使用して組み合わせることができます。
順伝搬の場合、平均と分散は実行時に計算 (プリミティブの出力として) されるか、ユーザーによって提供されます (入力として)。ユーザーが提供する場合、use_global_stats フラグを設定する必要があります。逆伝搬の場合、平均と分散は常に入力パラメーターとなります。
src と dst のメモリー形式とデータ型は同一であると想定され、API ではデータとして参照されます(dnnl::layer_normalization_forward::desc::desc() の
data_desc を 参 照 ) 。
diff_src と diff_dst に も 同 じ こ と が 当 て は ま り ま す 。 対 応 す る メ モ リ ー 記 述 子 は
diff_data_desc と呼ばれます。
順方向と逆方向の両方でインプレース操作がサポートされ、src は順方向伝搬の入力および出力として使用でき、diff_dst は逆伝搬の入力および出力として使用できます。インプレースの場合、元のデータは上書きされます。ただし、逆伝搬では元の src が必要であるため、対応する順伝搬をインプレースで実行してはなりません。

5.5 プリミティブ

145

oneAPI 仕様 リリース 1.0 リビジョン 3
サポートされるデータ型
レイヤーの正規化では次のデータ型の組み合わせをサポートします。
注: この節では、可読性のためデータ型の名称を省略しています。例えば、dnnl::memory::data_type::f32 は、
f32 に省略されます。
伝搬
順方向/逆方向

ソース/デスティネーション
f32

平均/分散/スケールシフト
f32

順方向

f16

f32

データ表現
平均と分散
平均 ( μ ) と分 散 ( δ 2) は 、 次元数 が (data_ndims − 1) とサ イズ (data_dim[0] 、 data_dim[1] 、 ... 、
data_dim[ndims − 2]) に等しい個別のテンソルです。
対応するメモリー・オブジェクトは、任意のメモリー形式であることができます。平均と分散が実行時に計算されて公開されていない場合 (つまり、伝搬の種別が forward_inference で use_global_stats が設定されていない)、
ユーザーはレイヤー正規化記述子を初期化する際に統計用のメモリー記述子を用意する必要があります。最高のパ
フォーマンスを達成するには、データメモリー形式に従ったメモリー形式を使用することを推奨します。つまり、データ形
式が tnc である場合、tn 形式の統計では最高のパフォーマンスを期待できますが、nt 形式の統計ではそうではありません。
スケールとシフト
使用する場合、スケール (γ) とシフト (β) は、形状 2 × C の単一 2D テンソルに結合されます。
対応するメモリー・オブジェクトの形式は nc(ab) である必要があります。
ソース、デスティネーション、およびそれらの勾配
レイヤー正規化プリミティブは任意のデータテンソルで機能しますが、RNN データテンソル (nc、tnc、ldnc) 向けに設計されています。CNN データテンソルとは異なり、RNN データテンソルには単一の特徴次元があります。レイヤーの正規化は、非特徴次元全体で最後の論理次元 (RNN テンソルの特徴次元) に対して正規化を実行します。
レイヤー正規化プリミティブは次のメモリー形式に最適化されています。
論理テンソルNC
TNC
LDNC

メモリー形式向けに最適化された実装
nc(ab)
tnc(abc)、ntc(bac)ldnc(abcd)APIstruct dnnl::layer_normalization_forward: public dnnl::primitive
レイヤー正規化順伝搬プリミティブ。
5.5 プリミティブ

146

oneAPI 仕様 リリース 1.0 リビジョン 3
パブリック関数layer_normalization_forward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
deconvolution_forward(const primitive_desc &pd)
レイヤー正規化順伝搬プリミティブを構築します。
パラメーター• pd: レイヤー正規化順伝搬プリミティブのプリミティブ記述子。
struct desc
レイヤーの正規化順伝搬プリミティブの記述子。
パブリック関数desc(prop_kind
aprop_kind,constmemory::desc&data_desc,&stat_desc, float epsilon, normalization_flags flags)
レイヤーの正規化順伝搬プリミティブの記述子を構築します。

constmemory::desc

パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• data_desc: ソースとデスティネーション・メモリー記述子。
• stat_desc: 統計メモリー記述子。
• epsilon: レイヤーの正規化イプシロン・パラメーター。
• flags: レイヤー正規化フラグ (dnnl::normalization_flags)。
desc(prop_kind
aprop_kind,constmemory::desc
normalization_flags flags)
レイヤーの正規化順伝搬プリミティブの記述子を構築します。

&data_desc,

float

epsilon,

パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• data_desc: ソースとデスティネーション・メモリー記述子。
• epsilon: レイヤーの正規化イプシロン・パラメーター。
• flags: レイヤー正規化フラグ (dnnl::normalization_flags)。
struct primitive_desc: public dnnl::primitive_desc
レイヤー正規化順伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const desc &adesc, const engine &aengine,
false)
レイヤーの正規化順伝搬プリミティブのプリミティブ記述子を構築します。

5.5 プリミティブ

boolallow_empty=

147

oneAPI 仕様 リリース 1.0 リビジョン 3
パラメーター• adesc: レイヤーの正規化順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine, bool allow_empty = false)
レイヤーの正規化順伝搬プリミティブのプリミティブ記述子を構築します。

&attr,

const

engine

パラメーター• adesc: レイヤーの正規化順伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc weights_desc() const
重みメモリー記述子を返します。
戻り値: 重みメモリー記述子。
戻り値: プリミティブに重みパラメーターがない場合は、ゼロメモリー記述子。
memory::desc workspace_desc() const
ワークスペース・メモリー記述子を返します。
戻り値: ワークスペース・メモリー記述子。
戻り値: プリミティブがワークスペース・パラメーターを要求しない場合は、ゼロメモリー記述子。
memory::desc mean_desc() const
平均メモリー記述子を返します。
5.5 プリミティブ

148

oneAPI 仕様 リリース 1.0 リビジョン 3

戻り値: 平均メモリー記述子。
memory::desc mean_desc() const
分散のメモリー記述子を返します。
戻り値: 分散のメモリー記述子。
struct dnnl::layer_normalization_backward: public dnnl::primitive
レイヤー正規化逆伝搬プリミティブ。
パブリック関数layer_normalization_backward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
layer_normalization_backward(const primitive_desc &pd)
レイヤー正規化逆伝搬プリミティブを構築します。
パラメーター• pd: レイヤー正規化逆伝搬プリミティブのプリミティブ記述子。
struct desc
レイヤーの正規化逆方向伝搬プリミティブの記述子。
パブリック関数desc(prop_kind
aprop_kind,
const
memory::desc&diff_data_desc,
const
memory::desc&data_desc,
constmemory::desc&stat_desc,
float
epsilon,normalization_flags flags)
レイヤーの正規化逆方向伝搬プリミティブの記述子を構築します。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::backward_data とdnnl::prop_kind::backward (この場合、すべてのパラメーターの差分が計算されます)。
• diff_data_desc: 差分ソースと差分デスティネーションのメモリー記述子。
• data_desc: ソースメモリー記述子。
• stat_desc: 統計メモリー記述子。
• epsilon: レイヤーの正規化イプシロン・パラメーター。
• flags: レイヤー正規化フラグ (dnnl::normalization_flags)。
desc(prop_kind
aprop_kind,
const
memory::desc&diff_data_desc,
memory::desc &data_desc, float epsilon, normalization_flags flags)
レイヤーの正規化逆方向伝搬プリミティブの記述子を構築します。

const

パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::backward_data とdnnl::prop_kind::backward (この場合、すべてのパラメーターの差分が計算されます)。
• diff_data_desc: 差分ソースと差分デスティネーションのメモリー記述子。

5.5 プリミティブ

149

oneAPI 仕様 リリース 1.0 リビジョン 3• data_desc: ソースメモリー記述子。
• epsilon: レイヤーの正規化イプシロン・パラメーター。
• flags: レイヤー正規化フラグ (dnnl::normalization_flags)。
struct primitive_desc: public dnnl::primitive_desc
レイヤー正規化逆伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const
desc&adesc,const
enginelayer_normalization_forward::primitive_desc &hint_fwd_pd,
false)
レイヤー正規化逆方向伝搬プリミティブのプリミティブ記述子を構築します。

&aengine,
constbool allow_empty =パラメーター• adesc: レイヤーの正規化逆方向伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• hint_fwd_pd: レイヤー正規化順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr &attr, const engine&aengine, const layer_normalization_forward::primitive_desc &hint_fwd_pd, bool
allow_empty = false)
レイヤー正規化逆方向伝搬プリミティブのプリミティブ記述子を構築します。
パラメーター• adesc: レイヤーの正規化逆方向伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• hint_fwd_pd: レイヤー正規化順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc weights_desc() const
重みメモリー記述子を返します。

5.5 プリミティブ

150

oneAPI 仕様 リリース 1.0 リビジョン 3
戻り値: 重みメモリー記述子。
戻り値: プリミティブに重みパラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_src_desc() const
差分ソースメモリー記述子を返します。
戻り値: 差分ソースメモリー記述子。
戻り値: プリミティブに差分ソースメモリーがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_desc() const
差分デスティネーション・メモリー記述子を返します。
戻り値: 差分デスティネーション・メモリー記述子。
戻り値: プリミティブに差分デスティネーション・メモリーがない場合は、ゼロメモリー記述子。
memory::desc diff_weights_desc() const
差分重みメモリー記述子を返します。
戻り値: 差分重みメモリー記述子。
戻り値: プリミティブに差分重みパラメーターがない場合は、ゼロメモリー記述子。
memory::desc mean_desc() const
平均メモリー記述子を返します。
戻り値: 平均メモリー記述子。
memory::desc mean_desc() const
分散のメモリー記述子を返します。
戻り値: 分散のメモリー記述子。
memory::desc workspace_desc() const
ワークスペース・メモリー記述子を返します。
戻り値: ワークスペース・メモリー記述子。

5.5 プリミティブ

151

oneAPI 仕様 リリース 1.0 リビジョン 3
戻り値: プリミティブがワークスペース・パラメーターを要求しない場合は、ゼロメモリー記述子。

5.5.10 LogSoftmax
logsoftmax プリミティブは、任意の次元のデータに対し特定の軸に沿ってソフトマックスを実行し、その後に対数関数を実行します。他のすべての軸は独立している (バッチ) として扱われます。
一般に、操作は次の式で定義されます。変数名は標準規則に従います。
順方向 (前方)
2 番目の形式は、数値的に安定しているものとして使用されます。

説明:• c 軸に対し logsoftmax 計算が行われ、• ou
̅̅̅ は最外のインデックス (logsoftmax 軸の左側) であり、
• in
̅ は最内のインデックス (logsoftmax 軸の右側) で、• ν は、正確な結果を得るため使用され、次のように定義されます。

順方向訓練と順方向推論の違い
forward_training と forward_inference 伝搬の種類に違いはありません。
逆方向 (後方)
逆方向伝搬は、diff_dst(ou, c, in) と dst(ou, c, in) に基づいて diff_src(ou, c, in) を計算します。
実行引数実行時に入力と出力は、次の表で示す実行引数インデックスにマップする必要があります。

5.5 プリミティブ

プリミティブの入力/出力
src

実行引数インデックス
DNNL_ARG_SRC

dst

DNNL_ARG_DST

diff_src

DNNL_ARG_DIFF_SRC

diff_dst

DNNL_ARG_DIFF_DST

152

oneAPI 仕様 リリース 1.0 リビジョン 3
操作の詳細
順方向と逆方向の両方でインプレース操作がサポートされ、src は順方向伝搬の入力および出力として使用でき、
diff_dst は逆伝搬の入力および出力として使用できます。インプレースの場合、元のデータは上書きされます。
post-op と属性
logsoftmax プリミティブは post-op や属性をサポートしません。
サポートされるデータ型
logsoftmax プリミティブ化では次のデータ型の組み合わせをサポートします。
注: この節では、可読性のためデータ型の名称を省略しています。例えば、dnnl::memory::data_type::f32 は、
f32 に省略されます。
伝搬

ソース/デスティネーション

順方向/逆方向

bf16、f32

データ表現
ソース、デスティネーション、およびそれらの勾配
logsoftmax プリミティブは任意のデータテンソルで機能します。論理的な次元については特別な意味はありません。
logsoftmax 軸は、通常、チャネルと呼ばれます (従って、式では c を使用します)。
API
struct dnnl::logsoftmax_forward: public dnnl::primitive
logsoftmax 順伝搬プリミティブ。
パブリック関数
logsoftmax_forward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
logsoftmax_forward(const primitive_desc &pd)
logsoftmax 順伝搬プリミティブを構築します。
パラメーター• pd: logsoftmax 順伝搬プリミティブのプリミティブ記述子。
struct desc
LogSoftmax 順伝搬プリミティブの記述子。
パブリック関数desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
desc(prop_kind aprop_kind, constmemory::desc &data_desc, int logsoftmax_axis)
logsoftmax 順伝搬プリミティブの記述子を構築します。
5.5 プリミティブ

153

oneAPI 仕様 リリース 1.0 リビジョン 3
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• data_desc: ソースとデスティネーション・メモリー記述子。
• logsoftmax_axis: ソフトマックスが計算される軸。
struct primitive_desc: public dnnl::primitive_desc
logsoftmax 順伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const desc &adesc, const engine &aengine,
false)
logsoftmax 順伝搬プリミティブのプリミティブ記述子を構築します。

bool

allow_empty=

パラメーター• adesc: logsoftmax 順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine, bool allow_empty = false)
logsoftmax 逆伝搬プリミティブのプリミティブ記述子を作成します。

&attr,

const

engine

パラメーター• adesc: LogSoftmax 順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• attr: 使用するプリミティブ属性。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。
5.5 プリミティブ

154

oneAPI 仕様 リリース 1.0 リビジョン 3

struct dnnl::logsoftmax_backward: public dnnl::primitive
Logsoftmax 逆伝搬プリミティブ。
パブリック関数
logsoftmax_backward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
logsoftmax_backward(const primitive_desc &pd)
Logsoftmax 逆伝搬プリミティブを構築します。
パラメーター• pd: Logsoftmax 逆伝搬プリミティブのプリミティブ記述子。
struct desc
logsoftmax 逆伝搬プリミティブの記述子。
パブリック関数desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
desc(const memory::desc &diff_data_desc, const
logsoftmax_axis)
logsoftmax 逆伝搬プリミティブの記述子を作成します。

memory::desc&data_desc,

int

パラメーター• diff_data_desc: 差分ソースと差分デスティネーションのメモリー記述子。
• data_desc: デスティネーション・メモリー記述子。
• logsoftmax_axis: ソフトマックスが計算される軸。
struct primitive_desc: public dnnl::primitive_desc
Logsoftmax 逆伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const desc
&adesc,const
engine&aengine,logsoftmax_forward::primitive_desc &hint_fwd_pd, bool allow_empty = false)
logsoftmax 逆伝搬プリミティブのプリミティブ記述子を構築します。

const

パラメーター• adesc: logsoftmax 逆伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• hint_fwd_pd: logsoftmax 順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
5.5 プリミティブ

155

oneAPI 仕様 リリース 1.0 リビジョン 3

primitive_desc(const desc &adesc, const primitive_attr&aengine,
const
logsoftmax_forward::primitive_desc
allow_empty = false)
logsoftmax 逆伝搬プリミティブのプリミティブ記述子を構築します。

&attr, const&hint_fwd_pd,

enginebool

パラメーター• adesc: logsoftmax 逆伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• hint_fwd_pd: logsoftmax 順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_src_desc() const
差分ソースメモリー記述子を返します。
戻り値: 差分ソースメモリー記述子。
戻り値: プリミティブに差分ソースメモリーがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。

5.5.11 ローカル応答の正規化
LRN プリミティブは、次の式で定義される順方向もしくは逆方向のローカル応答正規化操作を行います。変数名は標準規則に従います。
前方 (順方向)
チャネル間の LRN は次のようになります。

5.5 プリミティブ

156

oneAPI 仕様 リリース 1.0 リビジョン 3

チャネル内の LRNは は以下です。

ここで、nl は local_size です。2D 空間データ向けの式が提供されています。
逆方向 (後方)逆伝搬は、diff_dst(n, c, ℎ, w) および src(n, c, ℎ, w) に基づいて diff_src(n, c, ℎ, w) を計算します。
実行引数
実行時に入力と出力は、次の表で示す実行引数インデックスにマップする必要があります。
プリミティブの入力/出力
src

実行引数インデックス
DNNL_ARG_SRC

dst

DNNL_ARG_DST

workspace

DNNL_ARG_WORKSPACE

diff_src

DNNL_ARG_DIFF_SRC

diff_dst

DNNL_ARG_DIFF_DST

操作の詳細
1.

2.

訓練中、LRN は順方向パスと逆方向パスでワークスペースを必要とする場合があります。動作は実行に依存します。最適化された実装では、通常ワークスペースが必要であり、順方向パスからの中間結果を保存して、逆方向パスの計算を高速化します。ワークスペースが必要であるか確認するには、ワークスペー
スの LRN プリミティブ記述子を照会します。照会が成功した場合、ワークスペースが必要であり、その記述子が返ります。
src と dest のメモリー形式とデータ型は同一であると想定され、API ではデータとして参照されます(dnnl::lrn_forward::desc::desc() の data_desc を 参 照 ) 。 同 じ こ と が diff_src とdiff_dst にも当てはまります。対応するメモリー記述子は diff_data_desc と呼ばれます。

サポートされるデータ型
LRN プリミティブは次のデータ型の組み合わせをサポートします。
注: この節では、可読性のためデータ型の名称を省略しています。例えば、dnnl::memory::data_type::f32 は、
f32 に省略されます。

5.5 プリミティブ

157

oneAPI 仕様 リリース 1.0 リビジョン 3
伝搬

ソース/デスティネーション

順方向/逆方向

f32、bf16
f16

順方向

データ表現
ソース、デスティネーション、およびそれらの勾配
他のプリミティブと同様に、LRN プリミティブは次のテンソルを想定します。
空間

ソース/デスティネーション

0D

N × C

1D

N × C × W

2D

N × C × H × W

3D

N × C × D × H × W

LRN プリミティブは次のメモリー形式に最適化されています。
空間2D

論理テンソル
NCHW

メモリー形式向けに最適化された実装
nchw (abcd)、nhwc(acdb)、最適化済み

ここでいう最適化とは、前述の計算集約型プリミティブによって選択された形式を意味します。
post-op と属性
LRN プリミティブは post-op や属性をサポートしません。
API
struct dnnl::lrn_forward: public dnnl::primitive
ローカル応答正規化 (LRN) 順伝搬プリミティブ。
パブリック関数
lrn_forward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
lrn_forward(const primitive_desc &pd) LRN
順伝搬プリミティブを構築します。
パラメーター• pd: LRN 順伝搬プリミティブのプリミティブ記述子。
struct desc
LRN 順伝搬プリミティブの記述子。

5.5 プリミティブ

158

oneAPI 仕様 リリース 1.0 リビジョン 3
パブリック関数desc(prop_kind aprop_kind, algorithm aalgorithm, const memory::desc &data_desc,
memory::dim local_size, float alpha, float beta, float k = 1.f)
LRN 順伝搬プリミティブの記述子を構築します。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• aalgorithm: LRN アルゴリズムの種別は、dnnl::algorithm::lrn_across_channels ま
たは dnnl::algorithm::lrn_within_channel のいずれかです。
• data_desc: ソースとデスティネーション・メモリー記述子。
• local_size: 正規化ローカルサイズ。
• alpha: アルファ正規化パラメーター。
• beta: ベータ正規化パラメーター。
• k: k 正規化パラメーター。
struct primitive_desc: public dnnl::primitive_desc}
LRN 順伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const desc &adesc, const engine
false)
LRN 順伝搬プリミティブのプリミティブ記述子を構築します。

&aengine,boolallow_empty=

パラメーター• adesc: LRN 順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine, bool allow_empty = false)
LRN 順伝搬プリミティブのプリミティブ記述子を構築します。

&attr,

const

engine

パラメーター• adesc: LRN 順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• attr: 使用するプリミティブ属性。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_desc() const
ソースメモリー記述子を返します。

5.5 プリミティブ

159

oneAPI 仕様 リリース 1.0 リビジョン 3
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc workspace_desc() const
ワークスペース・メモリー記述子を返します。
戻り値: ワークスペース・メモリー記述子。
戻り値: プリミティブがワークスペース・パラメーターを要求しない場合は、ゼロメモリー記述子。
struct dnnl::lrn_backward: public dnnl::primitive
ローカル応答正規化 (LRN) 逆方向伝搬プリミティブ。
パブリック関数
lrn_backward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
eltwise_backward(const primitive_desc &pd)
LRN 逆伝搬プリミティブを構築します。
パラメーター• pd: LRN 逆伝搬プリミティブのプリミティブ記述子。
struct desc
LRN 逆伝搬プリミティブの記述子。
パブリック関数desc(algorithm aalgorithm, const memory::desc &data_desc, const memory::desc&diff_data_desc, memory::dim local_size, float alpha, float beta, float k = 1.f)
LRN 逆伝搬プリミティブの記述子を構築します。
パラメーター• aalgorithm: LRN アルゴリズムの種別は、dnnl::algorithm::lrn_across_channels ま
たは dnnl::algorithm::lrn_within_channel のいずれかです。
• diff_data_desc: 差分ソースと差分デスティネーションのメモリー記述子。
• data_desc: ソースメモリー記述子。
• local_size: 正規化ローカルサイズ。
• alpha: アルファ正規化パラメーター。
• beta: ベータ正規化パラメーター。

5.5 プリミティブ

160

oneAPI 仕様 リリース 1.0 リビジョン 3• k: k 正規化パラメーター。
struct primitive_desc: public dnnl::primitive_desc
LRN 順伝搬プリミティブのプリミティブの記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const
desc&adesc,const
engine&aengine,
lrn_forward::primitive_desc &hint_fwd_pd, bool allow_empty = false)
LRN 順伝搬プリミティブのプリミティブの記述子を構築します。

const

パラメーター• adesc: LRN 逆伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• hint_fwd_pd: LRN 順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定する
ヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr &attr, const engine&aengine, const lrn_forward::primitive_desc &hint_fwd_pd, bool allow_empty =false)
LRN 逆伝搬プリミティブのプリミティブ記述子を構築します。
パラメーター• adesc: LRN 逆伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• hint_fwd_pd: LRN 順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定する
ヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc diff_src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_desc() const
差分デスティネーション・メモリー記述子を返します。
戻り値: 差分デスティネーション・メモリー記述子。

5.5 プリミティブ

161

oneAPI 仕様 リリース 1.0 リビジョン 3
戻り値: プリミティブに差分デスティネーション・メモリーがない場合は、ゼロメモリー記述子。
memory::desc workspace_desc() const
ワークスペース・メモリー記述子を返します。
戻り値: ワークスペース・メモリー記述子。
戻り値: プリミティブがワークスペース・パラメーターを要求しない場合は、ゼロメモリー記述子。

5.5.12 行列の乗算
行列乗算 (MatMul) プリミティブは、オプションのバイアス加算により 2 つの 2D テンソルの積を計算します。変数名は標準規則に従います。

MatMul プリミティブは、複数の独立した行列乗算計算のバッチ処理もサポートします。この場合、テンソルは 3D である必要があります:バイアステンソルはオプションであり、暗黙のブロードキャストをサポートします。次元のいずれかを 1 に設定することができ、対応する次元全体で同じ値が適用されます。ただし、バイアスは dst と同じ次元数である必要があります。
実行引数実行時に入力と出力は、次の表で示す実行引数インデックスにマップする必要があります。
プリミティブの入力/出力
src

実行引数インデックス
DNNL_ARG_SRC

weights

DNNL_ARG_WEIGHTSbias

DNNL_ARG_BIAS

dst

DNNL_ARG_DST

操作の詳細
MatMul プリミティブは、実行時に指定される形状とメモリー形式の入力テンソルと出力テンソルをサポートします。実行時に与えられた次元やストライドは、プリミティブの初期化および作成段階で DNNL_RUNTIME_DIM_VAL ワイルド
カード値で指定されます。実行段階でプリミティブが計算できるよう、ユーザーは完全な形式のメモリー・オブジェクトを渡す必要があります。作成時に与えられる形状や形式に関する情報が少ないほど、実行パフォーマンスが低下することに注意してください。作成時に形状が不明である場合、特殊形式タグ any を使用して実装が対応する入力または出力形状に最適なメモリー形式を選択することはできません。一方、実行時に指定された形状を利用すると、ユーザーはプリ
ミティブを一度作成することでさまざまな状況に対応できます。
5.5 プリミティブ

162

oneAPI 仕様 リリース 1.0 リビジョン 3
サポートされるデータ型
MatMul プリミティブは、ソース、デスティネーション、重み、およびバイアステンソルのデータ型で次の組み合わせをサ
ポートします。
注: この節では、可読性のためデータ型の名称を省略しています。例えば、dnnl::memory::data_type::f32 は、
f32 に省略されます。
ソース
f32

重み
f32

デスティネーション
f32

バイアス
f32

f16

f16

f16

f16

bf16

bf16

bf16

bf16、f32

u8、s8

s8、u8

u8、s8、s32、f32

u8、s8、s32、f32

データ表現
MatMul プリミティブは、次のテンソルを想定します。
次元

ソース

重み

デスティネーション

バイアス (オプション)

2D

M × K

K × N

M × N

(M または 1) × (N または 1)

3D

MB × M × K

MB × K × N

MB × M × N(MB または 1) × (M または 1) × (N または 1)

MatMul プリミティブは、通常、メモリー・オブジェクトがプレーンメモリー形式を使用する用途向けに最適化されています (いくつかの制限がありますが、次の表を参照してください)。ただし、入力テンソルが実行時に再利用される場合、プ
レースホルダー・メモリー形式 any を使用することを推奨します。この場合、プリミティブは対応する入力テンソルに最も適したメモリー形式を設定します。
次の表は、MatMul プリミティブが最適化されるメモリー形式の組み合わせを示しています。デスティネーション・テンソ
ルのメモリー形式は、2D の場合は ab で、３D の場合は abc である必要があります。
次元

論理テンソル

MatMul は次のメモリー形式向けに最適化されています

2D

ソース: M × K、 重み: K x N

ソース: ab または ba、重み: ab または ba

3D

ソース: MB x M x K、 重み: MB x K x N

ソース: abc または acb、重み: abc または acb

5.5 プリミティブ

163

oneAPI 仕様 リリース 1.0 リビジョン 3
属性と post-op
属性と post-op により、MatMul プリミティブの動作を変えることができます。次の属性と post-op がサポートされ
ます。
型

操作

説明

属性

出力
スケール

指定されたスケーリング係数で結果をスケールします

属性

ゼロ
ポイント

対応するテンソルにゼロポイントを設定します

post-op

要素ごと

結果に要素ごとの演算を適用します

post-opsum

演算結果を上書きせずに、デスティネーション・テンソルに加算します

制限事項

Int8 計算のみ

動的な量子化を容易にするため、プリミティブは実行時に出力スケールをサポートする必要があります。プリミティブ記
述子を作成する時点でスケールが不明である場合、ユーザーは実際のスケールではなく DNNL_RUNTIME_F32_VAL
ワイルドカード値に設定された出力スケールで属性を構成できます 。その場合、ユーザーは、実行時に引数
DNNL_ARG_ATTR_OUTPUT_SCALES を指定して追加の入力メモリー・オブジェクトとしてスケールを提供する必要があります。
実行時の出力スケールと同様に、プリミティブは実行時のゼロポイントをサポートします。ゼロポイントのワイルドカー
ド値は DNNL_RUNTIME_S32_VAL です。実行ステージでは、インデックスが (DNNL_ARG_ATTR_ZERO_POINTS |DNNL_ARG_${MEMORY}) に設定された引数で対応するメモリー・オブジェクトを渡す必要があります。例えば、ソーステ
ンソルのゼロ・ポイント・メモリー引数は、インデックス (DNNL_ARG_ATTR_ZERO_POINTS | DNNL_ARG_SRC) で渡
されます。
API
struct dnnl::matmul: public dnnl::primitive
行列乗算 (matmul) プリミティブ。
パブリック関数
matmul()
デフォルト・コンストラクター。空のオブジェクトを生成します。
matmul(const primitive_desc &pd)
matmul プリミティブを構築。
パラメーター• pd: matmul プリミティブのプリミティブ記述子。
struct desc
matmul プリミティブの記述子。

5.5 プリミティブ

164

oneAPI 仕様 リリース 1.0 リビジョン 3
パブリック関数desc(const memory::desc &src_desc,
memory::desc &dst_desc)
matmul プリミティブの記述子を構築。

const

memory::desc&weights_desc,

const&weights_desc,

const

パラメーター• src_desc: ソースのメモリー記述子 (matrix A)。
• weights_desc: 重みのメモリー記述子 (matrix B)。
• dst_desc: デスティネーションのメモリー記述子 (matrix C)。
desc(const memory::desc &src_desc, const memory::desc
memory::desc &bias_desc, constmemory::desc &dst_desc)
matmul プリミティブの記述子を構築。
パラメーター• src_desc: ソースのメモリー記述子 (matrix A)。
• weights_desc: 重みのメモリー記述子 (matrix B)。
• dst_desc: デスティネーションのメモリー記述子 (matrix C)。
• bias_desc: バイアスのメモリー記述子。
struct primitive_desc: public dnnl::primitive_descmatmul プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const desc &adesc, const
false)
matmul プリミティブのプリミティブ記述子を構築。

engine&aengine,boolallow_empty=

パラメーター• adesc: matmul プリミティブの記述子。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const&aengine, bool allow_empty = false)matmul プリミティブのプリミティブ記述子を構築。

primitive_attr&attr,

const

engine

パラメーター• adesc: matmul プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。

5.5 プリミティブ

165

oneAPI 仕様 リリース 1.0 リビジョン 3

memory::desc src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc weights_desc() const
重みメモリー記述子を返します。
戻り値: 重みメモリー記述子。
戻り値: プリミティブに重みパラメーターがない場合は、ゼロメモリー記述子。
memory::desc workspace_desc() const
バイアスメモリー記述子を返します。
戻り値: バイアスメモリー記述子。
戻り値: プリミティブにバイアス・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値 プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。

5.5.13 プーリング
プーリング・プリミティブは、1D、２D、または 3D 空間データに対し順方向または逆方向の平均プーリング操作を実行します。
プーリング操作は次の式で定義されます。高次元と低次元のケースでは、一般化が容易な 2D 空間データの式のみを示します。変数名は標準の規則に従います。
順方向 (前方)最大プーリング:

5.5 プリミティブ

166

oneAPI 仕様 リリース 1.0 リビジョン 3
平均プーリング:

ここで、出力空間次元は、畳み込みと逆畳み込みと同様に計算されます。平均プーリングは 2 つのアルゴリズムをサ
ポートします。
• pooling_avg_include_padding。ここでは DENOM = KH - KW。
• pooling_avg_exclude_padding。この場合、DEMON は平均ウィンドウとイメージ間のオーバーラップ・
サイズと等しくなります。
順方向訓練と順方向推論の違い
最大プーリングでは、forward_training 伝搬種別向けのワークスペースが必要ですが、forward_inference のワークスペースは必要ありません (以下参照)。
逆方向 (後方)逆伝搬は、diff_dst(n, c, ℎ, w) に基づいて diff_src(n, c, ℎ, w) を計算し、最大プーリングではワークス
ペースを計算します。
実行引数実行時に入力と出力は、次の表で示す実行引数インデックスにマップする必要があります。
プリミティブの入力/出力
src

実行引数インデックス
DNNL_ARG_SRC

dst

DNNL_ARG_DST

workspace

DNNL_ARG_WORKSPACE

diff_src

DNNL_ARG_DIFF_SRC

diff_dst

DNNL_ARG_DIFF_DST

操作の詳細
1.

2.

訓練中、最大プーリングでは、最大値が検出されたインデックスを保持するため、前方パス(forward_training) と後方パスでワークスペースが必要になります。ワークスペースの形状は不透過であり、インデックスを復元することはできません。ただし、後方プーリングによりアップ・サンプリングが可能で す ( 一部 の検出 トポロ ジーで 使用さ れ ます ) 。 ワ ークスペー スは、
dnnl::pooling_forward::primitive_desc::workspace_desc() によって作成できます。
ユーザーは、プーリング順伝搬を作成する際に dst メモリー記述子に any メモリー形式タグ使用できます。ライブラリーは src メモリー記述子から適切な形式を判断しますが、src そのものは定義する必要があります。同様に、ユーザーはプーリング逆伝搬を作成する際に dst_src メモリー記述子にメモリー形
式タグ any を使用できます。

サポートされるデータ型
プーリング・プリミティブは次のデータ型の組み合わせをサポートします。

5.5 プリミティブ

167

oneAPI 仕様 リリース 1.0 リビジョン 3
注: この節では、可読性のためデータ型の名称を省略しています。例えば、dnnl::memory::data_type::f32 は、
f32 に省略されます。
伝搬

ソース/デスティネーション

順方向/逆方向
順方向

f32、bf16
f16

順方向

s8、u8、 s32

累積データ型 (平均プーリングにのみ使用)
f32
f16
s32

データ表現
ソース、デスティネーション、およびそれらの勾配
ほかの CNN プリミティブと同様に、プーリング・プリミティブは、データが 1D 空間の場合は N x C x W テンソル、2D
空間では N × C x H x W テンソル、3D 空間では N × C × D x H x W テンソルであると想定します。
プーリング・プリミティブは次のメモリー形式に最適化されています。
空間

データ型
f32

メモリー形式向けに最適化された実装

1D

論理テンソル
NCW

1D

NCW

2D

s32、s8、u8
f32

nwc(acb)、最適化済み*

NCHW

2D

NCHW

3D

s32、s8、u8
f32

nhwc(acdb)、最適化済み*

NCDHW

3D

NCDHW

s32、s8、u8

ndhwc(acdeb)、最適化済み*

ncw (abc)、nwc(acb)、最適化済み*

nchw (abcd)、nhwc(acdb)、最適化済み*

ncdhw (abcde)、ndhwc(acdeb)、最適化済み*

ここで、最適化済み* とは、先行する計算集約型プリミティブによって選択された形式を意味します。
post-op と属性
プーリング・プリミティブは post-op や属性をサポートしません。
API
struct dnnl::pooling_forward: public dnnl::primitive
プーリング順伝搬プリミティブ。
パブリック関数
pooling_forward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
pooling_forward(const primitive_desc &pd)
プーリング順伝搬プリミティブを構築。
パラメーター• pd: プーリング順伝搬プリミティブのプリミティブ記述子。
struct desc
プーリング順伝搬プリミティブの記述子。

5.5 プリミティブ

168

oneAPI 仕様 リリース 1.0 リビジョン 3
パブリック関数desc(prop_kind aprop_kind, algorithm aalgorithm, constmemory::desc &src_desc,
constmemory::desc&dst_desc,
constmemory::dims&strides,constmemory::dims&kernel, const memory::dims &padding_l, constmemory::dims &padding_r)
プーリング順伝搬プリミティブの記述子を構築します。
配列の strides、kernel、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テンソルの場合)、および幅の順です。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• aalgorithm: プーリング・アルゴリズムの種別: dnnl::algorithm::pooling_max、dnnl::algorithm::pooling_avg_include_padding、またはdnnl::algorithm::pooling_avg(dnnl::algorithm::pooling_avg_exclude_padding と同様)。
• src_desc: ソースメモリー記述子。
• dst_desc: デスティネーション・メモリー記述子。
• strides: 空間次元のストライドのベクトル。
• kernel: カーネル空間次元のベクトル。
• padding_l: 各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル。
• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
struct primitive_desc: public dnnl::primitive_desc
プーリング順伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const desc &adesc, const engine &aengine,
false)
プーリング順伝搬プリミティブのプリミティブ記述子を構築します。

bool

allow_empty=

パラメーター• adesc: プーリング順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine, bool allow_empty = false)
プーリング順伝搬プリミティブのプリミティブ記述子を作成します。

5.5 プリミティブ&attr,

const

engine169

oneAPI 仕様 リリース 1.0 リビジョン 3
パラメーター• adesc: プーリング順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• attr: 使用するプリミティブ属性。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc workspace_desc() const
ワークスペース・メモリー記述子を返します。
戻り値: ワークスペース・メモリー記述子。
戻り値: プリミティブがワークスペース・パラメーターを要求しない場合は、ゼロメモリー記述子。
struct dnnl::pooling_backward: public dnnl::primitive
プーリング逆伝搬プリミティブ。
パブリック関数
pooling_backward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
pooling_backward(const primitive_desc &pd)
プーリング逆伝搬プリミティブを構築。
パラメーター• pd: プーリング逆伝搬プリミティブのプリミティブ記述子。
struct desc
プーリング逆伝搬プリミティブの記述子。

5.5 プリミティブ

170

oneAPI 仕様 リリース 1.0 リビジョン 3
パブリック関数desc(algorithm aalgorithm, const memory::desc &diff_src_desc, const memory::desc&diff_dst_desc, const memory::dims &strides, const memory::dims &kernel, const
memory::dims &padding_l, constmemory::dims &padding_r)
プーリング逆伝搬プリミティブの記述子を構築します。
配列の strides、kernel、padding_l、および padding_r には、空間次元の値のみが含まれるため、空間次元と同じ数の要素が必要です。値の順番はテンソルと同様です。深さ (3D テンソルの場合)、高さ (2D および 3D テンソルの場合)、および幅の順です。
パラメーター• aalgorithm: プーリング・アルゴリズムの種別: dnnl::algorithm::pooling_max、dnnl::algorithm::pooling_avg_include_padding、またはdnnl::algorithm::pooling_avg(dnnl::algorithm::pooling_avg_exclude_padding と同様)。
• diff_src_desc: 差分ソースメモリー記述子。
• diff_dst_desc: 差分デスティネーション・メモリー記述子。
• strides: 空間次元のストライドのベクトル。
• kernel: カーネル空間次元のベクトル。
• padding_l: 各空間次元 ([[front,] top,] left) の低いインデックスのパディング値のベク
トル。
• padding_r: 各空間次元 ([[back,] bottom,] right) の高いインデックスのパディング値のベクトル。
struct primitive_desc: public dnnl::primitive_desc
プーリング逆伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const
desc&adesc,const
engine&aengine,pooling_forward::primitive_desc &hint_fwd_pd, bool allow_empty = false)
プーリング逆伝搬プリミティブのプリミティブ記述子を作成します。

const

パラメーター• adesc: プーリング逆伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• hint_fwd_pd: プーリング順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr &attr, const engine&aengine, const pooling_forward::primitive_desc &hint_fwd_pd, bool allow_empty =false)
プーリング逆伝搬プリミティブのプリミティブ記述子を作成します。

5.5 プリミティブ

171

oneAPI 仕様 リリース 1.0 リビジョン 3
パラメーター• adesc: プーリング逆伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• hint_fwd_pd: プーリング順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc diff_src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_desc() const
差分デスティネーション・メモリー記述子を返します。
戻り値: 差分デスティネーション・メモリー記述子。
戻り値: プリミティブに差分デスティネーション・メモリーがない場合は、ゼロメモリー記述子。
memory::desc workspace_desc() const
ワークスペース・メモリー記述子を返します。
戻り値: ワークスペース・メモリー記述子。
戻り値: プリミティブがワークスペース・パラメーターを要求しない場合は、ゼロメモリー記述子。

5.5.14 リオーダー
2 つのメモリー・オブジェクト間でデータをコピーするプリミティブ。このプリミティブは、通常、データがメモリーに配置される方法を変更する際に使用されます。
リオーダー・プリミティブは、異なるメモリー形式間でデータをコピーしますが、数学的観点からはテンソルを変更することはありません。変数名は標準の規則に従います。
、「はじめに」で説明したように、最高のパフォーマンスを達成するため、一部のプリミティブ (畳み込みなど) では最適化されたメモリー形式と呼ばれる特殊なメモリー形式が求まられます。最適化されたメモリー形式では、データが保存されているメモリー形式と一致する場合としない場合があります。この場合、ユーザーはリオーダー・プリミティブを使用してメモリー形式間でデータをコピー (並べ替え) できます。

5.5 プリミティブ

172

oneAPI 仕様 リリース 1.0 リビジョン 3
属性と post-op を使用して、ユーザーはリオーダー・プリミティブによりデータを量子化することもできます (必要に応じてメモリー形式を同時に変更します)。
実行引数
実行時に入力と出力は、次の表で示す実行引数インデックスにマップする必要があります。
プリミティブの入力/出力
src

実行引数インデックス
DNNL_ARG_FROM

dst

DNNL_ARG_TO

操作の詳細
1.
2.

リオーダー・プリミティブでは、ソースとデスティネーション・テンソルは同一形状である必要があります。
暗黙のブロードキャストはサポートされません。
ほとんどの場合、リオーダーは任意のソースとデスティネーションのメモリー形式とデータ型で処理できるはずですが、一部の組み合わせが実装されていない場合にリオーダーが発生する可能性があります。次に例を示します。
• 非プレーンメモリー形式では、重み間の並べ替え実装が制限される場合があります (ただし、実際に発生した場合は、バグとして oneDNN チームに報告してください)。
• ある Winograd 形式の重みを他の Winograd 形式の重みに並べ替えることはできません。
• #dnnl_s8 ソースデータ型の畳み込み量子化された重みは、#dnnl_f32 データ型に逆量子化することはできません;

3.

この問題を軽減するため、ユーザーはオリジナルのプレーンメモリー形式とデータ型から、選択されたデータ型に最適化された形式への並べ替えを実装する必要があります。

サポートされるデータ型
リオーダー・プリミティブは、ソースとデスティネーションの任意のデータ型をサポートします。
データをあるデータ型からそれより小さなデータ型へ変換する場合、飽和が必要になります。次に例を示します。
reorder(src={1024, data_type=f32}, dst={, data_type=s8})// dst == {127}reorder(src={-124, data_type=f32}, dst={, data_type=u8})// dst == {0}データ表現
リオーダー・プリミティブは任意のデータテンソルで機能します。論理的な次元については特別な意味はありません。

5.5 プリミティブ

173

oneAPI 仕様 リリース 1.0 リビジョン 3
post-op と属性
リオーダー・プリミティブは、次の属性と post-op をサポートする必要があります。
型

操作

属性

出力
スケール
post-op Sum

説明

制限事項

指定されたスケーリング係数で結果をスケールします
演算結果を上書きせずに、デスティネーション・テンソルに加算します。

次に疑似コードを示します。
reorder(src = {dims={N, C, H, W}, data_type=dt_src, memory_format=fmt_src},
dst = {dims={N, C, H, W}, data_type=dt_dst, memory_format=fmt_dst},
attr ={
output_scale=alpha,post-ops = { sum={scale=beta} },})これは次の操作につながります。

注: 中間操作は、単精度浮動小数点データ型を使用して実行されます。
API
struct dnnl::reorder: public dnnl::primitive
再配置プリミティブ。
パブリック関数
reorder()
デフォルト・コンストラクター。空のオブジェクトを生成します。
reorder(const primitive_desc &pd)
再配置プリミティブの構築。
パラメーター• pd: リオーダー・プリミティブのプリミティブ記述子。
reorder(const memory &src, const memory &dst, const primitive_attr &attr =primitive_attr())
メモリー・オブジェクト src と dst と同じメモリー記述子を持つメモリー・オブジェクト間で、データを並べ替えるリオーダー・プリミティブを構築します。
パラメーター• src: ソース・メモリー・オブジェクト。

5.5 プリミティブ

174

oneAPI 仕様 リリース 1.0 リビジョン 3• dst: デスティネーション・メモリー・オブジェクト。
• attr: 使用するプリミティブ属性 (オプション)。
void execute(const stream &astream, memory &src, memory &dst) const
リオーダー・プリミティブの実行。
パラメーター• astream: ストリーム・オブジェクト。ストリームはプリミティブと同じエンジンに属している必要があります。
• src: ソース・メモリー・オブジェクト。
• dst: デスティネーション・メモリー・オブジェクト。
struct primitive_desc: public dnnl::primitive_desc_base
再配置プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const engine &src_engine, const memory::desc &src_md, const
engine &dst_engine, const memory::desc &dst_md, const primitive_attr &attr =primitive_attr(), bool allow_empty = false)
再配置プリミティブのプリミティブ記述子を構築。
注: allow_empty が true の場合、プリミティブ記述子を作成できなくてもコンストラクターは例外をス
ローしません。
パラメーター• src_engine: ソース・メモリー・オブジェクトが配置されるエンジン。
• src_md: ソースメモリー記述子。
• dst_engine: デスティネーション・メモリー・オブジェクトが配置されるエンジン。
• dst_md: デスティネーション・メモリー記述子。
• attr: 使用するプリミティブ属性 (オプション)。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const memory &src, const memory &dst, const primitive_attr &attr= primitive_attr(), bool allow_empty = false)
再配置プリミティブのプリミティブ記述子を構築。
パラメーター• src: ソース・メモリー・オブジェクト。これは、ソースメモリー記述子とエンジンを取得するために使用されます。
• dst: デスティネーション・メモリー・オブジェクト。これは、デスティネーション・メモリー記述子とエンジンを取得するために使用されます。
• attr: 使用するプリミティブ属性 (オプション)。

5.5 プリミティブ

175

oneAPI 仕様 リリース 1.0 リビジョン 3• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
engine get_src_engine() const
ソースメモリーが配置されているエンジンを返します。
戻り値: ソースメモリーが配置されているエンジン。
engine get_dst_engine() const
デスティネーション・メモリーが配置されているエンジンを返します。
戻り値: デスティネーション・メモリーが配置されているエンジン。
memory::desc src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。

5.5.15 リサンプリング
リサンプリング・プリミティブは、1D、２D、または 3D 空間データの順方向または逆方向のリサンプリングリング操作を計算します。リサンプリングは、サポートされる補間アルゴリズムを使用して、オリジナルのテンソルの空間スケーリン
グを行います。
• 近傍法• 線形 (または 2D 空間テンソルでは双線形、3D 空間テンソルでは三線形)。
リサンプリング操作は、それぞれの空間次元のソーステンソルとスケーリング係数によって定義されます。アップ・サン
プリングとダウン・サンプリングは、すべてのスケーリング係数が 1 よりも大きい (アップ・サンプリング)、または小さい(ダウン・サンプリング) 場合に適用されるリサンプリングの代替用語です。
リサンプリング操作は次の式で定義されます。高次元と低次元のケースでは、一般化が容易な 2D 空間データの式のみを示します。変数名は標準の規則に従います。
src と dst はそれぞれ N × C × IH × IW と N × C × OH × OW テンソルとします。
は、それぞれの空間次元のスケーリング係数を定義します。

5.5 プリミティブ

176

oneAPI 仕様 リリース 1.0 リビジョン 3
次の式は、oneDNN が近傍法および双一次補間法のリサンプリングを計算する方法を示します。式を単純にするため、以下を前提とします。
• src(n, ic, iℎ, iw) = 0、 iℎ < 0 または iw < 0 の場合、
• src(n, ic, iℎ, iw) = src(n, ic, IH − 1, iw)、 iℎ ≥ IH の場合、
• src(n, ic, iℎ, iw) = src(n, ic, IW − 1)、 iw ≥ IW の場合。
順方向 (前方)近傍リサンプリング

説明:

バイリニア・リサンプリング

説明:

5.5 プリミティブ

177

oneAPI 仕様 リリース 1.0 リビジョン 3
順方向訓練と順方向推論の違い
forward_training と forward_inference 伝搬の種類に違いはありません。
後方 (逆方向)
逆方向伝搬は、diff_dst に基づいて diff_src を計算します。
実行引数実行時に入力と出力は、次の表で示す実行引数インデックスにマップする必要があります。
プリミティブの入力/出力
src

実行引数インデックス
DNNL_ARG_SRC

dst

DNNL_ARG_DST

diff_src

DNNL_ARG_DIFF_SRC

diff_dst

DNNL_ARG_DIFF_DST

操作の詳細
1.

2.

リサンプリングの実装では、任意のデータタグ (nchw、nhwc など) のデータをサポートしますが、src とdst のメモリータグは同一であると期待されます。リサンプリング・プリミティブは、dst および ｄiff_src
メモリータグ any をサポートし、ソース形式に基づいてデスティネーション形式を定義します。
リサンプリング記述子は、ソースとデスティネーションのメモリー記述子、ソース記述子と浮動小数点係
数のみ、またはソースとデスティネーションのメモリー記述子と係数を指定して作成できます。ユーザーがデスティネーション記述子を指定しない場合、デスティネーションの次元は次の係数から推測されます。

注: リサンプリング・アルゴリズムは、の関係が成り立つ係数を使用しますが、これは必ずしもユーザーが指定するものと同一ではありません。
サポートされるデータ型
リサンプリング・プリミティブは、ソース・メモリー・オブジェクトをデスティネーション・メモリー・オブジェクトのデータ型
で次の組み合わせをサポートします。
注: この節では、可読性のためデータ型の名称を省略しています。例えば、dnnl::memory::data_type::f32 は、
f32 に省略されます。
伝搬

ソース / デスティネーション

順方向 / 逆方向

f32、bf16

順方向

f16、s8、 u8

post-op と属性
リサンプリング・プリミティブは post-op や属性をサポートしません。

5.5 プリミティブ

178

oneAPI 仕様 リリース 1.0 リビジョン 3APIstruct dnnl::resampling_forward: public dnnl::primitive
リサンプリング順伝搬。
パブリック関数resampling_forward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
pooling_forward(const primitive_desc &pd)
リサンプリング順伝搬プリミティブを構築。
パラメーター• pd: リサンプリング順伝搬プリミティブのプリミティブ記述子。
struct desc
リサンプリング順伝搬の記述子。
パブリック関数desc(prop_kind aprop_kind, algorithm aalgorithm, constmemory::desc &src_desc,
constmem- ory::desc &dst_desc)
ソースおよびデスティネーション・メモリー記述子を使用して、リサンプリング順伝搬プリミティブの記述子を構築します。
注: デスティネーション・メモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化できます。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• aalgorithm: リサンプリング・アルゴリズムの種別は、dnnl::algorithm::resampling_nearest
または dnnl::algorithm::resampling_linear です。
• src_desc: ソースメモリー記述子。
• dst_desc: デスティネーション・メモリー記述子。
desc(prop_kind
aprop_kind,algorithm
aalgorithm,
const
std::vector<float>&factors, const memory::desc &src_desc)
ソースメモリー記述子と係数を使用して、リサンプリング順伝搬プリミティブの記述子を構築します。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• aalgorithm: リサンプリング・アルゴリズムの種別は、dnnl::algorithm::resampling_nearest
または dnnl::algorithm::resampling_linear です。
• factors: 空間次元のスケーリング係数のベクトル。
• src_desc: ソースメモリー記述子。

5.5 プリミティブ

179

oneAPI 仕様 リリース 1.0 リビジョン 3desc(prop_kind
aprop_kind,algorithm
aalgorithm,
const
std::vector<float>&factors, const memory::desc &src_desc, constmemory::desc &dst_desc)
リサンプリング順伝搬プリミティブ記述子を構築します。
注: デスティネーション・メモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化できます。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• aalgorithm: リサンプリング・アルゴリズムの種別は、dnnl::algorithm::resampling_nearest
または dnnl::algorithm::resampling_linear です。
• factors: 空間次元のスケーリング係数のベクトル。
• src_desc: ソースメモリー記述子。
• dst_desc: デスティネーション・メモリー記述子。
struct primitive_desc: public dnnl::primitive_desc
リサンプリング順伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const desc &adesc, const engine &aengine,
false)
リサンプリング順伝搬プリミティブのプリミティブ記述子を構築します。

bool

allow_empty=

パラメーター• adesc: リサンプリング順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine, bool allow_empty = false)
リサンプリング順伝搬プリミティブのプリミティブ記述子を作成します。

&attr,

const

engine

パラメーター• adesc: リサンプリング順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• attr: 使用するプリミティブ属性。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
5.5 プリミティブ

180

oneAPI 仕様 リリース 1.0 リビジョン 3

戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。
struct dnnl::resampling_backward: public dnnl::primitive
リサンプリング逆伝搬プリミティブ。
パブリック関数resampling_backward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
resampling_backward(const primitive_desc &pd)
リサンプリング逆伝搬プリミティブを構築。
パラメーター• pd: リサンプリング逆伝搬プリミティブのプリミティブ記述子。
struct desc
リサンプリング逆伝搬プリミティブの記述子。
パブリック関数desc(algorithm aalgorithm, const memory::desc &diff_src_desc, const memory::desc&diff_dst_desc)
ソースおよびデスティネーション・メモリー記述子を使用して、リサンプリング逆方向伝搬プリミティブ記述子
を構築します。
パラメーター• aalgorithm: リサンプリング・アルゴリズムの種別は、dnnl::algorithm::resampling_nearest
または dnnl::algorithm::resampling_linear です。
• diff_src_desc: 差分ソースメモリー記述子。
• diff_dst_desc: 差分デスティネーション・メモリー記述子。
desc(algorithm aalgorithm,
const std::vector<float> &factors,
memory::desc &diff_src_desc, constmemory::desc &diff_dst_desc)
リサンプリング逆伝搬プリミティブ記述子を構築します。

const

パラメーター• aalgorithm: リサンプリング・アルゴリズムの種別は、dnnl::algorithm::resampling_nearest
または dnnl::algorithm::resampling_linear です。
• factors: 空間次元のスケーリング係数のベクトル。
• diff_src_desc: 差分ソースメモリー記述子。

5.5 プリミティブ

181

oneAPI 仕様 リリース 1.0 リビジョン 3• diff_dst_desc: 差分デスティネーション・メモリー記述子。
struct primitive_desc: public dnnl::primitive_desc
リサンプリング逆伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const desc &adesc, const engine&aengine,
resampling_forward::primitive_desc &hint_fwd_pd, bool allow_empty = false)
リサンプリング逆伝搬プリミティブのプリミティブ記述子を構築します。

const

パラメーター• adesc: リサンプリング逆伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• hint_fwd_pd: リサンプリング順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr &attr, const engine&aengine, constresampling_forward::primitive_desc &hint_fwd_pd, bool allow_empty= false)リサンプリング逆伝搬プリミティブのプリミティブ記述子を構築します。
パラメーター• adesc: リサンプリング逆伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• hint_fwd_pd: リサンプリング順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc diff_src_desc() const
差分ソースメモリー記述子を返します。
戻り値: 差分ソースメモリー記述子。
戻り値: プリミティブに差分ソースメモリーがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_desc() const
差分デスティネーション・メモリー記述子を返します。
戻り値: 差分デスティネーション・メモリー記述子。

5.5 プリミティブ

182

oneAPI 仕様 リリース 1.0 リビジョン 3
戻り値: プリミティブに差分デスティネーション・メモリーがない場合は、ゼロメモリー記述子。

5.5.16 RNN
RNN プリミティブは次の図に示すように、展開されたリカレントセルのスタックを計算します。ここで、 破線で囲まれた
bias、src_iter および dst_iter パラメーターはオプションです。指定されない場合、bias、src_iter はデフォ
ルトで 0 となります。変数名は標準の規則に従います。

RNN プリミティブは 4 方向の評価モードをサポートします。
• left2right (左から右) は、入力データのタイムスタンプを昇順で処理します。
• right2left (右から左) は、入力データのタイムスタンプを降順で処理します。
• bidirectional_concat (双方向結合) は、left2right と right2left からすべてのスタックレイ
ヤーを個別に処理し、チャネル次元で dst_layer の出力を結合します。
• bidirectional_sumwill (双方向累積) は、left2right と right2left からすべてのスタックレイ
ヤーを個別に処理して、2 つの出力を dst_layer に累積します。
RNN プリミティブは、src_layer、src_iter、dst_layer、および dst_iter に対して異なるチャネルの引き渡しをサポートしていますが、次元の一貫性を保つには次の条件が整う必要があります。
• channels(dst_layer) = channels(dst_iter)• T > 1 の場合、channels(src_iter) = channels(dst_iter)• L > 1 の場合、channels(src_layer) = channels(dst_layer)• bidirectional_concatdirection を使用する場合、channels(dst_layer) = 2 * channels(dst_iter)
展開された反復セルのスタックを処理する一般式は、前のレイヤーの反復 (ℎt,l−1 と ct,l−1) および現在のレイヤー(ℎt−1,l) です。非 LSTM セルの正確な式は次のとおりです。

ℎt,l = Cell (ℎt,l−1, ℎt−1,l)ここで、t、l は、タイムスタンプのインデックスと処理中のセルのレイヤーです。そして、LSTM セルの式は次のようになります。

5.5 プリミティブ

183

oneAPI 仕様 リリース 1.0 リビジョン 3(ℎt,l, ct,l) = Cell (ℎt,l−1, ℎt−1,l, ct−1,l)ここで、t、l は、タイムスタンプのインデックスと処理中のセルのレイヤーです。
セル関数
RNN API は 4 つのセル関数を提供します。
• バニラ RNN (単一ゲートのリカレントセル)• LSTM (4 ゲートの長短期間のメモリーセル)• GRU (3 ゲートのリカレント・ユニット・セル)• リセット前の線形 GRU (リセットゲートの前に線形レイヤーを持つ 3 ゲートのリカレント・ユニット・セル)
バニラ RNN
次の例は、dnnl::vanilla_rnn_forward::desc または dnnl::vanilla_rnn_forward::desc で初期化された単一ゲートのリカレントセルです。
auto vanilla_rnn_desc = dnnl::vanilla_rnn_forward::desc(
aprop, activation, direction, src_layer_desc, src_iter_desc,
weights_layer_desc, weights_iter_desc, bias_desc,
dst_layer_desc, dst_iter_desc);

バニラ RNN セルは、ReLU、Tanh、および Sigmoid 活性化関数をサポートする必要があります。次の式は、前方パスに対してバニラ RNN セルで実行される数学操作を定義しています。
at = W · ℎi,l−1 + U · ℎt−1,l + Bℎt = activation(at)
LSTM
LSTM (またはバニラ LSTM)
次の例は、dnnl::lstm_forward::desc または dnnl::lstm_backward::desc で初期化された 4 ゲートの長短期メモリー・リカレント・セルを示します。
auto lstm_desc = dnnl::lstm_forward::desc(
aprop, direction, src_layer_desc, src_iter_h_desc, src_iter_c_desc,
weights_layer_desc, weights_iter_desc, bias_desc, dst_layer_desc,
dst_iter_h_desc, dst_iter_c_desc);

ゲート数に依存する次元で構成されるすべてのテンソルは、ゲートの順番が i、f、𝑐̃ 、および o であることが、暗黙的に求められることに注意してください。次の式は、これらのゲートと前方パス出力の数学的関係を示しています。

5.5 プリミティブ

184

oneAPI 仕様 リリース 1.0 リビジョン 3

ここで、W* は weights_layer に格納され、Ｕ* は weights_iter に格納され、B* は bias に格納されます。
注: 次元の一般性を維持するため、channels(src_iter_c) = channels(dst_iter_c) = channels(dst_iter)
である必要があります。
ピープホールがある LSTM
次の例は、dnnl::lstm_forward::desc または dnnl::lstm_backward::desc で初期化されたピープホールがある 4 ゲートの LSTM (長短期メモリーリカレント) を示します。
auto lstm_desc = dnnl::lstm_forward::desc(
aprop, direction, src_layer_desc, src_iter_h_desc, src_iter_c_desc,
weights_layer_desc, weights_iter_desc, weights_peephole_desc,
bias_desc, dst_layer_desc, dst_iter_h_desc, dst_iter_c_desc);

バニラ LSTM と同様に、ゲートの順番は i、f、𝑐̃ 、および o である必要があります。ピープホールの重みのゲートの順番
は、i、f、o となります。次の式は、これらのゲートと前方パス出力の数学的関係を示しています。

ここで、P* は weights_peephole に格納され、そのほかのパラメーターはバニラ LSTM と同じです。
注: 操作記述子コンストラクターに渡される weights_peephole_desc がゼロメモリー記述子である場合、プリミ
ティブはピープホールがない LSTM プリミティブと同じように動作します。

5.5 プリミティブ

185

oneAPI 仕様 リリース 1.0 リビジョン 3
予測 LSTM
次の例は、dnnl::lstm_forward::desc または dnnl::lstm_backward::desc で初期化されたピープホールがある 4 ゲートの LSTM (長短期メモリーリカレント) を示します。
auto lstm_desc = dnnl::lstm_forward::desc(
aprop, direction, src_layer_desc, src_iter_h_desc, src_iter_c_desc,
weights_layer_desc, weights_iter_desc, weights_peephole_desc,
weights_projection_desc, bias_desc, dst_layer_desc, dst_iter_h_desc,
dst_iter_c_desc);

バニラ LSTM と同様に、ゲート依存の次元を持つすべてのテンソルのゲートの順番は、暗黙的に i、ｆ、𝑐̃ 、および o である必要があります。次の式は、これらのゲートと前方パスの出力の数学的関係を示しています (簡素化するため、ピープ
ホールのない LSTM を使用します)。

ここで、R は weights_projection に格納され、そのほかのパラメーターはバニラ LSTM と同じです。
注: 操作記述子コンストラクターに渡される weights_projection_desc がゼロメモリー記述子である場合、プリミティブは予測なし LSTM プリミティブと同じように動作します。
GRU
次の例は、dnnl::gru_forward::desc または dnnl::gru_backward::desc で初期化された 3 ゲートのリカ
レント・セル・ユニットを示します。
auto gru_desc = dnnl::gru_forward::desc(
aprop, direction, src_layer_desc, src_iter_desc,
weights_layer_desc, weights_iter_desc, bias_desc,
dst_layer_desc, dst_iter_desc);

ゲート数に依存する次元で構成されるすべてのテンソルは、ゲートの順番が u、r および o であることが、暗黙的に求められることに注意してください。次の式は、これらのゲートの数学的関係を示しています。

5.5 プリミティブ

186

oneAPI 仕様 リリース 1.0 リビジョン 3

ここで、W* は weights_layer に格納され、Ｕ* は weights_iter に格納され、B* は bias に格納されます。
注: ℎt を計算する際に ut を (1 − ut) に置き換える必要がある場合、Wu、Uu, および Bu に -1 を掛けること
でこれを実現できます。これが可能な場合、
およびが成り立ちます。
リセット前の線形 GRU
次 の 例 は 、 リ セ ッ ト ゲ ー ト の 前 に 線 形 レ イ ヤ ー が 適 用 さ れ 、 dnnl::lbr_gru_forward::desc ま た は
dnnl::lbr_gru_backward::desc で初期化される 3 ゲートのリカレント・セル・ユニットを示します。
auto lbr_gru_desc = dnnl::lbr_gru_forward::desc(
aprop, direction, src_layer_desc, src_iter_desc,
weights_layer_desc, weights_iter_desc, bias_desc,
dst_layer_desc, dst_iter_desc);

次の式は、リセット前の線形 GRU (Linear-Before-Reset GRU) セルの数学的な動作を示します。

バイアスを除いて、ゲート数に依存する次元で構成されるすべてのテンソルは、ゲートの順番が u, r および o である
ことが、暗黙的に求められることに注意してください。バイアステンソルで場合、ゲートの順番は u、 r、 o および 𝑢̃ である必要があります。
注: ℎt を計算する際に ut を (1 − ut) に置き換える必要がある場合、Wu、Uu、および Bu に -1 を掛けることでこれを実現できます。これが可能な場合、ut = (Wu · ℎt,l−1 + Uu · ℎt−1,l + Bu) および 1˘σ(a) = σ(−a) が成り立ちます。

5.5 プリミティブ

187

oneAPI 仕様 リリース 1.0 リビジョン 3
実行引数
実行時に入力と出力は、次の表で示す実行引数インデックスにマップする必要があります。
プリミティブの入力/出力

実行引数インデックス

src_layer

DNNL_ARG_SRC_LAYER

src_iter

DNNL_ARG_SRC_ITER

src_iter_c

DNNL_ARG_SRC_ITER_C

weights_layer

DNNL_ARG_WEIGHTS_LAYER

weights_iter

DNNL_ARG_WEIGHTS_ITER

weights_peephole

DNNL_ARG_WEIGHTS_PEEPHOLE

weights_projection

DNNL_ARG_WEIGHTS_PROJECTION

bias

DNNL_ARG_BIAS

dst_layer

DNNL_ARG_DST_LAYER

dst_iter

DNNL_ARG_DST_ITER

dst_iter_c

DNNL_ARG_DST_ITER_C

workspace

DNNL_ARG_WORKSPACE

diff_src_layer

DNNL_ARG_DIFF_SRC_LAYER

diff_src_iter

DNNL_ARG_DIFF_SRC_ITER

diff_src_iter_c

DNNL_ARG_DIFF_SRC_ITER_C

diff_weights_layer

DNNL_ARG_DIFF_WEIGHTS_LAYER

diff_weights_iter

DNNL_ARG_DIFF_WEIGHTS_ITER

diff_weights_peephole

DNNL_ARG_DIFF_WEIGHTS_PEEPHOLE

diff_weights_projection

DNNL_ARG_DIFF_WEIGHTS_PROJECTION

diff_bias

DNNL_ARG_DIFF_BIAS

diff_dst_layer

DNNL_ARG_DIFF_DST_LAYER

diff_dst_iter

DNNL_ARG_DIFF_DST_ITER

diff_dst_iter_c

DNNL_ARG_DIFF_DST_ITER_C

操作の詳細
なし
サポートされるデータ型
次の表に、それぞれの入力および出力メモリー・オブジェクトの RNN プリミティブでサポートする必要があるデータ型の組み合わせを示します。
注: この節では、可読性のためデータ型の名称を省略しています。例えば、dnnl::memory::data_type::f32 は、
f32 に省略されます。

5.5 プリミティブ

188

oneAPI 仕様 リリース 1.0 リビジョン 3

伝搬

セル関数

入力データ

リカレントデータ1

重み

バイアス

出力データ

順方向/逆方向

All

f32

f32

f32

f32

f32

順方向/逆方向2

All3

bf16

bf16

bf16

f32

bf16

順方向

All3

f16

f16

f16

f16

f16

順方向推測

バニラ LSTM

u8

u8

s8

f32

u8、f32

1.
2.
3.

LSTM およびピープホール STM セルでは、セル状態データ型は常に f32 型です。
逆伝搬のすべての diff_* テンソルは f32 型です。
予測 LSTM はまだ定義されていません。

データ表現
oneDNN プ ロ グ ラ ミ ン グ ・ モ デ ル で は 、 RNN プ リ ミ テ ィ ブ は プ レ ー ス ホ ル ダ ー ・ メ モ リ ー 形 式#dnnl::memory::format_tag::any (any に短縮) をサポートし、プリミティブのパラメーターに基づいてデータと重みメモリー・オブジェクト形式を定義できます。
次の表は、RNN プリミティブでサポートされるデータレイアウトを示します。
入力/出力データ

リカレント
データ

レイヤーと反復の重み

ピープホールの重みとバイアス予測 LSTM の重み

any

any

any

ldgo

any、ldio (順伝搬)ntc、tnc

ldnc

ldigo、ldgoi

ldgo

any、ldio (順伝搬)RNN プリミティブは、明示的に指定されたメモリー形式によって作成できますが、パフォーマンスは最適ではない可能性があります。any を使用する場合、最初に RNN プリミティブ記述子を作成してから、実際のデータと重みメモリー・オ
ブジェクト形式を照会する必要があります。
注: RNN プリミティブは、パディングされたテンソルとビューをサポートする必要があります。従って、2 つのメモリー記
述子が同じデータレイアウトを共有していても、それらは異なる可能性があります。
post-op と属性
現在、post-op と属性は、LSTM の int8 異種でのみ使用されます。
API
enum dnnl::rnn_flags
RNN セルフラグ。
値:
列挙子 undef
未定義 RNN フラグ。
enum dnnl::rnn_direction
RNN プリミティブ実行の方向。
5.5 プリミティブ

189

oneAPI 仕様 リリース 1.0 リビジョン 3

値:
列挙子 unidirectional_left2right
左から右への RNN プリミティブの一方向実行。
列挙子 unidirectional_right2left
右から左への RNN プリミティブの一方向実行。
列挙子 bidirectional_concat
結果を結合した RNN プリミティブの双方向実行。
列挙子 bidirectional_sum
結果を累積した RNN プリミティブの双方向実行。
列挙子 unidirectional
dnnl::rnn_direction::unidirectional_left2right のエイリアス。
struct dnnl::vanilla_rnn_forward: public dnnl::primitive
バニラ RNN 順伝搬プリミティブ。
パブリック関数
vanilla_rnn_forward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
vanilla_rnn_forward(const primitive_desc &pd)
バニラ RNN 順伝搬プリミティブの構築。
パラメーター• pd: バニラ RNN 順伝搬プリミティブのプリミティブ記述子。
struct desc
バニラ RNN 順伝搬プリミティブの記述子。
パブリック関数desc(prop_kind aprop_kind, algorithm activation, rnn_direction direction, const
memory::desc&src_layer_desc,
const
memory::desc&src_iter_desc,
const
memory::desc &weights_layer_desc, const memory::desc &weights_iter_desc, const
memory::desc &bias_desc, const memory::desc &dst_layer_desc, const memory::desc&dst_iter_desc, rnn_flags flags = rnn_flags::undef , float alpha = 0.0f, float
beta = 0.0f)
バニラ RNN 順伝搬プリミティブの記述子を構築します。
次の引数はゼロメモリー記述子を指す可能性があります。
• src_iter_desc、• bias_desc、• dst_iter_desc。
これは、RNN 順伝搬プリミティブがそれらを使用せずに、デフォルトでゼロ値でなければならないことを示します。
注: src_iter_desc を除くすべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any
値で初期化できます。

5.5 プリミティブ

190

oneAPI 仕様 リリース 1.0 リビジョン 3
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• activation: 活 性 化 の 種 別 。 使 用 可 能 な 値 は 、 dnnl::algorithm::eltwise_relu 、
dnnl::algorithm::eltwise_tanh または dnnl::algorithm::eltwise_logistic です。
• direction: RNN の方向。詳細は、dnnl::rnn_direction を参照してください。
• src_layer_desc: 入力ベクトルのメモリー記述子。
• src_iter_desc: 入力リカレント隠匿状態ベクトルのメモリー記述子。
• weights_layer_desc: レイヤー入力に適用される重みメモリー記述子。
• weights_iter_desc: リカレント入力に適用される重みメモリー記述子。
• bias_desc: バイアスメモリー記述子。
• dst_layer_desc: 出力ベクトルのメモリー記述子。
• dst_iter_desc: 出力リカレント隠匿状態ベクトルのメモリー記述子。
• flags: 未使用。
• alpha: 活性化が dnnl::algorithm::eltwise_relu である場合は負の勾配。
• beta: 未使用。
struct primitive_desc: public dnnl::rnn_primitive_desc_base
バニラ RNN 順伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const desc &adesc, const engine
false)
バニラ RNN 順伝搬プリミティブのプリミティブ記述子の構築。

&aengine,boolallow_empty=

パラメーター• adesc: バニラ RNN 順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine, bool allow_empty = false)
バニラ RNN 順伝搬プリミティブのプリミティブ記述子を構築します。

&attr,

const

engine

パラメーター• adesc: バニラ RNN 順伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_layer_desc() const
ソース・レイヤー・メモリー記述子を返します。
5.5 プリミティブ

191

oneAPI 仕様 リリース 1.0 リビジョン 3

戻り値: ソース・レイヤー・メモリー記述子。
memory::desc src_iter_desc() const
ソース反復メモリー記述子を返します。
戻り値: ソース反復メモリー記述子。
戻り値: プリミティブにソース反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc weights_layer_desc() const
重みレイヤーメモリー記述子を返します。
戻り値: 重みレイヤーメモリー記述子。
memory::desc weights_iter_desc() const
重み反復メモリー記述子を返します。
戻り値: 重み反復メモリー記述子。
memory::desc bias_desc() const
バイアスメモリー記述子を返します。
戻り値: バイアスメモリー記述子。
戻り値: プリミティブにバイアス・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_layer_desc() const
デスティネーション・レイヤー・メモリー記述子を返します。
戻り値: デスティネーション・レイヤー・メモリー記述子。
memory::desc dst_iter_desc() const
デスティネーション反復メモリー記述子を返します。
戻り値: デスティネーション反復メモリー記述子。
戻り値: プリミティブにデスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc workspace_desc() const
ワークスペース・メモリー記述子を返します。
戻り値: ワークスペース・メモリー記述子。
戻り値: プリミティブがワークスペース・パラメーターを要求しない場合は、ゼロメモリー記述子。
struct dnnl::vanilla_rnn_backward: public dnnl::primitive
バニラ RNN 逆伝搬プリミティブ。

5.5 プリミティブ

192

oneAPI 仕様 リリース 1.0 リビジョン 3
パブリック関数
vanilla_rnn_backward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
vanilla_rnn_forward(const primitive_desc &pd)
バニラ RNN 逆伝搬プリミティブの構築。
パラメーター• pd: バニラ RNN 逆伝搬プリミティブのプリミティブ記述子。
struct desc
バニラ RNN 逆伝搬プリミティブの記述子。
パブリック関数desc(prop_kind aprop_kind, algorithm activation, rnn_direction direction, const
memory::desc&src_layer_desc,
const memory::desc&src_iter_desc,
const
memory::desc &weights_layer_desc, const memory::desc &weights_iter_desc, const
memory::desc &bias_desc, const memory::desc &dst_layer_desc, const memory::desc&dst_iter_desc, const memory::desc &diff_src_layer_desc, const memory::desc&diff_src_iter_desc,
const
memory::desc&diff_weights_layer_desc,
const
memory::desc &diff_weights_iter_desc, const memory::desc &diff_bias_desc, const
memory::desc&diff_dst_layer_desc,
constmemory::desc&diff_dst_iter_desc,
rnn_flags flags = rnn_flags::undef , float alpha = 0.0f, float beta = 0.0f)
バニラ RNN 逆伝搬プリミティブの記述子を構築します。
次の引数はゼロメモリー記述子を指す可能性があります。
• src_iter_desctogether と diff_src_iter_desc、• bias_desctogether と diff_bias_desc、• dst_iter_desctogether と diff_dst_iter_desc。
これは、RNN 逆伝搬プリミティブがそれぞれのデータを使用せず、ゼロ値でなければならないことを示します。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化されます。
パラメーター• aprop_kind: 伝搬の種類。dnnl::prop_kind::backward でなければなりません。
• activation: 活 性 化 の 種 別 。 使 用 可 能 な 値 は 、 dnnl::algorithm::eltwise_relu 、
dnnl::algorithm::eltwise_tanh または dnnl::algorithm::eltwise_logistic です。
• direction: RNN の方向。詳細は、dnnl::rnn_direction を参照してください。
• src_layer_desc: 入力ベクトルのメモリー記述子。
• src_iter_desc: 入力リカレント隠匿状態ベクトルのメモリー記述子。
• weights_layer_desc: レイヤー入力に適用される重みメモリー記述子。
• weights_iter_desc: リカレント入力に適用される重みメモリー記述子。
• bias_desc: バイアスメモリー記述子。
• dst_layer_desc: 出力ベクトルのメモリー記述子。
• dst_iter_desc: 出力リカレント隠匿状態ベクトルのメモリー記述子。
• diff_src_layer_desc: 入力ベクトルの差分メモリー記述子。
• diff_src_iter_desc: 入力リカレント隠匿状態ベクトルの差分メモリー記述子。
5.5 プリミティブ

193

oneAPI 仕様 リリース 1.0 リビジョン 3• diff_weights_layer_desc: レイヤー入力に適用される重みの差分メモリー記述子。
• diff_weights_iter_desc: リカレント入力に適用される重みの差分メモリー記述子。
• diff_bias_desc: 差分バイアスメモリー記述子。
• diff_dst_layer_desc: 出力ベクトルの差分メモリー記述子。
• diff_dst_iter_desc: 出力リカレント隠匿状態ベクトルの差分メモリー記述子。
• flags: 未使用。
• alpha: 活性化が dnnl::algorithm::eltwise_relu である場合は負の勾配。
• beta: 未使用。
struct primitive_desc: public dnnl::rnn_primitive_desc_base
RNN 逆伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const
desc&adesc,const
engine&aengine,
const
vanilla_rnn_forward::primitive_desc &hint_fwd_pd, bool allow_empty = false)
バニラ RNN 逆伝搬プリミティブのプリミティブ記述子を構築します。
パラメーター• adesc: バニラ RNN 逆伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• hint_fwd_pd: バニラ RNN 順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine,
const
vanilla_rnn_forward::primitive_desc
allow_empty = false)
バニラ RNN 逆伝搬プリミティブのプリミティブ記述子を構築します。

&attr, const&hint_fwd_pd,

enginebool

パラメーター• adesc: バニラ RNN 逆伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• hint_fwd_pd: バニラ RNN 順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_layer_desc() const
ソース・レイヤー・メモリー記述子を返します。
戻り値: ソース・レイヤー・メモリー記述子。

5.5 プリミティブ

194

oneAPI 仕様 リリース 1.0 リビジョン 3
memory::desc src_iter_desc() const
ソース反復メモリー記述子を返します。
戻り値: ソース反復メモリー記述子。
戻り値: プリミティブにソース反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc weights_layer_desc() const
重みレイヤーメモリー記述子を返します。
戻り値: 重みレイヤーメモリー記述子。
memory::desc weights_iter_desc() const
重み反復メモリー記述子を返します。
戻り値: 重み反復メモリー記述子。
memory::desc bias_desc() const
バイアスメモリー記述子を返します。
戻り値: バイアスメモリー記述子。
戻り値: プリミティブにバイアス・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_layer_desc() const
デスティネーション・レイヤー・メモリー記述子を返します。
戻り値: デスティネーション・レイヤー・メモリー記述子。
memory::desc dst_iter_desc() const
デスティネーション反復メモリー記述子を返します。
戻り値: デスティネーション反復メモリー記述子。
戻り値 プリミティブにデスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc workspace_desc() const
ワークスペース・メモリー記述子を返します。
戻り値: ワークスペース・メモリー記述子。
戻り値: プリミティブがワークスペース・パラメーターを要求しない場合は、ゼロメモリー記述子。
memory::desc diff_src_layer_desc() const
差分ソース・レイヤー・メモリー記述子を返します。
戻り値: 差分ソース・レイヤー・メモリー記述子。

5.5 プリミティブ

195

oneAPI 仕様 リリース 1.0 リビジョン 3
memory::desc diff_src_iter_desc()const
差分ソース反復メモリー記述子を返します。
戻り値: 差分ソース反復メモリー記述子。
戻り値: プリミティブに差分ソース反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_weights_layer_desc() const
差分重みレイヤーメモリー記述子を返します。
戻り値: 差分重みレイヤーメモリー記述子。
memory::desc diff_weights_iter_desc() const
差分重み反復メモリー記述子を返します。
戻り値: 差分重み反復メモリー記述子。
memory::desc diff_bias_desc() const
差分バイアスメモリー記述子を返します。
戻り値: 差分バイアスメモリー記述子。
戻り値: プリミティブに差分バイアス・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_layer_desc() const
差分デスティネーション・レイヤー・メモリー記述子を返します。
戻り値: 差分デスティネーション・レイヤー・メモリー記述子。
memory::desc diff_dst_layer_desc() const
差分デスティネーション反復メモリー記述子を返します。
戻り値: 差分デスティネーション反復メモリー記述子。
戻り値: プリミティブに差分デスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。
struct dnnl::lstm_forward: publicdnnl::primitive
LSTM 順伝搬プリミティブ。
パブリック関数
lstm_forward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
lstm_forward(const primitive_desc &pd)
LSTM 順伝搬プリミティブを構築。
パラメーター• pd: LSTM 順伝搬プリミティブのプリミティブ記述子。
5.5 プリミティブ

196

oneAPI 仕様 リリース 1.0 リビジョン 3

struct desc
LSTM 順伝搬プリミティブの記述子。
パブリック関数desc(prop_kind
aprop_kind,rnn_direction
direction,
const
memory::desc&src_layer_desc,
const
memory::desc&src_iter_desc,
const
memory::desc&src_iter_c_desc, const memory::desc &weights_layer_desc, const memory::desc&weights_iter_desc,
const
memory::desc&weights_peephole_desc,
const
memory::desc &weights_projection_desc, const memory::desc &bias_desc, const
memory::desc&dst_layer_desc,
const
memory::desc&dst_iter_desc,
const
memory::desc &dst_iter_c_desc, rnn_flags flags = rnn_flags::undef )LSTM (ピープホールや予測の有無にかかわらず) 順伝搬プリミティブ記述子を構築します。
次の引数はゼロメモリー記述子を指す可能性があります。
• src_iter_desctogether と src_iter_c_desc、• weights_peephole_desc、• bias_desc、• dst_iter_desctogether と dst_iter_c_desc。
これは、LSTM 順伝搬プリミティブがそれらを使用せずに、デフォルトでゼロ値でなければならないことを示します。
weights_projection_descmay はゼロメモリー記述子を指します。これは、LSTM にリカレント予測がないことを示します。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化できます。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• direction: RNN の方向。詳細は、dnnl::rnn_direction を参照してください。
• src_layer_desc: 入力ベクトルのメモリー記述子。
• src_iter_desc: 入力リカレント隠匿状態ベクトルのメモリー記述子。
• src_iter_c_desc: 入力リカレントセル状態ベクトルのメモリー記述子。
• weights_layer_desc: レイヤー入力に適用される重みメモリー記述子。
• weights_iter_desc: リカレント入力に適用される重みメモリー記述子。
• weights_peephole_desc: セル状態に適用される重みメモリー記述子 (ピープホール LSTM 式)。
• weights_projection_desc: 隠匿状態に適用される重みメモリー記述子 (ピープホール LSTM 式)。
• bias_desc: バイアスメモリー記述子。
• dst_layer_desc: 出力ベクトルのメモリー記述子。
• dst_iter_desc: 出力リカレント隠匿状態ベクトルのメモリー記述子。
• dst_iter_c_desc: 出力リカレントセル状態ベクトルのメモリー記述子。
• flags: 未使用。
desc(prop_kind
aprop_kind,rnn_direction
direction,
const
memory::desc&src_layer_desc,
const
memory::desc&src_iter_desc,
const
memory::desc&src_iter_c_desc, const memory::desc &weights_layer_desc, const memory::desc&weights_iter_desc,
const
memory::desc&weights_peephole_desc,
const
5.5 プリミティブ

197

oneAPI 仕様 リリース 1.0 リビジョン 3
memory::desc &bias_desc, const memory::desc &dst_layer_desc, const memory::desc&dst_iter_desc,
const
memory::desc&dst_iter_c_desc,
rnn_flags
flags=
rnn_flags::undef )LSTM (ピープホールの有無にかかわらず) 順伝搬プリミティブ記述子を構築します。
次の引数はゼロメモリー記述子を指す可能性があります。
• src_iter_desctogether と src_iter_c_desc、• weights_peephole_desc、• bias_desc、• dst_iter_desctogether と dst_iter_c_desc。
これは、LSTM 順伝搬プリミティブがそれらを使用せずに、デフォルトでゼロ値でなければならないことを示します。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化できます。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• direction: RNN の方向。詳細は、dnnl::rnn_direction を参照してください。
• src_layer_desc: 入力ベクトルのメモリー記述子。
• src_iter_desc: 入力リカレント隠匿状態ベクトルのメモリー記述子。
• src_iter_c_desc: 入力リカレントセル状態ベクトルのメモリー記述子。
• weights_layer_desc: レイヤー入力に適用される重みメモリー記述子。
• weights_iter_desc: リカレント入力に適用される重みメモリー記述子。
• weights_peephole_desc: セル状態に適用される重みメモリー記述子 (ピープホール LSTM 式)。
• bias_desc: バイアスメモリー記述子。
• dst_layer_desc: 出力ベクトルのメモリー記述子。
• dst_iter_desc: 出力リカレント隠匿状態ベクトルのメモリー記述子。
• dst_iter_c_desc: 出力リカレントセル状態ベクトルのメモリー記述子。
• flags: 未使用。
desc(prop_kind
aprop_kind,rnn_direction
direction,
const
memory::desc&src_layer_desc,
const
memory::desc&src_iter_desc,
const
memory::desc&src_iter_c_desc, const memory::desc &weights_layer_desc, const memory::desc&weights_iter_desc,
const
memory::desc&bias_desc,
const
memory::desc&dst_layer_desc,
const
memory::desc&dst_iter_desc,
constmemory::desc&dst_iter_c_desc, rnn_flags flags = rnn_flags::undef )LSTM 順伝搬プリミティブの記述子を構築します。
次の引数はゼロメモリー記述子を指す可能性があります。
• src_iter_desctogether と src_iter_c_desc、• bias_desc、• dst_iter_desctogether と dst_iter_c_desc。
これは、LSTM 順伝搬プリミティブがそれらを使用せずに、デフォルトでゼロ値でなければならないことを示します。

5.5 プリミティブ

198

oneAPI 仕様 リリース 1.0 リビジョン 3

注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化できます。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• direction: RNN の方向。詳細は、dnnl::rnn_direction を参照してください。
• src_layer_desc: 入力ベクトルのメモリー記述子。
• src_iter_desc: 入力リカレント隠匿状態ベクトルのメモリー記述子。
• src_iter_c_desc: 入力リカレントセル状態ベクトルのメモリー記述子。
• weights_layer_desc: レイヤー入力に適用される重みメモリー記述子。
• weights_iter_desc: リカレント入力に適用される重みメモリー記述子。
• bias_desc: バイアスメモリー記述子。
• dst_layer_desc: 出力ベクトルのメモリー記述子。
• dst_iter_desc: 出力リカレント隠匿状態ベクトルのメモリー記述子。
• dst_iter_c_desc: 出力リカレントセル状態ベクトルのメモリー記述子。
• flags: 未使用。
struct primitive_desc: public dnnl::rnn_primitive_desc_base
LSTM 順伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const desc &adesc, const engine
false)
LSTM 順伝搬プリミティブのプリミティブ記述子を構築します。

&aengine,boolallow_empty=

パラメーター• adesc: LSTM 順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine, bool allow_empty = false)
LSTM 順伝搬プリミティブのプリミティブ記述子を構築します。

&attr,

const

engine

パラメーター• adesc: LSTM 順伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。

5.5 プリミティブ

199

oneAPI 仕様 リリース 1.0 リビジョン 3
memory::desc src_layer_desc() const
ソース・レイヤー・メモリー記述子を返します。
戻り値: ソース・レイヤー・メモリー記述子。
memory::desc src_iter_desc() const
ソース反復メモリー記述子を返します。
戻り値: ソース反復メモリー記述子。
戻り値: プリミティブにソース反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc src_iter_c_desc() const
ソース反復メモリー記述子を返します。
戻り値: ソース反復メモリー記述子。
戻り値: プリミティブにソース反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc weights_layer_desc() const
重みレイヤーメモリー記述子を返します。
戻り値: 重みレイヤーメモリー記述子。
memory::desc weights_iter_desc() const
重み反復メモリー記述子を返します。
戻り値: 重み反復メモリー記述子。
memory::desc weights_peephole_desc() const
重みピープホール・メモリー記述子を返します。
戻り値: 重みピープホール・メモリー記述子。
memory::desc weights_projection_desc() const
重みピープホール・メモリー記述子を返します。
戻り値: 重みピープホール・メモリー記述子。
memory::desc bias_desc() const
バイアスメモリー記述子を返します。
戻り値: バイアスメモリー記述子。
戻り値: プリミティブにバイアス・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_layer_desc() const
デスティネーション・レイヤー・メモリー記述子を返します。

5.5 プリミティブ

200

oneAPI 仕様 リリース 1.0 リビジョン 3
戻り値: デスティネーション・レイヤー・メモリー記述子。
memory::desc dst_iter_desc() const
デスティネーション反復メモリー記述子を返します。
戻り値: デスティネーション反復メモリー記述子。
戻り値: プリミティブにデスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_iter_c_desc() const
デスティネーション反復メモリー記述子を返します。
戻り値: デスティネーション反復メモリー記述子。
戻り値: プリミティブにデスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc workspace_desc() const
ワークスペース・メモリー記述子を返します。
戻り値: ワークスペース・メモリー記述子。
戻り値: プリミティブがワークスペース・パラメーターを要求しない場合は、ゼロメモリー記述子。
struct dnnl::lstm_backward: public dnnl::primitive
LSTM 逆伝搬プリミティブ。
パブリック関数
lstm_backward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
lstm_backward(const primitive_desc &pd)
LSTM 逆伝搬プリミティブの構築。
パラメーター• pd: LSTM 逆伝搬プリミティブのプリミティブ記述子。
struct desc
LSTM 逆伝搬プリミティブの記述子。
パブリック関数desc(prop_kind
aprop_kind,rnn_direction
direction,
const
memory::desc&src_layer_desc,
const
memory::desc&src_iter_desc,
const
memory::desc&src_iter_c_desc, const memory::desc &weights_layer_desc, const memory::desc&weights_iter_desc,
const
memory::desc&weights_peephole_desc,
const
memory::desc &weights_projection_desc, const memory::desc &bias_desc, const
memory::desc&dst_layer_desc,
const
memory::desc&dst_iter_desc,
const
memory::desc &dst_iter_c_desc, const memory::desc &diff_src_layer_desc, const
memory::desc &diff_src_iter_desc, const memory::desc &diff_src_iter_c_desc,
const
memory::desc&diff_weights_layer_desc,
const
memory::desc&diff_weights_iter_desc, const memory::desc &diff_weights_peephole_desc, const

5.5 プリミティブ

201

oneAPI 仕様 リリース 1.0 リビジョン 3
memory::desc &diff_weights_projection_desc, const memory::desc &diff_bias_desc,
const memory::desc &diff_dst_layer_desc, const memory::desc &diff_dst_iter_desc,
const memory::desc &diff_dst_iter_c_desc, rnn_flags flags = rnn_flags::undef )prop_kind、direction およびメモリー記述子を使用した逆伝搬の予測記述子。
次の引数はゼロメモリー記述子を指す可能性があります。
• src_iter_desc と src_iter_c_desc、diff_src_iter_desc、および diff_src_iter_c_desc• weights_peephole_desctogether と diff_weights_peephole_desc• bias_desctogether と diff_bias_desc• dst_iter_desc と dst_iter_c_desc、diff_dst_iter_desc、および diff_src_iter_c_desc
これは、LSTM 逆伝搬プリミティブがそれらを使用せずに、デフォルトでゼロ値でなければならないことを示します。
weights_projection_desctogether と diff_weights_projection_descmay は、ゼロメモリー
記述子を指している可能性があります。これは、LSTM にリカレント予測レイヤーがないことを示します。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化できます。
パラメーター• aprop_kind: 伝搬の種類。dnnl::prop_kind::backward でなければなりません。
• direction: RNN の方向。詳細は、dnnl::rnn_direction を参照してください。
• src_layer_desc: 入力ベクトルのメモリー記述子。
• src_iter_desc: 入力リカレント隠匿状態ベクトルのメモリー記述子。
• src_iter_c_desc: 入力リカレントセル状態ベクトルのメモリー記述子。
• weights_layer_desc: レイヤー入力に適用される重みメモリー記述子。
• weights_iter_desc: リカレント入力に適用される重みメモリー記述子。
• weights_peephole_desc: セル状態に適用される重みメモリー記述子 (ピープホール LSTM 式)。
• weights_projection_desc: 隠匿状態に適用される重みメモリー記述子 (ピープホール LSTM 式)。
• bias_desc: バイアスメモリー記述子。
• dst_layer_desc: 出力ベクトルのメモリー記述子。
• dst_iter_desc: 出力リカレント隠匿状態ベクトルのメモリー記述子。
• dst_iter_c_desc: 出力リカレントセル状態ベクトルのメモリー記述子。
• diff_src_layer_desc: 入力ベクトルの差分メモリー記述子。
• diff_src_iter_desc: 入力リカレント隠匿状態ベクトルの差分メモリー記述子。
• diff_src_iter_c_desc: 入力リカレントセルの状態ベクトルの差分メモリー記述子。
• diff_weights_layer_desc: レイヤー入力に適用される重みの差分メモリー記述子。
• diff_weights_iter_desc: リカレント入力に適用される重みの差分メモリー記述子。
• diff_weights_peephole_desc: セル状態に適用される重み差分メモリー記述子 (ピープホー
ル LSTM 式)。
• diff_weights_projection_desc: リカレント予測を取得するため非表示状態に適用される重み差分メモリー記述子 (予測 LSTM 式)。
• diff_bias_desc: 差分バイアスメモリー記述子。
• diff_dst_layer_desc: 出力ベクトルの差分メモリー記述子。
• diff_dst_iter_desc: 出力リカレント隠匿状態ベクトルの差分メモリー記述子。

5.5 プリミティブ

202

oneAPI 仕様 リリース 1.0 リビジョン 3• diff_dst_iter_c_desc: 出力リカレントセル状態ベクトルの差分メモリー記述子。
• flags: 未使用。
desc(prop_kind
aprop_kind,rnn_direction
direction,
const
memory::desc&src_layer_desc,
const
memory::desc&src_iter_desc,
const
memory::desc&src_iter_c_desc, const memory::desc &weights_layer_desc, const memory::desc&weights_iter_desc,
const
memory::desc&weights_peephole_desc,
const
memory::desc &bias_desc, const memory::desc &dst_layer_desc, const memory::desc&dst_iter_desc,
const
memory::desc&dst_iter_c_desc,
const
memory::desc&diff_src_layer_desc, const memory::desc &diff_src_iter_desc, const memory::desc&diff_src_iter_c_desc,
const
memory::desc&diff_weights_layer_desc,
const
memory::desc&diff_weights_iter_desc,
const
memory::desc&diff_weights_peephole_desc,
const
memory::desc&diff_bias_desc,
const
memory::desc &diff_dst_layer_desc, const memory::desc &diff_dst_iter_desc, const
memory::desc &diff_dst_iter_c_desc, rnn_flags flags = rnn_flags::undef )prop_kind、direction、および memory 記述子を使用して、LSTM (ピープホールの有無にかかわらず) 逆
方向伝搬プリミティブ記述子を構築します。
次の引数はゼロメモリー記述子を指す可能性があります。
• src_iter_desc と src_iter_c_desc、diff_src_iter_desc、および diff_src_iter_c_desc• weights_peephole_desctogether と diff_weights_peephole_desc• bias_desctogether と diff_bias_desc• dst_iter_desc と dst_iter_c_desc、diff_dst_iter_desc、および diff_src_iter_c_desc
これは、 LSTM 逆伝搬プリミティブがそれらを使用せずに、デフォルトでゼロ値でなければならないことを示します。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化できます。
パラメーター• aprop_kind: 伝搬の種類。dnnl::prop_kind::backward でなければなりません。
• direction: RNN の方向。詳細は、dnnl::rnn_direction を参照してください。
• src_layer_desc: 入力ベクトルのメモリー記述子。
• src_iter_desc: 入力リカレント隠匿状態ベクトルのメモリー記述子。
• src_iter_c_desc: 入力リカレントセル状態ベクトルのメモリー記述子。
• weights_layer_desc: レイヤー入力に適用される重みメモリー記述子。
• weights_iter_desc: リカレント入力に適用される重みメモリー記述子。
• weights_peephole_desc: セル状態に適用される重みメモリー記述子 (ピープホール LSTM 式)。
• bias_desc: バイアスメモリー記述子。
• dst_layer_desc: 出力ベクトルのメモリー記述子。
• dst_iter_desc: 出力リカレント隠匿状態ベクトルのメモリー記述子。
• dst_iter_c_desc: 出力リカレントセル状態ベクトルのメモリー記述子。
• diff_src_layer_desc: 入力ベクトルの差分メモリー記述子。
• diff_src_iter_desc: 入力リカレント隠匿状態ベクトルの差分メモリー記述子。
• diff_src_iter_c_desc: 入力リカレントセルの状態ベクトルの差分メモリー記述子。
• diff_weights_layer_desc: レイヤー入力に適用される重みの差分メモリー記述子。
• diff_weights_iter_desc: リカレント入力に適用される重みの差分メモリー記述子。

5.5 プリミティブ

203

oneAPI 仕様 リリース 1.0 リビジョン 3• diff_weights_peephole_desc: セル状態に適用される重み差分メモリー記述子 (ピープホー
ル LSTM 式)。
• diff_bias_desc: 差分バイアスメモリー記述子。
• diff_dst_layer_desc: 出力ベクトルの差分メモリー記述子。
• diff_dst_iter_desc: 出力リカレント隠匿状態ベクトルの差分メモリー記述子。
• diff_dst_iter_c_desc: 出力リカレントセル状態ベクトルの差分メモリー記述子。
• flags: 未使用。
desc(prop_kind
aprop_kind,rnn_direction
direction,
const
memory::desc&src_layer_desc,
const
memory::desc&src_iter_desc,
const
memory::desc&src_iter_c_desc, const memory::desc &weights_layer_desc, const memory::desc&weights_iter_desc, const memory::desc&bias_desc,
const memory::desc&dst_layer_desc,
const
memory::desc&dst_iter_desc,
const
memory::desc&dst_iter_c_desc, const memory::desc &diff_src_layer_desc, const memory::desc&diff_src_iter_desc,
const
memory::desc&diff_src_iter_c_desc,
const
memory::desc&diff_weights_layer_desc,
const
memory::desc&diff_weights_iter_desc, const memory::desc &diff_bias_desc, const memory::desc&diff_dst_layer_desc, const memory::desc &diff_dst_iter_desc, const memory::desc&diff_dst_iter_c_desc, rnn_flags flags = rnn_flags::undef )prop_kind、direction、およびメモリー記述子を使用して、逆伝搬の LSTM 記述子を構築します。
次の引数はゼロメモリー記述子を指す可能性があります。
• src_iter_desc と src_iter_c_desc、diff_src_iter_desc、および diff_src_iter_c_desc• bias_desctogether と diff_bias_desc• dst_iter_desc と dst_iter_c_desc、diff_dst_iter_desc、および diff_src_iter_c_desc
これは、 LSTM 逆伝搬プリミティブがそれらを使用せずに、デフォルトでゼロ値でなければならないことを示します。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化できます。
パラメーター• aprop_kind: 伝搬の種類。dnnl::prop_kind::backward でなければなりません。
• direction: RNN の方向。詳細は、dnnl::rnn_direction を参照してください。
• src_layer_desc: 入力ベクトルのメモリー記述子。
• src_iter_desc: 入力リカレント隠匿状態ベクトルのメモリー記述子。
• src_iter_c_desc: 入力リカレントセル状態ベクトルのメモリー記述子。
• weights_layer_desc: レイヤー入力に適用される重みメモリー記述子。
• weights_iter_desc: リカレント入力に適用される重みメモリー記述子。
• bias_desc: バイアスメモリー記述子。
• dst_layer_desc: 出力ベクトルのメモリー記述子。
• dst_iter_desc: 出力リカレント隠匿状態ベクトルのメモリー記述子。
• dst_iter_c_desc: 出力リカレントセル状態ベクトルのメモリー記述子。
• diff_src_layer_desc: 入力ベクトルの差分メモリー記述子。
• diff_src_iter_desc: 入力リカレント隠匿状態ベクトルの差分メモリー記述子。
• diff_src_iter_c_desc: 入力リカレントセルの状態ベクトルの差分メモリー記述子。
• diff_weights_layer_desc: レイヤー入力に適用される重みの差分メモリー記述子。
• diff_weights_iter_desc: リカレント入力に適用される重みの差分メモリー記述子。

5.5 プリミティブ

204

oneAPI 仕様 リリース 1.0 リビジョン 3• diff_bias_desc: 差分バイアスメモリー記述子。
• diff_dst_layer_desc: 出力ベクトルの差分メモリー記述子。
• diff_dst_iter_desc: 出力リカレント隠匿状態ベクトルの差分メモリー記述子。
• diff_dst_iter_c_desc: 出力リカレントセル状態ベクトルの差分メモリー記述子。
• flags: 未使用。
struct primitive_desc: public dnnl::rnn_primitive_desc_base
LSTM 逆伝搬のプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const
desc&adesc,const
engine&aengine,
lstm_forward::primitive_desc &hint_fwd_pd, bool allow_empty = false)
LSTM 逆伝搬プリミティブのプリミティブ記述子を構築します。

const

パラメーター• adesc: LSTM 逆伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• hint_fwd_pd: LSTM 順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr &attr, const engine&aengine, const lstm_forward::primitive_desc &hint_fwd_pd, bool allow_empty =false)
LSTM 逆伝搬プリミティブのプリミティブ記述子を構築します。
パラメーター• adesc: LSTM 逆伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• hint_fwd_pd: LSTM 順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_layer_desc() const
ソース・レイヤー・メモリー記述子を返します。
戻り値: ソース・レイヤー・メモリー記述子。
memory::desc src_iter_desc() const
ソース反復メモリー記述子を返します。

5.5 プリミティブ

205

oneAPI 仕様 リリース 1.0 リビジョン 3
戻り値: デスティネーション反復メモリー記述子。
戻り値: プリミティブにデスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc src_iter_c_desc() const
ソース反復メモリー記述子を返します。
戻り値: デスティネーション反復メモリー記述子。
戻り値: プリミティブにデスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc weights_layer_desc() const
重みレイヤーメモリー記述子を返します。
戻り値: 重みレイヤーメモリー記述子。
memory::desc weights_iter_desc() const
重み反復メモリー記述子を返します。
戻り値: 重み反復メモリー記述子。
memory::desc weights_peephole_desc() const
重みピープホール・メモリー記述子を返します。
戻り値: 重みピープホール・メモリー記述子。
memory::desc weights_projection_desc() const
重みピープホール・メモリー記述子を返します。
戻り値: 重みピープホール・メモリー記述子。
memory::desc bias_desc() const
バイアスメモリー記述子を返します。
戻り値: バイアスメモリー記述子。
戻り値: プリミティブにバイアス・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_layer_desc() const
デスティネーション・レイヤー・メモリー記述子を返します。
戻り値: デスティネーション・レイヤー・メモリー記述子。
memory::desc dst_iter_desc() const
デスティネーション反復メモリー記述子を返します。
戻り値: デスティネーション反復メモリー記述子。
戻り値: プリミティブにデスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。

5.5 プリミティブ

206

oneAPI 仕様 リリース 1.0 リビジョン 3
memory::desc dst_iter_c_desc() const
デスティネーション反復メモリー記述子を返します。
戻り値: デスティネーション反復メモリー記述子。
戻り値: プリミティブにデスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc workspace_desc() const
ワークスペース・メモリー記述子を返します。
戻り値: ワークスペース・メモリー記述子。
戻り値: プリミティブがワークスペース・パラメーターを要求しない場合は、ゼロメモリー記述子。
memory::desc diff_src_layer_desc() const
差分ソース・レイヤー・メモリー記述子を返します。
戻り値: 差分ソース・レイヤー・メモリー記述子。
memory::desc diff_src_iter_desc()const
差分ソース反復メモリー記述子を返します。
戻り値: 差分ソース反復メモリー記述子。
戻り値: プリミティブに差分ソース反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_src_iter_desc() const
差分ソース・リカレント・セルの状態メモリー記述子を返します。
戻り値: 差分ソース・リカレント・セルの状態メモリー記述子。
memory::desc diff_weights_layer_desc() const
差分重みレイヤーメモリー記述子を返します。
戻り値: 差分重みレイヤーメモリー記述子。
memory::desc diff_weights_iter_desc() const
差分重み反復メモリー記述子を返します。
戻り値: 差分重み反復メモリー記述子。
memory::desc diff_weights_peephole_desc() const
差分重みピープホール・メモリー記述子を返します。
戻り値: 差分重みピープホール・メモリー記述子。
memory::desc diff_weights_projection_desc() const
差分重み予測メモリー記述子を返します。

5.5 プリミティブ

207

oneAPI 仕様 リリース 1.0 リビジョン 3

戻り値: 差分重み予測メモリー記述子。
memory::desc diff_bias_desc() const
差分バイアスメモリー記述子を返します。
戻り値: 差分バイアスメモリー記述子。
戻り値: プリミティブに差分バイアス・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_layer_desc() const
差分デスティネーション・レイヤー・メモリー記述子を返します。
戻り値: 差分デスティネーション・レイヤー・メモリー記述子。
memory::desc diff_dst_layer_desc() const
差分デスティネーション反復メモリー記述子を返します。
戻り値: 差分デスティネーション反復メモリー記述子。
戻り値: プリミティブに差分デスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_iter_c_desc() const
差分デスティネーション・リカレント・セル状態メモリー記述子を返します。
戻り値: 差分デスティネーション・リカレント・セル状態メモリー記述子。
struct dnnl::gru_forward: public dnnl::primitive
GRU 順伝搬プリミティブ。
パブリック関数
gru_forward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
gru_forward(const primitive_desc &pd)
GRU 順伝搬プリミティブの構築。
パラメーター• pd: GRU 順伝搬プリミティブのプリミティブ記述子。
struct desc
GRU 順伝搬プリミティブの記述子。
パブリック関数desc(prop_kind
aprop_kind,rnn_direction
direction,
const
memory::desc&src_layer_desc,
const
memory::desc&src_iter_desc,
const
memory::desc&weights_layer_desc, const memory::desc &weights_iter_desc, constmemory::desc&bias_desc, constmemory::desc &dst_layer_desc, constmemory::desc &dst_iter_desc,
rnn_flags flags = rnn_flags::undef )5.5 プリミティブ

208

oneAPI 仕様 リリース 1.0 リビジョン 3
GRU 順伝搬プリミティブの記述子を構築します。
次の引数はゼロメモリー記述子を指す可能性があります。
• src_iter_desc• bias_desc• dst_iter_desc
これは、GRU 順伝搬プリミティブがそれらを使用せずに、デフォルトでゼロ値でなければならないことを示します。
注: src_iter_desc を除くすべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any
値で初期化できます。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• direction: RNN の方向。詳細は、dnnl::rnn_direction を参照してください。
• src_layer_desc: 入力ベクトルのメモリー記述子。
• src_iter_desc: 入力リカレント隠匿状態ベクトルのメモリー記述子。
• weights_layer_desc: レイヤー入力に適用される重みメモリー記述子。
• weights_iter_desc: リカレント入力に適用される重みメモリー記述子。
• bias_desc: バイアスメモリー記述子。
• dst_layer_desc: 出力ベクトルのメモリー記述子。
• dst_iter_desc: 出力リカレント隠匿状態ベクトルのメモリー記述子。
• flags: 未使用。
struct primitive_desc: public dnnl::rnn_primitive_desc_base
GRU 順伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const desc &adesc, const engine
false)
GRU 順伝搬プリミティブのプリミティブ記述子の構築。

&aengine,boolallow_empty=

パラメーター• adesc: GRU 順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine, bool allow_empty = false)
GRU 順伝搬プリミティブのプリミティブ記述子を構築。

5.5 プリミティブ&attr,

const

engine209

oneAPI 仕様 リリース 1.0 リビジョン 3
パラメーター• adesc: GRU 順伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_layer_desc() const
ソース・レイヤー・メモリー記述子を返します。
戻り値: ソース・レイヤー・メモリー記述子。
memory::desc src_iter_desc() const
ソース反復メモリー記述子を返します。
戻り値: デスティネーション反復メモリー記述子。
戻り値: プリミティブにデスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc weights_layer_desc() const
重みレイヤーメモリー記述子を返します。
戻り値: 重みレイヤーメモリー記述子。
memory::desc weights_iter_desc() const
重み反復メモリー記述子を返します。
戻り値: 重み反復メモリー記述子。
memory::desc bias_desc() const
バイアスメモリー記述子を返します。
戻り値: バイアスメモリー記述子。
戻り値: プリミティブにバイアス・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_layer_desc() const
デスティネーション・レイヤー・メモリー記述子を返します。
戻り値: デスティネーション・レイヤー・メモリー記述子。
memory::desc dst_iter_desc() const
デスティネーション反復メモリー記述子を返します。
戻り値: デスティネーション反復メモリー記述子。
戻り値: プリミティブにデスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。
5.5 プリミティブ

210

oneAPI 仕様 リリース 1.0 リビジョン 3
memory::desc workspace_desc() const
ワークスペース・メモリー記述子を返します。
戻り値: ワークスペース・メモリー記述子。
戻り値: プリミティブがワークスペース・パラメーターを要求しない場合は、ゼロメモリー記述子。
struct dnnl::gru_backward: public dnnl::primitive
GRU 逆伝搬プリミティブ。
パブリック関数
gru_backward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
gru_backward(const primitive_desc &pd)
GRU 逆伝搬プリミティブの構築。
パラメーター• pd: GRU 逆伝搬プリミティブのプリミティブ記述子。
struct desc
GRU 逆伝搬プリミティブの記述子。
パブリック関数desc(prop_kind
aprop_kind,rnn_direction
direction,
const
memory::desc&src_layer_desc,
const
memory::desc&src_iter_desc,
const
memory::desc&weights_layer_desc, const memory::desc &weights_iter_desc, const memory::desc&bias_desc,
const
memory::desc&dst_layer_desc,
const
memory::desc&dst_iter_desc, const memory::desc &diff_src_layer_desc, const memory::desc&diff_src_iter_desc,
const
memory::desc&diff_weights_layer_desc,
const
memory::desc &diff_weights_iter_desc, const memory::desc &diff_bias_desc, const
memory::desc&diff_dst_layer_desc,
const
memory::desc&diff_dst_iter_desc,
rnn_flags flags = rnn_flags::undef )GRU 逆伝搬プリミティブの記述子を作成します。
次の引数はゼロメモリー記述子を指す可能性があります。
• src_iter_desctogether と diff_src_iter_desc• bias_desctogether と diff_bias_desc• dst_iter_desctogether と diff_dst_iter_desc
これは、GRU 順伝搬プリミティブがそれらを使用せずに、デフォルトでゼロ値でなければならないことを示します。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化できます。
パラメーター• aprop_kind: 伝搬の種類。dnnl::prop_kind::backward でなければなりません。
• direction: RNN の方向。詳細は、dnnl::rnn_direction を参照してください。
• src_layer_desc: 入力ベクトルのメモリー記述子。

5.5 プリミティブ

211

oneAPI 仕様 リリース 1.0 リビジョン 3• src_iter_desc: 入力リカレント隠匿状態ベクトルのメモリー記述子。
• weights_layer_desc: レイヤー入力に適用される重みメモリー記述子。
• weights_iter_desc: リカレント入力に適用される重みメモリー記述子。
• bias_desc: バイアスメモリー記述子。
• dst_layer_desc: 出力ベクトルのメモリー記述子。
• dst_iter_desc: 出力リカレント隠匿状態ベクトルのメモリー記述子。
• diff_src_layer_desc: 入力ベクトルの差分メモリー記述子。
• diff_src_iter_desc: 入力リカレント隠匿状態ベクトルの差分メモリー記述子。
• diff_weights_layer_desc: レイヤー入力に適用される重みの差分メモリー記述子。
• diff_weights_iter_desc: リカレント入力に適用される重みの差分メモリー記述子。
• diff_bias_desc: 差分バイアスメモリー記述子。
• diff_dst_layer_desc: 出力ベクトルの差分メモリー記述子。
• diff_dst_iter_desc: 出力リカレント隠匿状態ベクトルの差分メモリー記述子。
• flags: 未使用。
struct primitive_desc: public dnnl::rnn_primitive_desc_base
GRU 逆伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const
desc&adesc,const
engine&aengine,
gru_forward::primitive_desc &hint_fwd_pd, bool allow_empty = false)
GRU 逆伝搬プリミティブのプリミティブの記述子を構築します。

const

パラメーター• adesc: GRU 逆伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• hint_fwd_pd: GRU 順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定する
ヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr &attr, const engine&aengine, const gru_forward::primitive_desc &hint_fwd_pd, bool allow_empty =false)GRU 逆伝搬プリミティブのプリミティブ記述子を構築します。
パラメーター• adesc: GRU 逆伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• hint_fwd_pd: GRU 順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定する
ヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。

5.5 プリミティブ

212

oneAPI 仕様 リリース 1.0 リビジョン 3

memory::desc src_layer_desc() const
ソース・レイヤー・メモリー記述子を返します。
戻り値: ソース・レイヤー・メモリー記述子。
memory::desc src_iter_desc() const
ソース反復メモリー記述子を返します。
戻り値: デスティネーション反復メモリー記述子。
戻り値: プリミティブにデスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc weights_layer_desc() const
重みレイヤーメモリー記述子を返します。
戻り値: 重みレイヤーメモリー記述子。
memory::desc weights_iter_desc() const
重み反復メモリー記述子を返します。
戻り値: 重み反復メモリー記述子。
memory::desc bias_desc() const
バイアスメモリー記述子を返します。
戻り値: バイアスメモリー記述子。
戻り値: プリミティブにバイアス・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_layer_desc() const
デスティネーション・レイヤー・メモリー記述子を返します。
戻り値: デスティネーション・レイヤー・メモリー記述子。
memory::desc dst_iter_desc() const
デスティネーション反復メモリー記述子を返します。
戻り値: デスティネーション反復メモリー記述子。
戻り値: プリミティブにデスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc workspace_desc() const
ワークスペース・メモリー記述子を返します。
戻り値: ワークスペース・メモリー記述子。
戻り値: プリミティブがワークスペース・パラメーターを要求しない場合は、ゼロメモリー記述子。

5.5 プリミティブ

213

oneAPI 仕様 リリース 1.0 リビジョン 3

memory::desc diff_src_layer_desc() const
差分ソース・レイヤー・メモリー記述子を返します。
戻り値: 差分ソース・レイヤー・メモリー記述子。
memory::desc diff_src_iter_desc()const
差分ソース反復メモリー記述子を返します。
戻り値: 差分ソース反復メモリー記述子。
戻り値: プリミティブに差分ソース反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_weights_layer_desc() const
差分重みレイヤーメモリー記述子を返します。
戻り値: 差分重みレイヤーメモリー記述子。
memory::desc diff_weights_iter_desc() const
差分重み反復メモリー記述子を返します。
戻り値: 差分重み反復メモリー記述子。
memory::desc diff_bias_desc() const
差分バイアスメモリー記述子を返します。
戻り値: 差分バイアスメモリー記述子。
戻り値: プリミティブに差分バイアス・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_layer_desc() const
差分デスティネーション・レイヤー・メモリー記述子を返します。
戻り値: 差分デスティネーション・レイヤー・メモリー記述子。
memory::desc diff_dst_layer_desc() const
差分デスティネーション反復メモリー記述子を返します。
戻り値: 差分デスティネーション反復メモリー記述子。
戻り値: プリミティブに差分デスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。
struct dnnl::lbr_gru_forward: public dnnl::primitive
LBR GRU 順伝搬プリミティブ。
パブリック関数
lbr_gru_forward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
5.5 プリミティブ214

oneAPI 仕様 リリース 1.0 リビジョン 3

lbr_gru_forward(const primitive_desc &pd)
LBR GRU 順伝搬プリミティブの構築。
パラメーター• pd: LBR GRU 順伝搬プリミティブのプリミティブ記述子。
struct desc
LBR GRU 順伝搬プリミティブの記述子。
パブリック関数desc(prop_kind
aprop_kind,rnn_direction
direction,
const
memory::desc&src_layer_desc,
const
memory::desc&src_iter_desc,
const
memory::desc&weights_layer_desc, const memory::desc &weights_iter_desc, constmemory::desc&bias_desc, constmemory::desc &dst_layer_desc, constmemory::desc &dst_iter_desc,
rnn_flags flags = rnn_flags::undef )LBR GRU 順伝搬プリミティブの記述子を構築します。
次の引数はゼロメモリー記述子を指す可能性があります。
• src_iter_desc• bias_desc• dst_iter_desc
これは、LBR GRU 順伝搬プリミティブがそれらを使用せずに、デフォルトでゼロ値でなければならないことを示します。
注: src_iter_desc を除くすべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any
値で初期化できます。
パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• direction: RNN の方向。詳細は、dnnl::rnn_direction を参照してください。
• src_layer_desc: 入力ベクトルのメモリー記述子。
• src_iter_desc: 入力リカレント隠匿状態ベクトルのメモリー記述子。
• weights_layer_desc: レイヤー入力に適用される重みメモリー記述子。
• weights_iter_desc: リカレント入力に適用される重みメモリー記述子。
• bias_desc: バイアスメモリー記述子。
• dst_layer_desc: 出力ベクトルのメモリー記述子。
• dst_iter_desc: 出力リカレント隠匿状態ベクトルのメモリー記述子。
• flags: 未使用。
struct primitive_desc: public dnnl::rnn_primitive_desc_base
LBR GRU 順伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。

5.5 プリミティブ

215

oneAPI 仕様 リリース 1.0 リビジョン 3
primitive_desc(const desc &adesc, const engine
false)LBR GRU 順伝搬プリミティブのプリミティブ記述子の構築。

&aengine,boolallow_empty=

パラメーター• adesc: LBR GRU 順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine, bool allow_empty = false)
LBR GRU 順伝搬プリミティブのプリミティブ記述子を構築。

&attr,

const

engine

パラメーター• adesc: LBR GRU 順伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_layer_desc() const
ソース・レイヤー・メモリー記述子を返します。
戻り値: ソース・レイヤー・メモリー記述子。
memory::desc src_iter_desc() const
ソース反復メモリー記述子を返します。
戻り値: デスティネーション反復メモリー記述子。
戻り値: プリミティブにデスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc weights_layer_desc() const
重みレイヤーメモリー記述子を返します。
戻り値: 重みレイヤーメモリー記述子。
memory::desc weights_iter_desc() const
重み反復メモリー記述子を返します。
戻り値: 重み反復メモリー記述子。
memory::desc bias_desc() const
バイアスメモリー記述子を返します。
戻り値: バイアスメモリー記述子。

5.5 プリミティブ

216

oneAPI 仕様 リリース 1.0 リビジョン 3

戻り値: プリミティブにバイアス・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_layer_desc() const
デスティネーション・レイヤー・メモリー記述子を返します。
戻り値: デスティネーション・レイヤー・メモリー記述子。
memory::desc dst_iter_desc() const
デスティネーション反復メモリー記述子を返します。
戻り値: デスティネーション反復メモリー記述子。
戻り値: プリミティブにデスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc workspace_desc() const
ワークスペース・メモリー記述子を返します。
戻り値: ワークスペース・メモリー記述子。
戻り値: プリミティブがワークスペース・パラメーターを要求しない場合は、ゼロメモリー記述子。
struct dnnl::lbr_gru_backward: public dnnl::primitive
LBR GRU 逆伝搬プリミティブ。
パブリック関数
lbr_gru_backward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
lbr_gru_backward(const primitive_desc &pd)
LBR GRU 逆方向プリミティブの構築。
パラメーター• pd: LBR GRU 逆伝搬プリミティブのプリミティブ記述子。
struct desc
LBR GRU 逆伝搬プリミティブの記述子。
パブリック関数desc(prop_kind
aprop_kind,rnn_direction
direction,
const
memory::desc&src_layer_desc,
const
memory::desc&src_iter_desc,
const
memory::desc&weights_layer_desc, const memory::desc &weights_iter_desc, const memory::desc&bias_desc,
const
memory::desc&dst_layer_desc,
const
memory::desc&dst_iter_desc, const memory::desc &diff_src_layer_desc, const memory::desc&diff_src_iter_desc,
const
memory::desc&diff_weights_layer_desc,
const
memory::desc &diff_weights_iter_desc, const memory::desc &diff_bias_desc, const
memory::desc&diff_dst_layer_desc,
const
memory::desc&diff_dst_iter_desc,
rnn_flags flags = rnn_flags::undef )LBR GRU 逆伝搬プリミティブの記述子を構築します。

5.5 プリミティブ

217

oneAPI 仕様 リリース 1.0 リビジョン 3
次の引数はゼロメモリー記述子を指す可能性があります。
• src_iter_desctogether と diff_src_iter_desc• bias_desctogether と diff_bias_desc• dst_iter_desctogether と diff_dst_iter_desc
これは、LBR GRU 逆伝搬プリミティブがそれらを使用せずに、デフォルトでゼロ値でなければならないことを示します。
注: すべてのメモリー記述子は、format_tag の dnnl::memory::format_tag::any 値で初期化できます。
パラメーター• aprop_kind: 伝搬の種類。dnnl::prop_kind::backward でなければなりません。
• direction: RNN の方向。詳細は、dnnl::rnn_direction を参照してください。
• src_layer_desc: 入力ベクトルのメモリー記述子。
• src_iter_desc: 入力リカレント隠匿状態ベクトルのメモリー記述子。
• weights_layer_desc: レイヤー入力に適用される重みメモリー記述子。
• weights_iter_desc: リカレント入力に適用される重みメモリー記述子。
• bias_desc: バイアスメモリー記述子。
• dst_layer_desc: 出力ベクトルのメモリー記述子。
• dst_iter_desc: 出力リカレント隠匿状態ベクトルのメモリー記述子。
• diff_src_layer_desc: 入力ベクトルの差分メモリー記述子。
• diff_src_iter_desc: 入力リカレント隠匿状態ベクトルの差分メモリー記述子。
• diff_weights_layer_desc: レイヤー入力に適用される重みの差分メモリー記述子。
• diff_weights_iter_desc: リカレント入力に適用される重みの差分メモリー記述子。
• diff_bias_desc: 差分バイアスメモリー記述子。
• diff_dst_layer_desc: 出力ベクトルの差分メモリー記述子。
• diff_dst_iter_desc: 出力リカレント隠匿状態ベクトルの差分メモリー記述子。
• flags: 未使用。
struct primitive_desc: public dnnl::rnn_primitive_desc_base
LBR GRU 逆伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()= default
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const
desc&adesc,const
engine&aengine,
lbr_gru_forward::primitive_desc &hint_fwd_pd, bool allow_empty = false)
LBR GRU 逆伝搬プリミティブのプリミティブ記述子を構築します。

const

パラメーター• adesc: LBR GRU 逆伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• hint_fwd_pd: LBR GRU 順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。

5.5 プリミティブ

218

oneAPI 仕様 リリース 1.0 リビジョン 3• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr &attr, const engine&aengine, const lbr_gru_forward::primitive_desc &hint_fwd_pd, bool allow_empty =false)LBR GRU 逆伝搬プリミティブのプリミティブ記述子を構築します。
パラメーター• adesc: LBR GRU 逆伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• hint_fwd_pd: LBR GRU 順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_layer_desc() const
ソース・レイヤー・メモリー記述子を返します。
戻り値： ソース・レイヤー・メモリー記述子。
memory::desc src_iter_desc() const
ソース反復メモリー記述子を返します。
戻り値: デスティネーション反復メモリー記述子。
戻り値: プリミティブにデスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc weights_layer_desc() const
重みレイヤーメモリー記述子を返します。
戻り値: 重みレイヤーメモリー記述子。
memory::desc weights_iter_desc() const
重み反復メモリー記述子を返します。
戻り値: 重み反復メモリー記述子。
memory::desc bias_desc() const
バイアスメモリー記述子を返します。
戻り値: バイアスメモリー記述子。
戻り値: プリミティブにバイアス・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_layer_desc() const
デスティネーション・レイヤー・メモリー記述子を返します。
5.5 プリミティブ

219

oneAPI 仕様 リリース 1.0 リビジョン 3

戻り値: デスティネーション・レイヤー・メモリー記述子。
memory::desc dst_iter_desc() const
デスティネーション反復メモリー記述子を返します。
戻り値: デスティネーション反復メモリー記述子。
戻り値: プリミティブにデスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc workspace_desc() const
ワークスペース・メモリー記述子を返します。
戻り値: ワークスペース・メモリー記述子。
戻り値: プリミティブがワークスペース・パラメーターを要求しない場合は、ゼロメモリー記述子。
memory::desc diff_src_layer_desc() const
差分ソース・レイヤー・メモリー記述子を返します。
戻り値: 差分ソース・レイヤー・メモリー記述子。
memory::desc diff_src_iter_desc()const
差分ソース反復メモリー記述子を返します。
戻り値: 差分ソース反復メモリー記述子。
戻り値: プリミティブに差分ソース反復パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_weights_layer_desc() const
差分重みレイヤーメモリー記述子を返します。
戻り値: 差分重みレイヤーメモリー記述子。
memory::desc diff_weights_iter_desc() const
差分重み反復メモリー記述子を返します。
戻り値: 差分重み反復メモリー記述子。
memory::desc diff_bias_desc() const
差分バイアスメモリー記述子を返します。
戻り値: 差分バイアスメモリー記述子。
戻り値: プリミティブに差分バイアス・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_layer_desc() const
差分デスティネーション・レイヤー・メモリー記述子を返します。
5.5 プリミティブ

220

oneAPI 仕様 リリース 1.0 リビジョン 3

戻り値: 差分デスティネーション・レイヤー・メモリー記述子。
memory::desc diff_dst_layer_desc() const
差分デスティネーション反復メモリー記述子を返します。
戻り値: 差分デスティネーション反復メモリー記述子。
戻り値: プリミティブに差分デスティネーション反復パラメーターがない場合は、ゼロメモリー記述子。

5.5.17 シャッフル
シャッフル・プリミティブは、グループ・パラメーター G を使用して、シャッフル軸 (ここでは C として指定) に沿ってデー
タをシャッフルします。つまり、シャッフル軸はサイズの2D テンソルであると考えられ、に置き換えられます。変数名は標準規則に従います。
正式な定義を以下に示します。
順方向

説明:• c 次元はシャッフル軸と呼ばれます。
• G は group_size。
• ou̅̅̅ は最外のインデックス (シャッフル軸の左側)。
• in
̅ は最内のインデックス (シャッフル軸の右)。
• c’ と c の関係は次の式で定義されます。

ここで、

および

です。

順方向訓練と順方向推論の違い
forward_training と forward_inference 伝搬の種類に違いはありません。
後方 (逆方向)
逆方向伝搬は、diff_dst(ou, c, in) に基づいて diff_src(ou, c, in) を計算します。基本的に、逆伝搬は順伝搬と同じですが、C/g に置き換えられます。

5.5 プリミティブ

221

oneAPI 仕様 リリース 1.0 リビジョン 3
実行引数
実行時に入力と出力は、次の表で示す実行引数インデックスにマップする必要があります。
プリミティブの入力/出力
src

実行引数インデックス
DNNL_ARG_SRC

dst

DNNL_ARG_DST

diff_src

DNNL_ARG_DIFF_SRC

diff_dst

DNNL_ARG_DIFF_DST

操作の詳細
1.

src と dst のメモリー形式とデータ型は同一であると想定され、API では通常データとして参照されます (dnnl::shuffle_forward::desc::desc() の data_desc を参照)。同じことが diff_srcと diff_dst にも当てはまります。対応するメモリー記述子は diff_data_desc と呼ばれます。

サポートされるデータ型
シャッフル・プリミティブは次のデータ型の組み合わせをサポートします。
注: この節では、可読性のためデータ型の名称を省略しています。例えば、dnnl::memory::data_type::f32 は、
f32 に省略されます。
伝搬

ソース/デスティネーション

順方向/逆方向

f32、bf16

順方向

s32、s8、 u8

データレイアウト
シャッフル・プリミティブは任意のデータテンソルで機能します。論理的な次元については特別な意味はありません。
ただし、シャッフル軸は、通常、チャネルと呼ばれます (従って、式では c を使用します)。
シャッフル操作は通常、CNN トポロジーで使用されます。従って、ライブラリーではシャッフル・プリミティブは、対応する
メモリー形式に最適化されています。
空間

論理テンソルシャッフル軸メモリー形式向けに最適化された実装

2D

NCHW

1 (C)

nchw (abcd)、nhwc(acdb)、最適化済み*

3D

NCDHW

1 (C)

ncdhw (abcde)、ndhwc(acdeb)、最適化済み

ここで、最適化済み* とは、先行する計算集約型プリミティブによって選択された形式を意味します。
post-op と属性
シャッフル・プリミティブは post-op や属性をサポートする必要がありません。

5.5 プリミティブ

222

oneAPI 仕様 リリース 1.0 リビジョン 3APIstruct dnnl::shuffle_forward: public dnnl::primitive
シャッフル順伝搬プリミティブ。
パブリック関数
shuffle_forward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
shuffle_forward(const primitive_desc &pd)
シャッフル順伝搬プリミティブの構築。
パラメーター• pd: シャッフル順伝搬プリミティブのプリミティブ記述子。
struct desc
シャッフル順伝搬プリミティブの記述子。
パブリック関数desc(prop_kind
aprop_kind,constmemory::desc
group_size)
シャッフル順伝搬プリミティブの記述子を構築します。

&data_desc,

int

axis,

int

パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• data_desc: ソースとデスティネーション・メモリー記述子。
• axis: データがシャッフルされる軸。
• group_size: シャッフルグループのサイズ。
struct primitive_desc: public dnnl::primitive_desc
シャッフル順伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const desc &adesc, const engine &aengine, const primitive_attr&attr = primitive_attr(), bool allow_empty = false)
シャッフル順伝搬プリミティブのプリミティブ記述子を構築します。
パラメーター• adesc: シャッフル順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• attr: 使用するプリミティブ属性。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。

5.5 プリミティブ

223

oneAPI 仕様 リリース 1.0 リビジョン 3
memory::desc src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。
struct dnnl::shuffle_backward: public dnnl::primitive
シャッフル逆伝搬プリミティブ。
パブリック関数
shuffle_backward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
shuffle_backward(const primitive_desc &pd)
シャッフル逆伝搬プリミティブの構築。
パラメーター• pd: シャッフル逆伝搬プリミティブのプリミティブ記述子。
struct desc
シャッフル逆伝搬プリミティブの記述子。
パブリック関数desc(const memory::desc &diff_data_desc, int axis, int group_size)
シャッフル逆伝搬プリミティブの記述子を構築します。
パラメーター• diff_data_desc: 差分ソースと差分デスティネーションのメモリー記述子。
• axis: データがシャッフルされる軸。
• group_size: シャッフルグループのサイズ。
struct primitive_desc: publicdnnl::primitive_desc
シャッフル逆伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。

5.5 プリミティブ

224

oneAPI 仕様 リリース 1.0 リビジョン 3
primitive_desc(const desc &adesc, const engine &aengine, const
shuffle_forward::primitive_desc &hint_fwd_pd, const primitive_attr
primitive_attr(), bool allow_empty = false)
シャッフル逆伝搬プリミティブのプリミティブ記述子を構築します。

&attr

=

パラメーター• adesc: シャッフル逆伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• attr: 使用するプリミティブ属性。
• hint_fwd_pd: シャッフル順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc diff_src_desc() const
差分ソースメモリー記述子を返します。
戻り値: 差分ソースメモリー記述子。
戻り値: プリミティブに差分ソースメモリーがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_desc() const
差分デスティネーション・メモリー記述子を返します。
戻り値: 差分デスティネーション・メモリー記述子。
戻り値: プリミティブに差分デスティネーション・メモリーがない場合は、ゼロメモリー記述子。

5.5.18 ソフトマックス
ソフトマックス・プリミティブは、任意の次元のデータに対し特定の軸に沿ってソフトマックスを実行します。他のすべての軸は独立している (バッチ) として扱われます。
一般に、操作は次の式で定義されます。変数名は標準規則に従います。
順方向

説明:• c 軸に対し softmax 計算が行われます。
• ou̅̅̅ は最外のインデックス (softmax 軸の左側)。
5.5 プリミティブ

225

oneAPI 仕様 リリース 1.0 リビジョン 3• in̅ は最内のインデックス (softmax 軸の右側)。
• ν は、正確な結果を得るため使用され、次のように定義されます。

順方向訓練と順方向推論の違い
forward_training と forward_inference 伝搬の種類に違いはありません。
逆方向 (後方)
逆方向伝搬は、diff_dst(ou, c, in) と dst(ou, c, in) に基づいて diff_src(ou, c, in) を計算します。
実行引数
実行時に入力と出力は、次の表で示す実行引数インデックスにマップする必要があります。
プリミティブの入力/出力
src

実行引数インデックス
DNNL_ARG_SRC

dst

DNNL_ARG_DST

diff_src

DNNL_ARG_DIFF_SRC

diff_dst

DNNL_ARG_DIFF_DST

操作の詳細
1.

順方向と逆方向の両方でインプレース操作がサポートされ、src は順方向伝搬の入力および出力として使用でき、diff_dst は逆伝搬の入力および出力として使用できます。インプレースの場合、元のデータは上書きされます。

post-op と属性
ソフトマックス・プリミティブは post-op や属性をサポートする必要がありません。
サポートされるデータ型
ソフトマックス・プリミティブは、次のデータ型の組み合わせをサポートします。
注: この節では、可読性のためデータ型の名称を省略しています。例えば、dnnl::memory::data_type::f32 は、
f32 に省略されます。
伝搬

ソース/デスティネーション

順方向/逆方向

bf16、f32
f16

順方向

5.5 プリミティブ

226

oneAPI 仕様 リリース 1.0 リビジョン 3
データ表現
ソース、デスティネーション、およびそれらの勾配
ソフトマックス・プリミティブは任意のデータテンソルで機能します。論理的な次元については特別な意味はありません。
ただし、softmax 軸は、通常、チャネルと呼ばれます (従って、式では c を使用します)。
API
struct dnnl::softmax_forward: public dnnl::primitive
ソフトマックス順伝搬プリミティブ。
パブリック関数
softmax_forward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
softmax_forward(const primitive_desc &pd)
ソフトマックス順伝搬プリミティブの構築。
パラメーター• pd: ソフトマックス順伝搬プリミティブのプリミティブ記述子。
struct desc
ソフトマックス順伝搬プリミティブの記述子。
パブリック関数desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
desc(prop_kind aprop_kind, constmemory::desc
ソフトマックス順伝搬プリミティブの記述子を構築します。

&data_desc,

int

softmax_axis)

パラメーター• aprop_kind: 伝 搬 の 種 類 。 可 能 な 値 は 、 dnnl::prop_kind::forward_training とdnnl::prop_kind::forward_inference です。
• data_desc: ソースとデスティネーション・メモリー記述子。
• softmax_axis: ソフトマックスが計算される軸。
struct primitive_desc: public dnnl::primitive_desc
ソフトマックス順伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const desc &adesc, const engine &aengine,
false)
ソフトマックス順伝搬プリミティブのプリミティブ記述子の構築。

boolallow_empty=

パラメーター• adesc: ソフトマックス順伝搬プリミティブの記述子。
5.5 プリミティブ

227

oneAPI 仕様 リリース 1.0 リビジョン 3• aengine: 使用するエンジン。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr&aengine, bool allow_empty = false)
ソフトマックス順伝搬プリミティブのプリミティブ記述子を構築します。

&attr,

const

engine

パラメーター• adesc: ソフトマックス順伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• attr: 使用するプリミティブ属性。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc src_desc() const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにソース・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。
struct dnnl::softmax_backward: public dnnl::primitive
ソフトマックス逆伝搬プリミティブ。
パブリック関数
softmax_backward()
デフォルト・コンストラクター。空のオブジェクトを生成します。
softmax_backward(const primitive_desc &pd)
ソフトマックス逆伝搬プリミティブの構築。
パラメーター• pd: ソフトマックス逆伝搬プリミティブのプリミティブ記述子。
struct desc
ソフトマックス逆伝搬プリミティブの記述子。

5.5 プリミティブ

228

oneAPI 仕様 リリース 1.0 リビジョン 3
パブリック関数desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
desc(const memory::desc &diff_data_desc, const
softmax_axis)
ソフトマックス逆伝搬プリミティブの記述子を構築します。
パラメーター

memory::desc&data_desc,int• diff_data_desc: 差分ソースと差分デスティネーションのメモリー記述子。
• data_desc: デスティネーション・メモリー記述子。
• softmax_axis: ソフトマックスが計算される軸。
struct primitive_desc: public dnnl::primitive_desc
ソフトマックス逆伝搬プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const
desc&adesc,const
engine&aengine,softmax_forward::primitive_desc &hint_fwd_pd, bool allow_empty = false)
ソフトマックス逆伝搬プリミティブのプリミティブ記述子を構築します。

const

パラメーター• adesc: ソフトマックス逆伝搬プリミティブの記述子。
• aengine: 使用するエンジン。
• hint_fwd_pd: ソフトマックス順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
primitive_desc(const desc &adesc, const primitive_attr &attr, const engine&aengine, const softmax_forward::primitive_desc &hint_fwd_pd, bool allow_empty =false)
ソフトマックス逆伝搬プリミティブのプリミティブ記述子を構築します。
パラメーター• adesc: ソフトマックス逆伝搬プリミティブの記述子。
• attr: 使用するプリミティブ属性。
• aengine: 使用するエンジン。
• hint_fwd_pd: ソフトマックス順伝搬プリミティブのプリミティブ記述子。使用するメモリー形式を決定するヒントとして利用されます。
• allow_empty: 例外をスローせずに構築を失敗できることが許可されていることを示すフラグ。この場合、空のオブジェクトが生成されます。このフラグはオプションでありデフォルトは false です。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。

5.5 プリミティブ

229

oneAPI 仕様 リリース 1.0 リビジョン 3
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。
memory::desc diff_src_desc() const
差分ソースメモリー記述子を返します。
戻り値: 差分ソースメモリー記述子。
戻り値: プリミティブに差分ソースメモリーがない場合は、ゼロメモリー記述子。
memory::desc diff_dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。

5.5.19 累積
累積プリミティブは N テンソルを合計します。変数名は標準の規則に従います。

累積プリミティブには、順方向と逆方向の伝搬の概念がありません。累積操作の逆伝搬は、単純な単位元操作です。
実行引数
実行時に入力と出力は、次の表で示す実行引数インデックスにマップする必要があります。
プリミティブの入力/出力
src

実行引数インデックス
DNNL_ARG_MULTIPLE_SRC

dst

DNNL_ARG_DST

操作の詳細• dst メモリー形式は、ユーザーが指定することも、プリミティブによって取得することもできます。推奨される方法は、プリミティブが適切な形式を選択できるようにすることです。
• 累積プリミティブでは、すべてのソースとデスティネーション・テンソルは同一形状である必要があります。暗黙のブロードキャストはサポートされません。
post-op と属性
累積プリミティブは post-op や属性をサポートしません。
5.5 プリミティブ

230

oneAPI 仕様 リリース 1.0 リビジョン 3
サポートされるデータ型
累積プリミティブは、ソースとデスティネーション・テンソルの任意のデータ型をサポートします。
ソースとデスティネーションのデータ表現
累積プリミティブは任意のデータテンソルで機能します。論理的な次元に関連する特別な意味はありません。
APIstruct dnnl::sum: public dnnl::primitive
アウトオブプレース累積 (sum) プリミティブ。
パブリック関数sum()
デフォルト・コンストラクター。空のオブジェクトを生成します。
sum(constprimitive_desc &pd) sum
プリミティブの構築。
パラメーター• pd: sum プリミティブのプリミティブ記述子。
struct primitive_desc: public dnnl::primitive_desc_base
sum プリミティブのプリミティブ記述子。
パブリック関数primitive_desc()
デフォルト・コンストラクター。空のオブジェクトを生成します。
primitive_desc(const memory::desc &dst, const std::vector<float> &scales, const
std::vector<memory::desc> &srcs, const engine &aengine, const primitive_attr&attr = primitive_attr())
sum プリミティブのプリミティブ記述子を構築。
パラメーター• dst: デスティネーション・メモリー記述子。
• scales: それぞれのソースメモリー内のデータに掛けるスケールのベクトル。
• srcs: ソースメモリー記述子のベクトル。
• aengine: 操作を行うエンジン。
• attr: 使用するプリミティブ属性 (オプション)。
primitive_desc(const std::vector<float> &scales, const std::vector<memory::desc>&srcs, const engine &aengine, const primitive_attr &attr = primitive_attr())
sum プリミティブのプリミティブ記述子を構築。
このバージョンでは、デスティネーション・メモリー記述子が自動的に取得されます。
パラメーター• scales: それぞれのソース・メモリー・オブジェクトのデータを乗算するスケールのベクトル。
5.5 プリミティブ

231

oneAPI 仕様 リリース 1.0 リビジョン 3• srcs: ソースメモリー記述子のベクトル。
• aengine: 操作を行うエンジン。
• attr: 使用するプリミティブ属性 (オプション)。
memory::desc src_desc(int idx = 0) const
ソースメモリー記述子を返します。
戻り値: ソースメモリー記述子。
戻り値: プリミティブにインデックス付きのソース・パラメーターがない場合は、ゼロメモリー記述子。
パラメーター• idx: ソース・インデックス。
memory::desc dst_desc() const
デスティネーション・メモリー記述子を返します。
戻り値: デスティネーション・メモリー記述子。
戻り値: プリミティブにデスティネーション・パラメーターがない場合は、ゼロメモリー記述子。

5.6

オープンソース実装

インテルは、Apache* ライセンスによりオープンソース実装 (英語) を公開しています。

5.7

実装の注意点

この仕様は、oneDNN の高レベルの説明を提供し、オープンソース実装 (英語) 固有の詳細をすべて網羅しているわけではありません。具体的には、高度に最適化されたメモリー形式やプロファイル・ツールとの統合については対象外です。
これは、仕様の移植性を考慮した意図的なものです。この仕様で定義される API を使用するコードは、オープンソース実装やこの仕様の他の潜在的な実装で移植性があることが期待されます。
将来的にこのセクションは、仕様のさまざまな実装がどのように関連して共存するか、詳しい説明を拡張する予定です。

5.8

テスト

インテルの oneDNN バイナリーの配布には、ライブラリーの機能テストに利用できるサンプルコードが含まれています。
オープンソース実装 (英語) には包括的なテストスイートが含まれます。手順については README (英語) を参照してください。

5.6 オープンソース実装

232

第6章
oneCCL
6.1

概要

oneAPI コレクティブ・コミュニケーション・ライブラリー (oneCCL) は、ディープラーニング・アプリケーションで行われる通信パターンのプリミティブを提供します。oneCCL は、複数の oneAPI デバイスを搭載するプラットフォームのス
ケールアップと、複数の計算ノードで構成されるクラスターのスケールアウトの両方をサポートします。
oneCCL は、ディープラーニング (DL) アルゴリズムで使用される次の通信パターンをサポートします。
• allgatherv• allreduce• alltoallv• broadcast• reduce• reduce_scatter
oneCCL は次のような最適化と関数に対する制御を提供します。
• 通信操作の優先順位付け• 永続的な通信操作 (1 度きりの初期化と繰り返し実行の分離を可能にします)

6.2

名前空間

このセクションでは oneCCL 名前空間の規則について説明します。

6.2.1 oneapi::ccl 名前空間
oneapi::ccl 名前空間には、ライブラリーによって定義されたパブリック識別子が含まれる必要があります。

6.2.2 ccl 名前空間
代替の ccl 名前空間は、oneapi::ccl 名前空間のエイリアスと見なされます。

233

oneAPI 仕様 リリース 1.0 リビジョン 3

6.3

現在のバージョンの oneCCL 仕様

これは、oneCCL 仕様のバージョン 1.0 です。

6.4

定義

6.4.1 oneCCL の概念
oneCCL 仕様では、次の概念のリストが定義されています。
• デバイス• コンテキスト• キー値のストア• コミュニケーター• ストリーム• イベント• 操作属性デバイス
注: 以下では、ネイティブデバイス/コンテキスト/ストリーム/イベントが SYCL* デバイスのランタイム・スコープで定義されています。
using native_device_type = sycl::device;using native_context_type = sycl::context;
using native_stream_type = sycl::queue;
using native_event_type = sycl::event;

oneCCL 仕様では、デバイス (CPU、システム内の特定の GPU カード、または通信操作に関わるその他のデバイスなど)
を計算デバイスとして抽象化します。デバイスは、コミュニケーターのランク (通信操作でアドレス指定可能なエンティティー) に対応します。
oneCCL 仕様は、ネイティブ・オブジェクトなし (ホストに対応) と、ネイティブ・オブジェクト (native_device_type)を使用するデバイスクラスのインスタンスを作成する方法を定義します。
新しいデバイス・オブジェクトを作成:
device ccl::create_device(native_device_type& native_device);
device ccl::create_device();native_device: 既存のネイティブ・デバイス・オブジェクト。

6.3 現在のバージョンの oneCCL 仕様

234

oneAPI 仕様 リリース 1.0 リビジョン 3

戻り値: device。 デバイス・オブジェクト。
device クラスは、ネイティブ・オブジェクトを取得する機能を提供する必要があります。
ネイティブ・デバイス・オブジェクトを取得:
native_device_type device::get_native();

戻り値: native_event_type。ネイティブ・デバイス・オブジェクト。デバイス・オブジェクトがネイティブ・オブジェクトを包括しない場合例外をスローします。
コンテキスト
oneCCL 仕様では、コンテキストをリソース管理と、コンテキストで指定された複数のデバイスで通信操作を行う計算デバイス・コンテキストの抽象化として定義します。
oneCCL 仕様は、ネイティブ・オブジェクトなしでとネイティブ・オブジェクト (native_context_type) を使用するデバイスクラスのインスタンスを作成する方法を定義します。
新しいコンテキスト・オブジェクトを作成:
context ccl::create_context(native_context_type& native_context);
context ccl::create_context();

native_context: 既存のネイティブ・コンテキスト・オブジェクト。
戻り値: context。コンテキスト・オブジェクト。
context クラスは、ネイティブ・オブジェクトを取得する機能を提供する必要があります。
ネイティブ・コンテキスト・オブジェクトを取得:
native_context_type context::get_native();

戻り値: native_context_type。ネイティブ・コンテキスト・オブジェクト。コンテキスト・オブジェクトがネイティブ・オ
ブジェクトを包括しない場合例外をスローします
Key-Value Store (キー値のストア)
kvs_interface は、oneCCL コミュニケーターの作成中にランク間の接続を確立する際に使用する key-value
store (KVS) インターフェイスを定義します。インターフェイスには、get と set メソッドのブロックが含まれている必要があります。

6.4 定義235

oneAPI 仕様 リリース 1.0 リビジョン 3
KVS からレコードを取得:
virtual vector_class<char> kvs_interface::get(const string_class& key) = 0;

key: 取得する値のキー。
戻り値: vector_class<char>。指定されたキーに関連付けられた値。
注: get 操作に存在しないキーを使用すると空の結果が返されます。
KVS にレコードを保存:
void kvs_interface::set(const string_class& key,
const vector_class<char>& data) = 0;

key: は値を格納するキー。
data: は指定されたキーに関連付ける値。
注: 空の data を使用した set 操作は、KVS からレコードを削除します。
oneCCL 仕様では、KVS クラスは組込み KVS として定義されています。
class kvs : public kvs_interface {public:static constexpr size_t address_max_size = 256;
using address_type = array_class<char, address_max_size>;~kvs() override;
address_type get_address() const; vector_class<char> get(const string_class& key) override;
void set(
const string_class& key,
const vector_class<char>& data) override;}

組込み KVS のアドレスを取得:
kvs::address_type kvs::get_address() const;

戻り値: kvs::address_type。KVS のアドレス。メインの組込み KVS から取得し、組込み KVS を作成するため別のプロセスに渡す必要があります。

6.4 定義236

oneAPI 仕様 リリース 1.0 リビジョン 3
メインの組込み KVS を作成します。アドレスは、アウトオブバンド通信メカニズムを使用して配布し、他のランクで KVSを作成する際に使用されます。
shared_ptr_class<kvs> ccl::create_main_kvs();

戻り値: shared_ptr_class<kvs>。
メイン KVS オブジェクトのアドレスから新しい KVS を作成:
shared_ptr_class<kvs> ccl::create_kvs(const kvs::address_type& addr);

addr: メイン KVS のアドレス。
戻り値: shared_ptr_class<kvs>。KVS オブジェクト。
コミュニケーター
oneCCL 仕様は、通信ランクのグループを記述する communicator を定義します。ランクは通信操作にアクセス可能なエンティティーであり、単一の oneCCL デバイスに対応します。
communicator は、同種類の oneCCL デバイス間のメモリーバッファーの通信操作を定義します。すべての oneCCL
デバイスは、同じタイプのネイティブ・デバイス・オブジェクト (CPU のみ、または GPU のみ) を包括するか、ネイティブ・オ
ブジェクトを包括しません。
それぞれのプロセスは、複数ランクに対応することがあります。
注: プロセスごとの複数ランクのサポートはオプションです。
ユーザーが指定するサイズ、ランクからデバイスへのマッピング/ランク、コンテキスト、および KVS を使用して新しいコ
ミュニケーターを作成します。
注: device オブジェクトと context オブジェクトを省略すると、ネイティブ・オブジェクトなしで ccl::create_device()と ccl::create_context() 関数を使用して作成されます。
vector_class<communicator> ccl::create_communicators(
int size,
const map_class<int, device>& rank_device_map,
const context& context,
shared_ptr_class<kvs_interface> kvs) const;
communicator ccl::create_communicator(
int size,
int rank,
shared_ptr_class<kvs_interface> kvs);

size: ユーザーが指定したランクの合計数。
rank_device_map: デバイス上のローカルランクのユーザー指定マッピング。
6.4 定義237

oneAPI 仕様 リリース 1.0 リビジョン 3

rank: ユーザー指定のローカルランク。
context: はデバイス・コンテキスト。
kvs: ランクに対応する KVS。
戻り値: vector_class<communicator>/communicator。コミュニケーター・オブジェクトのベクトル/オブジェク
トのコミュニケーター。
communicator は、コミュニケーター・オブジェクトに対応するランク、デバイス、およびコンテキスト、ならびにコミュ
ニケーター内のランクの総数を取得するメソッドを提供する必要があります。
コミュニケーター内のランクを取得:
int communicator::rank() const;

戻り値: int。コミュニケーター・オブジェクトに対応するランク。
コミュニケーターのランクの総数を取得:
int communicator::size() const;

戻り値: int。ランクの総数。
コミュニケーターを構築する引数として使用されたデバイスを取得:
device get_device() const;

戻り値: device。コミュニケーター・オブジェクトに対応するデバイス。
コミュニケーターを構築する引数として使用されたコンテキストを取得:
context get_context() const;

戻り値: context。コミュニケーター・オブジェクトに対応するコンテキスト。
注: 「集合操作」も参照してください。
ストリーム
oneCCL 仕様では、communicator 通信操作の実行コンテキストをカプセル化する抽象化として stream を定義します。
ストリームは communicator 通信操作に渡されます。

6.4 定義238

oneAPI 仕様 リリース 1.0 リビジョン 3
oneCCL 仕様は、ネイティブ・オブジェクト (native_stream_type) を使用し、ネイティブ・オブジェクトを使用せずに
stream クラスのインスタンスを作成する方法を定義します。
新しいストリーム・オブジェクトを作成:
stream ccl::create_stream(native_stream_type& native_stream);
stream ccl::create_stream();native_stream: 既存のネイティブ・ストリーム・オブジェクト
戻り値: stream。ストリーム・オブジェクト。
stream クラスは、ネイティブ・オブジェクトを取得する機能を提供する必要があります。
ネイティブ・ストリーム・オブジェクトを取得:
native_stream_type stream::get_native();

戻り値: native_stream_type。ネイティブ・ストリーム・オブジェクト。stream オブジェクトがネイティブ・オブジェク
トを包括しない場合、例外をスローします。
イベント
oneCCL 仕様では、communicator 通信操作の実行コンテキストをカプセル化する抽象化として event を定義します。
oneCCL の各種通信操作は、操作の進行状況を追跡するイベント・オブジェクトを返す必要があります。イベントのベク
トルを communicator 通信操作に渡して、操作の入力依存関係を指定することができます。
注: 入力イベント処理のサポートはオプションです。
oneCCL 仕様は、ネイティブ・オブジェクト (native_event_type) を使用して event クラスのインスタンスを作成する方法を定義します。
新しいイベント・オブジェクトを作成:
event ccl::create_event(native_event_type& native_event);

native_event: 既存のネイティブ・イベント・オブジェクト。
戻り値: event。イベント・オブジェクト。
event クラスは、ネイティブ・オブジェクトを取得する機能を提供する必要があります。

6.4 定義239

oneAPI 仕様 リリース 1.0 リビジョン 3
ネイティブ・イベント・オブジェクトを取得:
native_event_type event::get_native();

戻り値: native_event_type。ネイティブ・イベント・オブジェクト。event オブジェクトがネイティブ・オブジェクトを包括しない場合、例外をスローします。
注: 「操作状況の追跡」も参照してください。
操作属性
操作属性を介して通信操作の動作を制御できます。
「操作属性」を参照してください。

6.4.2 通信操作
このセクションでは、oneCCL 仕様で定義される通信操作について説明します。
datatype
oneCCL 仕様では、通信操作に使用できる以下のデータ型を定義しています。
enum class datatype : int{
int8= /* 未指定 */,uint8= /* 未指定 */,int16= /* 未指定 */,int32= /* 未指定 */,uint32= /* 未指定 */,int64= /* 未指定 */,uint64= /* 未指定 */,float16= /* 未指定 */,float32= /* 未指定 */,bfloat16= /* 未指定 */,last_predefined= /* 未指定、上記のすべての値の最大値に等しい */};datatype::int8: 8 ビット符号付き整数。
datatype::uint8: 8 ビット符号なし整数。
datatype::int16: 16 ビット符号付き整数。
datatype::uint16: 16 ビット符号なし整数。

6.4 定義240

oneAPI 仕様 リリース 1.0 リビジョン 3
datatype::int32: 32 ビット符号付き整数。
datatype::uint32: 32 ビット符号なし整数。
datatype::int64: 64 ビット符号付き整数。
datatype::uint64: 64 ビット符号なし整数。
datatype::float16: 16 ビット/半精度浮動小数点。
datatype::float32: 32 ビット/単精度浮動小数点。
datatype::float64: 64 ビット/倍精度浮動小数点。
datatype::bfloat16: 非標準 16 ビット浮動小数点 (7 ビット仮数)。
注: datatype::float16 のサポートはオプションです。
カスタム Datatype
oneCCL 仕様は、datatype_attr 属性オブジェクトを使用してカスタム datatype 型を登録および登録解除する方法を定義します。
属性オブジェクトを指定するために使用できる識別子のリスト:
enum class datatype_attr_id { size = /* 未指定 */};datatype_attr_id::size: datatype 型のサイズ (バイト単位)。
カスタム datatype 型に登録可能な datatype 属性オブジェクトを作成:
datatype_attr ccl::create_datatype_attr();

戻り値: datatype_attr。カスタム datatype の属性を含むオブジェクト。
通信操作で使用するカスタム datatype を登録:
datatype ccl::register_datatype(const datatype_attr& attr);

attr: datatype の属性。
戻り値: datatype。カスタム datatype のハンドル。
カスタム datatype の登録解除:
void ccl::deregister_datatype(datatype dtype);

6.4 定義241

oneAPI 仕様 リリース 1.0 リビジョン 3
dtype: カスタム datatype のハンドル。
バイト単位の datatype サイズを取得:
size_t ccl::get_datatype_size(datatype dtype);

dtype: datatype のハンドル。
戻り値: size_t。バイト単位の datatype サイズ。
リダクション
oneCCL 仕様では、Allreduce、Reduce および ReduceScatter 集合操作に対しリダクション操作が定義されています。
enum class reduction{sum= /* 未指定 */,prod= /* 未指定 */,min= /* 未指定 */,max= /* 未指定 */,custom= /* 未指定 */};reduction::sum: 要素ごとの総和。
reduction::prod: 要素ごとの乗算。
reduction::min: 要素ごとの最小。
reduction::max: 要素ごとの最大。
reduction::custom: ユーザー定義のリダクション操作を指定。実際のリダクション関数は、reduction_fn 操作
属性を介して渡される必要があります。
「操作属性」を参照してください。
集合操作
oneCCL 仕様では、次の集合操作による通信操作が定義されています。
• Allgatherv• Allreduce• Alltoallv• Barrier• Broadcast• Reduce• ReduceScatter

6.4 定義242

oneAPI 仕様 リリース 1.0 リビジョン 3

これらの操作は集合操作です。つまり、oneCCL コミュニケーターに属するすべてのランクと通信する必要があり、集合
操作の順番はすべてのランクで同一でなければなりません。
communicator は、コミュニケーターの作成に使用されるデバイスに応じて、ホストまたはデバイスのメモリーバッ
ファーのどちらかで通信操作を行う機能を提供します。さらに、通信操作は、通信が関連する実行コンテキスト (ストリーム) およびイベントのベクトルを受け入れることがあります。出力イベント・オブジェクトは、操作の進行を追跡する機能も提供します。
注: 入力イベント処理のサポートはオプションです。
BufferType は、通信操作のデータバッファー (buf、send_buf および recv_buf) 内の要素の C++ タイプを定義するため以下で使用されます。少なくとも、[u]int{8/16/32/64}_t、float、double 型がサポートされている必要があります。関数の引数から推測できないデータ型を有効にするには、明示的に datatype パラメーターを指定しなけ
ればなりません。
注: 「カスタム Datatype」も参照してください。
通信操作は stream オブジェクトを受け入れる必要があります。コミュニケーターが native_device_type から作成された場合、デフォルトのストリームは対応するデバイスで native_stream_type に変換されます。
通信操作は属性オブジェクトを受け入れることがあります。パラメーターが指定されていない場合、デフォルトの属性オ
ブジェクトが使用されます (default_<operation_name>_attr)。デフォルトの属性オブジェクトはライブラリーによって提供されます。
注: 「操作属性」も参照してください。
通信操作の呼び出しに指定された引数が操作の要件を満たしていない場合、特に定義されていない限り動作は未定義です。
Allgatherv
Allgatherv は、コミュニケーター内のすべてのランクから単一のバッファーにデータを収集する集合通信操作です。ラ
ンクが異なると、異なるサイズのセグメントが収集されることがあります。出力バッファーの結果データは、ランクごとに同一である必要があります。

6.4 定義243

oneAPI 仕様 リリース 1.0 リビジョン 3
template<class BufferType>event ccl::allgatherv(const BufferType* send_buf,
size_t send_count,
BufferType* recv_buf,
const vector_class<size_t>& recv_counts,
const communicator& comm,const stream& stream,
const allgatherv_attr& attr = default_allgatherv_attr,
const vector_class<event>& deps = {});
event ccl::allgatherv(const void* send_buf,
size_t send_count,void* recv_buf,
const vector_class<size_t>& recv_counts,
datatype dtype,
const communicator& comm,const stream& stream,
const allgatherv_attr& attr = default_allgatherv_attr,
const vector_class<event>& deps = {});

send_buf: 収集するローカルデータを格納する BufferType の send_countelements を持つバッファー。
send_count: send_buf の BufferType の要素数。
recv_buf [out]: 収集された結果を格納するバッファー。すべてのランクの値を保持するのに十分な大きさがなければいけません。
recv_counts: 各ランクから受け取る BufferType 型の要素数を持つ配列。配列のサイズはランク数と等しくなければなりません。配列内の値はすべてのランクで同一であることが期待されます。呼び出し元ランクのポジション値は、
send_count と同一である必要があります。
dtype: send_buf および recv_buf の要素の detatype。BufferType が推測できる場合はスキップして、そうでない場合は明示的に渡す必要があります。
comm: 操作ランクのグループを定義するコミュニケーター。
stream: 操作に関連するオプションのストリーム。
attr: 操作をカスタマイズするオプションの属性。
deps: 操作が依存するイベントのベクトル (オプション)
戻り値: event。操作の進行状況を追跡するオブジェクト。
Allreduce
Allreduce は、コミュニケーターのすべてのランクの値に対しグローバルなリダクション操作を実行し、その結果をすべてのランクに送信する集合通信操作です。

6.4 定義244

oneAPI 仕様 リリース 1.0 リビジョン 3
template <class BufferType>event ccl::allreduce(const BufferType* send_buf,
BufferType* recv_buf,
size_t count,reduction rtype,
const communicator& comm,const stream& stream,
const allreduce_attr& attr = default_allreduce_attr,
const vector_class<event>& deps = {});
event ccl::allreduce(const void* send_buf,
void* recv_buf,
size_t count,reduction rtype,
datatype dtype,
const communicator& comm,const stream& stream,
const allreduce_attr& attr = default_allreduce_attr,
const vector_class<event>& deps = {});

send_buf: リダクションを行うローカルデータを格納する BufferType の count 要素を持つバッファー。
recv_buf [out]: リダクションされた結果を格納するバッファー。send_buf と同じ次元でなければなりません。
count: send_buf と recv_buf の BufferType 型の要素数。
rtype: 適用されるリダクション操作のタイプ。
dtype: send_buf および recv_buf の要素の detatype。BufferType が推測できる場合はスキップして、そうでない場合は明示的に渡す必要があります。
comm: 操作ランクのグループを定義するコミュニケーター。
stream: 操作に関連するオプションのストリーム。
attr: 操作をカスタマイズするオプションの属性。
deps: 操作が依存するイベントのベクトル (オプション) 。
戻り値: event。操作の進行状況を追跡するオブジェクト。
Alltoallv
Alltoall は、各ランクがそれぞれのランクに個別のデータブロックを送信する集合通信操作です。ブロックサイズは異なる可能性があります。i 番目のランクから捜査員された送信バッファーの j 番目のブロックは、j 番目のランクによって受信され、受信バッファーの i 番目のブロックに保持されます。

6.4 定義245

oneAPI 仕様 リリース 1.0 リビジョン 3
template <class BufferType>event ccl::alltoallv(const BufferType* send_buf,
const vector_class<size_t>& send_counts,
BufferType* recv_buf,
const vector_class<size_t>& recv_counts,
const communicator& comm,const stream& stream,
const alltoallv_attr& attr = default_alltoallv_attr,
const vector_class<event>& deps = {});
event ccl::alltoallv(const void* send_buf,
const vector_class<size_t>& send_counts,
void* recv_buf,
const vector_class<size_t>& recv_counts,
datatype dtype,
const communicator& comm,const stream& stream,
const alltoallv_attr& attr = default_alltoallv_attr,
const vector_class<event>& deps = {});

send_buf: 各ランクに送信されるローカルブロックを格納する BufferType の要素を持つバッファー。
send_counts: ランクごとに送信されるブロック内の BufferType 型の要素数を持つ配列。配列のサイズはランク数と等しくなければなりません。send_counts と recv_countsの呼び出し元ランクのポジション値は、同一である必要があります。
recv_buf [out]: 受信した結果を格納するバッファー。すべてのランクのブロックを保持するのに十分な大きさを持つ必要があります
recv_counts: 各ランクから受信したブロック内の BufferType 型の要素数を持つ配列。配列のサイズはランク数と等しくなければなりません。send_counts と recv_counts の呼び出し元ランクのポジション値は、同一である必要があります。
dtype: send_buf および recv_buf の要素の detatype。BufferType が推測できる場合はスキップして、そうでない場合は明示的に渡す必要があります。
comm: 操作ランクのグループを定義するコミュニケーター。
stream: 操作に関連するオプションのストリーム。
attr: 操作をカスタマイズするオプションの属性。
deps: 操作が依存するイベントのベクトル (オプション) 。
戻り値: event。操作の進行状況を追跡するオブジェクト。
Barrier
Barrier 同期は、コミュニケーターのすべてのランクで実行され、コミュニケーターのすべてのランクが呼び出しを終えたときにのみ完了します。

6.4 定義246

oneAPI 仕様 リリース 1.0 リビジョン 3
event ccl::barrier(const communicator& comm,const stream& stream,
const barrier_attr& attr = default_barrier_attr,
const vector_class<event>& deps = {});

comm: 操作ランクのグループを定義するコミュニケーター。
stream: 操作に関連するオプションのストリーム。
attr: 操作をカスタマイズするオプションの属性。
deps: 操作が依存するイベントのベクトル (オプション) 。
戻り値: event。操作の進行状況を追跡するオブジェクト。
Broadcast
Broadcast は、コミュニケーターの 1 つのランク (通常はルートとして示される) から、他のすべてのランクにデータを配
信 (ブロードキャスト) する集合通信操作です。
template <class BufferType>event ccl::broadcast(BufferType* buf,
size_t count,
int root,
const communicator& comm,const stream& stream = default_stream,
const broadcast_attr& attr = default_broadcast_attr,
const vector_class<event>& deps = {});
event ccl::broadcast(void* buf,
size_t count,datatype dtype,
int root,
const communicator& comm,const stream& stream = default_stream,
const broadcast_attr& attr = default_broadcast_attr,
const vector_class<event>& deps = {});

buf [in,out]: BufferType の count 要素を持つバッファー。ルートの send_buffer またはほかのランクのrecv_buffr として機能します。
count: buf 内の BufferType 型の要素数。
root: buf をブロードキャストするランク。
dtype: buf 内の要素の datatype。BufferType が推測できる場合はスキップして、そうでない場合は明示的に渡す必要があります。
comm: 操作ランクのグループを定義するコミュニケーター。
stream: 操作に関連するオプションのストリーム。
attr: 操作をカスタマイズするオプションの属性。
deps: 操作が依存するイベントのベクトル (オプション)。
6.4 定義247

oneAPI 仕様 リリース 1.0 リビジョン 3

戻り値: event。操作の進行状況を追跡するオブジェクト。
ReduceReduce は、コミュニケーターのすべてのランクの値に対しグローバルなリレデュース操作を実行し、その結果をすべてのランクに送信する集合通信操作です。
template <class BufferType>event ccl::reduce(const BufferType* send_buf,
BufferType* recv_buf,
size_t count,reduction rtype,
int root,
const communicator& comm,const stream& stream = default_stream,
const reduce_attr& attr = default_reduce_attr,
const vector_class<event>& deps = {});
event ccl::reduce(const void* send_buf,
void* recv_buf,
size_t count,datatype dtype,reduction rtype,
int root,
const communicator& comm,const stream& stream = default_stream,
const reduce_attr& attr = default_reduce_attr,
const vector_class<event>& deps = {});

send_buf: レデュースするローカルデータを格納する BufferType の count 要素を持つバッファー。
recv_buf [out]: レデュースされた結果を格納するバッファー。send_buf と同じ次元である必要があります。root
ランクによってのみ使用され、他のランクでは無視されます。
count: send_buf および recv_buf 内の BufferType 型の要素数。
rtype: 適用されるリダクション操作のタイプ。
root: リダクションの結果を取得するランク。
dtype: send_buf および recv_buf の要素の detatype。BufferType が推測できる場合はスキップして、そうでない場合は明示的に渡す必要があります。
comm: 操作ランクのグループを定義するコミュニケーター。
stream: 操作に関連するオプションのストリーム。
attr: 操作をカスタマイズするオプションの属性。
deps: 操作が依存するイベントのベクトル (オプション) 。
戻り値: event。操作の進行状況を追跡するオブジェクト。

6.4 定義248

oneAPI 仕様 リリース 1.0 リビジョン 3
ReduceScatter
Reduce-scatter は、コミュニケーターのすべてのランクの値に対しグローバルなリダクション操作を実行し、その結果
をすべてのランクに分散する集合通信操作です。
template <class BufferType>event ccl::reduce_scatter(const BufferType* send_buf,
BufferType* recv_buf,
size_t recv_count,reduction rtype,
const communicator& comm,const stream& stream,
const reduce_scatter_attr& attr = default_reduce_scatter_attr,
const vector_class<event>& deps = {});
event ccl::reduce_scatter(const void* send_buf,
void* recv_buf,
size_t recv_count,datatype dtype,reduction rtype,
const communicator& comm,const stream& stream,
const reduce_scatter_attr& attr = default_reduce_scatter_attr,
const vector_class<event>& deps = {});

send_buf: リダクションを行うローカルデータを格納する BufferType の comm_size * count 要素を持つバッファー。
recv_buf [out]: BufferType 型の recv_count 要素を含む結果ブロックを格納するバッファー。
recv_count: 受信したブロック内の BufferType 型の要素数。
rtype: 適用されるリダクション操作のタイプ。
dtype: send_buf および recv_buf の要素の detatype。BufferType が推測できる場合はスキップして、そうでない場合は明示的に渡す必要があります。
comm: 操作ランクのグループを定義するコミュニケーター。
stream: 操作に関連するオプションのストリーム。
attr: 操作をカスタマイズするオプションの属性。
deps: 操作が依存するイベントのベクトル (オプション) 。
戻り値: event。操作の進行状況を追跡するオブジェクト。
注: 以下も参照してください。
・ コミュニケーター
・ ストリーム・ イベント・ 操作状況の追跡

6.4 定義249

oneAPI 仕様 リリース 1.0 リビジョン 3
操作属性
oneCCL 仕様は、操作の動作修飾子として機能する通信操作の属性を定義します。オプションで、それらは対応する通信
操作に渡されることがあります。
oneCCL 仕様では、次の操作属性のクラスが定義されています。
• allgatherv_attr• allreduce_attr• alltoallv_attr• barrier_attr• broadcast_attr• reduce_attr• reduce_scatter_attr
oneCCL 仕様は、操作属性オブジェクトを埋めるために使用できる属性識別子を定義します。
通信操作に使用できる一般的な属性識別子のリスト:
enum class operation_attr_id {priority= /* 未指定 */,to_cache= /* 未指定 */,synchronous= /* 未指定 */,match_id= /* 未指定 */,last_value= /* 未指定、上記のすべての値の最大値に等しい */};operation_attr_id::priority: 通信操作の優先順位。
operation_attr_id::to_cache: 永続的/非永続的な通信操作。match_id と組み合わせて使用する必要があります。
operation_attr_id::synchronous: 同期/非同期通信操作。
operation_attr_id::match_id: 操作の一意な識別子。to_cache と組み合わせて通信操作のキャッシュを有効にします。
通信操作固有の属性識別子は、共通識別子のリストを拡張する場合があります。

6.4 定義250

oneAPI 仕様 リリース 1.0 リビジョン 3
Allreduce、Reduce および ReduceScatter 集合操作に使用できる属性識別子のリスト:
enum class allreduce_attr_id {reduction_fn = /* 未指定 */};enum class reduce_attr_id {reduction_fn = /* 未指定 */};enum class reduce_scatter_attr_id {reduction_fn = /* 未指定 */};allreduce_attr_id::reduction_fn/reduce_attr_id::reduction_fn/reduce_scatter_attr_id::reduction_fn: シグネチャーに続くカスタム・リダクション操作の関数ポインター。
typedef void (*reduction_fn) {const void*,/* in_buf
size_t,/* in_countvoid*,/* inout_buf
size_t*,/* out_countdatatype,/* datatypeconst fn_context* /* context
};

*/
*/
*/
*/
*/
*/

typedef struct {const char* match_id;
const size_t offset;} fn_context;

対応する通信操作で使用できる操作属性オブジェクトを作成します。
template <class OpAttrType>
OpAttrType ccl::create_operation_attr();

戻り値: OpAttrType。特定の通信操作の属性を保持するオブジェクト。
操作属性クラスは、特定の属性識別子を持つ値を取得および設定する get および set メソッドを提供します。
操作状況の追跡
oneCCL 通信操作は、操作の進行状況を追跡するために使用するイベント・オブジェクトを返します。
event クラスは、ブロック方式で操作の完了を待機する機能、非ブロッキング方式で完了ステータスをチェックする機能、および操作の完了時に通知されるネイティブ・オブジェクトを取得する機能を提供する必要があります。
イベント
ブロッキング方式で操作の完了を待機します。

6.4 定義251

oneAPI 仕様 リリース 1.0 リビジョン 3
void event::wait();

非ブロッキング方式で操作の完了をチェックします。
bool event::test();

戻り値: bool。操作が完了した場合は true を返し、完了しなかった場合は false を返します。
操作の完了時に通知されるネイティブ・オブジェクトを取得します。
native_event_type event::get_native();

戻り値: native_event_type。操作が完了した時に通知されるネイティブ・オブジェクト。event オブジェクトがネイ
ティブ・オブジェクトを包括しない場合、例外をスローします。

6.4.3 エラー処理
oneCCL エラー処理は、C++ の例外メカニズムに関連しています。エラーが発生すると、標準の C++ エラー処理メカニズムを使用してキャッチされた関数呼び出しに伝搬されます。
例外の分類
oneCCL の例外分類は、C++ 標準ライブラリーの分類と一致しています。oneCCL は、oneCCL 例外クラスの階層に基本クラスを定義するクラスを導入します。すべての oneCCL ルーチンは、基本クラスから継承される例外をスローします。
oneCCL 例外階層では、ccl::exception は std::exception クラスから継承された基本クラスです。
他のすべての oneCCL 例外クラスは、この基本クラスから派生しています。
この仕様では、エラーチェックを行う機能を実装する必要はありません。ただし、実装がエラーチェックを提供する場合、次の例外クラスを使用する必要があります。追加される実装固有の例外クラスは、これらのクラスのいずれにも適合しない例外条件に使用できます。
一般的な例外例外クラス

説明

ccl::exception

一般的な不特定のエラーをレポートします

ccl::invalid_argument

操作への引数が拒否されたときのエラーをレポートします

ccl::host_bad_alloc

ホストのメモリー割り当てで発生したエラーをレポートします

ccl::unimplemented

要求された操作が実装されていない場合にエラーをレポートします

ccl::unsupported

要求された操作がサポートされていない場合にエラーをレポートします

6.4 定義252

oneAPI 仕様 リリース 1.0 リビジョン 3

6.5

プログラミング・モデル

6.5.1 一般的なワークフロー
oneCCL API を使用した一般的なワークフローを示します
1.

メインの組込み KVS を作成します。アドレスは、アウトオブバンド通信メカニズムを使用して配布し、他のプロセスで KVS を作成する際に使用されます。
using namespace std;/* 例えば、MPI をアウトオブバウンドの通信メカニズムとして使用します */int mpi_rank, mpi_size;
MPI_Init(&argc, &argv);
MPI_Comm_rank(MPI_COMM_WORLD, &mpi_rank);
MPI_Comm_size(MPI_COMM_WORLD, &mpi_size);
ccl::shared_ptr_class<ccl::kvs> kvs;
ccl::kvs::address_type kvs_addr;
if (mpi_rank == 0) {kvs = ccl::create_main_kvs();kvs_addr = kvs->get_address();
MPI_Bcast((void*)kvs_addr.data(), ccl::kvs::address_max_size, MPI_BYTE, 0,
MPI_COMM_WORLD);}
else {
MPI_Bcast((void*)kvs_addr.data(), ccl::kvs::address_max_size, MPI_BYTE, 0,
MPI_COMM_WORLD);
kvs = ccl::create_kvs(kvs_addr);}2.

コミュニケーターを作成します。
/* ホスト通信 */auto comm = ccl::create_communicator(mpi_size, mpi_rank, kvs);

6.5 プログラミング・モデル

253

oneAPI 仕様 リリース 1.0 リビジョン 3/* SYCL デバイスは、プロセスごとに複数のデバイスと通信します *//* sycl_context -> sycl::context *//* sycl_devices -> vector< sycl::device> *//* sycl_queues -> vector< sycl::queue> *//* sycl::context オブジェクトから ccl::context を作成します */auto ccl_context = ccl::create_context(sycl_context);/* sycl::device オブジェクトから ccl::device を作成します */vector<ccl::device> ccl_devices;for (size_t idx = 0; idx < sycl_devices.size(); idx++) {ccl_devices.push_back(ccl::create_device(sycl_devices[idx]));}map<int, ccl::device> r2d_map;
for (auto& dev : ccl_devices) {int rank = /* 特定のデバイスに対してグローバルに一意のランクを生成します */r2d_map[rank] = dev;}/* sycl::queue オブジェクトから ccl::stream オブジェクトを作成します */vector<ccl::stream> ccl_streams;for (size_t idx = 0; idx < sycl_queues.size(); idx++) {ccl_streams.push_back(ccl::create_stream(sycl_queues[idx]));}
auto comms = ccl::create_communicators(mpi_size * r2d_map.size(),r2d_map,
ccl_context,
kvs);

3.

コミュニケーターで選択した通信操作を実行します。
/* ホスト通信 */allreduce(..., comm).wait();/* SYCL デバイス通信 */vector<ccl::event> events;for (auto& comm : comms) {events.push_back(allreduce(..., comm, ccl_streams[comm.rank()]));}for (auto& e : events) {e.wait();}6.5 プログラミング・モデル

254

第7章
レベルゼロ
oneAPI レベルゼロは、oneAPI プラットフォームのデバイスに合わせて調整された低レベルのダイレクト・メタル直接インターフェイスを提供します。レベルゼロでは、関数ポインター、仮想関数、統合メモリー、I/O 機能など幅広い言語機能をサポートすると同時に、次のような高レベルのランタイム API で必要な各種明示的な制御を提供します。
• デバイスの発見• メモリー割り当て• ピアツーピア通信• プロセス間共有• カーネル・サブミッション• 非同期実行とスケジュール• 同期プリミティブ• メトリックサポート
API アーキテクチャーは、ベースとなる oneAPI プラットフォーム・デバイスとその機能の物理的および論理的な抽象化を定義します。デバイス、サブデバイス、およびメモリーは物理レベルで定義されますが、コマンドキュー、イベント、および同期メソッドは論理エンティティーとして定義されます。すべての論理エンティティーは、デバイスレベルの物理的機能にバインドされます。API は、デバイスへの低レイテンシー送信モデルや、同時ホストスレッド間でのワークの構築と送信に適合するモデルなど、多様な用途に合わせて調査されたスケジュール・モデルを提供します。レベルゼロは、OpenCL など他の低レベル API の影響を受けますが、独立して進化するように設計されています。また、レベルゼロはGPU アーキテクチャーの影響も強く受けますが、FPGA などのさまざまな oneAPI 計算デバイス・アーキテクチャーでサポートされます。

7.1

API の詳細説明

詳しい仕様は、レベルゼロ仕様 (英語) でオンラインから参照できます。

255

第8章
oneDAL
このドキュメントでは、oneAPI データ・アナリティクス・ライブラリー (oneDAL) の実装要件を示します。
oneDAL は、データ解析 (前処理、変換、解析、モデリング、検証、意思決定) のすべてのステージで高度に最適化されたアルゴリズムのビルディング・ブロックをオンラインで、および分散処理モードの計算を提供することで、ビッグデータ解
析の高速化を支援するライブラリーです。oneDAL の現在のバージョンでは、従来の C++ インターフェイスに加えデー
タ並列 C++ (DPC++) API 拡張を提供します。
一般的な情報は、oneDAL GitHub* ページ (英語) でご覧ください。

8.1

概要

oneAPI データ・アナリティクス・ライブラリー (oneDAL) は、データ解析のすべてのステージ (データソースからのデータ
取得、前処理、変換、データマイニング、モデリング、検証および意思決定) をカバーするビルディング・ブロックを提供するライブラリーです。

oneDAL は、データ分析のいくつかのステージがエッジデバイス (データの生成と消費が近い場合) で実行されている場
合、エンドツーエンド分析の概念をサポートします。具体的には、oneDAL アプリケーション・プログラミング・インターフェイス (API) は、特定のクロスデバイス通信技術にとらわれないため、異なるエンドツーエンドの解析フレームワーク
内で使用することができます。

256

oneAPI 仕様 リリース 1.0 リビジョン 3

oneDAL は、次の主要コンポーネントで構成されます。
• データ管理: コンポーネントには、データの取得、前処理と正規化、(サポートされるデータソースにより行われる) 数値形式へのデータ変換、モデル表現用のクラスとユーティリティーが含まれます。
• アルゴリズム: コンポーネントは、データ解析 (データマイニング) およびデータモデリング (訓練と予測) 用のアルゴリズムを実装するクラスから構成されます。これらのアルゴリズムには、クラスター化、分類、回帰、
および推奨アルゴリズムが含まれます。アルゴリズムは、次の計算モードをサポートしています。
– バッチ処理: アルゴリズムは最終結果を生成するためデータセット全体を処理します。
– オンライン処理: アルゴリズムは、デバイスのメモリーにストリームされたブロックでデータブロック
を処理します– 分散処理: モードアルゴリズムは複数のデバイス (計算ノード) に分散されたデータを処理します。
oneDAL の分散アルゴリズムは、デバイス間の通信技術を抽象化するため、各種マルチデバイスの計算とデータ転送で利用できます。
使用方法に応じて、アルゴリズムは実際のデータ (データセット) とデータモデルの両方を処理します。
– 解析アルゴリズムは通常、データセットを処理します。
– 訓練アルゴリズムは通常、データセットを処理して適切なデータモデルを訓練します。
– 予測アルゴリズムは通常、訓練されたデータモデルと作業データセットを処理します。
• ユーティリティー・コンポーネントには、クラスの設計やメモリー・アロケーター、型特性などのメソッドの実装に使用することを目的とした補助機能が含まれています。
• その他のコンポーネントには、解析パイプラインの各種ステージでアルゴリズムをカスタマイズおよび最適化するため、oneDAL アルゴリズムとアプリケーションで使用することを目的とした機能が含まれます。このようなアルゴリズムには、ソルバーや乱数生成器が含まれます。
8.1 概要257

oneAPI 仕様 リリース 1.0 リビジョン 3

データ管理、アルゴリズム、ユーティリティーおよびその他のコンポーネント・クラスは、最も重要な使用シナリオをカバーし、直接 API 呼び出しにより複雑なデータ解析ワークフローのシームレスな実装を可能にします。同時に、ライブラ
リーはライブラリーの特定のクラスとメソッドを再定義することで API をカスタマイズできるオブジェクト指向のフレー
ムワークです。

8.2

用語集

8.2.1 マシンラーニング用語
カテゴリー特徴 (Categorical feature): 個別ドメインの特徴。名目 (nominal) または 順序 (ordinal) に分けられます。
同義語: 離散特徴、定性特徴。
分類 (Classification) : 特徴ベクトルにラベルを割り当てる教師ありマシンラーニングの問題。
例: 写真に写されているオブジェクトの種類 (犬や猫?) を予測して、電子メールがスパムであるかどうかを推測します。
クラスタリング (Clustering) : 特徴ベクトルをバンチにグループ化する教師なしのマシンラーニングの問題。バンチは通常、名目 (nominal) 値としてエンコードされます。
例: 宇宙空間のイメージから大規模な星団を検出します。
連続特徴 (Continuous feature): 実数のドメイン内の値を持つ特徴。interval または ratio にすることができます。
同義語: 量的特徴、数値的特徴。
例: 身長や家の値段。
CSV ファイル (CSV file): カンマで区切られた値のファイル (csv) は、テキストファイルの一種です。CSV ファイルの各
行は、区切り文字で区切られたフィールドを含むレコードです。フィールドは、数値形式またはテキスト形式にすることができます。テキストは、通常カテゴリー値を指します。デフォルトでは、区切り文字はカンマですが、任意の文字にすることもできます。詳細はこちら (英語) をご覧ください。
データセット (Data set): 観測された値のコレクション。
次元リダクション (Dimensional reduction): オリジナルの特徴ベクトルの意味のあるプロパティーを保持しながら、特徴ベクトルのセットを高次元空間から低次元空間に変換します。
特徴 (Feature): 実際のオブジェクトまたはイベントの特定のプロパティーまたは品質。タイプとドメインが定義されます。マシンラーニングの問題では、特徴は互いに独立した入力変数として見なされます。
同義語: 属性、変数、入力変数。

8.2 用語集

258

oneAPI 仕様 リリース 1.0 リビジョン 3
特徴ベクトル (Feature vector): 実際のオブジェクト、イベント、またはオブジェクトやイベントのグループに関する情報をエンコードするベクトル。1 つ以上の特徴を含みます。
例：長方形を特徴付ける幅と高さ。
推論 (Inference): 入力特徴ベクトルに基づいて応答値を予測するため、訓練済みモデルをデータセットに適用するプ
ロセス。
同義語: 予測。
推論セット (Inference set): 推論ステージで使用されるデータセット。通常、応答はありません。
区間特徴 (Interval feature): 比較、加算、または減算は可能ですが、乗算や除算はできない値を持つ連続特徴。
例: 時間枠のスケール、摂氏または華氏の温度。
ラベル (Label): カテゴリー (categorical) または順序 (ordinal) 値による応答。これは、分類とクラスタリング問題の出力です。
例: スパム検出では、電子メールがスパムであるかどうかを示すバイナリーラベルがあります。
モデル (Model): 新しいデータセットで推論を行うために必要な情報を格納するエンティティー。通常、訓練プロセスの結果です。
例: 線形回帰アルゴリズムでは、モデルにそれぞれの入力特徴の重み値と単一のバイアス値が含まれます。
名目特徴 (Nominal feature): 値の間で順序付けされていないカテゴリー特徴 (categorical feature)。名目特徴に対しては、等式演算のみが定義されています。
例: 人の性別、車の色。
観察 (Observation): 特徴ベクトルとゼロ以上の応答。
例: インスタンス、サンプル。
順序特徴 (Ordinal feature): 値の間の同等性と順序付け操作が定義されたカテゴリー特徴。
例: 生徒の成績。
外れ値 (Outlier): 他の観測とは大きく異なる観測。
比率特徴 (Ratio feature): 等式、比較、加算、減算、乗算、除算が定義された連続特徴。ゼロ値の要素は値がないことを意味します。
例: 塔の高さ。

8.2 用語集259

oneAPI 仕様 リリース 1.0 リビジョン 3

回帰 (Regression): 特徴ベクトルに連続応答を割り当てる教師ありのマシンラーニングの問題。
例: 気象条件に基づく気温の予測。
応答 (Response): 教師あり学習問題で特徴ベクトルから依存関係を定義する必要がある実際のオブジェクトまたはイ
ベントのプロパティー。特徴は、マシンラーニング問題の入力であり、応答は推論ステージのモデルで作成される出力の1 つです。
同義語: 従属変数。
教師あり学習 (Supervised learning): 特徴と応答の間の依存関係に関する情報を含むデータセットを使用する訓練
プロセス。
目標は、入力特徴ベクトルと応答の間の依存関係モデルを得ることです。
訓練 (Training): 訓練セットから抽出された情報を基にモデルを作成するプロセス。結果として得られるモデルは、いく
つかの品質基準に基づいて選択されます。
訓練セット (Training set): モデルを作成するため訓練ステージで使用するデータセット。
教師なし学習 (Unsupervised learning): 応答のない訓練セットを使用する訓練プロセス。目的は、特徴ベクトルの隠されたパターンとそれらの間の依存関係を検出することです。

8.2.2 oneDAL の用語
アクセサー (Accessor): 特別なデータ形式によって別のオブジェクトへのデータアクセスを提供するオブジェクトに対する oneDAL の概念。オブジェクトのインターフェイスからデータアクセスを抽象化し、さまざまなタイプのオブジェクトに格納されているデータへの均一なアクセスを提供します。
バッチモード (Batch mode): oneDAL アルゴリズムの計算モードであり、計算に必要なすべてのデータが開始時に利用可能で、計算が実行されるデバイスのメモリーに収まります。
ビルダー (Builder): 別のオブジェクトの作成をカプセル化し、反復的に作成を可能にする oneDAL の概念。
連続データ (Contiguous data): 1 つの連続したメモリーブロックに保存されるデータ。データ形式の特徴の 1 つ。
データ形式 (Data format): データの内部構造表現。
例: データは、構造体配列または圧縮された疎行形式で保存できます。
データレイアウト (Data layout): 連続データブロック内の要素の順序を表現するデータ形式。
例: 行優先形式 (要素は行ごとに格納される)。

8.2 用語集

260

oneAPI 仕様 リリース 1.0 リビジョン 3

データ型 (Data type): コンパイラーが格納およびアクセスする際に使用するデータ属性。バイト単位のサイズ、エン
コード原則、および利用可能な操作 (プログラミング言語の観点から) が含まれます。
例: int32_t、float、double。
フラットデータ (Flat data): 連続する同種データブロック。
ゲッター (Getter): プライベート・メンバー変数の値を返すメソッド。
例:
std::int64_t get_row_count() const;

異種データ (Heterogeneous data): 異なるデータ型または、それらに定義される異なる操作セットのどちらかの値を含むデータ。データ形式の特徴の 1 つ。
例：3 つの区間特徴の 100 個の観測値を含むデータセット。最初の 2 つの特徴は、float32 データ型であり、3 番目の特徴は float64 データ型です。
同種データ (Homogeneous data): 単一のデータ型とそれらに定義された同じセットの操作を含むデータ。データ形式の特徴の 1 つ。
例：3 つの区間特徴の 100 個の観測値を含むデータセット (それぞれ float32 型)。
不変性 (Immutability): 作成後に状態を変更できない場合、オブジェクトは不変です。
メタデータ (Metadata): オブジェクトの論理的および物理的な構造に関する情報。メタデータ値のすべての組み合わせ
は、特定のタイプのオブジェクトの完全なセットを示します。メタデータは、タイプ定義に含まれない情報は示しません(例: 実装の詳細)。
例: テーブル・オブジェクトには、100 個以上の観測値 (メタデータの論理部分) を持つ 3 つの名目特徴を含めることができます。このオブジェクトは、データを疎 CSR 配列として格納でき、それらの直接アクセスを提供します (物理部分)
オンラインモード (Online mode): oneDAL アルゴリズムの計算モードの 1 つであり、計算に必要なデータは、時間経
過とともに部分的に利用可能です。
参照カウント・オブジェクト (Reference-counted object): 一意な実装での参照カウントを格納する、コピー構築および割り当て可能な oneDAL オブジェクト。このオブジェクトに対して定義される両方のコピー操作は軽量です。新しいオブジェクトが作成されるたびに参照カウントだけが増加します。参照カウントがゼロになると、実装は自然にオブジェク
トを解放します。
セッター (Setter): パラメーターのみを受け入れて、その値をプライベート・メンバー変数に割り当てるメソッド。

8.2 用語集

261

oneAPI 仕様 リリース 1.0 リビジョン 3
例:void set_row_count(std::int64_t row_count);
テーブル (Table): カテゴリーまたは連続数値データのみを含むデータセットの oneDAL の概念。ユーザー・アプリケーションとoneDAL 内の計算間のデータ転送として機能します。データ形式の詳細を隠匿し、データへのアクセスを一般化します。

ワークロード (Workload): oneDAL アルゴリズムをデータセットに適用する際の問題。

8.2.3 oneAPI の一般用語
API: アプリケーション・プログラミング・インターフェイス。
DPC++: データ並列 C++ (DPC++) は、データ並列プログラミングの生産性向けに設計された高レベル言語です。
DPC++ は Khronos Group の SYCL* を基にしており、データ並列処理とヘテロジニアス・プログラミングをサポートします。
ホスト/デバイス (Host/Device): OpenCL* [OpenCL* 仕様] では、接続された GPU 実行カーネルを制御する CPU を指します。
JIT (Just in Time Compilation): プログラム実行中のコンパイル。
カーネル (Kernel): OpenCL* [OpenCL* 仕様] または SYCL* で記述され、GPU デバイスで実行されるコード。
SPIR-V (Standard Portable Intermediate Representation - V): 計算カーネルを中間表現する言語。
SYCL*: SYCL* [SYCL* 仕様] — OpenCL* の高水準プログラミング・モデル。標準の C++ 言語を使用して、異種プログ
ラミング・コードを「単一ソース」で記述できます。

8.2 用語集

262

oneAPI 仕様 リリース 1.0 リビジョン 3

8.3

数学表記

表記規則

定義

n または m

データセット内の観測値の数。一般的に n が使用されますが、訓練セットと推論セットなど 2 つのデー
タセットを区別する場合、m が必要になることがあります。

p または r

データセット内の特徴数。一般的に p が使用されますが、2 つのデータセットを区別する場合、r が必要になることがあります。

a × b
|A|

行列 (データセット) の次元には、a 行 (観測) と b 列 (特徴) があります。

‖x‖ベクトル x ∈ R の L2 ノルム。

sgn(n)x ∈ R の符号関数:xi

アルゴリズムの説明では、通常、訓練セットの i 番目の特徴ベクトルを示します。

′

アルゴリズムの説明では、通常、推論セットの i 番目の特徴ベクトルを示します。

𝑥𝑖

yi

アルゴリズムの説明では、通常、訓練セットの i 番目の応答を示します。
′′

アルゴリズムの説明では、通常、推論セットの特徴ベクトル 𝑥𝑖 が与えられた場合、推論アルゴリズムによって予測される i 番目の応答を示します。

𝑦𝑖

8.4

コンテキストに応じて次のように解釈されます。
• A が集合の場合、これはその基数、つまり集合 A の要素数を示します。
• A が実数の場合、これは A の絶対値を示します。

プログラミング・モデル

oneDAL は主にデータ解析で広く利用されるアルゴリズムを対象とします。これらのアルゴリズムには、通常、多くのパラメーター (内部動作と結果を制御する) があります。マシンラーニングでは、これらのパラメーターは、訓練中に学習されたモデル・パラメーターと区別するため、メタ・パラメーターと呼ばれることがあります。いくつかのアルゴリズム (英語) は、多くのメタ・パラメーターを定義していますが、ほかのアルゴリズムに依存するアルゴリズムもあります。例えば、ロジスティック回帰の訓練手順は最適化アルゴリズムに依存します。
メタ・パラメーターに加えて、マシンラーニング・アルゴリズムには、訓練や推論など、さまざまなステージがあります。さらに、アルゴリズムのステージには各種計算メソッドを実装できます。例えば、線形回帰モデルは連立一次方程式を解く[Friedman17]、または反復最適化ソルバーを経験値リスク関数に直接適用することで訓練できます [Zhang04]。
さまざまなタイプの問題解決に同じマシンラーニング手法が利用されることがよくあります。例えば、線形回帰では回帰問題の解決に使用される数学モデルが、ロジスティック回帰などの分類の解決にも一般化されます。このような手法は、問題固有のいくつかの面で異なりますが、同じメタ・パラメーターのサブセットを共有し、共通の計算フローを持ちます。

8.3 数学表記

263

oneAPI 仕様 リリース 1.0 リビジョン 3
oneDAL では、これらの手法を異なるアルゴリズムとは見なしません。それに代わり、oneDAL は同じアルゴリズムが異なる計算タスクを実行することがあります。
計算の面では、アルゴリズムの実装は float、double、bfloat16 などの浮動小数点データ型に依存する場合があります。精度の要件はワークロードによって異なるため、必要とする型を指定する機能を持つことはエンドユーザーから見れば重要です。
この課題に取り組むため、アルゴリズムは記述子と操作に分解されます。

8.4.1 エンドツーエンドの例
以下に、GPU で oneDAL アルゴリズムを使用する一般的なワークフローを示します。この例は、主成分分析アルゴリズ
ム (Principal Component Analysis algorithm (PCA)) 向けに提供されています。
以下に手順を示します。
• CSV ファイルからデータを読み取ります• PCA の訓練と推論操作を実行します• 訓練ステージで得られた中間結果にアクセスします1.

すべての oneDAL 宣言を利用できるように、次のヘッダーをインクルードします。
#include "oneapi/dal.hpp"/* この例で必要な標準ライブラリーのヘッダー */#include <cassert> #include <iostream>2.

対象のデバイスセレクターを使用して SYCL* キューを作成します。ここでは、GPU セレクターを使用します。
const auto queue = sycl::queue{ sycl::gpu_selector{} };3.

すべての oneDAL 宣言は oneapi::dal 名前空間にあるため、oneapi::dal の代わりに dal を使用
するには、oneapi 名前空間からすべての宣言をインポートします。
using namespace oneapi;

4.

CSV データソースを使用して、CSV ファイルからテーブルにデータを読み取ります。
const auto data = dal::read<dal::table>(queue, dal::csv::data_source{"data.csv"});

5.

PCA 記述子を作成し、パラメーターを構成して、CSV からロードされたデータに対して訓練アルゴリズム
を実行します。
const auto pca_desc = dal::pca::descriptor<float>.set_component_count(3).set_deterministic(true);
const dal::pca::train_result train_res = dal::train(queue, pca_desc, data);

8.4 プログラミング・モデル

264

oneAPI 仕様 リリース 1.0 リビジョン 3
6.

学習した固有ベクトルを出力します。
const dal::table eigenvectors = train_res.get_eigenvectors();
const auto acc = dal::row_accessor<const float>{eigenvectors};for (std::int64_t i = 0; i < eigenvectors.row_count(); i++) {/* テーブルから i 番目の行を取得し、固有ベクトルを USM ポインターの先へ格納します */const dal::array<float> eigenvector = acc.pull(queue, {i, i + 1});
assert(eigenvector.get_count() == eigenvectors.get_column_count());
std::cout << i << "-th eigenvector: ";for (std::int64_t j = 0; j < eigenvector.get_count(); j++) {std::cout << eigenvector[j] << " ";}std::cout << std::endl;}

7.

訓練されたモデルを推論に適用してデータの次元を減らします。
const dal::pca::model model = train_res.get_model();const dal::table data_transformed =dal::infer(queue, pca_desc, data).get_transformed_data();assert(data_transformed.column_count() == 3);

8.4.2 記述子
記述子は、すべてのメタ・パラメーター、ほかのアルゴリズムへの依存関係、浮動小数点データ型、計算メソッド、およびタスクを含むアルゴリズムを表すオブジェクトです。記述子は次のように機能します。
• 操作のディスパッチ・メカニズム。記述子のタイプを基に操作は特定のアルゴリズムの実装を実行します。
• メタ・パラメーターのアグリゲーター。コンパイル時または実行時にメタ・パラメーターを設定するインターフェイスを提供しています。
• アルゴリズムの状態を保存するオブジェクト。一般に、記述子は操作が適用された後に状態が変化する状態を持つオブジェクトです。
それぞれの oneDAL アルゴリズムには、対応する記述子が定義される専用の名前空間があります (詳細は、「名前空間」
を参照)。記述子は以下を定義します。
• テンプレート・パラメーター: 記述子には任意の数のテンプレート・パラメーターを含めることができますが、少なくとも 3 つをサポートする必要があります。
– float はアルゴリズムが計算に使用する浮動小数点の型。です。このパラメーターは最初に定義され、oneapi::dal::default_float_t デフォルト値を持ちます。
– メソッドは計算方法を定義するタグタイプです。このパラメーターは 2 番目に定義され、method::by_default デフォルト値を持ちます。

8.4 プログラミング・モデル

265

oneAPI 仕様 リリース 1.0 リビジョン 3– タスクは計算タスクを指定するタグタイプです。このパラメーターは 3 番目に定義され、
task::by_default デフォルト値を持ちます。
• プロパティー: プロパティーは、対応するゲッターとセッターメソッドを使用してアクセスできる実行パラ
メーターです。
次のサンプルコードは、抽象化アルゴリズムの記述子定義の一般的な構造を示します。特定のアルゴリズムを定義するには、次の文字列を置き換えます。
• %ALGORITHM% は、アルゴリズムの名称と名前空間です。アルゴリズムに関連するすべてのクラスと構造は、名前空間で定義されます。
• %PROPERTY_NAME% と %PROPERTY_TYPE% は、アルゴリズムのプロパティーの名前とタイプです。
namespace oneapi::dal::%ALGORITHM% {template <typename Float= default_float_t,
typename Method= method::by_default,
typename Task
= task::by_default,/* 追加のテンプレート・パラメーター */>class descriptor {public:/* コンストラクター */Descriptor{const %PROPERTY_TYPE%& %PROPERTY_NAME%,/* 追加のプロパティー */}/* `%PROPERTY_NAME%` プロパティーのゲッターとセッター */descriptor& set_%PROPERTY_NAME%(%PROPERTY_TYPE% value);%PROPERTY_TYPE% get_%PROPERTY_NAME%() const;/* 追加のプロパティー */};} // namespace oneapi::dal::%ALGORITHM%

アルゴリズムのメタ・パラメーターは、次の要件を満たすプロパティーにマップされます。
• プロパティーはゲッターメソッドとセッターメソッドで定義されます。プロパティーの値を格納するベースとなるクラスメンバーは、記述子のインターフェイスに現われることはありません。
• ゲッターはベースとなるクラスメンバー変数の値を取得します。
• セッターは、プロパティー・タイプのパラメーターを 1 つだけ受け入れ、それをベースとなるクラスメンバー
変数に設定します。
• ほとんどのプロパティーはデフォルト値で事前設定されますが、事前設定されないプロパティーは設定値をコンストラクターに渡すことで初期化されます。
• セッターは記述子オブジェクトへの参照を返しますが、次に示すように呼び出しを連鎖することもできます。
auto desc = descriptor{}.set_property_name_1(value_1).set_property_name_2(value_2).set_property_name_3(value_3);

8.4 プログラミング・モデル

266

oneAPI 仕様 リリース 1.0 リビジョン 3
浮動小数点タイプ
アルゴリズムは、少なくとも 1 つの実装定義の浮動小数点型をサポートする必要があります。その他の浮動小数点型はオプションです (float、double、float16、bfloat16 など)。これらの型をサポートするかどうかは、oneDAL の実装に依存します。
記述子のデフォルトで使用される浮動小数点型は実装依存であり、最上位の名前空間内で宣言する必要があります。
namespace oneapi::dal {using default_float_t = /* 実装定義 */;} // namespace oneapi::dal

計算メソッドサポートされる計算メソッドは、タグタイプを使用して %ALGORITHM%::method 名前空間で宣言されます。アルゴリ
ズムは、少なくとも 1 つのメソッドをサポートし、次に示すようにメソッドの 1 つを参照する by_default 型のエイリアスを宣言する必要があります。
namespace oneapi::dal::%ALGORITHM% {namespace method {struct x {};struct y {};using by_default = x;
} // namespace method} // namespace oneapi::dal::%ALGORITHM%

計算タスク
サポートされる計算タスクは、タグタイプを使用して %ALGORITHM%::task 名前空間で宣言されます。アルゴリズムは、
少なくとも 1 つのタスクをサポートし、次に示すようにタスクの 1 つを参照する by_default 型のエイリアスを宣言する必要があります。
アルゴリズムが分類タスクと回帰タスクの両方を想定する場合、デフォルトタスクは分類になります。アルゴリズムで訓練と推論ステージが明確に定義されていない場合、アルゴリズムは単一のタスクのみを定義することがあります。
namespace oneapi::dal::%ALGORITHM% {namespace task {struct classification {};struct regression {};using by_default = classification;} // namespace task
} // namespace oneapi::dal::%ALGORITHM%

8.4.3 操作 (Operation)
操作は、入力オブジェクトによって示される記述子と引数を結果オブジェクトに変換する関数です。操作記述子は以下を行います。
• 記述子で示されるアルゴリズムのすべての計算ルーチンを実行します。
• SYCL* キューを計算ルーチンに渡します。

8.4 プログラミング・モデル

267

oneAPI 仕様 リリース 1.0 リビジョン 3• 計算ルーチンの実行前の前提条件と実行後の事後条件を検証します。
一般操作の定義
次のサンプルコードは抽象化操作の宣言方法を示しています。特定の操作を宣言するには、%OPERATION% を操作名に置き換えます。
namespace oneapi::dal {template <typename Descriptor>
using %OPERATION%_input_t = /* 実装定義 */;template <typename Descriptor>
using %OPERATION%_result_t = /* 実装定義 */;template <typename Descriptor>%OPERATION%_result_t<Descriptor> %OPERATION%(
sycl::queue& queue,
const Descriptor& desc,
const %OPERATION%_input_t<Descriptor>& input);} // namespace oneapi::dal

それぞれの操作は次の要件を満たす必要があります。
• 操作は次の順序で 3 つのパラメーターを受け入れなければなりません。
– SYCL* キュー・オブジェクト– アルゴリズムの記述子– 入力オブジェクト• 操作は結果オブジェクトを返します。
• %OPERATION%_input_t と %OPERATION%_result_t エイリアス・テンプレートは、入力と戻り値の型推測に使用されます。
• 前提条件に違反した場合、操作は oneapi::dal::logic_error から派生する例外をスローします。
• 事後条件に違反した場合、操作は oneapi::dal::runtime_error から派生する例外をスローします。
• 記述子が一部の操作と互換性がない場合、コンパイル時にエラーがレポートされます。
• 互換性のある操作と事前/事後条件のリストは、特定のアルゴリズムの仕様によって定義されます。
操作の短縮形
ユーザーコードの冗長性を軽減するため、oneDAL では一般的な操作の定義で説明されている関数に加え、各操作の短縮形 (ショートカットとも呼ばれます) のオーバーロード関数が定義されています。
• ホストで実行される短縮形は、ホストの一般的な関数と同じ操作を実行しますが、キューを明示的に渡す必要がありません。

8.4 プログラミング・モデル

268

oneAPI 仕様 リリース 1.0 リビジョン 3
template <typename Descriptor>%OPERATION%_result_t<Descriptor> %OPERATION%(
const Descriptor& desc,
const %OPERATION%_input_t<Descriptor>& input);• 明示的な入力を省略できる短縮形。
template <typename Descriptor, typename... Args>%OPERATION%_result_t<Descriptor> %OPERATION%(
sycl::queue& queue,
const Descriptor& desc,
Args&&... args);• 明示的なキューと入力を省略できる短縮形。次は、前述の 2 つの省略形を組み合わせています。
template <typename Descriptor, typename...Args>%OPERATION%_result_t<Descriptor> %OPERATION%(
const Descriptor& desc,
Args&&... args);

入力データ
入力オブジェクトは、アルゴリズムが特定の操作を実行するために必要なすべてのデータを集約します。データはテーブ
ルを介して表現されるため、通常、入力はテーブルのコレクションですが、テーブルに縛られることなく任意のタイプのオ
ブジェクトを集約できます。
一般的に、入力クラスの定義は記述子に類似しています。入力は、対応するゲッターとセッターメソッドを使用してアクセス可能なプロパティーを定義します。入力プロパティーの要件は、記述子プロパティーの要件と同じです。
次のサンプルコードは、入力の定義で一般的な構造を示します。特定のアルゴリズムと操作の入力を定義するには、次の文字列を置き換えます。
• %ALGORITHM% は、アルゴリズムの名称と名前空間です。
• %OPERATION% は操作の名称です。
• %PROPERTY_NAME% と %PROPERTY_TYPE% は、入力プロパティーの名前とタイプです。

8.4 プログラミング・モデル

269

oneAPI 仕様 リリース 1.0 リビジョン 3
namespace oneapi::dal::%ALGORITHM% {template <typename Task = task::by_default>
class OPERATION_input {public:/* コンストラクター */%OPERATION%_input(const %PROPERTY_TYPE%& %PROPERTY_NAME%,/* 追加のプロパティー */)/* `%PROPERTY_NAME%` プロパティーのゲッターとセッター */descriptor& set_%PROPERTY_NAME%(%PROPERTY_TYPE% value);%PROPERTY_TYPE% get_%PROPERTY_NAME%() const;/* 追加のプロパティー */};} // namespace oneapi::dal::%ALGORITHM%

注: 入力はアルゴリズムと操作固有であるため、各 %ALGORITHM% と %OPERATION% のペアは、独自のプロパティー・
セットとして定義する必要があります。
結果
結果オブジェクトは、アルゴリズムが計算したすべての出力値を集約します。入力に対するすべての仮定は結果にも適用されます。
namespace oneapi::dal::%ALGORITHM% {template <typename Task = task::by_default>
class OPERATION_result {public:/* コンストラクター */%OPERATION%_result(const %PROPERTY_TYPE%& %PROPERTY_NAME%,/* 追加のプロパティー */)/* `%PROPERTY_NAME%` プロパティーのゲッターとセッター */descriptor& set_%PROPERTY_NAME%(%PROPERTY_TYPE% value);%PROPERTY_TYPE% get_%PROPERTY_NAME%() const;/* 追加のプロパティー */};} // namespace oneapi::dal::%ALGORITHM%

サポートされる操作
特定の操作の詳細ついては、「サポートされる操作」をご覧ください。
サポートされる操作
この節では oneDAL でサポートされる操作について説明します。一般的な操作の定義の詳細は、「操作」をご覧ください。
8.4 プログラミング・モデル

270

oneAPI 仕様 リリース 1.0 リビジョン 3

次の表は、アルゴリズムの記述子とそれぞれの操作が同時に使用できるかどうかを示します。
アルゴリズム

操作
訓練

推論

計算

K 平均法

はい

はい

いいえ

K 平均法の初期化

いいえ

いいえ

はい

k-NN

はい

はい

いいえ

PCA

はい

はい

いいえ

訓練
訓練操作は、マシンラーニング・アルゴリズムの訓練手順を実行します。訓練後に得られる結果には、推論操作に渡すことが可能なモデルが含まれます。
namespace oneapi::dal {template <typename Descriptor>
using train_input_t = /* 実装定義 */;template <typename Descriptor>
using train_result_t = /* 実装定義 */;template <typename Descriptor>
train_result_t<Descriptor> train(sycl::queue& queue,
const Descriptor& desc,
const train_input_t<Descriptor>& input);} // namespace oneapi::dal

推論
推論操作は、訓練の結果として得られたモデルに基づいて、マシンラーニング・アルゴリズムの推論手順を実行します。

8.4 プログラミング・モデル

271

oneAPI 仕様 リリース 1.0 リビジョン 3
namespace oneapi::dal {template <typename Descriptor>
using infer_input_t = /* 実装定義 */;template <typename Descriptor>
using infer_result_t = /* 実装定義 */;template <typename Descriptor>
infer_result_t<Descriptor> infer(sycl::queue& queue,
const Descriptor& desc,
const infer_input_t<Descriptor>& input);} // namespace oneapi::dal

計算
アルゴリズムで明確に訓練ステージと推論ステージが定義されていない場合、計算操作が実行されます。
namespace oneapi::dal {template <typename Descriptor>
using compute_input_t = /* 実装定義 */;template <typename Descriptor>
using compute_result_t = /* 実装定義 */;template <typename Descriptor>
compute_result_t<Descriptor> compute(sycl::queue& queue,
const Descriptor& desc,
const compute_input_t<Descriptor>& input);} // namespace oneapi::dal

8.4.4 計算モード
バッチ
バッチ処理モードでは、アルゴリズムはデータセット全体を処理して最終結果を生成します。その時点でデータセット全体が利用可能でないか、データセットがデバイスメモリーに収まらない場合、シナリオはより複雑になります。
オンライン
オンライン処理モードでは、アルゴリズムはデバイスのメモリーにストリームされたブロックでデータセットを処理します。部分的な結果は段階的に更新され、最後のデータブロックが処理されると確定されます。

8.4 プログラミング・モデル

272

oneAPI 仕様 リリース 1.0 リビジョン 3
分散
分散処理モードでは、アルゴリズムは複数のデバイス (計算ノード) に分散されたデータセットを処理します。各ノードでアルゴリズムは部分的な結果を生成し、最後にメインノードの結果にマージされます。

8.5

共通インターフェイス

8.5.1 現在のバージョンの oneDAL 仕様
これは、oneAPI 仕様バージョン 1.0 の一部である oneDAL の仕様です。

8.5.2 ヘッダーファイル
oneDAL パブリック識別子は、次のヘッダーファイルに含まれます。
ヘッダーファイル
oneapi/dal.hpp

説明

oneapi/dal/%FILE%.hpp

他の oneDAL レイヤーで使用される一般的なタイプ定義。
例: data_type や range。

oneapi/dal/algo/%ALGO%.hpp

特定のアルゴリズムのヘッダーファイル。アルゴリズム自体のフォルダーは、
oneapi/dal/algo/%ALGO%/ です。
文字列 %ALGO% は、アルゴリズムの名称に置き換える必要があります (例:kmeans または knn)。

oneapi/dal/algo/
misc/%FUNC%.hpp

oneDAL アルゴリズムおよび分析パイプラインのアプリケーションで利用することを目的とした、その他のデータ型と関数のヘッダーファイル。
文字列 %FUNC% は、機能名に置き換える必要があります (例: mt19937 やcross_enthropy_loss)。

oneapi/dal/table/%FILE%.hpp

テーブルの概念に関連するタイプのヘッダーファイル。
文字列 %FILE% は、機能名に置き換える必要があります。例えば、テーブルタ
イプに関連する主な概念です (例: table、table_metadata、data_layoutクラス)。名前に _table サフィックスが含まれるエンティティーでは、関連する
ヘッダーファイル名にこのサフィックスが含まれている必要があります (例:homogen_table クラスの homogen)。

oneapi/dal/io/%FILE%.hpp

入出力機能のタイプとエンティティーのヘッダーファイル。
文字列 %FILE% は、機能名に置き換える必要があります (例: csv ファイルの読み書きには csv を使用します)。

oneapi/dal/util/%UTIL%.hpp

クラスの設計や各種メソッドの実装に使用するメモリー・アロケーターやタイ
プ特性など、補助機能向けのヘッダーファイル。
文字列 %UTIL% は、補助機能の名称に置き換える必要があります (例:usm_allocatoror type_traits など)。

8.5 共通インターフェイス

oneDAL ライブラリーのメイン・ヘッダー・ファイル。

273

oneAPI 仕様 リリース 1.0 リビジョン 3

8.5.3 名前空間
oneDAL の機能は、以下で説明する C++ 名前空間で表されます。
名前空間
oneapi::daloneDAL の概念

oneapi::dal::%ALGORITHM%

アルゴリズムの名前空間。アルゴリズムに関連するすべてのクラスと構造は、この名前空間で定義します。
アルゴリズムにの名前空間を定義するには、文字列 %ALGORITHM% をアルゴリズム名に置き換えます (例: oneapi::dal::kmeans や oneapi::dal::knn)。

oneapi::dal::%DATA_SOURCE%

データソースの名前空間。データソースに関連するすべてのクラスと構造は、この名前空間で定義される必要があります。
データソースを定義するには、文字列 %DATA_SOURCE% をデータソース名に置き換え
ます (例: oneapi::dal::csv)。

oneapi::dal::misc

分析パイプラインの各種ステージでアルゴリズムをカスタマイズして最適化するため、
oneDAL アルゴリズムとアプリケーションで利用することを目的としたその他のデータ型と機能を含む名前空間。

%PARENT%::detail

親の名前空間データ型と機能実装の詳細を含む名前空間。名前空間は、名前空間の階層の任意のレベルであることができます。
名前空間を定義するには、文字列 %PARENT% を詳細が提供される親の名前空間に置き換えます (例: oneapi::dal::detail や oneapi::dal::kmeans::detail)。
アプリケーションは、詳細名前空間にあるデータ型を使用したり、機能を呼び出してはなりません。

oneDAL の外部から見えるデータ型、データ管理エンティティー、処理、およびサービス
機能を含むライブラリーの名前空間。

8.5.4 エラー処理
oneDAL のエラー処理は、C++ の例外メカニズムに関連しています。エラーが発生すると、標準の C++ エラー処理メカ
ニズムを使用してキャッチされた関数呼び出しに伝搬されます。
例外の分類
oneDAL の例外分類は、C++ 標準ライブラリーの分類と一致しています。oneDAL は例外クラスの階層に基本クラスを定義する抽象化クラスを導入する必要があります。非抽象化クラスは、それぞれの C+C 標準ライブラリー例外クラスから派生します。oneDAL は、非抽象化クラスで表現される例外をスローします。
oneDAL 例外階層では、oneapi::dal::exception はすべての例外クラスの派生元である基本抽象化クラスです。
class oneapi::dal::exception;

すべての oneDAL 例外は 3 つのグループに分けられます。
• 論理エラー• ランタイムエラー• アプリケーションのエラー
8.5 共通インターフェイス

274

oneAPI 仕様 リリース 1.0 リビジョン 3

class oneapi::dal::logic_error : public oneapi::dal::exception;
class oneapi::dal::runtime_error : public oneapi::dal::exception;
class oneapi::dal::bad_alloc : public oneapi::dal::exception, public std::bad_alloc;
例外

説明

抽象化

oneapi::dal::logic_error

前提条件と不変条件違反をレポートします。

はいoneapi::dal::runtime_error

oneDAL 機能の実行中に発生した事後条件違反やその他のエラーをレ はい
ポートします。

oneapi::dal::bad_alloc

ストレージ割り当ての失敗をレポートします。

はいoneapi::dal::logic_error で表現されるすべての前提条件と不変エラーは、次のグループに分類されます。
• 無効な引数エラー• ドメインエラー• 範囲外エラー• 実装されていないメソッドやアルゴリズムのエラー• サポートされないデバイス
class oneapi::dal::invalid_argument
public std::invalid_argument;
class oneapi::dal::domain_error
public std::domain_error;class oneapi::dal::out_of_range
public std::out_of_range;class oneapi::dal::unimplemented
public std::logic_error;class oneapi::dal::unsupported_device
public std::logic_error;: public oneapi::dal::logic_error,: public oneapi::dal::logic_error,: public oneapi::dal::logic_error,: public oneapi::dal::logic_error,: public oneapi::dal::logic_error,

例外
oneapi::dal::invalid_arguement

説明

抽象化

引数が受け入れられなかった状況をサポートします。

いいえoneapi::dal::domain_error

引数が操作が定義されるドメイン外にある状況をサポートします。

いいえoneapi::dal::out_of_range

oneapi::dal::invalid_argument よりも優先順位が高くなり いいえます。

oneapi::dal::unimplemented

インデックスが範囲外にある状況をレポートします。
いいえoneapi::dal::invalid_argument よりも優先順位が高くなります。

oneapi::dal::unsupported_device

アルゴリズムまたはメソッドが実装されていないため発生したエラーを いいえ
レポートします。

oneDAL 機能の実行中に発生するエラーは、oneapi::dal::runtime_error に示されます。
2 つのエラーグループを区別する必要があります。
• デスティネーション・タイプの範囲エラー• OS 機能との相互作用エラー

8.5 共通インターフェイス

275

oneAPI 仕様 リリース 1.0 リビジョン 3

他のすべてのエラーは、oneapi::dal::internal_error でレポートされます。
class oneapi::dal::range_error: public oneapi::dal::runtime_error,
public std::range_error;class oneapi::dal::system_error: public oneapi::dal::runtime_error,
public std::system_error;class oneapi::dal::internal_error : public oneapi::dal::runtime_error,
public std::runtime_error;
例外
oneapi::dal::range_error

説明

抽象化

oneapi::dal::system_error

OS 機能を使用中に発生したエラーをレポートします。

いいえoneapi::dal::internal_error

継承できなかったすべてのラインタイム・エラーをレポートします。

いいえ

計算結果をデスティネーションのタイプで表現できない状況をレポート いいえ
します。

すべてのメモリーの割り当てエラーは oneapi::dal::bad_alloc で報告されます。メモリーエラーは発生した場所
により 2 つのグループに分けられます。
• ホストメモリー割り当てエラー• デバイスメモリー割り当てエラー
class oneapi::dal::host_bad_alloc : public oneapi::dal::bad_alloc;
class oneapi::dal::device_bad_alloc : public oneapi::dal::bad_alloc;

例外
oneapi::dal::host_bad_alloc

説明

抽象化

ホストのストレージが割り当てられなかったことをレポートします。

いいえoneapi::dal::device_bad_alloc

デバイスのストレージが割り当てられなかったことをレポーします。

いいえ

8.5.5 共通型定義
ここでは、oneDAL で使用される一般的な型について説明します。
プログラミング・インターフェイス
この節のすべての型と関数は、oneapi::dal 名前空間で宣言され、oneapi/dal/common.hpp ヘッダーファイルをインクルードして使用できます。
スカラー型
oneDAL は <cstdint> で定義される整数型を使用します。このファイルは oneapi/dal/ common.hpp でインクルードされ、すべての oneDAL 型はこれらのデータ型を使用します。
ライブラリーのインターフェイスは、std::int64_tdata 型を使用して、次元 (例えば、テーブルの行と列) を表現します。
アプリケーションでも標準の C++ データ型を使用することを推奨します。

8.5 共通インターフェイス

276

oneAPI 仕様 リリース 1.0 リビジョン 3
enum class
oneDAL の概念を表す列挙型や列挙型クラスを定義する際に使用する基本型は、仕様で定義される特定の基本型を除いて実装依存です。
データ型
データ型の概念の基本。計算を実行するため、oneDAL でサポートされるすべてのデータ型を列挙する必要があります。
data_type クラスには、すべての基本スカラー型が含まれ、それらを拡張することもできます。基本スカラー型には、名前のパターンが std::int_XX_t または std::uint_XX_t である必要があります。ここで、XX は 8、16、32 または64 です。
enum class data_type {
int8,
int16,
int32,
int64,
uint8,
uint16,
uint32,
uint64,float32,
float64,
bfloat16};

enum class data_type
data_type::int8: 8 ビットの符号付き整数値型。
data_type::int16: 16 ビットの符号付き整数値型。
data_type::int32: 32 ビットの符号付き整数値型。
data_type::int64: 64 ビットの符号付き整数値型。
data_type::uint8: 8 ビットの符号なし整数値型。
data_type::uint16: 16 ビットの符号なし整数値型。
data_type::uint32: 32 ビットの符号なし整数値型。
data_type::uint64: 64 ビットの符号なし整数値型。
data_type::float32: 32 ビットの浮動小数点値型。
data_type::float64: 64 ビットの浮動小数点値型。
data_type::bfloat16: 半精度浮動小数点値型。
Range
配列または値のインデックスをサポートするコンテナの範囲 [start_index, end_index)。

8.5 共通インターフェイス

277

oneAPI 仕様 リリース 1.0 リビジョン 3
struct range {public:range(std::int64_t start, std::int64_t end);
std::int64_t get_element_count(std::int64_t max_end_index) const noexcept;
std::int64_t start_idx;
std::int64_t end_idx;};

struct range
コンストラクター
range(std::int64_t start, std::int64_t end)
指定された開始インデックスと終了インデックスから要素の範囲を構築します。
パラメーター• start – 範囲の最初のインデックス。値は 0 以上である必要があります。
• end – 範囲内の相対的な終了インデックス。範囲内の最後のインデックスの次のインデックスを示します。正の場合、start より大きくなければなりません。負の場合、範囲の終わりから最後の要素のオフセットを示します。例えば、start = 1 で end = -2 である場合、セット [0, 1, 2, 3, 4] 内の要
素 [1, 2, 3] の範囲を指定します。
プロパティー
std::int64_t element_count範囲内の要素数。max_end_index 値には、シーケンスの最後の最大インデックスを指定します。
ゲッターとセッター
std::int64_t
noexcept

8.6

get_element_count(std::int64_t

max_end_index)

const

データ管理

ここには、データを操作する概念とオブジェクトが含まれます。oneDAL では、このような一連の操作、またはデータ管理
は、データ分析パイプラインの各ステージに分散されます。データ管理の観点から、このパイプラインには、データの取得、準備、計算の 3 つのステップが含まれます (以下の図を参照)。
1.

生データの取得• 各種ソース (データベース、ファイル、リモートストレージ) からメモリー外部にあるデータをメモリー内に転送します。

2.

データの準備• 異なるメモリー内のデータ形式をサポートします。
• データの圧縮と展開。
• データを数値表現に変換。
• 欠落しているデータを回復。
• データをフィルター処理して正規化を行います。

8.6 データ管理278

oneAPI 仕様 リリース 1.0 リビジョン 3• 平均、分散、共分散など、数値データのさまざまな統計メトリックを計算します。
3.

アルゴリズムの計算• メモリー内の数値データをアルゴリズムにストリームします。

複雑なシナリオでは、データフローはこの 2 つのステージを行き来します。例えば、計算を開始する時にデータ全体がまだ利用不可である場合、データをブロック化して利用できます。あるブロックの計算が完了したら、次のブロックを取得して準備する必要があります。

8.6.1 主要な概念
oneDAL では、データ分析パイプラインのそれぞれのステージで、メモリー外部またはメモリー内のデータを操作する一連の概念を提供します。
データセットoneDAL が動作する主なデータに関連する概念はデータセットです。これはデータの表形式表示であり、表の行は観測値を示し、列は特徴を示します。

8.6 データ管理279

oneAPI 仕様 リリース 1.0 リビジョン 3

データセットは、データ分析パイプラインのすべてのステージで使用されます。以下に例を示します。
1.
2.
3.

取得ステージでは、ローカルメモリーにダウンロードされます。
準備ステージでは、数値表現に変換されます。
計算ステージでは、アルゴリズムや記述子プロパティーの入力、または結果の 1 つとして使用されます。

データソース
データソースは、データセットのメモリー外部ストレージの概念です。これは、データ収集とデータ準備ステージにおいて次の用途に使用されます。
• データベース、ファイル、リモートストレージなど外部ソースからデータセットを抽出します。
• データセットをデバイスのローカルメモリーにロードします。アクセラレーターで処理を行う場合、データが常にローカルメモリーに収まるとは限りません。データソースは、データをバッチでロードして、デバイスのローカルメモリーに直接展開する機能があります。そのため、データソースを使用することで、オンライン計
算など複雑なデータ分析シナリオが可能になります。
• データセットを数値表現に変換します。データソースは、非数値のカテゴリーと連続データを数値データ形
式に自動変換します。
詳細は、「データソース」をご覧ください。

8.6 データ管理

280

oneAPI 仕様 リリース 1.0 リビジョン 3
テーブル
テーブルは、複数の行と列を持つ表形式表示に編成されたメモリー内の数値データ概念です。これは、データ準備とデータ処理ステージにおいて次の用途に使用されます。
• データセットまたは他の表形式データ (行列、ベクトル、スカラーなど) のメモリー内表現。
• 異種データを、密、疎、チャンク、連続など各種データ形式で保存します。
• 外部データ表現からの変換で、不要なデータのコピーを回避します。
• データのメモリー所有権をユーザー・アプリケーションからテーブルに転送するか、データを共有します。
• データソースに接続して、データをメモリー外部からメモリー内表現に変換します。
• アルゴリズムへのデータのストリーミングをサポートします。
• 要求されるデータ形式でデバイス上のデータにアクセスします。例えば、定義されたデータレイアウトのブ
ロックなど。
注: スレッドセーフと外部エンティティーとの統合性の観点から、テーブルはデータへの読み取り専用アクセスを許可します。そのため、テーブル・オブジェクトは不変でなければなりません。
この概念では、データの論理構成と物理形式が異なります。
• 論理的にテーブルは n 行と p 列で構成されます。すべての列には、独自の型のデータ値と許容される操作セットがあります。
• 物理的には、テーブルはさまざまな形式で編成できます。バイト単位の同種の、連続した配列、または異なる
データ型配列の異種リストとして、圧縮された疎行形式を編成できます。データを格納するために必要なバ
イト数は、テーブル内の要素数 n × p とは異なります。
詳細は、「テーブル」をご覧ください。
テーブルのメタデータ
テーブルのメタデータの概念は、テーブル内のデータに関する追加情報を提供します。
1.
2.

列のデータ型。
列データの論理型には、名目 (nominal)、順序 (ordinal)、区間 (interval)、または比率 (ratio) があります。

テーブルの概念の定義に影響しないデータのプロパティーのみが、メタデータの概念の一部になります。
警告: テーブルの概念を拡張する場合、仕様の実装者は追加する新しいプロパティーが特定のテーブルのサブタイプのプロパティーであるか、テーブルのメタデータのプロパティーであるかを区別する必要があります。
例えば、データレイアウトとデータ形式は、テーブルの構造、定義、および動作に影響するテーブル・オブジェクトのプ
ロパティーです。テーブル内の特徴または列の名前リストは、メタデータ・プロパティーの一例です。

8.6 データ管理281

oneAPI 仕様 リリース 1.0 リビジョン 3
アクセサー
アクセサーは、テーブルからデータを抽出する 1 つの方法を定義する概念です。これにより次のことが可能になります。
• 実装の詳細を明確にすることなく、さまざまな型のテーブル・オブジェクトのデータに一元的にアクセスできます。
• データの局所性を高めるため、テーブルのデータブロックのフラットなビューを提供します。例えば、アクセ
サーは行優先で格納されたテーブルの列を、連続した配列として返すことができます。
• 特定の操作セットが定義されるデータを必要とするデータ形式で取得できます。
• データへの読み取り専用アクセスを許可します。詳細は、アクセサーの節をご覧ください。
テーブルとアクセサー・オブジェクト間の相互作用の例
ここでは、テーブルとアクセサーの概念における基本的なシナリオを示し、それらの関連を示します。次の図は、この概念のオブジェクトを示し、それぞれの色で強調表示しています。
• テーブル・オブジェクトは紺色です。
• アクセサーはオレンジ色です。
• テーブルのメタデータは水色です。

データセットを使用して計算を実行するには、最初にテーブル・オブジェクトを作成する必要があります。これは、データソースを使用するか、ユーザー定義のメモリーから直接実行できます。この図では、ユーザーから提供されたデータ (図には示されていません) からテーブル・オブジェクト t を作成する例を示しています。テーブルの作成過程で、テーブルのメタデータ・オブジェクト tm が構築されて初期化されます。

8.6 データ管理282

oneAPI 仕様 リリース 1.0 リビジョン 3

テーブル・オブジェクトが作成されると、計算の入力として、もしくはアルゴリズムのパラメーターとして使用できます。
テーブルのデータには、図に示すように、独自のインターフェイスや読み取り専用アクセサーを介してアクセスできます。

8.6.2 詳細
ここには、oneDAL のすべてのデータ管理オブジェクトの説明が含まれています。
配列
配列は oneDAL のデータにおける単純な概念です。次のようなストレージを表します。
1.
2.
3.
4.
5.
6.

内部に割り当てられたデータ、または外部データへの参照を保持します。データは、1 つの同種の、連続したメモリーブロックとして構成されます。
メモリーブロックのサイズ情報が含まれます。
不変データと可変データの両方がサポートされます。
データの状態を不変から可変に変更する機能を提供します。
データの所有権情報を保持します (「データ所有権の要件」を参照)。
データの所有権情報は複数の配列で共有できます。データをコピーすることなく、別の配列から新しい配列を作成できます。

使用例
次のリストは、配列 API の簡単な例と、基本的な使用シナリオを示します。
#include <CL/sycl.hpp>#include <iostream>#include <string>#include "oneapi/dal/array.hpp"
using namespace oneapi;
void print_property(const std::string& description, const auto& property) {std::cout << description << ": " << property << std::endl;}
int main() {sycl::queue queue { sycl::default_selector() };constexpr std::int64_t data_count = 4;
const float data[] = { 1.0f, 2.0f, 3.0f, 4.0f };// ユーザー定義の不変メモリーから配列を作成
auto arr_data = dal::array<float>::wrap(data, data_count);// 内部に割り当てられたメモリーから配列を作成
auto arr_ones = dal::array<float>::full(queue, data_count, 1.0f);
print_property("Is arr_data mutable", arr_data.has_mutable_data()); // false
print_property("Is arr_ones mutable", arr_ones.has_mutable_data()); // true

(次のページへ続く)

8.6 データ管理283

oneAPI 仕様 リリース 1.0 リビジョン 3(前のページの続き)// データをコピーせずに arr_data から新しい配列を作成 (所有権情報を共有)
dal::array<float> arr_mdata = arr_data;
print_property("arr_mdata elements count", arr_mdata.get_count()); // data_count に等しい
print_property("Is arr_mdata mutable", arr_mdata.has_mutable_data()); // false// arr_mdata 内のデータを新しい可変メモリーブロックにコピー// arr_data は、元のデータポインターを参照します
arr_mdata.need_mutable_data(queue);print_property("Is arr_data mutable", arr_data.has_mutable_data()); // false
print_property("Is arr_mdata mutable", arr_mdata.has_mutable_data()); // true
queue.submit([&](sycl::handler& cgh){auto mdata = arr_mdata.get_mutable_data();
auto cones = arr_ones.get_data();cgh.parallel_for<class array_addition>(sycl::range<1>(data_count), [=](sycl::id<1>idx) {
mdata[idx[0]] += cones[idx[0]];});}).wait();
std::cout << "arr_mdata values: ";for(std::int64_t i = 0; i < arr_mdata.get_count(); i++) {std::cout << arr_mdata[i] << ", ";}std::cout << std::endl;
return 0;}

データ所有権の要件
配列は、内部データ管理に関する次の要件をサポートする必要があります。
1.

配列は、データへの生ポインターを持つ 2 つのプロパティーを所有する必要があります。
• 不変データブロックへのポインターデータ• 可変データブロックへのポインター mutable_data (「プログラミング・インターフェイス」を参照)

2.
3.
4.
5.

配列が可変データを所有する場合、両方のプロパティーが同じメモリーブロックを指している必要があります。
配列が不変データを所有する場合、mutable_data は nullptr でなければなりません。
配列は所有するブロック内の要素数を格納し、新しいメモリーブロックが配列に割り当てられると countプロパティーを更新する必要があります。
配列には、データの所有権構造体へのポインターが格納されています:• 参照カウントは、同じメモリーブロックを参照する配列オブジェクトの数を示します。
• deleter オブジェクトは、参照カウントがゼロの時にメモリーブロックを解放するために使用されます。

6.

配列は、所有権構造体に関連付けられていない新しいメモリーブロックの所有権構造体を作成する必要があります。

8.6 データ管理284

oneAPI 仕様 リリース 1.0 リビジョン 37.
8.

配列が実行スコープから外れると、メモリーブロックへの参照数をデクリメントする必要があります。参照
カウントがゼロになると、配列は deleter を呼び出して、メモリーブロックの所有権情報を解放します。
配列は、データを共有する際に別の配列によって作成された所有権構造体へのポインターを保持する必要があります。配列は、同じデータを共有する配列オブジェクトの数と等しくなるように、参照カウントをインクリメントする必要があります。

プログラミング・インターフェイス
この節のすべての型と関数は、oneapi::dal 名前空間で宣言され、oneapi/dal/array.hpp ヘッダーファイルをインクルードして使用できます。
すべての配列クラスメソッドは、いくつかのグループに分類できます。
1.
2.
3.
4.
5.
6.

外部、可変、不変メモリーから配列を作成する際に使用されるコンストラクター。
データを別の配列と共有する配列を作成する際に使用されるコンストラクターと代入演算子。
配列を別の外部メモリーブロックに再割り当てする際に使用される reset() メソッドのグループ。
内部的に割り当てられたメモリーブロックを再割り当てする際に使用される reset() メソッドのグ
ループ。
データへのアクセスに使用されるメソッド。
外部メモリー、または新しいオブジェクト内に配列を割り当てることで、配列を作成する簡略された方法を提供する静的メソッド。

template <typename Data>
class array {public:using data_t = Data;public:static array<Data> empty(const sycl::queue& queue,
std::int64_t count,
const sycl::usm::alloc& alloc =sycl::usm::alloc::shared);
template <typename Element>
static array<Data> full(sycl::queue& queue,
std::int64_t count,
Element&& element,
const sycl::usm::alloc& alloc = sycl::usm::alloc::shared);static array<Data> zeros(sycl::queue& queue,
std::int64_t count,
const sycl::usm::alloc& alloc =sycl::usm::alloc::shared);static array<Data> wrap(const Data* data,
std::int64_t count,
const sycl::vector_class<sycl::event>& dependencies = {});

(次のページへ続く)

8.6 データ管理285

oneAPI 仕様 リリース 1.0 リビジョン 3(前のページの続き)
public:array();
array(const array<Data>& other);array(array<Data>&& other);template <typename Deleter>
explicit array(const sycl::queue& queue,
Data* data,
std::int64_t count,
Deleter&& deleter,
const sycl::vector_class<sycl::event>& dependencies = {});
template <typename ConstDeleter>
explicit array(const sycl::queue& queue,
const Data* data,
std::int64_t count,
ConstDeleter&& deleter,
const sycl::vector_class<sycl::event>& dependencies = {});
template <typename RefData, typename ExtData>
explicit array(const array<RefData>& ref, ExtData* data, std::int64_t count);array<Data> operator=(const array<Data>& other);array<Data> operator=(array<Data>&& other);
Data* get_mutable_data() const;
const Data* get_data() const noexcept;
bool has_mutable_data() const noexcept;
array& need_mutable_data(sycl::queue& queue,
const sycl::usm::alloc& alloc = sycl::usm::alloc::shared);
std::int64_t get_count() const noexcept;
std::int64_t get_size() const noexcept;
void reset();void reset(const sycl::queue& queue,
std::int64_t count,
const sycl::usm::alloc& alloc = sycl::usm::alloc::shared);
template <typename Deleter>void reset(Data* data,
std::int64_t count,
Deleter&& deleter,
const sycl::vector_class<sycl::event>& dependencies = {});

(次のページへ続く)

8.6 データ管理286

oneAPI 仕様 リリース 1.0 リビジョン 3(前のページの続き)
template <typename ConstDeleter>void reset(const Data* data,
std::int64_t count,
ConstDeleter&& deleter,
const sycl::vector_class<sycl::event>& dependencies = {});
template <typename RefData>
void reset(const array<RefData>& ref, Data* data, std::int64_t count);
template <typename RefData>
void reset(const array<RefData>& ref, const Data* data, std::int64_t count);
const Data& operator[](std::int64_t index) const noexcept;};

template<typename Data>
class array
テンプレート・パラメーター
Data – 配列内のメモリーブロック要素のタイプ。Data は任意の型を表現できます。
パブリック静的メソッド
static array<Data> empty(const sycl::queue &queue, std::int64_t count, const
sycl::usm::alloc &alloc = sycl::usm::alloc::shared)
可変データ向けに新しいメモリーブロックを割り当てて、初期化なしでメモリーブロックへのポインターを渡す
ことで新しい配列インスタンスを作成します。配列はメモリーブロックを所有する必要があります (詳細は、「データ所有権の要件」を参照)。
パラメーター• queue – SYCL* キュー・オブジェクト。
• count – メモリーを割り当てる Data 型の要素数。
• alloc – 割り当てられる USM の種別。
前提条件
count > 0
template<typename Element>
staticarray<Data>full(sycl::queue&queue,std::int64_t
count,
Element&&element, const sycl::usm::alloc &alloc = sycl::usm::alloc::shared)
可変データ向けに新しいメモリーブロックを割り当てて、スカラー値で初期化し、メモリーブロックへのポイン
ターを渡すことで新しい配列インスタンスを作成します。配列はメモリーブロックを所有する必要があります(詳細は、「データ所有権の要件」を参照)。
テンプレート・パラメーター
Element – Data 型の配列要素をコンストラクトできる型。
パラメーター• queue – SYCL* キュー・オブジェクト。
• count – メモリーを割り当てる Data 型の要素数。
8.6 データ管理287

oneAPI 仕様 リリース 1.0 リビジョン 3• element – メモリーブロックを埋めるために使用する値。
• alloc – 割り当てられる USM の種別。
前提条件
count > 0
Data 型の要素は、Element 型から構成できます。
staticarray<Data>
zeros(sycl::queue&queue,std::int64_t
count,
const
sycl::usm::alloc &alloc = sycl::usm::alloc::shared)
可変データ向けに新しいメモリーブロックを割り当てて、ゼロで初期化し、メモリーブロックへのポインターを渡すことで新しい配列インスタンスを作成します。配列はメモリーブロックを所有する必要があります (詳細は、「データ所有権の要件」を参照)。
パラメーター• queue – SYCL* キュー・オブジェクト。
• count – メモリーを割り当てる Data 型の要素数。
• alloc – 割り当てられる USM の種別。
前提条件
count > 0
staticarray<Data>wrap(Data*data,
std::int64_t
count,
const
sycl::vector_class<sycl::event> &dependencies = {})可変データ向けに外部に割り当てられたメモリーブロックへのポインターを渡すことで、新しい配列インスタンスを作成します。参照カウントがゼロである場合、配列はメモリーブロックを解放しないため、メモリーブ
ロックを解放するのはアプリケーションの責任となります。
パラメーター• data – 外部に割り当てられたメモリーブロックへのポインター。
• count – メモリーブロック内の Data 型の要素数。
• dependencies – 読み取りまたは書き込み用の data の可用性を示すイベント。
前提条件
data != nullptr
count > 0
staticarray<Data>wrap(const
Data*data,
std::int64_t
count,
const
sycl::vector_class<sycl::event> &dependencies = {})不変データ向けに外部に割り当てられたメモリーブロックへのポインターを渡すことで、新しい配列インスタンスを作成します。参照カウントがゼロである場合、配列はメモリーブロックを解放しないため、メモリーブ
ロックを解放するのはアプリケーションの責任となります。
パラメーター• data – 外部に割り当てられたメモリーブロックへのポインター。
• count – メモリーブロック内の Data 型の要素数。
• dependencies – 読み取りまたは書き込み用の data の可用性を示すイベント。

8.6 データ管理288

oneAPI 仕様 リリース 1.0 リビジョン 3
前提条件
data != nullptr
count > 0
コンストラクター
array()
メモリー割り当てなしでクラスの新しいインスタンスを作成します。mutable_data と data ポインターは
nullptr に設定され、count はゼロに設定されます。所有権構造体へのポインターは nullptr に設定されます。
array(const array<Data> &other)
メモリーブロックを other と所有権を共有する新しい配列インスタンスを作成します。
array(array<Data> &&other)data、mutable_data ポインター、count、および other の所有権構造体へのポインターを新しい配列インスタンスに移動します。
template<typename
Deleter>array(const sycl::queue &queue, Data *data, std::int64_t count, Deleter&&deleter, const sycl::vector_class<sycl::event> &dependencies = {})外部に割り当てられた可変データのメモリーブロックを所有する新しい配列インスタンスを作成します。ブロックの所有権構造体を作成して入力 deleter を割り当てます。
テンプレート・パラメーター
Deleter – data を 解 放 す る 際 に 使 用 さ れ る deleter の タ イ プ 。 deleter は void
operator()(Data*) メンバー関数を提供する必要があります。
パラメーター• queue – SYCL* キュー・オブジェクト。
• data – 外部に割り当てられたメモリーブロックへのポインター。
• count – メモリーブロック内の Data 型の要素数。
• deleter – data を解放する際に使用されるオブジェクト。
• dependencies – data の読み取りまたは書き込みの準備ができたことを示すイベント。
template<typename ConstDeleter>array(const
sycl::queue&queue,const
Data*data,
std::int64_t
count,
ConstDeleter &&deleter, const sycl::vector_class<sycl::event> &dependencies ={})外部に割り当てられた不変データのメモリーブロックを所有する新しい配列インスタンスを作成します。ブロックの所有権構造体を作成して入力 deleter を割り当てます。
テンプレート・パラメーター
ConstDeleter – data を 解 放 す る 際 に 使 用 さ れ る deleter の タ イ プ 。 deleter は void
operator()(const Data*) メンバー関数を実装する必要があります。
パラメーター• queue – SYCL* キュー・オブジェクト。
• data – 外部に割り当てられたメモリーブロックへのポインター。
• count – data 内の Data 型の要素数。

8.6 データ管理289

oneAPI 仕様 リリース 1.0 リビジョン 3• deleter – data を解放する際に使用されるオブジェクト。
• dependencies – 読み取りまたは書き込み用の data の可用性を示すイベント。
template<typename RefData, typename ExtData>
array(const array<RefData> &ref, ExtData *data, std::int64_t count)
エイリアス・コンストラクター。data ポインターを格納する新しい配列インスタンスを作成し、新しいインスタ
ンスの ref の所有権構造体へのポインターを割り当てます。配列は、ExtData タイプに応じて、可変ブロック
または不変ブロックの data ポインターを返します。
テンプレート・パラメーター• RefData – 参照される配列内の要素タイプ。
• ExtData – Data または constData タイプのいずれか。
パラメーター• ref – 所有権構造体を作成したものと共有する配列。
• data – 作成された配列によって保持される不変または可変のアンマネージド・ポインター。
• count – data 内の Data 型の要素数。
前提条件
std::is_same_v<ExtData, const Data> || std::is_same_v<ExtData, Data>
パブリック・メソッド
array<Data> operator=(const array<Data> &other)data、mutable_data ポインター、count、配列インスタンスの所有権構造体へのポインターを other の値に置き換えます。
事後条件
data == other.data
mutable_data == other.mutable_data count == other.countarray<Data> operator=(array<Data> &&other)data、mutable_data ポインター、count、配列インスタンスの所有権構造体へのポインターを other の値と入れ替えます。
bool has_mutable_data() const noexcept
配列に mutable_data が含まれているかどうかを返します。
array &need_mutable_data(sycl::queue &queue, const sycl::usm::alloc &alloc =sycl::usm::alloc::shared)
配列が mutable_data を含んでれば、そのデータを返します。それ以外の場合、可変データ向けのメモリーブ
ロックを割り当て、データに含まれるデータを格納します。割り当てられたメモリーブロックの所有権構造を作成してポインターを格納します。
パラメーター• queue – SYCL* キュー・オブジェクト。
• alloc – 割り当てられる USM の種別。
事後条件
has_mutable_data() == true
8.6 データ管理

290

oneAPI 仕様 リリース 1.0 リビジョン 3
void reset()
所有権構造ポインターを nullptr にリセットし、カウントをゼロに設定して、データと mutable_data を
nullptr に設定します。
void reset(const sycl::queue &queue, std::int64_t count, const sycl::usm::alloc&alloc = sycl::usm::alloc::shared)
可変データ向けに新しいメモリーブロックを割り当てて、初期化なしでブロックの所有権構造を作成し、配列内に構造を割り当てます。配列は割り当てられたメモリーブロックを所有する必要があります。
パラメーター• queue – SYCL* キュー・オブジェクト。
• count – メモリーを割り当てるデータ型の要素数。
• alloc – 割り当てられる USM の種別。
template<typename Deleter>void
reset(Data*data,
std::int64_t
count,
Deleter&&deleter,
const
sycl::vector_class<sycl::event> &dependencies = {})外部に割り当てられた可変データ・メモリー・ブロックの所有権構造を作成し、入力 deleter オブジェクトを割り当てて、このブロックに data と mutable_data ポインターを設定します。
テンプレート・パラメーター
Deleter – data を 解 放 す る 際 に 使 用 さ れ る deleter の タ イ プ 。 deleter は void
operator()(Data*) メンバー関数を実装する必要があります。
パラメーター• data – 配列内に割り当てられている可変メモリーブロックへのポインター。
• count – ブロック内の Data 型の要素数。
• deleter – data を解放する際に使用されるオブジェクト。
• dependencies – 読み取りまたは書き込み用の data の可用性を示すイベント。
template<typename ConstDeleter>void reset(const Data *data, std::int64_t count, ConstDeleter &&deleter, const
sycl::vector_class<sycl::event> &dependencies = {})外部に割り当てられた不変データ・メモリー・ブロックの所有権構造を作成し、入力 deleter オブジェクトを割り当てて、このブロックにデータポインターを設定します。
テンプレート・パラメーター
ConstDeleter – data を 解 放 す る 際 に 使 用 さ れ る deleter の タ イ プ 。 deleter は void
operator()(const Data*) `メンバー関数を実装する必要があります。
パラメーター• data – 配列内に割り当てられている不変メモリーブロックへのポインター。
• count – ブロック内の Data 型の要素数。
• deleter – data を解放する際に使用されるオブジェクト。
• dependencies – 読み取りまたは書き込み用の data の可用性を示すイベント。

8.6 データ管理291

oneAPI 仕様 リリース 1.0 リビジョン 3
template<typename RefData>
void reset(const array<RefData> &ref, Data *data, std::int64_t count)data と mutable_data を data ポインターで初期化し、count を入力 count 値で初期化して、所有権構造体へのポインターを ref で初期化します。配列は、可変ブロックとして data ポインターを返します。
テンプレート・パラメーター
RefData – 参照される配列内の要素タイプ。
パラメーター• ref – 所有権構造体を現在のものと共有する際に使用される配列。
• data – 配列内に割り当てられている可変のアンマネージド・ポインター。
• count – data 内の Data 型の要素数。
template<typename RefData>
void reset(const array<RefData> &ref, const Data *data, std::int64_t count)data を data ポインターで初期化し、count を入力 count 値で初期化して、所有権構造体へのポインターを ref で初期化します。配列は、不変ブロックとして data ポインターを返します。
テンプレート・パラメーター
RefData – 参照される配列内の要素タイプ。
パラメーター• ref – 所有権構造体を現在のものと共有する際に使用される配列。
• data – 配列内に割り当てられている不変のアンマネージド・ポインター。
• count – data 内の Data 型の要素数。
const Data &operator[] (std::int64_t index) const noexcept
配列要素への読み取り専用アクセスを提供します。境界チェックを行ってはいけません。
プロパティーData *mutable_data
可変データを保持するメモリーブロックへのポインター。
ゲッターとセッター
Data * get_mutable_data() const
不変mutable_data != nullptrif has_mutable_data() && count > 0
const Data *data
不変データを保持するメモリーブロックへのポインター。
ゲッターとセッター
const Data * get_data() const noexcept
不変data != nullptrif count > 0
has_mutable_data() == true であれば data == mutable_data

8.6 データ管理292

oneAPI 仕様 リリース 1.0 リビジョン 3
std::int64_t count
メモリーブロック内の Data 型の要素数。
ゲッターとセッター
std::int64_t get_count() const noexcept
std::int64_t size
バイト単位のメモリーブロックのサイズ。
ゲッターとセッター
std::int64_t get_size() const noexcept
不変size == count * sizeof(Data)
アクセサー
この節では、アクセサーの実装要件を定義し、いくつかのアクセサータイプを紹介します。
要件
アクセサーの実装は以下を行います。
1.
2.
3.
4.

5.

アクセス用に単一のデータ形式を定義します。すべてのアクセサータイプは 1 つのデータ形式のみを返し使用します。
テーブルタイプのデータへの読み取り専用アクセスを提供します。
テーブルから値を取得する pull() メソッドを提供します。
軽量である必要があります。コンストラクターは、データのコピー、読み取り、変換などの計算集約型の操作を行ってはなりません。これらの操作は pull() メソッドによってのみ可能です。アクセサーのコピーおよび移動コンストラクターのサポートは、ローカルスコープで使用できるように設計されているため、作成された場所で直接使用できます。
pull() メソッドは、テーブル内のメモリーブロックへのポインターを返すことができる場合、データのコ
ピーと変換を回避する必要があります。これは、テーブル内のデータ形式およびデータ型が、アクセスのデータ形式およびデータ型と同じである場合に適用されます。

アクセサータイプ
oneDAL は一連のアクセサークラスを定義します。各クラスは、テーブルからデータを取得する特定の方法をサポートします。以下に oneDAL におけるすべてのアクセサークラスを示します。
アクセサータイプ

説明

行アクセサー

行範囲のアクセスを連続した同種のメモリーブロックアクセス 同種テーブルとして提供します。

列アクセサー

連続した同種のメモリーブロックとして、単一列内の値の範囲
へのアクセスを提供します。

8.6 データ管理

サポートされるタイプのリスト

同種テーブル

293

oneAPI 仕様 リリース 1.0 リビジョン 3
詳細
列アクセサーcolumn_accessor クラスは、連続した同種の配列として、テーブル内の列値への読み取り専用アクセスを提供します。
使用例#include <CL/sycl.hpp>#include <iostream>#include "oneapi/dal/table/homogen.hpp"#include "oneapi/dal/table/column_accessor.hpp"
using namespace oneapi;
int main() {syｃｌ::queue queue { sycl::default_selector() };constexpr float host_data[] = {1.0f, 1.5f, 2.0f,
2.1f, 3.2f, 3.7f,
4.0f, 4.9f, 5.0f,
5.2f, 6.1f, 6.2f};
constexpr std::int64_t row_count = 4;
constexpr std::int64_t column_count = 3;
auto shared_data = sycl::malloc_shared<float>(row_count * column_count, queue);auto event = queue.memcpy(shared_data, host_data,
sizeof(float) * row_count * column_count);
auto t = dal::homogen_table::wrap(queue, data, row_count, column_count, { event });// 最初の列の要素全体にアクセス
dal::column_accessor<const float> acc { t };auto block = acc.pull(queue, 0);for(std::int64_t i = 0; i < block.get_count(); i++) {std::cout << block[i] << ", ";}std::cout << std::endl;
sycl::free(shared_data, queue);
return 0;}

8.6 データ管理294

oneAPI 仕様 リリース 1.0 リビジョン 3
プログラミング・インターフェイス
この節のすべての型と関数は、oneapi::dal 名前空間で宣言され、oneapi/dal/table/column_accessor.hpp
ヘッダーファイルをインクルードして使用できます。
template<typename Data>
class column_accessor
テンプレート・パラメーター
Data – アクセサーが返すブロック内のデータ値の型。読み取り専用アクセスは const-qualified である
必要があります。アクセサーは少なくとも float、double、および std::int32_t の Data 型をサポートする必要があります。
コンストラクター
column_accessor(const table &obj)
テーブルから新しい読み取り専用アクセサー・オブジェクトを作成します。アクセサーがテーブルの obj 種別をサポートしていることを確認します。obj テーブルの参照は、テーブルからデータを取得するためアクセサー内に格納されるものとします。
パブリック・メソッド
array<data_t> pull(sycl::queue &queue, std::int64_t column_index, const range&rows = {0, -1}, const sycl::usm::alloc &alloc = sycl::usm::alloc::shared) const
テーブルの列値へのアクセスを提供します。メソッドは、可能であればテーブル内のメモリーを直接指す配列を返す必要があります。この場合、配列は不変データに対してはメモリーを参照する必要があります。それ以外
では、新しいメモリーブロックが割り当てられ、テーブル行のデータが変換されてブロックにコピーされます。
配列は、可変データに対してはブロック参照する必要があります。
パラメーター• queue – SYCL* キュー・オブジェクト。
• column_index – アクセサーがデータを返す列のインデックス。
• rows – column index ブロックで読み取る必要がある行の範囲。
• alloc – 返されたブロックで要求された USM の種別。
前提条件
rows は [0, obj.row_count) の範囲内です。
column_index は [0, obj.column_count) の範囲内です。
Data *pull(sycl::queue &queue, array<data_t> &block, std::int64_t column_index,
const
range
&rows
=
{0,
-1},
const
sycl::usm::alloc&alloc=sycl::usm::alloc::shared) const
テーブルの列の値へのアクセスを提供します。メソッドは block.data ポインターを返します。
パラメーター• queue – SYCL* キュー・オブジェクト。
• block – テーブルからデータを取得する際にメモリーが再利用されるブロック (可能な場合)。ブロッ
クメモリーは、サイズが十分に大きくない場合や、不変データが含まれている場合、またはテーブルの直接メモリーを利用できる場合にリセットされます。オブジェクトから直接メモリーポインターを

8.6 データ管理295

oneAPI 仕様 リリース 1.0 リビジョン 3
利用するようにブロックがリセットされると、ブロックはこのポインターを不変メモリーブロックとして参照します。
• column_index – アクセサーがデータを返す列のインデックス。
• rows – column index ブロックで読み取る必要がある行の範囲。
• alloc – 返されたブロックで要求された USM の種別。
前提条件
rows は [0, obj.row_count) の範囲内です。
column_index は [0, obj.column_count) の範囲内です。
行アクセサー
row_accessor クラスは、連続した同種の配列として、テーブルの行への読み取り専用アクセスを提供します。
使用例#include <CL/sycl.hpp>#include <iostream>#include "oneapi/dal/table/homogen.hpp"#include "oneapi/dal/table/row_accessor.hpp"
using namespace oneapi;
int main() {sycl::queue queue { sycl::default_selector() };constexpr float host_data[] = {1.0f, 1.5f, 2.0f,
2.1f, 3.2f, 3.7f,
4.0f, 4.9f, 5.0f,
5.2f, 6.1f, 6.2f};
constexpr std::int64_t row_count = 4;
constexpr std::int64_t column_count = 3;
auto shared_data = sycl::malloc_shared<float>(row_count * column_count, queue);auto event = queue.memcpy(shared_data, host_data,
sizeof(float) * row_count * column_count);
auto t = dal::homogen_table::wrap(queue, data, row_count, column_count, { event });// テーブルの 2 番目と 3 番目の行にアクセス
dal::row_accessor<const float> acc { t };auto block = acc.pull(queue, {1, 3});for(std::int64_t i = 0; i < block.get_count(); i++) {std::cout << block[i] << ", ";}std::cout << std::endl;
sycl::free(shared_data, queue);
return 0;}

8.6 データ管理296

oneAPI 仕様 リリース 1.0 リビジョン 3
プログラミング・インターフェイス
この節のすべての型と関数は、oneapi::dal 名前空間で宣言され、oneapi/dal/table/row_accessor.hpp
ヘッダーファイルをインクルードして使用できます。
template<typename Data>
class row_accessor
テンプレート・パラメーター
Data – アクセサーが返すブロック内のデータ値の型。読み取り専用アクセスは const-qualified である
必要があります。アクセサーは少なくとも float、double、および std::int32_t の Data 型をサポートする必要があります。
コンストラクター
row_accessor(const table &obj)
テーブルから新しい読み取り専用アクセサー・オブジェクトを作成します。アクセサーがテーブルの obj 種別をサポートしていることを確認します。obj テーブルの参照は、テーブルからデータを取得するためアクセサー内に格納されるものとします。
パブリック・メソッド
array<data_t> pull(sycl::queue &queue, const range &rows = {0, -1}, const
sycl::usm::alloc &al- loc = sycl::usm::alloc::shared) const
テーブルの行アクセスを提供します。メソッドは、可能であればテーブル内のメモリーを直接指す配列を返す必要があります。
この場合、配列は不変データに対してはメモリーを参照する必要があります。それ以外では、新しいメモリーブ
ロックが割り当てられ、テーブル行のデータが変換されてブロックにコピーされます。配列は、可変データに対してはブロック参照する必要があります。
パラメーター• queue – SYCL* キュー・オブジェクト。
• rows – データがアクセサーから返される行の範囲。
• alloc – 返されたブロックで要求された USM の種別。
前提条件
rows は [0, obj.row_count) の範囲内です。
Data *pull(sycl::queue &queue, array<data_t> &block, const range &rows = {0, -1},
const sycl::usm::alloc &alloc = sycl::usm::alloc::shared) const
テーブルの行アクセスを提供します。メソッドは block.data ポインターを返します。
パラメーター• queue – SYCL* キュー・オブジェクト。
• block – テーブルからデータを取得する際にメモリーが再利用されるブロック (可能な場合)。ブロッ
クメモリーは、サイズが十分に大きくない場合や、不変データが含まれている場合、またはテーブルの直接メモリーを利用できる場合にリセットされます。オブジェクトから直接メモリーポインターを利用するようにブロックがリセットされると、ブロックはこのポインターを不変メモリーブロックとして参照します。
• rows – データがアクセサーから返される行の範囲。
8.6 データ管理297

oneAPI 仕様 リリース 1.0 リビジョン 3• alloc – 返されたブロックで要求された USM の種別。
前提条件
rows は [0, obj.row_count) の範囲内です。
データソース
ここでは、データソースの概念に関連するタイプについて説明します。
リード
リード操作は、args オブジェクトによって示されるデータソースと引数を結果オブジェクトに変換する関数です。操作は以下を行います。
• データソースのすべてのデータを取得して変換ルーチンを実行します。
• SYCL* キューをデータ取得および変換ルーチンに渡します。
リード操作の定義
次のサンプルコードはリード操作の宣言方法を示しています。
namespace oneapi::dal {template <typename Object, typename DataSource>
using read_args_t = /* implementation defined */;template <typename Object, typename DataSource>
using read_result_t = Object;template <typename Object, typename DataSource>
read_result_t<Object, DataSource> read(sycl::queue& queue,
const DataSource& data_source,
const read_args_t<Object, DataSource>& args);} // namespace oneapi::dal

それぞれの操作は次の要件を満たす必要があります。
• 操作は次の順序で 3 つのパラメーターを受け入れなければなりません。
– SYCL* キュー・オブジェクト。
– データソース。
– args オブジェクト。
• 操作は結果オブジェクトを返します。
• read_args_t と read_result_talias テンプレートは、args と戻り値の型推測に使用されます。
リード操作の短縮形
ユーザーコードの冗長性を軽減するため、oneDAL では読み取り操作の定義で説明されている関数に加え、読み取りを操作の短縮形 (ショートカットとも呼ばれます) のオーバーロード関数が定義されています。

8.6 データ管理298

oneAPI 仕様 リリース 1.0 リビジョン 3• ホストで実行する短縮形。ホストの一般的な関数と同じ操作を実行しますが、キューを明示的に渡す必要はありません。
template <typename Object, typename DataSource>
read_result_t<Object, DataSource> read(
const DataSource& data_source,
const read_args_t<Object, DataSource>& args);• 明示的な args の作成を省略できる短縮形。
template <typename Object, typename DataSource, typename... Args>
read_result_t<Object, DataSource> read(sycl::queue& queue,
const DataSource& data_source,
Args&&... args);• 明示的なキューと args の作成を省略できる短縮形。これは、前述の 2 つの省略形を組み合わせています。
template <typename Object, typename DataSource, typename...Args>
read_result_t<Object, DataSource> read(
const DataSource& data_source,
Args&&... args);

Args• 文字列 %DATA_SOURCE% は、データソース名に置き換える必要があります (例: csv)。
• %PROPERTY_NAME% と %PROPERTY_TYPE% は、データソースの args プロパティーの名前とタイプに置き換える必要があります。
namespace oneapi::dal::%DATA_SOURCE% {template <typename Object, typename DataSource> class read_args {public:read_args(
const %PROPERTY_TYPE_1%& property_name_1,
const %PROPERTY_TYPE_2%& property_name_2,/* 追加のプロパティー */)/* `%PROPERTY_NAME_1%` プロパティーのゲッターとセッター */descriptor& set_%PROPERTY_NAME_1%(%PROPERTY_TYPE_1% value);%PROPERTY_TYPE_1% get_%PROPERTY_NAME_1%() const;/* `%PROPERTY_NAME_2%` プロパティーのゲッターとセッター */descriptor& set_%PROPERTY_NAME_2%(%PROPERTY_TYPE_2% value);%PROPERTY_TYPE_2% get_%PROPERTY_NAME_2%() const;/* 追加のプロパティー */};} // namespace oneapi::dal::%DATA_SOURCE%

結果
読み取り操作の結果は、オブジェクト・タイプのメモリー内オブジェクトのインスタンスです。

8.6 データ管理299

oneAPI 仕様 リリース 1.0 リビジョン 3
データのソースタイプ
oneDAL では一連のクラスを定義します。
データソースタイプ

説明

CSV データソース

テキストファイルからテーブルにデータを読み取ることを許可するデータソース。

詳細
CSV データソース
csv::data_source クラスは、csv ファイルとして表現されるデータソースにアクセスする API です。CSV データ
ソースをリード操作で使用し、指定された入力ファイルからテキスト形式のデータを抽出して、与えられたパラメーター(区切り文字やリードオプションなど) を使用して処理することで数値表現に変換してメモリー内に選択された型のデー
タセットとして保存します。
CSV データソースを使用するリード操作でサポートされるメモリー内オブジェクトのタイプは oneapi::dal::tableです。
CSV データソースでは、コンストラクターで入力ファイル名を指定しますが、区切り文字や読み取りオプションなどのパラメーターはデフォルト値に依存します。
使用例
using namespace oneapi;
const auto data_source = dal::csv::data_source("data.csv", ',');
const auto table = dal::read<dal::table>(data_source);

プログラミング・インターフェイス
この節のすべての型と関数は、oneapi::dal::csv 名前空間で宣言され、oneapi/dal/io/csv.hpp ヘッダーファ
イルをインクルードして使用できます。
class data_source
data_source(const
char*file_name,char
delimiter=
default_delimiter,
read_options opts = de- fault_read_options)
指定された file_name、delimiter および read オプションフラグを使用して、CSV データソースの新しいインスタンスを作成します。
data_source(const std::string &file_name, char delimiter = default_delimiter,
read_options opts = default_read_options)
指定された file_name、delimiter および read オプションの opts フラグを使用して、CSV データソー
スの新しいインスタンスを作成します。
std::string file_name= ""
読み取るデータセットを含むファイル名を含む文字列。
ゲッター
std::string get_filename() const
8.6 データ管理

300

oneAPI 仕様 リリース 1.0 リビジョン 3

char delimiter = default_delimiter
入力ファイル内の機能を分離する区切り文字。
ゲッター
char get_delimter() const
read_options options = default_read_options
入力ファイルの読み取り中に適用されるリードオプションを格納する値。有効な parse_header オプション
は、入力ファイルの最初の行が特徴名のヘッダーレコードとして処理されることを示します。
ゲッター
read_options get_read_options() const
oneapi::dal::read<Object>... のリード
Args
template <typename Object>class read_args {public:read_args();};

template<typename Object>class read_args
read_args()
デフォルト属性で読み取り専用の引数を作成します。
操作
oneapi::dal::table は、CSV データソースで読み取り操作がサポートされているオブジェクト・テンプレート・パ
ラメーターとして利用できる唯一の値です。
template<typename Object, typename DataSource>
Object read(const DataSource &ds)
テンプレート・パラメーター• Object – データソースから読み取りの結果として生成される oneDAL オブジェクトのタイプ。
• DataSource – CSV データソース csv::data_source。
テーブル
ここでは、テーブルの概念に関連するタイプについて説明します。
型
table

説明

table_metadata

テーブルメタデータ概念の実装。

data_layout

テーブル内に連続するデータブロックを格納するために使用されるデータレイアウトの列挙。

feature_type

データに対して利用可能な操作のセットを定義するため、oneDAL で使用される特徴タイプの列挙。

8.6 データ管理

テーブルの概念の共通実装。ほかのテーブルタイプの基本クラス。

301

oneAPI 仕様 リリース 1.0 リビジョン 3
テーブルタイプの要件
テーブルの概念の実装には以下を行います。
1.
2.
3.
4.

テーブルの概念と制限 (不変性など) の定義に従います。
oneapi::dal::table クラスから派生します。クラスの動作は拡張できますが、制限することはできません。
参照カウントされます。
新しい oneapi::dal::table サブタイプは、一意の ID 番号 (実行時にタイプのオブジェクトを表す種
別 「kind」） を定義する必要があります。

次のリストは、テーブルの種別とコピー割り当て操作を説明するため、テーブル API の例を示しています。
using namespace onedal;// homogen_table sub-type を作成
dal::homogen_table table1 = homogen_table::wrap(queue, data_ptr, row_count, column_count);// table1 と table2 は同じデータを共有します (データはコピーされません)
dal::table table2 = table1;// 空のテーブルを作成
dal::table table3;
std::cout << table1.get_kind() == table2.get king() << std::endl; // true
std::cout << homogen_table::kind() == table2.het kind() << std::endl; // true
std::cout << table2.get kind() == table2.get kind() << std::endl; // true// table3 を table2 参照にします
table3 = table2;
std::cout << table2.get_kind() == table3.get_kind() << std::endl; // true

テーブルタイプ
oneDAL は、特定のデータ形式のテーブルの概念を実装するクラスのセットを定義します。
テーブルタイプ 説明
同種テーブル

連続した 同種のデータを含む密なテーブル。

プログラミング・インターフェイス
この節のすべての型と関数は、oneapi::dal 名前空間で宣言され、oneapi/dal/table/common.hpp ヘッダー
ファイルをインクルードして使用できます。
テーブル
テーブルの概念の基本実装。テーブルのタイプとすべてのサブタイプは、参照カウントされます。
1.
2.

インスタンスは、すべてのプロパティー値とデータを保持するテーブル実装へのポインターを格納する必要があります。
参照カウントは、同じ実装を参照するテーブル・オブジェクトの数を示します。

8.6 データ管理302

oneAPI 仕様 リリース 1.0 リビジョン 3
3.
4.

テーブルは、同じ実装を共有するテーブル・オブジェクトの数と等しくなるように、参照カウントをインクリ
メントしなければなりません。
テーブルがスコープ外になると、参照カウントをデクリメントする必要があります。参照カウントがゼロである場合、テーブルは実装を解放します。

class table {public:table();
table(const table& other);table(table&& other);table& operator=(const table& other);table& operator=(table&& other);bool has_data() const noexcept;
std::int64_t get_column_count() const;
std::int64_t get_row_count() const;
const table_metadata& get_metadata() const;
std::int64_t get_kind() const;
data_layout get_data_layout() const;};class table
コンストラクター
table()
空のテーブル・コンストラクター: 行と列の数がゼロのテーブル・インスタンスを作成します。実装は、デフォル
トに設定されたすべてのプロパティー値を返す特別の「空の」オブジェクトに設置されます (「プロパティー」を参照)。
table(const table &other)other と実装を共有する新しいテーブル・インスタンスを作成します。
table(table &&other)
新しいテーブル・インスタンスを作成して、実装を other からそのインスタンスに移動します。
パブリック・メソッド
table &operator=(const table &other)
実装を other の別の実装に置き換えます。
table &operator=(table &&other)
オブジェクトと other の実装を入れ替えます。
bool has_data()const noexcept
テーブルにゼロ以外の値の行と列が含まれているかどうかを示します。

8.6 データ管理303

oneAPI 仕様 リリース 1.0 リビジョン 3
プロパティー
std::int64_t column_count = 0
テーブルの列数。
ゲッターとセッター
std::int64_t get_column_count() const
std::int64_t row_count = 0
テーブルの行数。
ゲッターとセッター
std::int64_t get_row_count() const
const table_metadata &metadata = table_metadata()
テーブル内のデータの追加情報を保持するメタデータ・オブジェクト。
ゲッターとセッター
const table_metadata & get_metadata() const
std::int64_t kind = empty_table_kind
テーブル型のランタイム ID。各テーブルのサブタイプには、固有の kind があります。空のテーブル (デフォル
トのコンストラクターを参照) にも一意の kind 値が必要です。
ゲッターとセッター
std::int64_t get_kind() const
data_layout data_layout= data_layout::unknown
テーブル内のデータレイアウト。
ゲッターとセッター
data_layout get_data_layout() const
テーブルのメタデータ
テーブルのメタデータ概念の実装。テーブル内のデータの追加情報を保持します。table_metadata のオブジェクト
は、参照カウントされます。
class table_metadata {public:table_metadata();
table_metadata(const array<data_type>& dtypes, const array<feature_type>& ftypes);
std::int64_t get_feature_count() const;
const feature_type& get_feature_type(std::int64_t feature_index) const;
const data_type& get_data_type(std::int64_t feature_index) const;};

8.6 データ管理304

oneAPI 仕様 リリース 1.0 リビジョン 3
class table_metadata
コンストラクター
table_metadata()
特徴に関する情報なしでメタデータのインスタンスを作成します。feature_count はゼロに設定されます。
data_type と feature_type プロパティーは初期化されません。
table_metadata(constarray<data_type> &dtypes, constarray<feature_type> &ftypes)
データ型と機能タイプに関する外部情報からメタデータ・インスタンスを作成します。
パラメーター• dtypes– 機能のデータ型。data_type プロパティーに割り当てる必要があります。
• ftypes– 機能タイプ。feature_type プロパティーに割り当てる必要があります。
前提条件
dtypes.get_count() == ftypes.get_count()
プロパティー
std::int64_t feature_count
メタデータに情報が含まれる機能の数。
ゲッターとセッター
std::int64_t get_feature_count() const
const feature_type &feature_type
メタデータ・オブジェクトの特徴タイプ。[0, feature_count) の範囲内にある必要があります。
ゲッターとセッター
const feature_type & get_feature_type(std::int64_t feature_index) const
const data_type &data_type
メタデータ・オブジェクトの特徴データ型。[0, feature_count) の範囲内にある必要があります。
ゲッターとセッター
const data_type & get_data_type(std::int64_t feature_index) const
データ形式
data layout 概念の実装。
enum class data_layout { unknown, row_major, column_major };enum class data_layout
data_layout::unknown: 未定義または不明なデータレイアウトを示します。
data_layout::row_major: データブロックの要素は、行-列レイアウトで保存されます。
data_layout::column_major: データブロックの要素は、列優先レイアウトで保存されます。

8.6 データ管理305

oneAPI 仕様 リリース 1.0 リビジョン 3
機能タイプ
論理データ型の実装。
enum class feature_type { nominal, ordinal, interval, ratio };enum class feature_type
feature_type::nominal 名目特徴の型を示します。
feature_type::ordinal: 順序特徴の型を示します。
feature_type::interval: 区間特徴の型を示します。
feature_type::ratio: 比率特徴の型を示します。
同種テーブル
クラス homogen_tableis は、以下が当てはまるテーブル型の実装です。
• テーブル内のデータは密であり、1 つの連続したメモリーブロックとして格納されます。
• すべての列は同じデータ型です。
プログラミング・インターフェイス
この節のすべての型と関数は、oneapi::dal 名前空間で宣言され、oneapi/dal/table/homogen.hpp ヘッダー
ファイルをインクルードして使用できます。
class homogen_table : public table {public:static std::int64_t kind();template <typename Data>static homogen_table wrap(const sycl::queue& queue,
const Data* data_pointer,
std::int64_t row_count,
std::int64_t column_count,
const sycl::vector_class<sycl::event>& dependencies = {},data_layout layout = data_layout::row_major);
public:homogen_table();template <typename Data, typename ConstDeleter>
homogen_table(const sycl::queue& queue,
const Data* data_pointer,
std::int64_t row_count,
std::int64_t column_count,
ConstDeleter&& data_deleter,
const sycl::vector_class<sycl::event>& dependencies = {},data_layout layout = data_layout::row_major);(次のページへ続く)

8.6 データ管理306

oneAPI 仕様 リリース 1.0 リビジョン 3(前のページの続き)
template <typename Data>
const Data* get_data() const {return reinterpret_cast<const Data*>(this->get_data());}
const void* get_data() const;
std::int64_t get_kind() const {return kind();}};class homogen_table
パブリック静的メソッド
static std::int64_t kind()homogen_table クラスの一意の id を返します。
template<typename Data>static homogen_table wrap(const sycl::queue &queue, const Data *data_pointer,
std::int64_t
row_count,
std::int64_t
column_count,const
sycl::vector_class<sycl::event> &dependencies ={},data_layout layout =data_layout::row_major)
外部で定義されたデータブロックから、新しい homogen_table インスタンスを作成します。テーブル・オブジェクトはデータを参照しますが、所有はしません。
データを解放する責任はユーザーにあります。データは、data_pointer メモリーブロックを指していなければなりません。
テンプレート・パラメーター
Data – テーブルに格納されるデータブロック内の要素型。テーブルは、メタデータのデータ型をこのデータ型で初期化します。特徴タイプは Data 型のデフォルト値に設定する必要があります。浮動小数点型では連続 (contiguous)、整数型では順序 (ordinal) です。Data 型は少なくとも float、double、または
std::int32_t である必要があります。
パラメーター• queue – SYCL* キュー・オブジェクト。
• data_pointer – 同種データブロックへのポインター。
• row_count – テーブルの行数。
• column_count – テーブルの列数。
• dependencies – 読み取りまたは書き込み用の data の可用性を示すイベント。
• layout – データのレイアウト。data_layout::row_major または data_layout::column_major
である必要があります。
コンストラクター
homogen_table()
行 と 列 の 数 が ゼ ロ で あ る 新 し い homogen_table イ ン ス タ ン ス を 作 成 し ま す 。 種 別 (kind) はhomogen_table::kind() に設定されます。すべてのプロパティーはデフォルト値に設定されます (プロパティーの節を参照)。
`

8.6 データ管理`307

oneAPI 仕様 リリース 1.0 リビジョン 3
template<typename Data, typename ConstDeleter>
homogen_table(const
sycl::queue&queue,const
Data*data_pointer,
std::int64_t row_count, std::int64_t column_count, ConstDeleter &&data_deleter,
const sycl::vector_class<sycl::event> &dependencies = {}, data_layout layout =data_layout::row_major)
外部で定義されたデータブロックから、新しい homogen_table インスタンスを作成します。テーブル・オブジェクトはデータポインター所有します。
データは、data_pointer メモリーブロックを指していなければなりません。
テンプレート・パラメーター• Data – テーブルに格納されるデータブロック内の要素型。Data 型は少なくとも float、double、または std::int32_t である必要があります。
• ConstDeleter – 参照する最後のテーブルがスコープ外にある場合、data_pointer で呼び出されるデリーター。
パラメーター• queue – SYCL* キュー・オブジェクト。
• data_pointer – 同種データブロックへのポインター。
• row_count – テーブルの行数。
• column_count – テーブルの列数。
• data_deleter – 参照する最後のテーブルがスコープ外にある場合、data_pointer で呼び出されるデリーター。
• dependencies – 読み取りまたは書き込み用の data の可用性を示すイベント。
• layout – データのレイアウト。data_layout::row_major または data_layout::column_major
である必要があります。
パブリック・メソッド
template<typename Data>
const Data *get_data()const
Data 型にキャストされた data ポインターを返します。この型がテーブル内の実際の型であるかはチェックされません。
プロパティー
const void *data
テーブル内のデータブロックへのポインター。row_count == 0 と column_count == 0 の場合、nullptr と等しくなります。
ゲッターとセッター
const void * get_data() const
std::int64_t kind
homogen テーブル型の一意な ID。
ゲッターとセッター
std::int64_t get_kind() const

8.6 データ管理308

oneAPI 仕様 リリース 1.0 リビジョン 3

8.7

アルゴリズムアルゴリズム・コンポーネントは、データ解析 (データマイニング) およびデータモデリング (訓練と予測) 用のアルゴリズ
ムを実装するクラスから構成されます。これらのアルゴリズムには、行列分解、クラスタリング、分類、回帰アルゴリズムと相関ルールが含まれます。

8.7.1 クラスタリング
K 平均法
K 平均法アルゴリズムは、n 個の特徴ベクトルを k 個のクラスターに分散することでクラスタリングの問題を解決し、いくつかの基準を最小化します。各クラスターは、セントロイド (中心) と呼ばれる代表点により特徴付けられます。
操作

計算メソッド訓練

ロイド

プログラミング・インターフェイス
train(. . . ) train_input train_result

推論

ロイド

infer(... ) infer_input infer_result

数学的な定式訓練
p 次元の特徴ベクトルの訓練セット X = {x1, ..., xn} と正の整数 k が与えられた場合、問題は目的関数を最小化する中心 p 次元のセット C = {c1, ..., ck} を見つけることです。

ここで、d2(xi,C) は、xi から C の最も近い中心までのユークリッド距離の 2 乗です。

式 ‖ · ‖ は L2 ノルム (英語) を示します。
注: 一般に d は任意の距離関数です。oneDAL の現在の仕様ではユークリッド距離のみが定義されています。
訓練方法: ロイド
ロイド法 [Lloyd82] は、割り当てと更新ステップを交互に適用し、中心を繰り返し更新することで構成されます。ここで、t は現在のインデックスを示します。例えば、C(t) = {c(t)x,...,c(t)k} は、t 番目の反復の中心セットです。

8.7 アルゴリズム

309

oneAPI 仕様 リリース 1.0 リビジョン 3
この方法では、アルゴリズムの開始時に中心 C(1) を指定する必要があります (t = 1)。
1.

割り当てステップ: 各特徴ベクトル xi を最も近い中心に割り当てます。yi(t) は、特徴ベクトル xi に割り当てられたラベル (クラスター・インデックス) を示します。

訓練セット X の特徴ベクトルは、X が k 個の互いに素なセット (クラスター) に分割されるように、正確に 1 つの中心に割り当てられます2.

更新ステップ: 各クラスターに割り当てられた特徴ベクトルを平均化して、中心を再計算します。

ステップ 1 と 2 は、次の停止条件が満たされるか、反復回数がユーザーが定義した最大値 T を超るまで繰り返されます。

推論
p 次元特徴ベクトルの推論セット X ′ = { x1 ′ , ..., xm ’ } と、訓練ステージで生成された中心セット C ={ c1, ... , ck } を 考えると、 問題はメソッ ド で手尾後された規則に従 って、 中心のインデッ クス yj ’ ∈{0, ... , k - 1}, 1 ≤ j ≤ m を予測します。
推論法: ロイド
ロイドの推論方法は、yj′を特徴ベクトル xj′に最も近い中心のインデックスとして計算します。

8.7 アルゴリズム

310

oneAPI 仕様 リリース 1.0 リビジョン 3
使用例
kmeans::model<> run_training(const table& data,
const table& initial_centroids) {const auto kmeans_desc = kmeans::descriptor<float>{}.set_cluster_count(10).set_max_iteration_count(50).set_accuracy_threshold(1e-4);
const auto result = train(kmeans_desc, data, initial_centroids);
print_table("labels", result.get_labels());
print_table("centroids", result.get_model().get_centroids());
print_value("objective", result.get_objective_function_value());
return result.get_model();}推論
table run_inference(const kmeans::model<>& model,
const table& new_data) {const auto kmeans_desc = kmeans::descriptor<float>{}.set_cluster_count(model.get_cluster_count());
const auto result = infer(kmeans_desc, model, new_data);
print_table("labels", result.get_labels());}

プログラミング・インターフェイス
この節のすべての型と関数は、oneapi::dal::kmeans 名前空間で宣言され、oneapi/dal/algo/kmeans.hpp
ヘッダーファイルをインクルードして使用できます。
記述子
template <typename Float = float,
typename Method = method::by_default,
typename Task = task::by_default>
class descriptor {public:explicit descriptor(std::int64_t cluster_count = 2);
int64_t get_cluster_count() const;
descriptor& set_cluster_count(int64_t);
int64_t get_max_iteration_count() const;
descriptor& set_max_iteration_count(int64_t);
double get_accuracy_threshold() const;
descriptor& set_accuracy_threshold(double);};

8.7 アルゴリズム

311

oneAPI 仕様 リリース 1.0 リビジョン 3
template<typename Float= float, typename Method= method::by_default, typename Task=
task::by_default> class descriptor
テンプレート・パラメーター• Float – アルゴリズムが中間計算に使用する浮動小数点の型。float または double にすることができます。
• Method – アルゴリズムの実装を指定するタグタイプ。method::lloyd とすることができます。
• Task – 解決する問題のタイプを指定するタグタイプ。task::clustering とすることができます。
コンストラクター
descriptor(std::int64_t cluster_count = 2)
指定された cluster_count を使用して、クラスの新しいインスタンスを作成します。
プロパティー
int64_t cluster_count= 2
クラスターの数 k。
ゲッターとセッター
int64_tget_cluster_count()
descriptor & set_cluster_count(int64_t)
不変cluster_count> 0

const

int64_t max_iteration_count= 100
反復の最大数 T。
ゲッターとセッター
int64_tget_max_iteration_count()
descriptor & set_max_iteration_count(int64_t)

const

不変
max_iteration_count > 0
double accuracy_threshold= 0.0
停止条件のしきい値 ε。
ゲッターとセッター
doubleget_accuracy_threshold()
descriptor & set_accuracy_threshold(double)

const

不変
accuracy_threshold >= 0.0
メソッドタグ
namespace method {struct lloyd {};using by_default = lloyd;} // namespace method

8.7 アルゴリズム

312

oneAPI 仕様 リリース 1.0 リビジョン 3
struct lloyd
Lloyd の計算法を表すタグタイプ。
using by_default= lloyd
Lloyd の計算方法のエイリアス・タグ・タイプ。
タスクタグ
namespace task {struct clustering {};using by_default = clustering;} // namespace task

struct clustering
クラスタリング問題の解決に使用されるエンティティーをパラメーター化するタグタイプ。
using by_default= clustering
クラスタリング・タスクのエイリアス・タグ・タイプ。
モデル
template <typename Task = task::by_default>
class model {public:model();
const table& get_centroids() const;
int64_t get_cluster_count() const;};

template<typename Task= task::by_default>
class model
テンプレート・パラメーター
Task – 解決する問題のタイプを指定するタグタイプ。task::clustering とすることができます。
コンストラクター
model()
デフォルトのプロパティー値を使用してクラスの新しいインスタンスを作成します。
プロパティー
const table &centroids= table{}クラスターの中央値を含む k × p テーブル。テーブルの各行には、1 つの中央値が格納されます。
ゲッターとセッター
const table & get_centroids() const
int64_t cluster_count= 0
訓練されたモデルのクラスター数 k 。
ゲッターとセッター
int64_t get_cluster_count() const
不変cluster_count == centroids.row_count
8.7 アルゴリズム

313

oneAPI 仕様 リリース 1.0 リビジョン 3
訓練 train...
入力
template <typename Task = task::by_default>
class train_input {public:train_input(const table& data = table{},const table& initial_centroids = table{});const table& get_data() const;
train_input& set_data(const table&);const table& get_initial_centroids() const;
train_input& set_initial_centroids(const table&);};template<typename Task= task::by_default>
class train_input
テンプレート・パラメーター
Task – 解決する問題のタイプを指定するタグタイプ。task::clustering とすることができます。
コンストラクター
train_input(consttable &data = table{}, consttable &initial_centroids = table{})指定された initial_centroids を使用して、クラスの新しいインスタンスを作成します。
プロパティー
const table &data
データを取りクラスターを含む n × p テーブル。各行には 1 つの特徴ベクトルが格納されます。
ゲッターとセッター
const
table
&
train_input & set_data(const table &)get_data()

const

const table &initial_centroids
初期の中央値を含む n × p テーブル。各行には 1 つの中央値が格納されます。
ゲッターとセッター
const
table
&
get_initial_centroids()
train_input & set_initial_centroids(const table &)8.7 アルゴリズム

const

314

oneAPI 仕様 リリース 1.0 リビジョン 3
結果
template <typename Task = task::by_default>
class train_result {public:train_result();
const model<Task>& get_model() const;
const table& get_labels() const;
int64_t get_iteration_count() const;
double get_objective_function_value() const;};

template<typename Task= task::by_default>
class train_result
テンプレート・パラメーター
Task – 解決する問題のタイプを指定するタグタイプ。task::clustering とすることができます。
コンストラクター
train_result()
デフォルトのプロパティー値を使用してクラスの新しいインスタンスを作成します。
プロパティー
const model<Task> &model= model<Task>{}
訓練された K 平均法モデル。
ゲッターとセッター
const model< Task > & get_model() const
const table &labels= table{}
入力データのサンプル xi にラベル yi が割り当てられた n x 1 のテーブル、1 ≤ 1 ≤ n。
ゲッターとセッター
const table & get_labels() const
int64_t iteration_count = 0
アルゴリズムの最大反復回数。
ゲッターとセッター
int64_t get_iteration_count() const
不変
iteration_count > 0
double objective_function_value
目的関数 Φx(C) の値。C は model.centroids (kmeans::model::centroids を参照)。
ゲッターとセッター
double get_objective_function_value() const
8.7 アルゴリズム

315

oneAPI 仕様 リリース 1.0 リビジョン 3不変
objective_function_value >= 0.0
操作
template<typename Float, typename Method, typename Task>
train_result<Task> train(constdescriptor<Float, Method, Task> &desc,
consttrain_input<Task> &input)
K 平均クラスタリングのトレーニング操作を実行します。詳細については、oneapi::dal::train をご覧ください。
テンプレート・パラメーター• Float – アルゴリズムが中間計算に使用する浮動小数点の型。float または double にすることができます。
• Method – アルゴリズムの実装を指定するタグタイプ。method::lloyd とすることができます。
• Task – 解決する問題のタイプを指定するタグタイプ。task::clustering とすることができます。
パラメーター• desc – アルゴリズムの記述子。
• input – トレーニング操作の入力データ。
前提条件
input.data.has_data==
true
input.initial_centroids.row_count==desc.cluster_count
input.initial_centroids.column_count == input.data.column_count
事後条件
result.labels.row_count==
input.data.row_countresult.labels.column_count==1
result.labels[i]>=0result.labels[i]<desc.cluster_countresult.iteration_count<=desc.max_iteration_countresult.model.clusters.row_count==desc.cluster_countresult.model.clusters.column_count == input.data.column_count
推論 infer...
入力
template <typename Task = task::by_default>
class infer_input {public:infer_input(const model<Task>& m = model<Task>{},const table& data = table{});const model<Task>& get_model() const;
infer_input& set_model(const model<Task>&);const table& get_data() const;
infer_input& set_data(const table&);};8.7 アルゴリズム

316

oneAPI 仕様 リリース 1.0 リビジョン 3
template<typename Task= task::by_default>
class infer_input
テンプレート・パラメーター
Task – 解決する問題のタイプを指定するタグタイプ。task::clustering とすることができます。
コンストラクター
infer_input(constmodel<Task> &m = model<Task>{}, consttable &data = table{})指定されたモデルとデータを使用して、クラスの新しいインスタンスを作成します。
プロパティー
const model<Task> &model= model<Task>{}
クラスターに割り当てられるデータを含む n × p テーブル。各行には 1 つの特徴ベクトルが格納されます。
ゲッターとセッター
const
model<Task>&
infer_input& set_model(const model<Task>&)

get_model()const

const table &data= table{}
訓練された K 平均モデル。
ゲッターとセッター
const table & get_data() const infer_input & set_data(const table &)結果
template <typename Task = task::by_default>
class infer_result {public:infer_result();
const table& get_labels() const;};

double get_objective_function_value() const;

template<typename Task= task::by_default>
class infer_result
テンプレート・パラメーター
Task – 解決する問題のタイプを指定するタグタイプ。task::clustering とすることができます。
コンストラクター
infer_result()
デフォルトのプロパティー値を使用してクラスの新しいインスタンスを作成します。
プロパティー
const table &labels= table{}
入力データの特徴ベクトルへの割り当てラベルを持つ n × 1 テーブル。
ゲッターとセッター
const table & get_labels() const

8.7 アルゴリズム

317

oneAPI 仕様 リリース 1.0 リビジョン 3
double objective_function_value = 0.0
目的関数 Φx(C) の値。これは、対応する infer_input::model::centroids によって定義されます。
ゲッターとセッター
double get_objective_function_value() const
不変
objective_function_value >= 0.0
操作
template<typename Float, typename Method, typename Task>
infer_result<Task> infer(constdescriptor<Float, Method, Task> &desc,
constinfer_input<Task> &input)
K 平均クラスタリングの推論操作を実行します。詳細については、oneapi::dal::infer をご覧ください。
テンプレート・パラメーター• Float – アルゴリズムが中間計算に使用する浮動小数点の型。float または double にすることができます。
• Method – アルゴリズムの実装を指定するタグタイプ。method::lloyd とすることができます。
• Task – 解決する問題のタイプを指定するタグタイプ。task::clustering とすることができます。
パラメーター• desc – アルゴリズムの記述子。
• input – 推論操作の入力データ。
前提条件
input.data.has_data==
true
input.model.centroids.has_data==
true
input.model.centroids.row_count==desc.cluster_count
input.model.centroids.column_count == input.data.column_count
事後条件
result.labels.row_countresult.labels.column_countresult.labels[i]result.labels[i] < desc.cluster_count

==
>=

==

input.data.row_count10

K 平均法の初期化
K 平均法初期化アルゴリズムは、入力として n 個の特徴ベクトルを受け取り、k 個の初期中心を選択します。初期化後、K 平均法アルゴリズムは初期化した結果を使用して、入力データを k 個のクラスターに分散します。
操作

計算メソッド計算

密プログラミング・インターフェイス
compute(.. . )compute_input
compute_result

数学的な定式 計算
p 次元の特徴ベクトルの訓練セット X = {x1, ..., xn} と正の整数 k が与えられた場合、問題は目的関数を最小化する中心 p 次元のセット C = {c1, ..., ck} を見つけることです。

8.7 アルゴリズム

318

oneAPI 仕様 リリース 1.0 リビジョン 3
計算メソッド: dense (密)この方法では、訓練セット X から最初の k 個の特徴ベクトルを選択します。
計算の使用例
table run_compute(const table& data) {const auto kmeans_desc = kmeans_init::descriptor<float, kmeans_init::method::dense>{}.set_cluster_count(10)const auto result = compute(kmeans_desc, data);
print_table("centroids", result.get_centroids());
return result.get_centroids();}

プログラミング・インターフェイス
この節のすべての型と関数は、oneapi::dal::kmeans_init 名前空間で宣言され、oneapi/dal/algo/kmeans_init.hpp
ヘッダーファイルをインクルードして使用できます。
記述子
template <typename Float = float,
typename Method = method::by_default,
typename Task = task::by_default>
class descriptor {public:explicit descriptor(std::int64_t cluster_count = 2);
std::int64_t get_cluster_count() const;
descriptor& set_cluster_count(std::int64_t);};

template<typename Float= float, typename Method= method::by_default, typename Task=
task::by_default>
class descriptor
テンプレート・パラメーター• Float – アルゴリズムが中間計算に使用する浮動小数点の型。float または double にすることができます。
• Method – K 平均法初期化アルゴリズムの実装を指定するタグタイプ。
• Task – 解決する問題のタイプを指定するタグタイプ。task::init とすることができます。
コンストラクター
descriptor(std::int64_t cluster_count = 2)
指定された cluster_count を使用して、クラスの新しいインスタンスを作成します。

8.7 アルゴリズム

319

oneAPI 仕様 リリース 1.0 リビジョン 3
プロパティー
std::int64_t cluster_count= 2
クラスターの数 k。
ゲッターとセッター
std::int64_t
get_cluster_count()
descriptor & set_cluster_count(std::int64_t)

const

不変
cluster_count > 0
メソッドタグ
namespace method {struct dense {};using by_default = dense;} // namespace method

struct dense
dense 計算法を表すタグタイプ。
using by_default= dense
タスクタグ
namespace task {struct init {};using by_default = init;} // namespace task

struct init
初期の K 平均法の中心を取得するのに使用されるエンティティーをパラメーター化するタグタイプ。
using by_default= init
初期化タスクのエイリアス・タグ・タイプ。
計算 compute...
入力
template <typename Task = task::by_default>
class compute_input {public:compute_input(const table& data = table{});const table& get_data() const;
compute_input& set_data(const table&);};8.7 アルゴリズム

320

oneAPI 仕様 リリース 1.0 リビジョン 3
template<typename Task= task::by_default>
class compute_input
テンプレート・パラメーター
Task – 解決する問題のタイプを指定するタグタイプ。task::init とすることができます。
コンストラクター
compute_input(consttable &data = table{})指定されたデータを使用して、クラスの新しいインスタンスを作成します。
プロパティー
const table &data= table{}
データを取りクラスターを含む n × p テーブル。各行には 1 つの特徴ベクトルが格納されます。
ゲッターとセッター
const table& get_data() const; compute_input& set_data(const table&);結果
template <typename Task = task::by_default>
class compute_result {public:compute_result();
const table& get_centroids() const;};

template<typename Task= task::by_default>
class compute_result
テンプレート・パラメーター
Task – 解決する問題のタイプを指定するタグタイプ。task::clustering とすることができます。
コンストラクター
compute_result()
デフォルトのプロパティー値を使用してクラスの新しいインスタンスを作成します。
プロパティー
const table &centroids= table{}
初期の中央値を含む k × p テーブル。テーブルの各行には、1 つの中央値が格納されます。
ゲッターとセッター
const table & get_centroids() const
操作
template<typename Float, typename Method, typename Task>
compute_result<Task> compute(const descriptor<Float, Method, Task> &desc, const
compute_input<Task> &input)
K 平均法初期化の計算操作を実行します。詳細については、oneapi::dal::compute をご覧ください。

8.7 アルゴリズム

321

oneAPI 仕様 リリース 1.0 リビジョン 3
テンプレート・パラメーター• Float – アルゴリズムが中間計算に使用する浮動小数点の型。float または double にすることができます。
• Method – K 平均法初期化アルゴリズムの実装を指定するタグタイプ。
• Task – 解決する問題のタイプを指定するタグタイプ。task::init とすることができます。
パラメーター• desc – アルゴリズムの記述子。
• input – 計算操作の入力データ。
前提条件
input.data.has_data
input.data.row_count == desc.cluster_count

==

true

事後条件
result.centroids.has_data==
result.centroids.row_count==result.centroids.column_count == input.data.column_counttruedesc.cluster_count

8.7.2 近傍法 (kNN)
k 近傍法分類 (k-NN)

k-NN 分類アルゴリズムは、訓練セットから k 近傍観測値の多数決を計算することで、新しい特徴ベクトルのクラスを推
測します。
操作

計算メソッド訓練

ブルートフォース

k-d ツリー

プログラミング・インターフェイス
train(...)
train_input
train_result

推論ブルートフォース

k-d ツリー

infer(...)

infer_input

infer_result

数学的な定式訓練
X = { x1, ... , xn } を p 次元の特徴ベクトルの訓練セットとし、Y = {y1, ... , yn } をクラスラベルのセットとします。ここで、yi ∈ { 0, ... , c - 1 }, 1 ≤ i ≤ n です。X、Y および最近傍数 k が与えられる
場合、問題は、訓練の特徴ベクトルと推論ステージの推論セット間の距離を計算するモデルを構築します。
訓練メソッド: ブルートフォース
訓練操作は、初期訓練セット X からすべての特徴ベクトルを格納するモデルを生成します。
訓練メソッド: k-d ツリー
訓練操作は、訓練セット X を分割する ｋ-d ツリーを構築します (詳細は、「k-d ツリー」を参照)。

8.7 アルゴリズム

322

oneAPI 仕様 リリース 1.0 リビジョン 3
推論
X′= {x1′, ... , xm’ } を p 次元の特徴ベクトルの推論セットとします。訓練ステージで生成されたモデル X′、
および最近傍数 k が与えられた場合、問題は、次の手順を実行してこれぞれの xj′, 1 ≤ j < m のラベル ｙj′を予測します。
1.
2.

ユークリッド距離に関して、ｘj′に最も近い訓練セット内の k 個の特徴ベクトルセット N (xj′) ⊆X を特定します。
l 番目のクラスの条件付き確立を、ラベル yj が l に等しい N (xj′) のベクトルの割合として推測
します。
(8.1)

3.

特徴ベクトル xj’ の確立が最も高いクラスを予測します。
(8.2)

推論メソッド: ブルートフォース
ブルートフォース推論は、実装で定義される順序、1 ≤ i ≤ n、1 ≤ j ≤ m のすべてのペア (xj’ , xi ) を反復することで、最も近い特徴ベクトルのセット N (xj′) を決定します。最終的な予測は式 (8.1) と (8.2) に従って計算されます。
推論メソッド: k-d ツリー
k-d ツリー推論は、k-d ツリーをトラバースして xj′, 1 ≤ j ≤ m に最も近いルーフノードに関連する特徴ベクトルを検出します。現在知られている最も近い k 番目の近傍セット n˜(xj′) は、ツリーのトラバース中に徐々に更新されます。検索アルゴリズムは、xj′と特徴空間の各部分間の距離が xj′と n˜(xj′) から最も遠い特徴ベクトル間との距離以上であるノードの探索を制限します。ノードのトラバースが終了すると n˜(xj′) ≡ N (xj′) です。最終的な予測は式 (8.1) と (8.2) に従って計算されます。
使用例
knn::model<> run_training(const table& data,
const table& labels) {const std::int64_t class_count = 10;
const std::int64_t neighbor_count = 5;
const auto knn_desc = knn::descriptor<float>{class_count, neighbor_count};
const auto result = train(knn_desc, data, labels);
return result.get_model();}

8.7 アルゴリズム

323

oneAPI 仕様 リリース 1.0 リビジョン 3
推論
table run_inference(const knn::model<>& model,
const table& new_data) {const std::int64_t class_count = 10;
const std::int64_t neighbor_count = 5;
const auto knn_desc = knn::descriptor<float>{class_count, neighbor_count};
const auto result = infer(knn_desc, model, new_data);
print_table("labels", result.get_labels());}

プログラミング・インターフェイス
この節のすべての型と関数は、oneapi::dal::knn 名前空間で宣言され、oneapi/dal/algo/knn.hpp ファイルをインクルードして使用できます。
記述子
template <typename Float = float,
typename Method = method::by_default,
typename Task = task::by_default>
class descriptor {public:explicit descriptor(std::int64_t class_count,
std::int64_t neighbor_count);
std::int64_t get_class_count() const; descriptor& set_class_count(std::int64_t);
std::int64_t get_neighbor_count() const;
descriptor& set_neighbor_count(std::int64_t);};

template<typename Float= float, typename Method= method::by_default, typename Task=
task::by_default>
class descriptor
テンプレート・パラメーター• Float – アルゴリズムが中間計算に使用する浮動小数点の型。float または double にすることができます。
• Method – ア ル ゴ リ ズ ム の 実 装 を 指 定 す る タ グ タ イ プ 。 method::bruteforce ま た は
method::kd_tree とすることができます。
• Task – 解決する問題のタイプを指定するタグタイプ。task::classification とすることができます。
コンストラクター
descriptor(std::int64_t class_count, std::int64_t neighbor_count)指定された class_count と neighbor_count のプロパティー値を使用して、クラスの新しいインスタンス
を作成します。

8.7 アルゴリズム

324

oneAPI 仕様 リリース 1.0 リビジョン 3
プロパティー
std::int64_t class_count
クラスの数 c。
ゲッターとセッター
std::int64_t get_class_count() const descriptor & set_class_count(std::int64_t)
不変class_count > 1
std::int64_t neighbor_count
近傍数 k。
ゲッターとセッター
std::int64_t
get_neighbor_count()
descriptor & set_neighbor_count(std::int64_t)
不変neighbor_count > 0

const

メソッドタグ
namespace method { struct
bruteforce {}; struct
kd_tree {};using by_default = bruteforce;} // namespace method

struct bruteforce
総当たり分散 (bruteforce) 計算法を表すタグタイプ。
struct kd_tree
k-d ツリーの計算方法を示すタグタイプ。
using by_default= bruteforce
総当たり分散 (bruteforce) 計算法のエイリアス・タグ・タイプ。
タスクタグ
namespace task {struct classification {};using by_default = classification;} // namespace task

struct classification
分類問題の解決に使用されるエンティティーをパラメーター化するタグタイプ。
using by_default= classification
分類タスクのエイリアス・タグ・タイプ。

8.7 アルゴリズム

325

oneAPI 仕様 リリース 1.0 リビジョン 3
モデル
template <typename Task = task::by_default>
class model {public:model();};

template<typename Task= task::by_default>
class model
テンプレート・パラメーター
Task – 解決する問題のタイプを指定するタグタイプ。task::classification とすることができます。
コンストラクター
model()
デフォルトのプロパティー値を使用してクラスの新しいインスタンスを作成します。
訓練 train...
入力
template <typename Task = task::by_default>
class train_input {public:train_input(const table& data = table{},const table& labels = table{});const table& get_data() const;
train_input& set_data(const table&);const table& get_labels() const;
train_input& set_labels(const table&);};template<typename Task= task::by_default>
class train_input
テンプレート・パラメーター
Task – 解決する問題のタイプを指定するタグタイプ。task::classification とすることができます。
コンストラクター
train_input(const table &data = table{}, const table &labels = table{})指定されたデータとラベルのプロパティー値を使用して、クラスの新しいインスタンスを作成します。
プロパティー
const table &data= table{}
訓練セット X。
ゲッターとセッター
const
table
&
train_input & set_data(const table &)8.7 アルゴリズム

get_data()

const

326

oneAPI 仕様 リリース 1.0 リビジョン 3
const table &labels= table{}
訓練セット X のラベル y のベクトル。
ゲッターとセッター
const
table
&
train_input & set_labels(const table &)get_labels()

const

結果
template <typename Task = task::by_default>
class train_result {public:train_result();
const model<Task>& get_model() const;};

template<typename Task= task::by_default>
class train_result
テンプレート・パラメーター
Task – 解決する問題のタイプを指定するタグタイプ。task::classification とすることができます。
コンストラクター
train_result()
デフォルトのプロパティー値を使用してクラスの新しいインスタンスを作成します。
プロパティー
const model<Task> &model= model<Task>{}
訓練された k-NN モデル。
ゲッターとセッター
const model< Task > & get_model() const
操作
template<typename Float, typename Method, typename Task>
train_result<Task>
train(const
descriptor<Float,
Method,Task>&desc,
train_input<Task> &input)
k-NN 分類器の訓練操作を実行します。詳細については、oneapi::dal::train をご覧ください。

const

テンプレート・パラメーター• Float – アルゴリズムが中間計算に使用する浮動小数点の型。float または double にすることができます。
• Method – ア ル ゴ リ ズ ム の 実 装 を 指 定 す る タ グ タ イ プ 。 method::bruteforce ま た は
method::kd_tree とすることができます。
• Task – 解決する問題のタイプを指定するタグタイプ。task::classification とすることができます。
パラメーター• desc – アルゴリズムの記述子。
• input – トレーニング操作の入力データ。
8.7 アルゴリズム

327

oneAPI 仕様 リリース 1.0 リビジョン 3
前提条件
input.data.has_data==
true
input.labels.has_data==
true
input.data.row_count == input.labels.row_count input.labels.column_count == 1
input.labels[i]>=0input.labels[i] < desc.class_count
推論 infer...
入力
template <typename Task = task::by_default>
class infer_input {public:infer_input(const model<Task>& m = model<Task>{},const table& data = table{});const model<Task>& get_model() const;
infer_input& set_model(const model&);const table& get_data() const;
infer_input& set_data(const table&);};template<typename Task= task::by_default>
class infer_input
テンプレート・パラメーター
Task – 解決する問題のタイプを指定するタグタイプ。task::classification とすることができます。
コンストラクター
infer_input(const model<Task> &m = model<Task>{}, const table &data = table{})指定されたモデルとデータ・プロパティー値を使用して、クラスの新しいインスタンスを作成します。
プロパティー
const model<Task> &model= model<Task>{}
訓練された k-NN モデル。
ゲッターとセッター
const
model<
Task>
infer_input & set_model(const model &)&get_model()const

const table &data= table{}
推論 X ′のデータセット。
ゲッターとセッター
const
table
&
infer_input & set_data(const table &)8.7 アルゴリズム

get_data()

const

328

oneAPI 仕様 リリース 1.0 リビジョン 3
結果
template <typename Task = task::by_default>
class infer_result {public:infer_result();
const table& get_labels() const;};

template<typename Task= task::by_default>
class infer_result
テンプレート・パラメーター
Task – 解決する問題のタイプを指定するタグタイプ。task::classification とすることができます。
コンストラクター
infer_result()
デフォルトのプロパティー値を使用してクラスの新しいインスタンスを作成します。
プロパティー
const table &labels= table{}
予測されたラベル。
ゲッターとセッター
const table & get_labels() const
操作
template<typename Float, typename Method, typename Task>
infer_result<Task>
infer(const
descriptor<Float,
Method,Task>&desc,
infer_input<Task> &input)
k-NN 分類器の推論操作を実行します。詳細については、oneapi::dal::infer をご覧ください。

const

テンプレート・パラメーター• Float – アルゴリズムが中間計算に使用する浮動小数点の型。float または double にすることができます。
• Method – ア ル ゴ リ ズ ム の 実 装 を 指 定 す る タ グ タ イ プ 。 method::bruteforce ま た は
method::kd_tree とすることができます。
• Task – 解決する問題のタイプを指定するタグタイプ。task::classification とすることができます。
パラメーター• desc – アルゴリズムの記述子。
• input – 推論操作の入力データ。
前提条件
input.data.has_data == true

8.7 アルゴリズム

329

oneAPI 仕様 リリース 1.0 リビジョン 3
事後条件
result.labels.row_count==
input.data.row_countresult.labels.column_count==1
result.labels[i] >= 0 result.labels[i] < desc.class_count

8.7.3 分解
主成分分析 (PCA)
主成分解析 (PCA) は、探索的データ解析と次元リダクション向けのアルゴリズムです。PCA は、1 セットの相関の可能性がある特徴の特徴ベクトル値を、主成分と呼ばれる相関しない特徴の新しいセットに変換します。主成分とは、分散が最大になる方向、つまりデータが最も分散する方向のことです。
操作

計算メソッド

訓練

共分散

SVD

プログラミング・インターフェイス
train(...) train_input train_result

推論

共分散

SVD

infer(...) infer_input infer_result

数学的な定式訓練
p 次元の特徴ベクトルの訓練セット X = {x1, ..., xn} と主成分の数 r が与えられた場合、問題は訓練の r 個の主方向 (p 次元固有のベクトル [Lang87]) を計算します。
固有ベクトルは、各行に 1 つの固有ベクトルを含む r × p 行列 T にグループ化できます。
訓練方法: 共分散
このメソッドでは、共分散行列の固有値分解によりデータセットの主成分を計算します。このメソッドは次の手順に従います。
1. 共分散行列の計算
2. 固有ベクトルと固有値の計算
3. 結果を保存する行列の形成
共分散行列の計算は、次の方法で実行する必要があります。
1. 合計ベクトル列を計算
2.

外積を計算

3.

共分散行列を計算

固有値 λ と固有ベクトル vi を計算するため、実装は [Ping14] など任意の方法を選択できます。
最後のステップは、ペアのセット (λi , vi) を λ の降順でソートし、結果行列 T = ( vi,1, ··· , vi,r ), 1 ≤ i ≤ pを形成します。さらに、初期データセットの平均と分散が返されます。

8.7 アルゴリズム

330

oneAPI 仕様 リリース 1.0 リビジョン 3
訓練方法: SVD
このメソッドは、データセットの特異値分解により主成分を計算します。このメソッドは次の手順に従います。
1. 特異値と特異ベクトルの計算
2. 結果を保存する行列の形成
特異値 λ と特異ベクトル υi と vi を計算するため、実装は [Demmel90] など任意の方法を選択できます。
最後のステップは、ペアのセット (λi , vi) を λ の降順でソートし、結果行列 T = ( vi,1, ··· , vi,r ), 1 ≤ i ≤ pを形成します。さらに、初期データセットの平均と分散が返されます。
サインフリップ法
一部の固有値ソルバーによって計算された固有ベクトルは、符号が曖昧であるため一意に定義されていません。決定論的な結果を得るには、サインフリップ法を適用する必要があります。[Bro07] で提案されるサインフリップ法の 1 つでは、
行列 T を次のように変更する必要があります。

ここで、 Ti は i 目の行、T ij は i 目の行、j 目の列の要素で、sgn(·) は符号関数です。

注: 上記のサインフリップ法は一例であり、oneDAL 仕様ではこのサインフリップ法の実装は必要ありません。実装する場合、固有ベクトルの符号を変更する任意の手法を選択できます。
推論
p 元特徴ベクトルの推論セット X′ = {x′1, ... , X′m} と、訓練段階で生成された r × p 行列が与えられると、問題は X′をセット X′′= {x′1′, ..., x′m′ } に変換します。ここで、 x′j′ は r-次元の特徴ベクトル 1 ≤ j ≤ m です。
特徴ベクトル x′j′は、行列によって定義された線形変換 [Lang87] を特徴ベクトル x′j
れます、に適用することで計算さ推論法: 共分散と SVD
共分散および SVD 推論法は、(8.3) に従って 𝑥𝑗" を計算します。

8.7 アルゴリズム

331

oneAPI 仕様 リリース 1.0 リビジョン 3
使用例
pca::model<> run_training(const table& data) {const auto pca_desc = pca::descriptor<float>{}.set_component_count(5).set_deterministic(true);
const auto result = train(pca_desc, data);
print_table("means", result.get_means()); print_table("variances",
result.get_variances()); print_table("eigenvalues",
result.get_eigenvalues()); print_table("eigenvectors",
result.get_eigenvectors());}

return result.get_model();推論
table run_inference(const pca::model<>& model,
const table& new_data) {const auto pca_desc = pca::descriptor<float>{}.set_component_count(model.get_component_count());
const auto result = infer(pca_desc, model, new_data);
print_table("labels", result.get_transformed_data());}

プログラミング・インターフェイス
この節のすべての型と関数は、oneapi::dal::pcanamespace で宣言され、oneapi/dal/algo/pca.hpp ヘッダーファイルをインクルードして使用できます。
記述子
template <typename Float = float,
typename Method = method::by_default,
typename Task = task::by_default>
class descriptor {public:explicit descriptor(std::int64_t component_count = 0);
int64_t get_component_count() const; descriptor&
set_component_count(int64_t);bool get_deterministic() const; descriptor&
set_deterministic(bool);};

8.7 アルゴリズム

332

oneAPI 仕様 リリース 1.0 リビジョン 3
template<typename Float= float, typename Method= method::by_default, typename Task=
task::by_default>
class descriptor
テンプレート・パラメーター• Float – アルゴリズムが中間計算に使用する浮動小数点の型。float または double にすることができます。
• Method – アルゴリズムの実装を指定するタグタイプ。method::cov または method::svd とすることができます。
• Task – 解決する問題のタイプを指定するタグタイプ。task::dim_reduction とすることができます。
コンストラクター
descriptor(std::int64_t component_count = 0)
指定された component_count プロパティー値を使用して、クラスの新しいインスタンスを作成します。
プロパティー
int64_t component_count= 0
主成分の数 r。ゼロの場合、アルゴリズムはすべての特徴固有のベクトルを計算します (ｒ = p)。
ゲッターとセッター
int64_tget_component_count()
descriptor & set_component_count(int64_t)

const

不変
component_count >= 0bool deterministic= true
アルゴリズムがサインフリップ手法を適用するかどうか指定します。true である場合、固有ベクトルの方向は決定論的である必要があります。
ゲッターとセッターbool
get_deterministic()
descriptor & set_deterministic(bool)

const

メソッドタグ
namespace method {struct cov {};struct svd {};using by_default = cov;
} // 名前空間メソッド

struct cov
共分散計算法を表すタグタイプ。
struct svd
SVD 計算法を表すタグタイプ。

8.7 アルゴリズム

333

oneAPI 仕様 リリース 1.0 リビジョン 3
using by_default= cov
共分散 計算法のエイリアス・タグ・タイプ。
タスクタグ
namespace task {struct dim_reduction {};using by_default = dim_reduction;} // 名前空間タスク

struct dim_reduction
次元リダクション問題の解決に使用されるエンティティーをパラメーター化するタグタイプ。
using by_default= dim_reduction
次元リダクションのエイリアス・タグ・タイプ。
モデル
template <typename Task = task::by_default>
class model {public:model();
const table& get_eigenvectors() const;
int64_t get_component_count() const;};

template<typename Task= task::by_default>
class model
テンプレート・パラメーター
Task – 解決する問題のタイプを指定するタグタイプ。task::dim_reduction とすることができます。
コンストラクター
model()
デフォルトのプロパティー値を使用してクラスの新しいインスタンスを作成します。
プロパティー
const table &eigenvectors= table{}
固有ベクトルを含む r × p テーブル。行には 1 つの固有ベクトルが含まれます。
ゲッターとセッター
const table & get_eigenvectors() const
int64_t component_count= 0
訓練されたモデルのコンポーネントの数 r。
ゲッターとセッター
int64_t get_component_count() const

8.7 アルゴリズム

334

oneAPI 仕様 リリース 1.0 リビジョン 3
不変
component_count == eigenvectors.row_count
訓練 train...
入力
template <typename Task = task::by_default>
class train_input {public:train_input(const table& data = table{});const table& get_data() const;
train_input& set_data(const table&);};template<typename Task= task::by_default>
class train_input
テンプレート・パラメーター
Task – 解決する問題のタイプを指定するタグタイプ。task::dim_reduction とすることができます。
コンストラクター
train_input(const table &data = table{})指定された data プロパティー値を使用して、クラスの新しいインスタンスを作成します。
プロパティー
const table &data= table{}
訓練データを含む n × p テーブル。各行には 1 つの特徴ベクトルが格納されます。
ゲッターとセッター
const
table
train_input & set_data(const table &)&get_data()

const

結果
template <typename Task = task::by_default>
class train_result {public:train_result();
const model<Task>& get_model() const;
const table& get_means() const;
const table& get_variances() const;
const table& get_eigenvalues() const;
const table& get_eigenvectors() const;};

8.7 アルゴリズム

335

oneAPI 仕様 リリース 1.0 リビジョン 3
template<typename Task= task::by_default>
class train_result
テンプレート・パラメーター
Task – 解決する問題のタイプを指定するタグタイプ。task::dim_reduction とすることができます。
コンストラクター
train_result()
デフォルトのプロパティー値を使用してクラスの新しいインスタンスを作成します。
プロパティー
const model<Task> &model= model<Task>{}
訓練された PCA モデル。
ゲッターとセッター
const model< Task > & get_model() const
const table &means= table{}
最初の ｒ 個の特徴の平均値を含む 1 × r テーブル。
ゲッターとセッター
const table & get_means() const
const table &variances= table{}
最初の ｒ 個の特徴の分散を含む 1 × r テーブル。
ゲッターとセッター
const table & get_variances() const
const table &eigenvalues= table{}
最初の ｒ 個の特徴の固有値を含む 1 × r テーブル。
ゲッターとセッター
const table & get_eigenvalues() const
const table &eigenvectors= table{}
固有ベクトルを含む r × p テーブル。行には 1 つの固有ベクトルが含まれます。
ゲッターとセッター
const table & get_eigenvectors() const
不変eigenvectors == model.eigenvectors
操作
template<typename Float, typename Method, typename Task>
train_result<Task>
train(const
descriptor<Float,
Method,Task>
train_input<Task> &input)
PCA の訓練操作を実行します。詳細については、oneapi::dal::train をご覧ください。

8.7 アルゴリズム&desc,

const

336

oneAPI 仕様 リリース 1.0 リビジョン 3
テンプレート・パラメーター• Float – アルゴリズムが中間計算に使用する浮動小数点の型。float または double にすることができます。
• Method – アルゴリズムの実装を指定するタグタイプ。method::cov または method::svd とすることができます。
• Task – 解決する問題のタイプを指定するタグタイプ。task::dim_reduction とすることができます。
パラメーター• desc – アルゴリズムの記述子。
• input – 訓練操作の入力データ。
前提条件
input.data.has_data == true
input.data.column_count >= desc.component_count
事後条件
result.means.row_count == 1
result.means.column_count == desc.component_count result.variances.row_count == 1
result.variances.column_count == desc.component_count result.variances[i] >= 0.0
result.eigenvalues.row_count==1
result.eigenvalues.column_count==desc.component_countresult.model.eigenvectors.row_count==1
result.model.eigenvectors.column_count == desc.component_count
推論 infer...
入力
template <typename Task = task::by_default>
class infer_input {public:infer_input(const model<Task>& m = model<Task>{}, const table& data = table{});const model<Task>& get_model() const; infer_input& set_model(const model&);const table& get_data() const; infer_input& set_data(const table&);};template<typename Task= task::by_default>
class infer_input
テンプレート・パラメーター
Task – 解決する問題のタイプを指定するタグタイプ。task::dim_reduction とすることができます。
コンストラクター
infer_input(const model<Task> &m = model<Task>{}, const table &data = table{})指定されたモデルとデータ・プロパティー値を使用して、クラスの新しいインスタンスを作成します。

8.7 アルゴリズム

337

oneAPI 仕様 リリース 1.0 リビジョン 3
プロパティー
const model<Task> &model= model<Task>{}
訓練された PCA モデル。
ゲッターとセッター
const model< Task > & get_model() const
infer_input & set_model(const model &)const table &data= table{}
推論 X’ のデータセット。
ゲッターとセッター
const
table
&
infer_input & set_data(const table &)get_data()

const

結果
template <typename Task = task::by_default>
class infer_result {public:infer_result();
const table& get_transformed_data() const;};

template<typename Task= task::by_default>
class infer_result
テンプレート・パラメーター
Task – 解決する問題のタイプを指定するタグタイプ。task::dim_reduction とすることができます。
コンストラクター
infer_result()
デフォルトのプロパティー値を使用してクラスの新しいインスタンスを作成します。
プロパティー
const table &transformed_data= table{}r 個の主成分の予測データを含む n x r テーブル。
ゲッターとセッター
const table & get_transformed_data() const
操作
template<typename Float, typename Method, typename Task>
infer_result<Task>
infer(const
descriptor<Float,
Method,Task>infer_input<Task> &input)
PCA の推論操作を実行します。詳細については、oneapi::dal::infer をご覧ください。

&desc,

const

テンプレート・パラメーター• Float – アルゴリズムが中間計算に使用する浮動小数点の型。float または double にすることができます。

8.7 アルゴリズム

338

oneAPI 仕様 リリース 1.0 リビジョン 3• Method – アルゴリズムの実装を指定するタグタイプ。method::cov または method::svd とすることができます。
• Task – 解決する問題のタイプを指定するタグタイプ。task::dim_reduction とすることができます。
パラメーター• desc – アルゴリズムの記述子。
• input – 推論操作の入力データ。
前提条件
input.data.has_data==
true
input.model.eigenvectors.row_count==desc.component_count
input.model.eigenvectors.column_count == input.data.column_count
事後条件
result.transformed_data.row_count==
input.data.row_countresult.transformed_data.column_count == desc.component_count

8.8

付録

8.8.1 k-d ツリー
k-d ツリーは空間分割二分木 [Bentley80] であり、次の特性を備えています。
• それぞれの非リーフノードは特徴空間を 2 つの部分に分割する超平面を誘導します。分割超平面を明示的に定義するため、非リーフノードは特徴の識別子 (特徴空間の軸を定義) と、カットポイントを格納します。
• ツリーの各リーフノードには、訓練データセット要素のサブセット (バケット) が関連付けられています。バケットから特徴ベクトルは、ルートノードからそれぞれのリーフへのパス上のツリーノードによって定義された空間の領域に属します。
関連する用語
カットポイント: k-d ツリーの非リーフノードに対応し、指定された特徴によって指定された軸に直交する分割超平面を定義する特徴値。

8.9

文献目録

oneAPI データ・アナリティクス・ライブラリーで実装されるアルゴリズムの詳細は、次の文献を参照してください。

8.8 付録339