計算関数

計算関数#

このページでは、関数テンプレートoneapi::mkl::dft::compute_forward と oneapi::mkl::dft::compute_backward について説明します。これらはすべて、コミットされた oneapi::mkl::dft::descriptor オブジェクト desc によって定義された DFT の計算に関係します。これらの関数テンプレートは oneapi::mkl::dft 名前空間に属し、oneapi/mkl/dft.hpp (インクルードするファイル) で宣言されています。簡潔にするため、先頭に付加された名前空間指定子 oneapi::mkl::dft は以下では省略されています。

namespace oneapi::mkl::dft { 
  /*----------------------- for in-place transforms -----------------------*/ 
  // using SYCL buffers 
  template<typename descriptor_type, typename data_type> 
  void compute_forward(descriptor_type &desc, 
                       sycl::buffer<data_type, 1> &inout); 
  template<typename descriptor_type, typename data_type> 
  void compute_backward(descriptor_type &desc, 
                        sycl::buffer<data_type, 1> &inout); 
  // using device-accessible USM allocations 
  template <typename descriptor_type, typename data_type> 
  sycl::event compute_forward(descriptor_type &desc, 
                              data_type *inout, 
                              const std::vector<sycl::event> &dependencies = {}); 
  template <typename descriptor_type, typename data_type> 
  sycl::event compute_backward(descriptor_type &desc, 
                               data_type *inout, 
                               const std::vector<sycl::event> &dependencies = {}); 
  /*--------------------- for out-of-place transforms ---------------------*/ 
  // using SYCL buffers 
  template<typename descriptor_type, typename input_type, typename output_type> 
  void compute_forward(descriptor_type &desc, 
                       sycl::buffer<input_type, 1> &in, 
                       sycl::buffer<output_type, 1> &out); 
  template<typename descriptor_type, typename input_type, typename output_type> 
  void compute_backward(descriptor_type &desc, 
                        sycl::buffer<input_type, 1> &in, 
                        sycl::buffer<output_type, 1> &out); 
  // using device-accessible USM allocations 
  template<typename descriptor_type, typename input_type, typename output_type> 
  sycl::event compute_forward(descriptor_type &desc, 
                              input_type *in, 
                              output_type *out, 
                              const std::vector<sycl::event> &dependencies = {}); 
  template<typename descriptor_type, typename input_type, typename output_type> 
  sycl::event compute_backward(descriptor_type &desc, 
                               input_type *in, 
                               output_type *out, 
                               const std::vector<sycl::event> &dependencies = {}); 
}

説明

