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

19 Fortran の API

 Fortran からはモジュール parcel_sycl_mod (capi/parcel_sycl_mod.f90) を use し, 本章の手続きを呼ぶ. 実装は C言語の API と同じラッパ (capi/wrapper_parcel_sycl.cpp) であり, ライブラリの同じソルバを実行する. 設定の意味と既定値, 結果, 収束状態は共通事項とソルバごとの収束判定に, 使い方の流れと例は利用者ガイドの使用方法の「Fortran」に示す.

19.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 —
基底生成の大きさss, tt cagmres_s, cagmres_t —
QR 分解の方式 (pcagmres) cagmres_qr_algo 成分の既定値はPARCEL_QR_MGS. IMPLICIT でこの既定値のままなら Cholesky QR を使う
QQの作り方 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で有効. A−σIA - \sigma Iはラッパが組み立てる
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

19.2 定数

 モジュールは次の名前付き定数を持つ. 型はいずれもinteger(c_int)である. 設定の値の意味は共通事項の定数, 収束状態の意味は共通事項の「収束状態」に示す.

定数 値 用途
PARCEL_SOLVER_PCG, PARCEL_SOLVER_PBICGSTAB, PARCEL_SOLVER_PGMRES, PARCEL_SOLVER_PCAGMRES 0, 1, 2, 3 線形ソルバ (parcel_solve_linear のsolver)
PARCEL_SOLVER_POWER, PARCEL_SOLVER_INVERSE_POWER, PARCEL_SOLVER_KS_ARNOLDI 4, 5, 6 固有値ソルバ (parcel_solve_eigen のsolver)
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
PARCEL_CONVERGED_RTOL, PARCEL_ITERATING, PARCEL_DIVERGED_ITS, PARCEL_DIVERGED_NANORINF, PARCEL_DIVERGED_BREAKDOWN 1, 0, -1, -2, -3 収束状態 (res%converged_reason)

 関数の戻り値は次のとおりである. 引数検査の結果は全ランクにそろえてから返すので, 1 つのランクだけが不正な場合も全ランクが同じエラーを返す.

戻り値 値 意味
PARCEL_OK 0 正常に終了した. 反復が収束したかどうかは含まない (res%converged_reason で確かめる)
PARCEL_ERR_ARG -1 引数・設定が不正
PARCEL_ERR_DISTRIBUTION -2 各ランクの行ブロックが全体を重複・欠落なく覆わない
PARCEL_ERR_NOT_BUILT -3 指定したソルバがビルドから外されている (「ビルドするソルバの取捨」参照)
PARCEL_ERR_RUNTIME -4 ライブラリ内の失敗. MPI ありのビルドでは呼び出し側に返らない (下記)

 ライブラリ内で失敗が起きた場合 (デバイスのメモリ不足, 行列の大きさがライブラリ内部の整数の範囲を超えるなど), ラッパはメッセージ ([parcel_c] exception: ...) を標準エラー出力に書いてからMPI_Abortを呼び, 全ランクを終了させる. この失敗は 1 つのランクだけで起きうるので, 呼び出し側に任せると他のランクが集団通信で待ち続けるためである. MPI なしのビルドではPARCEL_ERR_RUNTIMEを返す.

19.3 parcel_options / parcel_result

概要 設定をまとめた派生型parcel_optionsと, 結果を受け取る派生型parcel_result. どちらもbind(C)である.

書式

type(parcel_options) :: opt
type(parcel_result)  :: res

項目 opt%tolerance, res%converged_reasonのように参照する. parcel_optionsの成分と, parcel_options_init が入れる既定値は次のとおりである. 意味は共通事項の設定のとおりである. 内部線形ソルバのlinsolve_tolerance, linsolve_max_iteration, linsolve_restartは 0 (0 以下は「ソルバの既定値を使う」の意味) を入れる. 最大反復回数の既定値が inverse_power (5000) と ks_arnoldi (2000) で異なり, 1 つの成分では両方を表せないためである.

