9 共通メンバ関数
全ソルバクラスが持つ関数である. 収束判定と収束状態の関数は parcel::krylov::krylov_param から, 前処理の関数は parcel::precon_param から継承する. 前処理の設定 (set_precon_algo() から set_scaling_vector() まで) は, 線形ソルバでは反復の前処理行列 を, 固有値ソルバでは set_precon_spectrum(true) のときの の を決める. 固有値ソルバで 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 では (pcagmres は ) の倍数でなくてよい. 最後のリスタートだけ列数を端数 (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 前処理の行列の扱い (求解中にを破棄・変更しない, -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;戻り値 . 線形ソルバが終了時に計算した値であり, この関数は追加の 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