PARCEL SYCL v1.2 / API リファレンス 利用者ガイド API リファレンス 検索 ダウンロード English

9 共通メンバ関数

 全ソルバクラスが持つ関数である. 収束判定と収束状態の関数は parcel::krylov::krylov_param から, 前処理の関数は parcel::precon_param から継承する. 前処理の設定 (set_precon_algo() から set_scaling_vector() まで) は, 線形ソルバでは反復の前処理行列 KK を, 固有値ソルバでは set_precon_spectrum(true) のときの AK−1AK^{-1} の KK を決める. 固有値ソルバで set_precon_spectrum(false) (既定) のときは使われない.

 例の cg, bi, gm, ca, pw, ip, ks は, それぞれ parcel::krylov::pcg<>, pbicgstab<>, pgmres<>, pcagmres<>, power<>, inverse_power<>, ks_arnoldi<> のオブジェクトである (parcel::krylov::pcg<> cg; のように作る).

9.1 set_tolerance() / get_tolerance()

概要 収束判定値を設定・取得する.

書式

void   set_tolerance(double tol);
double get_tolerance();

引数

名前 入出力 型 説明 既定値
tol 入力 double 収束判定値 1.0e-8

前提条件 有限の正の値. 0 以下, NaN, Inf は std::invalid_argument.

戻り値 get_tolerance() は設定値.

MPI 局所操作. 全ランクで同じ値を与える.

関連項目 set_max_iteration(), get_residual()

例

cg.set_tolerance(1.0e-9);

9.2 set_max_iteration() / get_max_iteration()

概要 最大反復回数を設定・取得する.

書式

void       set_max_iteration(PARCEL_INT itrmax);
PARCEL_INT get_max_iteration();

引数

名前 入出力 型 説明 既定値
itrmax 入力 PARCEL_INT 最大反復回数. pgmres / pcagmres では内側反復の総数の上限, power / inverse_power では外側反復の上限 10000

前提条件 1 以上. 0 以下は std::invalid_argument. pgmres / pcagmres では mm (pcagmres は s×ts \times t) の倍数でなくてよい. 最後のリスタートだけ列数を端数 (itrmax からそれまでの反復回数を引いた値) にし, 上限ちょうどまで反復する (pgmres の収束判定).

戻り値 get_max_iteration() は設定値.

MPI 局所操作. 全ランクで同じ値を与える.

注意 ks_arnoldi はこの値を使わない (最大リスタート回数は set_ks_max_restart() で指定する).

例

cg.set_max_iteration(10000);

9.3 set_precon_algo() / get_precon_algo()

概要 前処理の種類を設定・取得する.

書式

void       set_precon_algo(PARCEL_INT precon_algo);
PARCEL_INT get_precon_algo();

引数

名前 入出力 型 説明 既定値
precon_algo 入力 PARCEL_INT 前処理の種類. parcel::PRECON_NONE (0, 前処理無し), PRECON_POINTJACOBI (1), PRECON_BLOCKJACOBI (2), PRECON_JACOBI (4) PRECON_NONE

前提条件 上の 4 値のいずれか. それ以外の値 (3 など) は std::invalid_argument.

戻り値 get_precon_algo() は設定値.

MPI 局所操作. 全ランクで同じ値を与える.

注意 ブロック Jacobi 前処理は GPU では遅く, GPU では Jacobi 前処理 (4) を推奨する. 前処理の種類は前処理の章を参照.

 Jacobi 前処理の行列の扱い (求解中にAAを破棄・変更しない, -DPARCEL_JACOBI_ONTHEFLY=0) は共通事項の「前処理の補足」に示す. pgmresのexternal_preconに構築済みの前処理を渡す場合は, それを使い終えるまで構築に使った行列を破棄・変更しない.

関連項目 set_jacobi(), set_blockjacobi(), set_scaling_matrix()

例

cg.set_precon_algo(parcel::PRECON_JACOBI);

9.4 set_jacobi() / get_jacobi()

概要 Jacobi 前処理 (PRECON_JACOBI) の反復回数を設定・取得する.

書式

void       set_jacobi(PARCEL_INT iter);
PARCEL_INT get_jacobi();

引数

名前 入出力 型 説明 既定値
iter 入力 PARCEL_INT Jacobi 前処理の反復回数 1

前提条件 1 以上. 0 以下は std::invalid_argument.

MPI 局所操作. 全ランクで同じ値を与える.

注意 PRECON_JACOBI 以外では使われない.

例

cg.set_jacobi(2);

9.5 set_blockjacobi() / get_blockjacobi()

概要 ブロック Jacobi 前処理 (PRECON_BLOCKJACOBI) のランクあたりのブロック数を設定・取得する.

書式

void       set_blockjacobi(PARCEL_INT nblock);
PARCEL_INT get_blockjacobi();

引数

名前 入出力 型 説明 既定値
nblock 入力 PARCEL_INT ブロック数. 適用カーネルの並列度に等しい 呼ばない場合は自動 (共通事項)

前提条件 1 以上で担当行数以下. 0 以下は std::invalid_argument. 担当行数以下であることは検査しない.

戻り値 get_blockjacobi() は設定値. 呼んでいない場合は 1 を返すが, 実際に使われるのは自動で決めた値である (環境変数 PARCEL_PRECON_VERBOSE を設定すると表示される).