成分 型 既定値 説明
tolerance real(c_double) 1.0d-8 収束判定値
linsolve_tolerance real(c_double) 0 内部線形ソルバの収束判定値. 0 以下はソルバの既定値 (inverse_power, ks_arnoldi とも 1.0d-10)
shift_sigma real(c_double) 0.0 shift-invert のシフト σ (shift_enable=1 のとき)
max_iteration integer(c_int) 10000 最大反復回数 (ks_arnoldi は使わない)
precon_algo integer(c_int) PARCEL_PRECON_NONE 前処理の種類
jacobi_iter integer(c_int) 1 Jacobi 前処理の反復回数
blockjacobi integer(c_int) 0 ブロック Jacobi 前処理のブロック数. 0 は自動
scaling_matrix integer(c_int) -1 前処理行列のスケーリング. -1: 自動, 0: 無効, 1: 有効
scaling_vector integer(c_int) -1 前処理ベクトルのスケーリング (値の意味は同上)
index_base integer(c_int) 0 nstart と col の番号付け (0 または 1)
verbose integer(c_int) 0 1 で rank 0 がデバイス名と設定を表示する
gmres_restart integer(c_int) 30 pgmres のリスタート周期 mm
gmres_qr_algo integer(c_int) PARCEL_QR_MGS pgmres の直交化の方式. PARCEL_QR_CGS または PARCEL_QR_MGS. それ以外は PARCEL_ERR_ARG
cagmres_s integer(c_int) 8 pcagmres の ss
cagmres_t integer(c_int) 4 pcagmres の tt
cagmres_qr_algo integer(c_int) PARCEL_QR_MGS pcagmres のQR 分解の方式
precon_spectrum integer(c_int) 0 前処理後の行列のスペクトル. 0: AA の固有値, 1: AK−1AK^{-1} の固有値
linsolve_algo integer(c_int) PARCEL_LINSOLVE_PGMRES inverse_power の内部線形ソルバの種類
linsolve_max_iteration integer(c_int) 0 内部線形ソルバの最大反復回数. 0 以下はソルバの既定値 (inverse_power 5000, ks_arnoldi の shift-invert 2000)
linsolve_restart integer(c_int) 0 内部 pgmres のリスタート周期. 0 以下はソルバの既定値 (どちらも 30)
linsolve_precon_algo integer(c_int) PARCEL_PRECON_JACOBI 内部線形ソルバの前処理 KinK_{in} の種類. precon_spectrum=1 では使われない
linsolve_jacobi_iter integer(c_int) 1 KinK_{in} の Jacobi 前処理の反復回数
linsolve_blockjacobi integer(c_int) 0 KinK_{in} のブロック Jacobi 前処理のブロック数 (0 は自動)
ks_m integer(c_int) 30 ks_arnoldi の Krylov 部分空間の最大次元 mm
ks_k_keep integer(c_int) 10 ks_arnoldi のリスタートで保持する Ritz 対の数 kkeepk_{keep}
ks_nev integer(c_int) 4 ks_arnoldi で求める固有値の数 nevnev
ks_max_restart integer(c_int) 200 ks_arnoldi の最大リスタート回数
shift_enable integer(c_int) 0 1 で shift-invert. ks_arnoldi のみ
eigvec_seed integer(c_int) 0 1 で ks_arnoldi の初期ベクトルに eigvec の先頭 n_local 要素を使う. 0 ではラッパが大域行番号から作る
cagmres_q_mode integer(c_int) PARCEL_CAGMRES_Q_AUTO pcagmres の QQの作り方. 組合せの規則は共通事項のとおりで, 規則に反する組合せはPARCEL_ERR_ARG
ks_qr_algo integer(c_int) PARCEL_QR_CGS (ライブラリのビルド時の既定) ks_arnoldi の直交化の方式. PARCEL_QR_CGS (CGS2) または PARCEL_QR_MGS (MGS2). それ以外はPARCEL_ERR_ARG

 parcel_resultの成分は次のとおりである. 値は全ランクで同じである. 引数検査で解かなかった場合はconverged_reason = PARCEL_ITERATING (0), iterations = 0, 残差は NaN が入る.

成分 型 説明
converged_reason integer(c_int) 収束状態. 正なら収束, 負なら失敗
iterations integer(c_int) 反復回数 (反復回数と残差の意味)
residual real(c_double) 残差. 未計算なら NaN
true_residual real(c_double) 真の残差. 固有値ソルバでは NaN
ks_nconv integer(c_int) 収束した固有対の数. ks_arnoldi 以外では 0
linsolve_failures integer(c_int) 内部線形ソルバの失敗回数

前提条件 必ず 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を返す. 派生型の大きさがラッパの構造体と一致することを parcel_options_check() / parcel_result_check() で確かめるとよい.

MPI 全ランクで同じ内容を与える.

19.4 parcel_options_init

概要 parcel_optionsに既定値を入れる.

書式

call parcel_options_init(opt)

引数

名前 入出力 型 説明 既定値
opt 出力 type(parcel_options) 既定値を入れる派生型 —

