18 C言語の API
C言語からは capi/parcel_sycl_c.h をインクルードし, 本章の関数を呼ぶ. 実装は capi/wrapper_parcel_sycl.cpp (ラッパ) であり, ライブラリの同じソルバを実行する. 設定の意味と既定値, 結果, 収束状態は共通事項とソルバごとの収束判定に, 使い方の流れと例は利用者ガイドの使用方法の「C言語」に示す.
- 7 つのソルバすべてを実行時に選べる. 線形方程式は parcel_solve_linear(), 固有値問題は parcel_solve_eigen() で解く. 設定は構造体 parcel_options に入れ, 結果は構造体 parcel_result で受け取る.
- 行番号・列番号・行数・非零要素数の型は
parcel_int(typedef int64_t parcel_int;. 64 ビット) である. ラッパを-DPARCEL_INT32でビルドした場合に値が 32 ビットに収まらなければPARCEL_ERR_ARGを返す.parcel_optionsとparcel_resultの項目とparcel_eigen_count()の戻り値はintである. - 行列は各ランクが担当する行ブロックを CRS 形式で渡す (共通事項の「入力の行列」). 番号付けは
parcel_optionsのindex_base(0 または 1) で選ぶ. 入力配列は書き換えない (ラッパが複製してから登録する). - コミュニケータの引数の型は
PARCEL_C_COMMである. MPI ありのビルド (PARCEL_MPIの既定 1) ではMPI_Comm, MPI なしのビルド (-DPARCEL_MPI=0) ではint(値は使われない. 0 を渡す) になる. ラッパとparcel_sycl_c.hをインクルードするプログラムは同じPARCEL_MPIでビルドする (食い違うと引数の型が合わない). MPI ありでは呼ぶ前にMPI_Init()を済ませる (1 プロセスの場合も). - 呼び出しごとに SYCL キュー (既定デバイスの in-order キュー) の作成と行列の登録を行う. デバイスは
ACPP_VISIBILITY_MASKなど SYCL 実装の環境変数で選ぶ. - 精度 (共通事項の「精度」) はラッパのコンパイル時のマクロ (
parcel_solver_data_typeなどで, 既定値はcapi/parcel_capi_default.hpp. すべて倍精度) で決まり, 実行時には変えられない. 入出力の配列はdoubleである. - 関数は引数と設定を検査し, 誤りを戻り値 (
PARCEL_ERR_ARGなど) で知らせる (戻り値). ライブラリ内の失敗の扱いは戻り値の表の後に示す.
18.1 共通事項との対応
共通事項の設定とparcel_optionsの項目, 結果とparcel_resultの項目の対応を示す. 既定値と意味は共通事項と同じである. 共通事項と表し方が異なるものは右の列に示す.
| 共通事項の設定 | parcel_optionsの項目 |
表し方の違い |
|---|---|---|
| 収束判定値 | tolerance |
— |
| 最大反復回数 | max_iteration |
— |
| 前処理の種類 | precon_algo |
— |
| Jacobi 前処理の反復回数 | jacobi_iter |
— |
| ブロック Jacobi 前処理のブロック数 | blockjacobi |
0 で自動 |
| スケーリング | scaling_matrix, scaling_vector |
-1: 自動, 0: 無, 1: 有 |
| リスタート周期 (pgmres) | gmres_restart |
— |
| 直交化の方式 (pgmres) | gmres_qr_algo |
— |
| 基底生成の大きさ, | cagmres_s, cagmres_t |
— |
| QR 分解の方式 (pcagmres) | cagmres_qr_algo |
項目の既定値はPARCEL_QR_MGS. IMPLICIT でこの既定値のままなら Cholesky QR を使う |
| の作り方 | cagmres_q_mode |
— |
| 前処理後の行列のスペクトル | precon_spectrum |
0: 偽, 1: 真 |
| 内部線形ソルバの種類 | linsolve_algo |
precon_spectrum = 1との併用はPARCEL_ERR_ARG |
| 内部線形ソルバの収束判定値 | linsolve_tolerance |
0 以下でソルバの既定値 (項目の既定値は 0) |
| 内部線形ソルバの最大反復回数 | linsolve_max_iteration |
同上 |
| 内部線形ソルバのリスタート周期 | linsolve_restart |
同上 |
| 内部線形ソルバの前処理 | linsolve_precon_algo, linsolve_jacobi_iter, linsolve_blockjacobi |
ブロック数は 0 で自動. スケーリングは指定できない (常に自動) |
| shift-invert | shift_enable, shift_sigma |
shift_enable = 1で有効. はラッパが組み立てる |
| Krylov 部分空間の大きさ | ks_m, ks_k_keep, ks_nev |
— |
| 最大リスタート回数 | ks_max_restart |
— |
| 直交化の方式 (ks_arnoldi) | ks_qr_algo |
— |
| 初期ベクトル | eigvec_seedとeigvecの先頭n_local要素 |
eigvec_seed = 1でeigvecを初期ベクトルに使う |
| 共通事項の結果 | parcel_resultの項目 |
|---|---|
| 収束状態 | converged_reason |
| 反復回数 | iterations |
| 残差 | residual |
| 真の残差 | true_residual |
| 収束した固有対の数 | ks_nconv |
| 内部線形ソルバの失敗回数 | linsolve_failures |
共通事項の定数はPARCEL_を前に付けた名前 (前処理はPARCEL_PRECON_, QR 分解はPARCEL_QR_, 内部線形ソルバはPARCEL_LINSOLVE_, の作り方はPARCEL_CAGMRES_Q_, 収束状態はPARCEL_CONVERGED_RTOLなどを付けた名前) である (定数).
18.2 定数
ソルバは次の定数で指定する.
| 定数 | 値 | ソルバ | 呼ぶ関数 |
|---|---|---|---|
PARCEL_SOLVER_PCG |
0 | pcg | parcel_solve_linear |
PARCEL_SOLVER_PBICGSTAB |
1 | pbicgstab | 同上 |
PARCEL_SOLVER_PGMRES |
2 | pgmres | 同上 |
PARCEL_SOLVER_PCAGMRES |
3 | pcagmres | 同上 |
PARCEL_SOLVER_POWER |
4 | power (絶対値最大の固有値 1 個) | parcel_solve_eigen |
PARCEL_SOLVER_INVERSE_POWER |
5 | inverse_power (絶対値最小の固有値 1 個) | 同上 |
PARCEL_SOLVER_KS_ARNOLDI |
6 | ks_arnoldi (絶対値最大側. shift-invert 時は σ 近傍) | 同上 |
設定の値は次の定数で指定する (意味は共通事項の定数).
| 定数 | 値 | 用いる項目 |
|---|---|---|
PARCEL_PRECON_NONE, PARCEL_PRECON_POINTJACOBI, PARCEL_PRECON_BLOCKJACOBI, PARCEL_PRECON_JACOBI |
0, 1, 2, 4 | precon_algo, linsolve_precon_algo |
PARCEL_QR_CGS, PARCEL_QR_MGS, PARCEL_QR_CHOLESKYQR, PARCEL_QR_CAGMRES_CHOLESKYQR |
0, 1, 2, 202 | gmres_qr_algo と ks_qr_algo (CGS, MGS だけ), cagmres_qr_algo |
PARCEL_LINSOLVE_PGMRES, PARCEL_LINSOLVE_PCG |
0, 1 | linsolve_algo |
PARCEL_CAGMRES_Q_AUTO, PARCEL_CAGMRES_Q_EXPLICIT, PARCEL_CAGMRES_Q_IMPLICIT |
0, 1, 2 | cagmres_q_mode |
関数の戻り値は次のとおりである. 引数検査の結果はMPI_Allreduceで全ランクにそろえてから返すので, 1 つのランクだけが不正な場合も全ランクが同じエラーを返す.
| 戻り値 | 値 | 意味 |
|---|---|---|
PARCEL_OK |
0 | 正常に終了した. 反復が収束したかどうかは含まない (parcel_result の converged_reason で確かめる) |
PARCEL_ERR_ARG |
-1 | 引数・設定が不正 |
PARCEL_ERR_DISTRIBUTION |
-2 | 各ランクの行ブロックが全体を重複・欠落なく覆わない (parcel_solve_linear() の前提条件) |
PARCEL_ERR_NOT_BUILT |
-3 | 指定したソルバがビルドから外されている (「ビルドするソルバの取捨」参照) |
PARCEL_ERR_RUNTIME |
-4 | ライブラリ内の失敗. MPI ありのビルドでは呼び出し側に返らない (下記) |
ライブラリ内で失敗が起きた場合 (デバイスのメモリ不足, 行列の大きさがライブラリ内部の整数の範囲を超えるなど), ラッパはメッセージ ([parcel_c] exception: ...) を標準エラー出力に書いてからMPI_Abort(comm, 4)を呼び, 全ランクを終了させる. この失敗は 1 つのランクだけで起きうるので, PARCEL_ERR_RUNTIMEを返して呼び出し側に任せると, 他のランクがソルバ内の集団通信で待ち続けてジョブが止まるためである. MPI なしのビルドでは待つ相手がいないので, メッセージを書いてPARCEL_ERR_RUNTIMEを返す.
収束状態 (parcel_resultのconverged_reason) は次の定数で表す. 意味と, ソルバごとに起こる場合は共通事項の「収束状態」に示す.
| 定数 | 値 | 意味 |
|---|---|---|
PARCEL_CONVERGED_RTOL |
1 | 収束判定値 (tolerance) を満たした |
PARCEL_ITERATING |
0 | 未実行 (引数エラーで解かなかった場合など) |
PARCEL_DIVERGED_ITS |
-1 | 最大反復回数 (ks_arnoldi は最大リスタート回数) に達した |
PARCEL_DIVERGED_NANORINF |
-2 | 判定値 (残差・固有値の推定) に NaN / Inf が現れた |
PARCEL_DIVERGED_BREAKDOWN |
-3 | アルゴリズムの破綻 |
18.3 parcel_options
概要 ソルバ・前処理・収束判定などの設定をまとめた構造体.
書式
typedef struct parcel_options { double tolerance; ... } parcel_options;項目 parcel_options_init() が入れる既定値を示す. 意味は共通事項の設定のとおりである. 内部線形ソルバのlinsolve_tolerance, linsolve_max_iteration, linsolve_restartは 0 (0 以下は「ソルバの既定値を使う」の意味) を入れる. 最大反復回数の既定値が inverse_power (5000) と ks_arnoldi (2000) で異なり, 1 つの項目では両方を表せないためである. ビルドから外したソルバだけが使う項目は 0 のままである.
| 項目 | 既定値 | 説明 |
|---|---|---|
double tolerance |
1.0e-8 | 収束判定値 (線形ソルバは相対残差, power / inverse_power は固有値の相対変化, ks_arnoldi は Ritz 残差) |
double linsolve_tolerance |
0 | 固有値ソルバの内部線形ソルバの収束判定値. 0 以下はソルバの既定値 (inverse_power, ks_arnoldi とも 1.0e-10) |
double shift_sigma |
0.0 | shift-invert のシフト σ (shift_enable=1 のとき) |
int max_iteration |
10000 | 最大反復回数 (線形ソルバ, power / inverse_power の外側の反復. ks_arnoldi は使わない) |
int precon_algo |
PARCEL_PRECON_NONE |
前処理の種類 . PARCEL_PRECON_NONE (0), _POINTJACOBI (1), _BLOCKJACOBI (2), _JACOBI (4) |
int jacobi_iter |
1 | Jacobi 前処理の反復回数 |
int blockjacobi |
0 | ブロック Jacobi 前処理のブロック数. 0 は自動 |
int scaling_matrix |
-1 | 前処理行列のスケーリング. -1: 自動, 0: 無効, 1: 有効 |
int scaling_vector |
-1 | 前処理ベクトルのスケーリング (値の意味は同上) |
int index_base |
0 | nstart と col の番号付け (0 または 1) |
int verbose |
0 | 1 で rank 0 がデバイス名と設定を表示する |
int gmres_restart |
30 | pgmres のリスタート周期 |
int gmres_qr_algo |
PARCEL_QR_MGS |
pgmres の直交化の方式. PARCEL_QR_CGS (0) または _MGS (1). それ以外 (_CHOLESKYQR (2) を含む) は PARCEL_ERR_ARG |
int cagmres_s |
8 | pcagmres の |
int cagmres_t |
4 | pcagmres の (リスタート周期は ) |
int cagmres_qr_algo |
PARCEL_QR_MGS |
pcagmres のQR 分解の方式. PARCEL_QR_CGS (0), _MGS (1), _CHOLESKYQR (2), _CAGMRES_CHOLESKYQR (202. cagmres_q_mode = PARCEL_CAGMRES_Q_IMPLICITのときだけ) |
int precon_spectrum |
0 | 固有値ソルバ共通の前処理後の行列のスペクトル. 0: の固有値, 1: の固有値 ( は precon_algo などで作る) |
int linsolve_algo |
PARCEL_LINSOLVE_PGMRES |
inverse_power の内部線形ソルバの種類. PARCEL_LINSOLVE_PGMRES (0) または PARCEL_LINSOLVE_PCG (1) |
int linsolve_max_iteration |
0 | 内部線形ソルバの最大反復回数. 0 以下はソルバの既定値 (inverse_power 5000, ks_arnoldi の shift-invert 2000) |
int linsolve_restart |
0 | 内部 pgmres のリスタート周期. 0 以下はソルバの既定値 (どちらも 30) |
int linsolve_precon_algo |
PARCEL_PRECON_JACOBI |
内部線形ソルバの前処理 の種類. precon_spectrum=1 では使われない |
int linsolve_jacobi_iter |
1 | の Jacobi 前処理の反復回数 |
int linsolve_blockjacobi |
0 | のブロック Jacobi 前処理のブロック数 (0 は自動) |
int ks_m |
30 | ks_arnoldi の Krylov 部分空間の最大次元 |
int ks_k_keep |
10 | ks_arnoldi のリスタートで保持する Ritz 対の数 |
int ks_nev |
4 | ks_arnoldi で求める固有値の数 |
int ks_max_restart |
200 | ks_arnoldi の最大リスタート回数 |
int shift_enable |
0 | 1 で shift-invert (σ 近傍の固有値). ks_arnoldi のみ |
int eigvec_seed |
0 | 1 で ks_arnoldi の初期ベクトルに eigvec の先頭 n_local 要素を使う. 0 ではラッパが大域行番号から作る |
int cagmres_q_mode |
PARCEL_CAGMRES_Q_AUTO |
pcagmres の の作り方. PARCEL_CAGMRES_Q_AUTO (0), _EXPLICIT (1), _IMPLICIT (2). 組合せの規則は共通事項のとおりで, 規則に反する組合せと 0〜2 以外の値はPARCEL_ERR_ARG. _IMPLICITでcagmres_qr_algoが既定のPARCEL_QR_MGSのままならPARCEL_QR_CHOLESKYQRを使い, PARCEL_QR_CGSはPARCEL_ERR_ARG |
int ks_qr_algo |
PARCEL_QR_CGS (ライブラリのビルド時の既定) |
ks_arnoldi の直交化の方式. PARCEL_QR_CGS (0, CGS2) または PARCEL_QR_MGS (1, MGS2). それ以外はPARCEL_ERR_ARG. 既定値はparcel_options_init()がライブラリから読む |
前提条件 必ず parcel_options_init() で既定値を入れてから, 必要な項目だけを変える. 呼んだソルバが使わない項目は無視される. ただしtolerance (有限の正の数), max_iteration (1 以上) と前処理の項目 (precon_algo (定数のいずれか), jacobi_iter (1 以上), blockjacobi (0 以上), scaling_matrix・scaling_vector (-1, 0, 1)) は常に, linsolve_algo, linsolve_precon_algo, linsolve_jacobi_iter, linsolve_blockjacobiとlinsolve_tolerance (NaN でないこと) は固有値ソルバでは常に値の範囲を検査し, 外れていればPARCEL_ERR_ARGを返す. linsolve_tolerance, linsolve_max_iteration, linsolve_restartの 0 以下は「ソルバの既定値」の意味である. 構造体の大きさは版によって変わりうるので, ラッパと Fortran モジュールは同じ版のparcel_sycl_c.hでビルドする.
MPI 全ランクで同じ内容を与える.
関連項目 parcel_options_init(), 共通事項の設定
18.4 parcel_result
概要 解いた結果の収束状態を受け取る構造体.
書式
typedef struct parcel_result {
int converged_reason;
int iterations;
double residual;
double true_residual;
int ks_nconv;
int linsolve_failures;
} parcel_result;項目 意味は共通事項の「結果」のとおりであり, 定義はソルバごとに異なる (反復回数と残差の意味). 値は全ランクで同じである. 引数検査で解かなかった場合はconverged_reason = PARCEL_ITERATING (0), iterations = 0, 残差は NaN が入る.
| 項目 | 説明 |
|---|---|
int converged_reason |
収束状態. 正なら収束, 負なら失敗 (定数) |
int iterations |
反復回数. pgmres は内側反復の総数, pcagmres は基底ベクトルの総数, power / inverse_power は外側反復の回数, ks_arnoldi はリスタートの回数 |
double residual |
残差. tolerance と比べた相対値. 線形ソルバは (pcg / pbicgstab は漸化式, pgmres / pcagmres は真の残差), power / inverse_power は固有値の相対変化, ks_arnoldi は判定対象 ks_nev 個の Ritz 残差推定の最大値. 未計算なら NaN |
double true_residual |
真の残差. 線形ソルバの終了時の . 固有値ソルバでは NaN |
int ks_nconv |
収束した固有対の数 (ks_nev 個のうち). 他のソルバでは 0 |
int linsolve_failures |
内部線形ソルバの失敗回数 (inverse_power と ks_arnoldi の shift-invert). 他では 0 |
関連項目 parcel_solve_linear(), parcel_solve_eigen(), 収束状態の定数
18.5 parcel_options_init()
概要 parcel_optionsに既定値を入れる.
書式
void parcel_options_init(parcel_options *opt);引数
| 名前 | 入出力 | 型 | 説明 | 既定値 |
|---|---|---|---|---|
opt |
出力 | parcel_options * |
既定値を入れる構造体 | — |
前提条件 optはNULLでない.
戻り値 無し. 既定値はライブラリのソルバを作ってその初期値を読むので, 共通事項の既定値と一致する (parcel_options の表).
MPI 局所操作.
例
parcel_options opt;
parcel_options_init(&opt);
opt.tolerance = 1.0e-9;18.6 parcel_solver_from_name()
概要 ソルバ名からPARCEL_SOLVER_*の値を得る.
書式
int parcel_solver_from_name(const char *name);引数
| 名前 | 入出力 | 型 | 説明 | 既定値 |
|---|---|---|---|---|
name |
入力 | const char * |
ソルバ名 ("pcg", "pbicgstab", "pgmres", "pcagmres", "power", "inverse_power", "ks_arnoldi") |
— |
戻り値 対応するPARCEL_SOLVER_*の値. 不明な名前では -1.
MPI 局所操作.
注意 Fortran のモジュールには含まれない.
18.7 parcel_eigen_count()
概要 固有値ソルバが返す固有対の個数 k を返す. parcel_solve_eigen()に渡す配列の大きさを決めるのに使う.
書式
int parcel_eigen_count(int solver, const parcel_options *opt);引数
| 名前 | 入出力 | 型 | 説明 | 既定値 |
|---|---|---|---|---|
solver |
入力 | int |
PARCEL_SOLVER_* |
— |
opt |
入力 | const parcel_options * |
設定 (ks_arnoldi ではks_k_keepを使う) |
— |
戻り値 power / inverse_power では 1, ks_arnoldi ではopt->ks_k_keep (このうち収束が保証されるのは先頭ks_nev個), 線形ソルバと不正な値では 0.
MPI 局所操作.
関連項目 parcel_solve_eigen()
18.8 parcel_solve_linear()
概要 線形方程式を解く (pcg, pbicgstab, pgmres, pcagmres).
書式
int parcel_solve_linear(int solver, const parcel_options *opt, PARCEL_C_COMM comm,
parcel_int n_local, parcel_int nstart, parcel_int n_global, parcel_int nnz_local,
const parcel_int *rowptr, const parcel_int *col, const double *val,
const double *b, double *x, parcel_result *res);引数
| 名前 | 入出力 | 型 | 説明 | 既定値 |
|---|---|---|---|---|
solver |
入力 | int |
PARCEL_SOLVER_PCG, _PBICGSTAB, _PGMRES, _PCAGMRES のいずれか. それ以外はPARCEL_ERR_ARG |
— |
opt |
入力 | const parcel_options * |
設定. 共通に使う項目はtolerance, max_iterationと前処理の項目. pgmres はgmres_restart, gmres_qr_algoを, pcagmres はcagmres_s, cagmres_t, cagmres_qr_algo, cagmres_q_modeを使う |
— |
comm |
入力 | PARCEL_C_COMM |
コミュニケータ (MPI ありではMPI_Comm. MPI_COMM_WORLD以外も可. MPI なしではintの 0) |
— |
b |
入力 | const double * |
右辺の担当行の部分 (長さn_local) |
— |
x |
入出力 | double * |
入力は初期値, 出力は解の担当行の部分 (長さn_local) |
— |
res |
出力 | parcel_result * |
結果. NULLなら返さない |
— |
行列の引数は次のとおりである (parcel_solve_eigen()と共通).
| 引数 | 説明 |
|---|---|
parcel_int n_local |
担当行数 (1 以上) |
parcel_int nstart |
担当する最初の行の大域行番号 (index_base の番号付け) |
parcel_int n_global |
大域行数 (全ランクの n_local の和) |
parcel_int nnz_local |
担当行の非零要素数 |
const parcel_int *rowptr |
行ポインタ (長さ n_local + 1). rowptr[0] からの差だけを使うので, 0 始まりでも 1 始まりでもよい |
const parcel_int *col |
列番号 (長さ nnz_local). 大域の列番号 (index_base の番号付け) |
const double *val |
行列要素 (長さ nnz_local) |
前提条件 行列は共通事項の「入力の行列」の条件を満たす.
- 各ランクの行ブロックは連続した行であればよく, ランクごとに行数が異なってよい. ランク番号の順に並んでいる必要もない. 全ランクの行ブロックを合わせたものがを重複・欠落なく覆わなければならない. ラッパは各ランクの (
nstart,n_local) をMPI_Allgatherで集めて検査し, 満たさなければ全ランクでPARCEL_ERR_DISTRIBUTIONを返す. MPI なしのビルドではnstart = index_base,n_local = n_globalとする. - 行ポインタが非減少で
rowptr[n_local] - rowptr[0] == nnz_localであること, 列番号と行範囲がに収まることを検査し, 満たさなければPARCEL_ERR_ARGを返す. - pgmres は
gmres_restart >= 1, pcagmres はcagmres_s >= 1,cagmres_t >= 1を検査する.
戻り値 PARCEL_OKまたは負のエラーコード (定数). 反復が収束したかどうかは戻り値に含まない. resのconverged_reasonで確かめる.
MPI 集団操作. コミュニケータの全ランクで, 同じsolverと同じ内容のoptを与えて呼ぶ. 反復の途中経過と計算時間は rank 0 の標準出力に表示される (共通事項の「標準出力」).
関連項目 parcel_options, parcel_result, ソルバごとの収束判定
例
parcel_options opt;
parcel_options_init(&opt);
opt.tolerance = 1.0e-9;
opt.precon_algo = PARCEL_PRECON_BLOCKJACOBI;
parcel_result res;
int rc = parcel_solve_linear(PARCEL_SOLVER_PGMRES, &opt, MPI_COMM_WORLD,
n_local, nstart, n_global, nnz_local, rowptr, col, val, b, x, &res);
if(rc != PARCEL_OK){ /* 引数エラーなど */ }
else if(res.converged_reason <= 0){ /* 未収束 (PARCEL_DIVERGED_*) */ }18.9 parcel_solve_eigen()
概要 固有値問題 (precon_spectrum=1では) を解く (power, inverse_power, ks_arnoldi).
書式
int parcel_solve_eigen(int solver, const parcel_options *opt, PARCEL_C_COMM comm,
parcel_int n_local, parcel_int nstart, parcel_int n_global, parcel_int nnz_local,
const parcel_int *rowptr, const parcel_int *col, const double *val,
double *eigval, double *eigvec, parcel_result *res);引数 行列の引数, opt, comm, resは parcel_solve_linear() と同じである. k = parcel_eigen_count() として,
| 名前 | 入出力 | 型 | 説明 | 既定値 |
|---|---|---|---|---|
solver |
入力 | int |
PARCEL_SOLVER_POWER, _INVERSE_POWER, _KS_ARNOLDIのいずれか |
— |
eigval |
出力 | double * |
2*k要素. 実部と虚部を交互に格納する (eigval[2*j]が j 番目の実部, eigval[2*j+1]が虚部). power / inverse_power ではeigval[0]に固有値, eigval[1]に 0 |
— |
eigvec |
入出力 | double * |
n_local*k要素. 列優先で, eigvec + j*n_localからのn_local要素が j 番目の固有ベクトルの担当行の部分. 複素共役対は実部と虚部の 2 本として格納する (固有値と固有ベクトルの出力). eigvec_seed=1の ks_arnoldi では先頭n_local要素が初期ベクトル (入力) |
— |
求める固有値と主に使う項目は次のとおりである.
| ソルバ | 求めるもの | 主に使う項目 |
|---|---|---|
| power | 絶対値最大の固有値 1 個 | tolerance, max_iteration, precon_spectrum |
| inverse_power | 絶対値最小の固有値 1 個 | 上記 + linsolve_algo, linsolve_tolerance, linsolve_max_iteration, linsolve_restart, linsolve_precon_* |
| ks_arnoldi | 絶対値最大側の ks_nev 個 (shift-invert 時は σ 近傍) |
tolerance, precon_spectrum, ks_m, ks_k_keep, ks_nev, ks_max_restart, ks_qr_algo, shift_enable, shift_sigma, eigvec_seed, shift-invert 時は linsolve_* |
前提条件
- ks_arnoldi は
1 <= ks_nev <= ks_k_keep < ks_m <= n_global,ks_max_restart >= 1,ks_qr_algoがPARCEL_QR_CGSかPARCEL_QR_MGSでなければPARCEL_ERR_ARGを返す. - inverse_power の
linsolve_algo = PARCEL_LINSOLVE_PCGはprecon_spectrum=0のときだけ使える (1 と併用するとPARCEL_ERR_ARG). shift_enable=1(shift-invert) は ks_arnoldi だけで使える (power / inverse_power ではPARCEL_ERR_ARG).precon_spectrum=0ではラッパが (対角要素が無い行にはを加える) を組み立て, の近傍の固有値を返す. 内部線形ソルバの前処理はから作る.precon_spectrum=1ではシフト行列を作らず, の近傍の固有値を返す.- 初期ベクトルは, power / inverse_power では内部で生成する. ks_arnoldi は既定 (
eigvec_seed=0) ではラッパが大域行番号から作るので, 結果は行分割のしかたに依らない.
戻り値 parcel_solve_linear() と同じ. inverse_power と shift-invert ではres->linsolve_failuresが 0 でなければ内部線形ソルバが収束しなかった反復がある. ks_arnoldi のres->ks_nconvは判定値を満たした固有対の数である.
MPI 集団操作 (parcel_solve_linear() と同じ).
関連項目 parcel_eigen_count(), 固有値ソルバの補足, ソルバごとの収束判定
例
const int k = parcel_eigen_count(PARCEL_SOLVER_KS_ARNOLDI, &opt); /* = ks_k_keep */
double *ev = malloc(sizeof(double) * 2 * k); /* Re, Im 交互 */
double *v = malloc(sizeof(double) * (size_t)n_local * k); /* 列優先 */
int rc = parcel_solve_eigen(PARCEL_SOLVER_KS_ARNOLDI, &opt, MPI_COMM_WORLD,
n_local, nstart, n_global, nnz_local, rowptr, col, val, ev, v, &res);18.10 parcel_options_size() / parcel_result_size()
概要 sizeof(parcel_options)とsizeof(parcel_result)を返す. Fortran の派生型との照合に使う.
書式
int parcel_options_size(void);
int parcel_result_size(void);戻り値 ラッパをビルドしたときの構造体の大きさ [バイト].
注意 構造体の大きさは版によって変わりうるので, ラッパ, Fortran のモジュール, 利用者のプログラムは同じ版のparcel_sycl_c.hでビルドする.
18.11 parcel_get_version() / parcel_version_string()
概要 ライブラリの版を返す. 値はラッパをビルドしたときの Include/parcel_version.hpp のもの.
書式
int parcel_get_version(int *major, int *minor, int *patch);
const char *parcel_version_string(void);引数 major, minor, patch: 出力. 版の番号. NULL を渡した引数は書かない.
戻り値 parcel_get_version() は PARCEL_OK. parcel_version_string() は "1.2.0" の形の文字列 (静的な領域. 解放しない).
MPI 局所操作. MPI の初期化の前, MPI なしのビルドでも呼べる.
18.12 run_parcel_sycl_c() (非推奨)
概要 v1.0 の C言語の API (旧 API). pcg でを解く. 互換のために残している. 新しく作るプログラムでは parcel_solve_linear() を使う.
書式
void run_parcel_sycl_c(PARCEL_C_COMM mpi_comm_c, parcel_int n, parcel_int nnz,
double *crsA, parcel_int *crsCol, parcel_int *crsRow_ptr,
double *vecx, double *vecb);引数
| 名前 | 入出力 | 型 | 説明 | 既定値 |
|---|---|---|---|---|
mpi_comm_c |
入力 | PARCEL_C_COMM |
コミュニケータ | — |
n |
入力 | parcel_int |
担当行数 | — |
nnz |
入力 | parcel_int |
担当行の非零要素数 | — |
crsA |
入力 | double * |
行列要素 | — |
crsCol |
入力 | parcel_int * |
大域の列番号 (0 始まり) | — |
crsRow_ptr |
入力 | parcel_int * |
行ポインタ (0 始まり) | — |
vecx |
入出力 | double * |
入力は初期値, 出力は解 | — |
vecb |
入力 | double * |
右辺 | — |
前提条件 担当範囲の先頭行は各ランクのnの累積和 (MPI_Exscan) で求める. 全ランクのnが等しければn*myrankとなり, 不均等な分割も扱える. 入力配列は書き換えない.
戻り値 無し. 失敗した場合は rank 0 が標準エラー出力にエラーコードを表示する.
MPI 集団操作.
注意 収束判定値は 1.0e-9 固定, 最大反復回数はラッパのコンパイル時マクロMAX_ITERATION (既定 10000), 前処理は-Dparcel_solver_precon_algo=<0|1|2|4>で決まる. ブロック Jacobi (2) と Jacobi (4) では行列・ベクトルのスケーリングを有効にし, 分割数・反復回数にはBLOCKJACOBI_BLOCK (既定 1) とJACOBI_ITER (既定 1) を用いる. 整数引数は v1.0 のintからparcel_int (64 ビット) に変わった (利用者ガイドの「版と互換性」).