構成と設定するメンバー関数#

ここでは、oneapi::mkl::dft 名前空間に属し、oneapi/mkl/dft.hpp (インクルードするファイル) で宣言されている descriptor クラス・テンプレートの設定メンバー関数 set_value について説明します。

namespace oneapi::mkl::dft { 
  template <precision prec, domain dom> 
  class descriptor { 
    using real_scalar_t = std::conditional_t<prec == precision::DOUBLE, double, float>; 
  public:     // 整数値パラメーターの場合: 
    void set_value(config_param param, std::int64_t value); 
    template <typename T, std::enable_if_t<std::is_integral_v<T>, bool> = true> 
    void set_value(config_param param, T value) { 
        set_value(param, static_cast<std::int64_t>(value)); 
    } 
    // 実数値パラメーターの場合: 
    void set_value(config_param param, real_scalar_t value); 
    template <typename T, std::enable_if_t<std::is_floating_point_v<T>, bool> = true> 
    void set_value(config_param param, T value) { 
        set_value(param, static_cast<real_scalar_t>(value)); 
    } 
    // ベクトル値パラメーターの場合: 
    void set_value(config_param param, const std::vector<std::int64_t>& value); 
    // その他のパラメーター: 
    void set_value(config_param param, config_value value); 
    // 非推奨の使用法。将来のリリースで削除される予定です:     [[deprecated("Use set_value(config_param, config_value) instead.")]] 
    void set_value(config_param param, DFTI_CONFIG_VALUE value); 
    [[deprecated("Use set_value(config_param, const std::vector<std::int64_t>&) instead.")]] 
    void set_value(config_param param, const std::int64_t* value); 
    [[deprecated("This set_value member function is deprecated.")]] 
    void set_value(config_param param, ...); 
  } 
}

簡潔にするため、先頭に付加された名前空間指定子 oneapi::mkl::dft は以下では省略されています。

set_value 関数を使用すると、oneMKL ユーザーは descriptor オブジェクトの書き込み可能な構成パラメーターに構成値を割り当てできます。このページでは、config_param::FWD_STRIDES と config_param::BWD_STRIDES パラメーターを除く、このパラメーターに関連付けられたデフォルトの構成値についても説明します (詳細は、データレイアウトの構成ページを参照してください)。

すべての set_value 関数は、2 つの引数を必要とします。1 つ目は設定する呼び出し元オブジェクトの構成パラメーター (config_param 列挙子で)、2 つ目はそのパラメータに割り当てる値です。後者のタイプは設定されるパラメーターによって異なり、許容される値が制限される場合があります。以下の表で「受け入れ」とラベル付けされた構成パラメーターと値のペアは、descriptor オブジェクトによって無条件にサポートされることが保証されるわけではありません。descriptor オブジェクトの構成値は正常に正しく設定されていても、その後オブジェクトをコミットしようとしたときに無効となっている場合があります。descriptor オブジェクトの構成の有効性を評価するには、すべての構成値 (オブジェクトがコミットされたときに「フリーズ」されていると見なす) に関する知識 (および解析) が必要です。

コミットされた descriptor オブジェクトの構成変更する set_value の呼び出しは、そのオブジェクトのコミットを解除します。このような変更は通常、最後にコミットされたときに実行されたオブジェクトの計算準備手順を無効にします。結果として、このような操作を行うと、構成パラメーター config_param::COMMIT_STATUS に関連付けられたオブジェクトの (読み取り専用) 構成値が config_value::COMMITTED から config_value::UNCOMMITTED に変更されます。

整数値の構成パラメーターの設定#

次のメンバー関数

template <precision prec, domain dom> 
void descriptor<prec, dom>::set_value(config_param param, std::int64_t value); 
template <precision prec, domain dom> 
template <typename T, std::enable_if_t<std::is_integral_v<T>, bool> = true> 
void descriptor<prec, dom>::set_value(config_param param, T value) { 
    set_value(param, static_cast<std::int64_t>(value)); 
}

ユーザーが以下の表の任意の param の値を設定できるようにします。

整数値の構成パラメーターの許容値とデフォルト値#
受け入れられる構成パラメーター	受け入れられる値 :	デフォルト値。
`config_param::FWD_DISTANCE`	すべての整数	`0`
`config_param::BWD_DISTANCE`	すべての整数	`0`
`config_param::NUMBER_OF_TRANSFORMS`	正の整数	`1`
`config_param::THREAD_LIMIT`	非負の整数	`0`

これらのメンバー関数は、ユーザー指定の整数値の精度を損なうことなく double 値として表現できる限り、config_param::FORWARD_SCALE または config_param::BACKWARD_SCALE のいずれかの (実数値) パラメーターを設定するのに使用できます (そうでない場合は、oneapi::mkl::invalid_argument 例外がスローされます)。

非推奨#