戻り値 無し (サブルーチン). 既定値は共通事項の既定値と一致する (parcel_options の表).

MPI 局所操作.

例

type(parcel_options) :: opt
call parcel_options_init(opt)
opt%tolerance = 1.0d-9

19.5 parcel_solve_linear

概要 線形方程式Ax=bAx = bを解く (pcg, pbicgstab, pgmres, pcagmres).

書式

ierr = parcel_solve_linear(solver, opt, comm, n_local, nstart, n_global, nnz_local, &
                           rowptr, col, val, b, x [, res])

引数

名前 入出力 型 説明 既定値
solver 入力 integer(c_int) PARCEL_SOLVER_PCG, PARCEL_SOLVER_PBICGSTAB, PARCEL_SOLVER_PGMRES, PARCEL_SOLVER_PCAGMRES のいずれか. それ以外はPARCEL_ERR_ARG —
opt 入力 type(parcel_options) 設定. 共通に使う成分はtolerance, max_iterationと前処理の成分. pgmres はgmres_restart, gmres_qr_algoを, pcagmres はcagmres_s, cagmres_t, cagmres_qr_algo, cagmres_q_modeを使う —
comm 入力 integer(c_int) コミュニケータ (Fortran の整数ハンドル. MPI_COMM_WORLD以外も可) —
n_local 入力 integer(parcel_int_kind) 担当行数 (1 以上) —
nstart 入力 integer(parcel_int_kind) 担当する最初の行の大域行番号 (index_baseの番号付け) —
n_global 入力 integer(parcel_int_kind) 大域行数 (全ランクのn_localの和) —
nnz_local 入力 integer(parcel_int_kind) 担当行の非零要素数 —
rowptr(*) 入力 integer(parcel_int_kind) 行ポインタ (長さn_local + 1). 先頭からの差だけを使うので 0 始まりでも 1 始まりでもよい —
col(*) 入力 integer(parcel_int_kind) 大域の列番号 (長さnnz_local. index_baseの番号付け) —
val(*) 入力 real(c_double) 行列要素 (長さnnz_local) —
b(*) 入力 real(c_double) 右辺の担当行の部分 (長さn_local) —
x(*) 入出力 real(c_double) 入力は初期値, 出力は解の担当行の部分 (長さn_local) —
res 出力 (省略可) type(parcel_result) 結果. 省略すると返さない —

前提条件 行列は共通事項の「入力の行列」の条件を満たす.

戻り値 integer(c_int). PARCEL_OKまたは負のエラーコード (定数). 反復が収束したかどうかは戻り値に含まない. res%converged_reasonで確かめる.

MPI 集団操作. コミュニケータの全ランクで, 同じsolverと同じ内容のoptを与えて呼ぶ. 反復の途中経過と計算時間は rank 0 の標準出力に表示される (共通事項の「標準出力」).

関連項目 parcel_options / parcel_result, ソルバごとの収束判定

例

call parcel_options_init(opt)
opt%index_base  = 1
opt%tolerance   = 1.0d-9
opt%precon_algo = PARCEL_PRECON_BLOCKJACOBI
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) then
   ! 引数エラーなど
else if (res%converged_reason <= 0) then
   ! 未収束 (PARCEL_DIVERGED_*)
end if

19.6 parcel_solve_eigen

概要 固有値問題Av=λvAv = \lambda v (precon_spectrum=1ではAK−1AK^{-1}) を解く (power, inverse_power, ks_arnoldi).

書式

ierr = parcel_solve_eigen(solver, opt, comm, n_local, nstart, n_global, nnz_local, &
                          rowptr, col, val, eigval, eigvec [, res])

引数 opt, comm, 行列の引数 (n_localからvalまで), resは parcel_solve_linear と同じである. k = parcel_eigen_count として,

名前 入出力 型 説明 既定値
solver 入力 integer(c_int) PARCEL_SOLVER_POWER, PARCEL_SOLVER_INVERSE_POWER, PARCEL_SOLVER_KS_ARNOLDIのいずれか —
eigval(*) 出力 real(c_double) 2*k要素. j 番目 (1 始まり) の固有値の実部がeigval(2*j-1), 虚部がeigval(2*j). power / inverse_power でも 2 要素要り, eigval(1)に固有値, eigval(2)に 0 が入る —
eigvec(*) 入出力 real(c_double) n_local*k要素. j 番目の固有ベクトルの担当行の部分がeigvec((j-1)*n_local+1 : j*n_local). 複素共役対は実部と虚部の 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_*

前提条件