compute_forward (または compute_backward 関数テンプレートは、コミットされた descriptor オブジェクト desc とそれに続く 1 つ以上のデータを含む引数を受け入れ、desc が定義する順方向 (または 逆方向) DFT、つまり \(\delta = -1\) (または. \(\delta = +1\)) で定義される変換の計算をキューに入れます。計算は、desc がコミットされたキューに登録されます。

正しい結果を保証するには、同じ descriptor オブジェクトを使用した連続した計算をシリアル化する必要があります。これは、コミット時に渡されたキューを待機するか、順序付きキューを使用することによって実行できます。あるいは、任意の引数に対して同じバッファーを繰り返し使用しても計算がシリアル化されます (sycl::bufffer オブジェクトを使用する場合)。また、返されたイベントと入力依存関係を使用して計算をシリアル化することもできます (デバイスでアクセス可能な USM 割り当てを使用する場合)。ほとんどの場合、これらの代替方法の方がパフォーマンスが高くなります。可能であれば、バッチ変換用の descriptor オブジェクトを構成すると、ほとんどの場合、このような連続計算よりも優れたパフォーマンスが得られます。

提供されるデータを含む引数の数は、目的の DFT 計算がインプレース (出力データが入力データを上書き) で実行されるか、アウトオブプレース (出力データが入力データとは別に格納される) で実行されるかによってのみ異なります。インプレース操作にはデータを含む引数が 1 つ必要ですが、アウトオブプレース計算にはそのような引数が 2 つ必要です。インプレース操作では、データレイアウトが、構成専用のページに記載されている特定の要件を満たす必要があります。

警告

  • インプレース (またはアウトオブプレース) 操作用に設計された関数を使用する場合、desc (関数の最初の引数) には、config_param::PLACEMENT に関連付けられた config_value::INPLACE (または config_value::NOT_INPLACE) の構成値が必要です。それ以外の場合、関数の動作は未定義です。

  • アウトオブプレース操作用に設計された関数を使用する場合、 in と out は共通要素を共有してはなりません。

テンプレート・パラメーター#

インプレース操作の場合#

インプレース操作の compute_forward および compute_backward 関数テンプレートは、次の順序で 2 つのタイプ・テンプレート・パラメーターでパラメーター化されます。

  • 記述子クラス・テンプレートの特殊化のインスタンスである desc のタイプを表す descriptor_type;

  • 使用されているデータを含む引数の基本データタイプを表す data_type。

利用可能な特殊化は以下の表に記載されています。

インプレース操作用の計算関数テンプレートで利用可能な特殊化#

関数テンプレート

descriptor_type

data_type
compute_forward
compute_backward

descriptor<precision::SINGLE, domain::REAL>

float
compute_forward
compute_backward

descriptor<precision::SINGLE, domain::REAL>

std::complex<float>
compute_forward
compute_backward

descriptor<precision::SINGLE, domain::COMPLEX>

float
compute_forward
compute_backward

descriptor<precision::SINGLE, domain::COMPLEX>

std::complex<float>
compute_forward
compute_backward

descriptor<precision::DOUBLE, domain::REAL>

double
compute_forward
compute_backward

descriptor<precision::DOUBLE, domain::REAL>

std::complex<double>
compute_forward
compute_backward

descriptor<precision::DOUBLE, domain::COMPLEX>

double
compute_forward
compute_backward

descriptor<precision::DOUBLE, domain::COMPLEX>

std::complex<double>

アウトオブプレース操作の場合#

アウトオブプレース操作の compute_forward および compute_backward 関数テンプレートは、次の順序で 3 つのタイプ・テンプレート・パラメーターによってパラメーター化されます。

  • 記述子クラス・テンプレートの特殊化のインスタンスである desc のタイプを表す descriptor_type;

  • 使用されている最初の (入力) データを含む引数の基本データタイプを表す input_type。

  • 使用されている 2 番目の (出力) データを含む引数の基本データタイプを表す output_type。

利用可能な特殊化は以下の表に記載されています。

アウトオブプレース操作用の計算関数テンプレートで利用可能な特殊化#

関数テンプレート

descriptor_type

input_type

output_type
compute_forward
compute_backward

descriptor<precision::SINGLE, domain::REAL>

float

float
compute_forward
compute_backward

descriptor<precision::SINGLE, domain::REAL>

std::complex<float>

std::complex<float>
compute_forward
compute_backward

descriptor<precision::SINGLE, domain::COMPLEX>

float

float
compute_forward
compute_backward

descriptor<precision::SINGLE, domain::COMPLEX>

std::complex<float>

std::complex<float>

compute_forward

descriptor<precision::SINGLE, domain::REAL>

float

std::complex<float>

compute_backward

descriptor<precision::SINGLE, domain::REAL>

std::complex<float>

float
compute_forward
compute_backward

descriptor<precision::DOUBLE, domain::REAL>

double

double
compute_forward
compute_backward

descriptor<precision::DOUBLE, domain::REAL>

std::complex<double>

std::complex<double>
compute_forward
compute_backward

descriptor<precision::DOUBLE, domain::COMPLEX>

double

double
compute_forward
compute_backward

descriptor<precision::DOUBLE, domain::COMPLEX>

std::complex<double>

std::complex<double>

compute_forward

descriptor<precision::DOUBLE, domain::REAL>

double

std::complex<double>

compute_backward

descriptor<precision::DOUBLE, domain::REAL>

std::complex<double>

double

入力パラメーターと戻り値#

compute_forward および compute_backward テンプレート関数の入力パラメーターについては以下に記載されています。デバイスアクセス可能な USM 割り当てが使用されている場合、これらの関数は、関数呼び出しによってキューに投入された計算の完了を追跡するのに使用する sycl::event オブジェクトを返します。

インプレース操作の場合#

インプレース計算関数の入力パラメーター#

名前

サポートされるタイプ

説明

desc

descriptor_type

記述子クラステンプレートの特殊化のコミットされたインスタンスであり、計算する DFT を定義します。

inout
i. sycl::buffer<data_type, 1>
ii. data_type*

DFT のデータを含む引数 (入力時に入力データ、出力時に出力結果)

dependencies

std::vector<sycl::event>
キューに入れられた DFT 計算によって尊重される依存関係のベクトル
(デバイスでアクセス可能な USM 割り当て引数を使用している場合のみ)

アウトオブプレース操作の場合#

アウトオブプレース計算関数の入力パラメーター#

名前

サポートされるタイプ

説明

desc

descriptor_type

記述子クラステンプレートの特殊化のコミットされたインスタンスであり、計算する DFT を定義します。

in
i. sycl::buffer<input_type, 1>
ii. input_type*

DFT の入力データに対するデータを含む引数

out
i. sycl::buffer<output_type, 1>
ii. output_type*

DFT の出力データに対するデータを含む引数

dependencies

std::vector<sycl::event>
キューに入れられた DFT 計算によって尊重される依存関係のベクトル
(デバイスでアクセス可能な USM 割り当て引数を使用している場合のみ)

例外#

compute_forward および compute_backward テンプレート関数は、次の場合に std::runtime_error をスローする可能性があります。

  • desc に問題が見つかった場合。

  • desc がコミットされていない場合。

  • desc が外部割り当てワークスペースを使用するように設定されているが、ワークスペースが提供されていない場合。

  • desc が外部割り当てワークスペースを使用するように設定されているが、使用されるデータを含む引数の形式が提供されたワークスペースの形式と異なる場合。

  • DFT の計算中にエラーが検出された場合。

SYCL* バッファーを使用する場合、一部のコードパスではサブバッファーをデータを含む引数としてサポートされず、サブバッファーが使用されると std::invalid_argument 例外がスローされる可能性があります。