構成パラメーター config_param::CONJUGATE_EVEN_STORAGE、config_param::PACKED_FORMAT、config_param::COMPLEX_STORAGE、config_param::PLACEMENT および config_param::DESTROY_INPUT も上記の関数を使用して設定できます。受け入れ可能な値とデフォルト値は、(スコープなしの) 列挙タイプ DFTI_CONFIG_VALUE の列挙子に明示的に割り当てられた整数値に対応します。これらの値は、パラメーターについて以下で説明する config_value 列挙子に明示的に割り当てられます。oneMKL の DPC++ インターフェイスを介した DFTI_CONFIG_VALUE 列挙子のサポートが廃止されたため、使用できなくなりました。上記のメンバー関数でこのようなパラメーターを設定すると、実行時に非推奨の警告が発行されます。

注

std::int64_t 以外の整数タイプを使用することもできますが、oneMKL によって行われる入力検証は、ユーザーが指定した値を std::int64_t にキャストした後に実行されるため、値は std::int64_t 値で表現可能な範囲内になければなりません。
精度を損なうことなく double として表現できるが float としては表現できない整数スケーリング係数を単精度記述子に設定することは推奨されません。切り捨てられた、おそらく不正確な結果が生成される可能性があるためです。

実数値の構成パラメーターの設定#

次のメンバー関数

template <precision prec, domain dom> 
void descriptor<prec, dom>::set_value(config_param param, real_scalar_t value); 
template <precision prec, domain dom> 
template <typename T, std::enable_if_t<std::is_floating_point_v<T>, bool> = true> 
void set_value(config_param param, T value) { 
    set_value(param, static_cast<real_scalar_t>(value)); 
}

ユーザーが以下の表の任意の param の値を設定できるようにします。

実数の構成パラメーターの許容値とデフォルト値#
受け入れられる構成パラメーター	受け入れられる値 :	デフォルト値。
`config_param::FORWARD_SCALE`	すべての浮動小数点値	`1.0`
`config_param::BACKWARD_SCALE`	すべての浮動小数点値	`1.0`

注

精度を損なうことなく float (または double) として表現できない浮動小数点値を単精度 (または倍精度) 記述子に設定することは推奨されません。切り捨てられた、おそらく不正確な結果が生成される可能性があるためです。

ベクトル値の構成パラメーターの設定#

次のメンバー関数

template <precision prec, domain dom> 
void descriptor<prec, dom>::set_value(config_param param, const std::vector<std::int64_t>& value);

ユーザーは、以下の表にある任意の param 構成値を設定できます。

ベクトル値の構成パラメーターと許容値およびデフォルト値 (概要の表記法を使用)#
受け入れられる構成パラメーター	受け入れられる値 :	デフォルト値。
`config_param::INPUT_STRIDES`	サイズ \(\left(d + 1\right)\) の `std::vector<std::int64_t>` オブジェクト	`std::vector<std::int64_t>(d+1, 0)` (非推奨のためデフォルトでは無視されます)
`config_param::OUTPUT_STRIDES`	サイズ \(\left(d + 1\right)\) の `std::vector<std::int64_t>` オブジェクト	`std::vector<std::int64_t>(d+1, 0)` (非推奨のためデフォルトでは無視されます)
`config_param::FWD_STRIDES`	サイズ \(\left(d + 1\right)\) の `std::vector<std::int64_t>` オブジェクト	データレイアウトの設定ページに記載されています
`config_param::BWD_STRIDES`	サイズ \(\left(d + 1\right)\) の `std::vector<std::int64_t>` オブジェクト	データレイアウトの設定ページに記載されています

上記の整数値の構成パラメーターも、一意の (受け入れられる) 整数値を含む std::vector<std::int64_t> 引数が使用されている限り、このメンバー関数を使用して構成できます。

非推奨#

config_param::INPUT_STRIDES および config_param::OUTPUT_STRIDES は非推奨です。詳細はデータレイアウトの設定ページに記載されています

他の構成パラメーターの設定#

次のメンバー関数

template <precision prec, domain dom> 
void descriptor<prec, dom>::set_value(config_param param, config_value value);

ユーザーは、以下の表にある任意の param 構成値を設定できます。

`config_value` 内の構成値に関連付けられた構成パラメーターと許容値およびデフォルト値#
受け入れられる構成パラメーター	受け入れられる値	デフォルト値。
`config_param::CONJUGATE_EVEN_STORAGE` (廃止予定の非推奨です ;デフォルト値以外のサポートは廃止されます)	`config_value::COMPLEX_COMPLEX` または `config_value::COMPLEX_REAL` (非推奨)	`config_value::COMPLEX_COMPLEX`
`config_param::PACKED_FORMAT` (廃止予定の非推奨です ;デフォルト値以外のサポートは廃止されます)	`config_value::CCE_FORMAT`、`config_value::PERM_FORMAT` (非推奨)、`config_value::PACK_FORMAT` (非推奨) または `config_value::CCS_FORMAT` (非推奨)	`config_value::CCE_FORMAT`
`config_param::COMPLEX_STORAGE`	`config_value::COMPLEX_COMPLEX` または `config_value::REAL_REAL`	`config_value::COMPLEX_COMPLEX`
`config_param::PLACEMENT`	`config_value::INPLACE` または `config_value::NOT_INPLACE`	`config_value::INPLACE`
`config_param::WORKSPACE` (または `config_param::WORKSPACE_PLACEMENT` と同等)	`config_value::WORKSPACE_AUTOMATIC` (`config_value::WORKSPACE_INTERNAL` と同等)) または `config_value::WORKSPACE_EXTERNAL`	`config_value::WORKSPACE_AUTOMATIC`
`config_param::DESTROY_INPUT`	`config_value::AVOID` または `config_value::ALLOW`	`config_value::AVOID`