MPI 局所操作. 全ランクで同じ値を与える.

注意 ブロックを細かくするほど前処理は弱くなる. PRECON_BLOCKJACOBI 以外では使われない.

例

cg.set_blockjacobi(20);

9.6 set_scaling_matrix() / set_scaling_vector() / get_scaling_matrix() / get_scaling_vector()

概要 前処理行列 / 前処理ベクトルのスケーリングの有無を設定・取得する. スケーリングは行列・残差を最大値で割って半精度の表現範囲に収める処理である.

書式

void set_scaling_matrix(bool flag);
void set_scaling_vector(bool flag);
bool get_scaling_matrix();
bool get_scaling_vector();

引数

名前 入出力 型 説明 既定値
flag 入力 bool スケーリング. false: 無, true: 有 呼ばない場合は自動 (共通事項)

戻り値 get_scaling_*() は設定値. 呼んでいない場合は false を返すが, 実際に使われるのは自動で決めた値である.

MPI 局所操作. 全ランクで同じ値を与える.

注意 ポイント Jacobi 前処理と前処理なしでは使われない.

例

cg.set_scaling_matrix(true);  cg.set_scaling_vector(true);

9.7 get_converged_reason()

概要 直前の solver() の収束状態を返す.

書式

PARCEL_INT get_converged_reason() const;

戻り値 収束状態の定数 のいずれか (意味). 正は収束, 負は失敗, 0 は solver() を呼んでいない.

MPI 局所操作. 値は全ランクで同じである.

関連項目 is_converged(), converged_reason_name()

例

if (cg.get_converged_reason() == parcel::krylov::DIVERGED_ITS) { /* 反復上限 */ }

9.8 is_converged()

概要 直前の solver() が収束したかを返す.

書式

bool is_converged() const;

戻り値 get_converged_reason() > 0 のとき true.

MPI 局所操作. 値は全ランクで同じである.

例

if (!cg.is_converged()) MPI_Abort(MPI_COMM_WORLD, 1);

9.9 get_iterations()

概要 直前の solver() の反復回数を返す.

書式

PARCEL_INT get_iterations() const;

戻り値 反復回数. 数え方はソルバごとに異なる (共通事項の「反復回数と残差の意味」).

MPI 局所操作. 値は全ランクで同じである.

9.10 get_residual()

概要 直前の solver() が収束判定に用いた相対値を返す.

書式

double get_residual() const;

戻り値 set_tolerance() の値と比べた相対値 (意味は共通事項の「反復回数と残差の意味」). 計算していなければ NaN. pgmres が反復上限で終わった場合は最後の更新後の値 (= get_true_residual()) である.

MPI 局所操作. 値は全ランクで同じである.

9.11 get_true_residual()

概要 線形ソルバの終了時の真の相対残差を返す.

書式

double get_true_residual() const;

戻り値 ∥b−Ax∥/∥b∥\|b - Ax\|/\|b\|. 線形ソルバが終了時に計算した値であり, この関数は追加の SpMV をしない. 固有値ソルバでは NaN.

MPI 局所操作. 値は全ランクで同じである.

注意 pcg / pbicgstab の get_residual() は漸化式の残差なので, 丸め誤差により真の残差と離れることがある. 解の精度を確かめる場合はこちらを見る.

9.12 converged_reason_name()

概要 収束状態の値を定数名の文字列に変換する (メンバ関数ではなく名前空間 parcel::krylov の関数).

書式

const char *parcel::krylov::converged_reason_name(PARCEL_INT r);

引数

名前 入出力 型 説明 既定値
r 入力 PARCEL_INT get_converged_reason() の値 なし

戻り値 "CONVERGED_RTOL", "ITERATING", "DIVERGED_ITS", "DIVERGED_NANORINF", "DIVERGED_BREAKDOWN" のいずれか. 未定義の値には "UNKNOWN".

MPI 局所操作.

例

std::printf("pcg: %s after %d iterations (residual %.3e)\n",
            parcel::krylov::converged_reason_name(cg.get_converged_reason()),
            (int)cg.get_iterations(), cg.get_residual());

9.13 version_string() / get_version() / PARCEL_VERSION_*

概要 PARCEL の版を返す (名前空間 parcel の関数とマクロ. Include/parcel_version.hpp で定義し, parcel_sycl.hpp が読む).

書式

const char *parcel::version_string() noexcept;
void parcel::get_version(int *major, int *minor, int *patch) noexcept;

#define PARCEL_VERSION_MAJOR 1
#define PARCEL_VERSION_MINOR 2
#define PARCEL_VERSION_PATCH 0
#define PARCEL_VERSION_STRING "1.2.0"
#define PARCEL_VERSION_NUMBER (MAJOR * 10000 + MINOR * 100 + PATCH)   // 10200
#define PARCEL_VERSION_GE(a, b, c)                                    // 版が a.b.c 以上なら 1

引数

名前 入出力 型 説明 既定値
major, minor, patch 出力 int * 版の番号. nullptr を渡した引数は書かない なし

戻り値 version_string() は PARCEL_VERSION_STRING と同じ文字列 (静的な領域).

MPI 局所操作. MPI の初期化の前でも呼べる.

例

#if PARCEL_VERSION_GE(1, 2, 0)
std::printf("PARCEL %s\n", parcel::version_string());
#endif