戻り値 parcel_solve_linear と同じ. inverse_power と shift-invert ではres%linsolve_failuresが 0 でなければ内部線形ソルバが収束しなかった反復がある. ks_arnoldi のres%ks_nconvは判定値を満たした固有対の数である.

MPI 集団操作 (parcel_solve_linear と同じ).

関連項目 parcel_eigen_count, 固有値ソルバの補足, ソルバごとの収束判定

例

integer(c_int) :: k
real(c_double), allocatable :: ev(:), v(:)
k = parcel_eigen_count(PARCEL_SOLVER_KS_ARNOLDI, opt)     ! = ks_k_keep
allocate(ev(2*k), v(n_local*k))                             ! ev は Re, Im 交互, v は列ごと
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)

19.7 parcel_eigen_count

概要 固有値ソルバが返す固有対の個数 k を返す. parcel_solve_eigenに渡す配列の大きさを決めるのに使う.

書式

k = parcel_eigen_count(solver, opt)      ! integer(c_int)

引数

名前 入出力 型 説明 既定値
solver 入力 integer(c_int) PARCEL_SOLVER_* —
opt 入力 type(parcel_options) 設定 (ks_arnoldi ではks_k_keepを使う) —

戻り値 power / inverse_power では 1, ks_arnoldi ではopt%ks_k_keep (このうち収束が保証されるのは先頭ks_nev個), 線形ソルバと不正な値では 0.

MPI 局所操作.

19.8 parcel_options_check() / parcel_result_check()

概要 Fortran の派生型とラッパの構造体の大きさが一致するかを確かめる.

書式

logical :: ok
ok = parcel_options_check() .and. parcel_result_check()

戻り値 一致すれば.true.. 内部で parcel_options_size() / parcel_result_size() とc_sizeofを比べる.

注意 自動では呼ばれないので, プログラムの最初で確かめるとよい. 一致しなければ, ラッパとモジュールを同じ版でビルドし直す.

19.9 parcel_options_size() / parcel_result_size()

概要 ラッパ側の構造体parcel_options, parcel_resultの大きさ [バイト] を返す.

書式

n = parcel_options_size()      ! integer(c_int)
n = parcel_result_size()

注意 構造体の大きさは版によって変わりうるので, ラッパ, モジュール, 利用者のプログラムは同じ版でビルドする.

19.10 parcel_get_version / parcel_version_string

概要 ライブラリの版を返す (C言語の parcel_get_version() / parcel_version_string() と同じ値).

書式

integer(c_int) :: major, minor, patch, ierr
character(len=32) :: str
ierr = parcel_get_version(major, minor, patch)   ! PARCEL_OK
call parcel_version_string(str)                  ! "1.2.0" (短ければ切り詰め, 残りは空白)

19.11 run_parcel_sycl_f() (非推奨)

概要 v1.0 の Fortran の API (旧 API). pcg でAx=bAx = bを解く. 互換のために残している. 新しく作るプログラムでは parcel_solve_linear を使う.

書式 モジュールには含まれないので, 次のインタフェースを利用者が書く. コミュニケータは参照渡し, nとnnzは値渡しであり, 整数の引数と配列は 64 ビット (integer(c_int64_t)) である. CRS は 0 始まりで渡す.

interface
   subroutine run_parcel_sycl(mpi_comm_f, n, nnz, crsA, crsCol, crsRow_ptr, vecx, vecb) &
        bind(c, name="run_parcel_sycl_f")
     use iso_c_binding
     implicit none
     integer(c_int) mpi_comm_f
     integer(c_int64_t), value :: n
     integer(c_int64_t), value :: nnz
     real(c_double) crsA(*)
     integer(c_int64_t) crsCol(*)
     integer(c_int64_t) crsRow_ptr(*)
     real(c_double) vecx(*)
     real(c_double) vecb(*)
   end subroutine run_parcel_sycl
end interface

引数 nは担当行数, nnzは担当行の非零要素数, crsAは行列要素, crsColは大域の列番号 (0 始まり), crsRow_ptrは行ポインタ (0 始まり), vecxは入力が初期値で出力が解, vecbは右辺である.

前提条件 担当範囲の先頭行は各ランクのnの累積和で求める. 全ランクの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 の 32 ビットから 64 ビットに変わった (利用者ガイドの「版と互換性」).

例

rowptr0 = rowptr - 1          ! 1 始まりの CRS を 0 始まりに直して渡す
col0    = col - 1
call run_parcel_sycl(MPI_COMM_WORLD, n_local, nnz_local, val, col0, rowptr0, x, b)