非推奨のサポート#

非推奨のメンバー関数

template <precision prec, domain dom> 
void descriptor<prec, dom>::set_value(config_param param, DFTI_CONFIG_VALUE value);

config_param::WORKSPACE パラメーター (config_param::WORKSPACE_PLACEMENT に相当) を除き、上記で説明した config_value タイプの value を使用するメンバー関数と同様のサポートを提供します。前者へのすべての呼び出しは、value を対応する config_value 列挙子に変換した後、内部的に後者にリダイレクトされます。前者の関数を使用すると、コンパイル時に非推奨の警告が発生します。

非推奨のメンバー関数

template <precision prec, domain dom> 
void descriptor<prec, dom>::set_value(config_param param, std::int64_t* value);

config_param::INPUT_STRIDES、config_param::OUTPUT_STRIDES、config_param::FWD_STRIDES および config_param::BWD_STRIDES (のみ) パラメーターに対して、上記で説明した std::vector<std::int64_t> タイプの value を使用するメンバー関数と同じサポートを提供します。前者への呼び出しはすべて、std::vector(value, value + d + 1) オブジェクト (導入で定義した \(d\) を構築した後、内部的に後者にリダイレクトされます。前者の関数を使用すると、コンパイル時に非推奨の警告が発生します。

非推奨の可変長引数メンバー関数

template <precision prec, domain dom> 
void descriptor<prec, dom>::set_value(config_param param, ...);

すべての構成パラメーターをサポートします。設定されるパラメーターに関係なく、この関数は 2 つの引数を必要とし、可変長引数リストから一意の引数を読み取る際に、以下の表に記載されているパラメーター依存のタイプを想定します (該当する場合は、可変長引数のデフォルトの引数プロモーションの後)。このルーチンのすべての呼び出しは、想定される値のタイプ (上記に記載されているもの、非推奨かどうかに関係なく) と一致する適切な構成の設定メンバー関数に内部的にリダイレクトされます。この可変長メンバー関数を使用すると、コンパイル時および実行時に非推奨の警告が発行されます。

可変長引数の構成と照会するメンバー関数が 2 番目の引数 (つまり、可変長引数リストの最初の引数) を読み取るときに想定するタイプ (導入の表記法を使用)#
受け入れられる構成パラメーター	想定される値のタイプ
`config_param::FORWARD_SCALE` と `config_param::BACKWARD_SCALE`	`double`
`config_param::CONJUGATE_EVEN_STORAGE`、`config_param::PACKED_FORMAT`、`config_param::COMPLEX_STORAGE`、`config_param::PLACEMENT` および `config_param::DESTROY_INPUT`	`DFTI_CONFIG_VALUE`
`config_param::WORKSPACE_PLACEMENT` と `config_param::WORKSPACE`	`config_value`
`config_param::NUMBER_OF_TRANSFORMS`、`config_param::FWD_DISTANCE`、`config_param::BWD_DISTANCE` および `config_param::THREAD_LIMIT`	`std::int64_t`
`config_param::INPUT_STRIDES`、`config_param::OUTPUT_STRIDES`、`config_param::FWD_STRIDES` および `config_param::BWD_STRIDES`	`std::int64_t*` ( \(\left(d + 1\right)\) 個の連続する `std::int64_t` 値の最初のアドレス)

警告

可変長構成を設定するメンバー関数の使い方がドキュメントと異なる場合、動作は未定義になります。

例外#

設定と設定するメンバー関数は、以下をスローします

呼び出し元のオブジェクトに問題が見つかった場合は std::runtime_error 例外が発生します;
次の場合、oneapi::mkl::invalid_argument 例外が発生します
- 設定されているパラメーターは書き込みできません;
- 照会されているパラメーターが拒否された (例: 使用されている構成値のタイプと一致しない場合);
- 設定されている特定の構成パラメーターに対して、設定されている構成値が拒否されました。

構成を設定するメンバー関数

目次

構成と設定するメンバー関数#

整数値の構成パラメーターの設定#

非推奨#

実数値の構成パラメーターの設定#

ベクトル値の構成パラメーターの設定#

非推奨#

他の構成パラメーターの設定#

非推奨のサポート#

例外#