5 使用方法
SYCL版PARCELを C++, C言語, Fortran, Python から利用する方法を示す. 言語ごとの説明はタブで切り替えて表示する (選んだ言語はページを移っても保たれ, API リファレンスの言語の選択とも連動する). 各言語のタブは, その言語の説明だけを読めば使えるようにまとめている. C++, C言語, Fortran の節は同じ項目 (行列の設定, ベクトルの設定, 前処理の設定, 線形ソルバの呼び出し, 固有値ソルバの呼び出し, 精度の指定, MPI 分割, コンパイルと実行, 自分の行列を渡す) で構成しており, 言語間で対応する項目を比較できる. 自分の問題の行列を PARCEL に渡す方法 (三つ組からの CRS の作成, Matrix Market のファイルの読み込み, 各ランクへの配布, 分割の決め方) は, 各言語の節の最後の小節「自分の行列を渡す」に示す.
PARCEL 本体は C++ のヘッダライブラリである. C言語と Fortran からは, 同梱の C API (capi/parcel_sycl_c.h, 実装は capi/wrapper_parcel_sycl.cpp) と Fortran モジュール (capi/parcel_sycl_mod.f90) を通して, C++ の 7 種のソルバすべてを実行時に選んで呼び出せる. 言語ごとの違いを以下にまとめる. Python からは C言語・Fortran の API とは別のネイティブ層を通して呼ぶ. Python との違いは Python の節にまとめる.
| 項目 | C++ | C言語 / Fortran |
|---|---|---|
| 線形ソルバ | pcg, pbicgstab, pgmres, pcagmres | 同左 (parcel_solve_linear) |
| 固有値ソルバ | power, inverse_power, ks_arnoldi | 同左 (parcel_solve_eigen) |
| ソルバ・前処理・収束判定値・反復回数の指定 | 実行時 (ソルバクラスのメンバ関数) | 実行時 (構造体 parcel_options の値) |
| 精度 (混合精度) | テンプレート引数 | ラッパのコンパイル時マクロ. 入出力配列は double 固定 |
| 行列の入力配列 | set_crsMat() が列番号と値を書き換える |
書き換えない (ラッパ内で複製する) |
| 添字の始まり | 0 | 0 または 1 (index_base) |
| 複数本のベクトル (固有ベクトル) の並び | 1 本ずつ連続 (EigenVecの j 番目はj*n_localから) |
同じく 1 本ずつ連続 (列優先). Fortran のeigvec(n_local, k)の並びと一致し, 転置は不要 |
| MPI の行分割 | 任意 (ランクごとに nstart, nend). 行ブロックの被覆をset_crsMat()が検査する |
任意 (ランクごとに nstart, n_local). 行ブロックの被覆を検査する |
| 行番号・列番号などの整数 | PARCEL_INT (既定 64 ビット. -DPARCEL_INT32で 32 ビット). ライブラリ内部のランク内の添字はPARCEL_LINT (既定 32 ビット) |
64 ビット固定 (C はparcel_int, Fortran はinteger(parcel_int_kind)) |
| 行列・ベクトルの再利用 | オブジェクトを作って繰り返し使える | 呼び出しごとに SYCL キューの作成と行列の登録を行う |
| 収束状態 (収束したか・反復回数・残差) の取得 | ソルバクラスの取得関数 (is_converged(), get_converged_reason(), get_iterations() など) |
最後の引数の構造体 parcel_result (C は NULL, Fortran は省略可). 戻り値は引数検査などのエラーコードのみ |
pgmres の set_precon_space_output()・set_shift() (固有値ソルバが内部で用いる機能. C++ からは使える) と, 内部線形ソルバのスケーリング指定 (set_linsolve_scaling_matrix/vector) は C/Fortran からは指定できない (後者は自動決定となる).
5.1 C++
5.1.1 概要
Include/parcel_sycl.hpp をインクルードし, 次の順に呼び出す.
- in-order の
sycl::queueとparcel::comm(MPI コミュニケータ) を作る. キューはsycl::queue q{sycl::default_selector_v, sycl::property::queue::in_order{}};のようにin_orderプロパティを付けて作る (デバイスの選び方はsycl::queue q;と同じ). 理由はクイックスタートに示す. 検査は-DPARCEL_REQUIRE_IN_ORDER=0で外せるが推奨しない. parcel::matrixに CRS 形式の行列をset_crsMat()で登録する.parcel::vectorを作り, ホスト配列からsetValue()で値を写す.- ソルバクラス (
parcel::krylov::pcg等) を作り, 前処理・収束判定値・最大反復回数を設定する. solver<...>()を呼び, 結果をgetValue()でホスト配列に戻す.
MPI ありのビルドでは, 1 プロセスで実行する場合も MPI_Init() と parcel::comm が必要である (MPI なしのビルドではMPI_Init()は要らず, parcel::comm comm(&q);で作る. 「MPI なしのビルド」). 線形ソルバと固有値ソルバは同じ行列オブジェクトを共有でき, 呼び出しの違いは solver() の第 2, 第 3 引数の意味だけである.
以下に, 1 次元 Laplace 作用素の差分行列 (三重対角行列) を行分割して登録し, pcg で を解いた後, 同じ行列の固有値を ks_arnoldi で求める完全なプログラムを示す. 同様の例は examples/example_pcg_ks.cpp にある.
#include <cmath>
#include <iostream>
#include <vector>
#include "./Include/parcel_sycl.hpp"
int main(int argc, char *argv[]) {
MPI_Init(&argc, &argv);
// SYCL キュー: in-order で作る (PARCEL の前提)
sycl::queue q{sycl::default_selector_v, sycl::property::queue::in_order{}};
parcel::comm comm(MPI_COMM_WORLD,&q);
int myrank = comm.mpi_rank();
int nprocess = comm.mpi_size();
// ---- MPI 分割: 連続した行を各ランクに割り当てる ----
const PARCEL_INT n_global = 1000;
PARCEL_INT nper = n_global / nprocess;
PARCEL_INT nstart = nper*myrank;
PARCEL_INT nend = nper*(myrank+1)-1;
if(myrank == nprocess-1){ nend = n_global-1; } // 端数は最終ランク
PARCEL_INT n_local = nend - nstart + 1; // 担当行数
// ---- 行列の設定: 担当行の CRS (行ポインタは局所 0 始まり, 列番号は大域 0 始まり) ----
std::vector<PARCEL_INT> rowptr(n_local+1), col;
std::vector<double> val;
rowptr[0] = 0;
for(PARCEL_INT i = nstart; i <= nend; i++){
if(i > 0) { col.push_back(i-1); val.push_back(-1.0); }
col.push_back(i); val.push_back(2.0);
if(i < n_global-1){ col.push_back(i+1); val.push_back(-1.0); }
rowptr[i-nstart+1] = (PARCEL_INT)col.size();
}
parcel::matrix<parcel_double> A(&q);
A.set_crsMat<double>(&comm, nstart, nend, n_local, col.size(),
rowptr.data(), col.data(), val.data());
// 注意: この時点で col, val は局所番号に書き換えられている
// ---- ベクトルの設定 ----
std::vector<double> x_h(n_local, 0.0), b_h(n_local, 1.0);
parcel::vector<parcel_double> x(n_local,&q), b(n_local,&q);
x.setValue(x_h.data());
b.setValue(b_h.data());
// ---- 線形ソルバ (pcg) ----
parcel::krylov::pcg<
parcel_double, parcel_double, parcel_double, parcel_double // Tspmv,Tprecon,Taxpy,Tdot
> cg;
cg.set_tolerance(1.0e-9);
cg.set_max_iteration(10000);
cg.set_precon_algo(parcel::PRECON_JACOBI); // 前処理の設定
cg.set_jacobi(1);
q.wait();
cg.solver<
parcel_double, parcel_double, parcel_double, // Tmat,Tvecx,Tvecb
parcel_double, parcel_double, parcel_double // Tvec,Tprecon_mat,Tprecon_vec
>(A, x, b);
x.getValue(x_h.data()); q.wait();
if(!cg.is_converged()){ // 未収束でも solver() はエラーを返さない
if(myrank == 0)
std::cout << "pcg: " << parcel::krylov::converged_reason_name(cg.get_converged_reason())
<< " after " << cg.get_iterations() << " iterations" << std::endl;
MPI_Abort(MPI_COMM_WORLD, 1);
}
// ---- 固有値ソルバ (ks_arnoldi): 絶対値の大きい nev 個 ----
const PARCEL_INT m = 30, k_keep = 10, nev = 4;
parcel::krylov::ks_arnoldi<
parcel_double, parcel_double, parcel_double, parcel_double
> ks;
ks.set_ks_subspace(m, k_keep, nev);
ks.set_ks_max_restart(50);
ks.set_tolerance(1.0e-9);
ks.set_precon_spectrum(false); // 既定. true にすると set_precon_algo() の K で A K^-1 の固有値になる
std::vector<double> eval_h(2*k_keep, 0.0); // 実部・虚部が交互
std::vector<double> evec_h(n_local*k_keep, 0.0); // 先頭 n_local 要素が初期ベクトル
for(PARCEL_INT i = 0; i < n_local; i++){
double g = (double)(nstart + i);
evec_h[i] = 1.0 + 0.5*std::sin(0.317*g + 0.7) + 0.3*std::cos(0.181*g - 1.3);
}
parcel::vector<parcel_double> eval(2*k_keep,&q), evec(n_local*k_keep,&q);
eval.setValue(eval_h.data());
evec.setValue(evec_h.data());
q.wait();
ks.solver<parcel_double, parcel_double, parcel_double>(A, eval, evec);
eval.getValue(eval_h.data()); evec.getValue(evec_h.data()); q.wait();
if(myrank == 0){
std::cout << "ks_arnoldi: " << parcel::krylov::converged_reason_name(ks.get_converged_reason())
<< ", restarts = " << ks.get_iterations()
<< ", converged pairs = " << ks.get_ks_nconv() << "/" << nev << std::endl;
for(int j = 0; j < nev; j++)
std::cout << "lambda_" << j << " = " << eval_h[2*j] << " + i " << eval_h[2*j+1] << std::endl;
}
MPI_Finalize();
return 0;
}5.1.2 行列の設定
parcel::matrix<T> (T は保持精度) を作り, set_crsMat<Ttype>(comm, nstart, nend, n, nnz, rowptr, crsCol, val) で担当行の CRS 行列を登録する. Ttype は入力配列 val の型であり, 登録時に T へ変換される.
rowptr: 長さ n+1. 担当行の先頭を 0 とする局所の行ポインタ.crsCol: 長さ nnz. 大域の 0 始まり列番号.n,nnz: 担当行数 (= nend−nstart+1) と担当行の非零要素数.
set_crsMat() は crsCol と val をその場で書き換える (列番号を局所番号に変換し, 各行で自ランク列を前, 袖を後に並べ替える). rowptr は変更されない. 同じ配列から 2 つ目の行列 (例: shift-invert 用の ) を作ると列番号が二重に変換され, MPI 実行時に袖通信が壊れる. 複数の行列を作る場合は, 最初の set_crsMat() の前に配列を複製しておく.
set_crsMat() は登録の前に次の 4 点を検査する. 各ランクの判定を集団通信で集め, 1 つでも崩れていれば全ランクが同じ std::invalid_argument (崩れていたランクと内容を示すメッセージ) を投げる. 通常版と double-double の上位・下位を別配列で渡す版の両方で行う.
n == nend - nstart + 1であり, 1 行以上であること (0 行のランクは扱えない).rowptr[0] == 0,rowptrが単調非減少,rowptr[n] == nnzであること.- 全ランクの行ブロックが を隙間・重複なく覆うこと (ランク番号の順に並んでいなくてよい).
- 列番号が にあること.
費用は非零要素の走査 1 回と少数回の集団通信である. -DPARCEL_NO_CRS_CHECK=1 を付けると検査を外せる.
このほか, 入力の CRS は次の条件を満たす必要がある. これらは検査されないので, 満たさないと誤った結果を黙って返しうる. C言語・Fortran・Python の API でも同じである.
- 対称な行列でも, 上三角と下三角の両方の要素を格納する (片側だけを格納する形式は無い).
- 各行に対角要素を格納する (値が 0 でも格納する). Jacobi 系の前処理が対角要素を使う. 対角要素が格納されていない行があると, 前処理の結果は不正になる.
- 各行の列番号は昇順に並べ, 同じ列番号を 1 行に 2 回以上入れない.
5.1.3 ベクトルの設定
parcel::vector<T> v(n, &q) でデバイス上に長さ n のベクトルを確保し, setValue(ptr) でホスト配列から写し, getValue(ptr) でホストへ戻す. 長さは担当行数である. 線形ソルバでは solver(A, x, b) の x が初期値 (入力) と解 (出力), b が右辺である. 固有値ソルバでは第 2 引数が固有値, 第 3 引数が固有ベクトルであり, 大きさはソルバごとに異なる (「固有値ソルバの呼び出し」参照). resize(n, &q) で大きさを変更できる.
5.1.4 前処理の設定
前処理はソルバオブジェクトのメンバ関数で実行時に設定する. 全ソルバ (固有値ソルバを含む) に共通である.
| 関数 | 内容 |
|---|---|
set_precon_algo(algo) |
parcel::PRECON_NONE (0), PRECON_POINTJACOBI (1), PRECON_BLOCKJACOBI (2), PRECON_JACOBI (4) |
set_jacobi(iter) |
Jacobi 前処理の反復回数 (既定 1) |
set_blockjacobi(nblock) |
ブロック Jacobi 前処理の分割数. 呼ばない場合はデバイスから自動で決まる (CPU: ランクあたりスレッド数, GPU: 1 ブロック 2 行) |
set_scaling_matrix(flag) |
前処理行列のスケーリング. 呼ばない場合は自動 (ブロック Jacobi と半精度では有効, それ以外は無効) |
set_scaling_vector(flag) |
前処理ベクトルのスケーリング. 既定は同上 |
GPU での前処理の選び方は「ソルバの選び方」の「前処理」に示す. 固有値ソルバでは, これらの設定は set_precon_spectrum(true) を指定したときだけ使われ, 3 つのソルバとも ではなく の固有値を返す. 既定 (set_precon_spectrum(false)) では前処理の設定は使われず, の固有値を返す. inverse_power と ks_arnoldi の shift-invert の内部線形ソルバの前処理は, 別の関数 set_linsolve_precon_algo(), set_linsolve_blockjacobi(), set_linsolve_jacobi() で設定する (既定は Jacobi 前処理, 反復 1 回).
5.1.5 線形ソルバの呼び出し
4 種類のクラスはいずれも template<Tspmv, Tprecon, Taxpy, Tdot> であり, set_tolerance(tol) (相対残差の収束判定値, 既定 1.0e-8), set_max_iteration(itr) (既定 10000) を持つ. solver() のテンプレート引数はソルバにより数が異なる. クラスのテンプレート引数と, solver() のうち実引数から推論される Tmat, Tvecx, Tvecb 以外の引数は既定が parcel_double なので省略できる (例: parcel::krylov::pcg<> s; s.solver(A, x, b);).
| クラス | 固有の設定 | solver<...>(A, x, b) のテンプレート引数 |
|---|---|---|
parcel::krylov::pcg |
なし | Tmat, Tvecx, Tvecb, Tvec, Tprecon_mat, Tprecon_vec |
parcel::krylov::pbicgstab |
なし | 同上 |
parcel::krylov::pgmres |
set_restart(m) (既定 30), set_qr_algo(algo) (QR_CGS / QR_MGS. 既定 QR_MGS) |
同上 + TGS, THessenberg |
parcel::krylov::pcagmres |
set_restart(s,t) (既定 8,4), set_explicit_q(mode) (CAGMRES_Q_AUTO / CAGMRES_Q_EXPLICIT / CAGMRES_Q_IMPLICIT. 既定 CAGMRES_Q_AUTO), set_qr_algo(algo) (QR_CGS / QR_MGS / QR_CHOLESKYQR / QR_CAGMRES_CHOLESKYQR. 既定 QR_MGS. CAGMRES_Q_IMPLICITではQR_CHOLESKYQRかQR_CAGMRES_CHOLESKYQRで, 指定しなければQR_CHOLESKYQR) |
同上 + Tbasis, TcalcQR, THessenberg [, Todd_basis, Teven_basis] |
parcel::krylov::pgmres<parcel_double,parcel_double,parcel_double,parcel_double> gm;
gm.set_restart(8);
gm.set_qr_algo(parcel::qr::QR_MGS);
gm.set_tolerance(1.0e-9);
gm.set_max_iteration(10000);
gm.set_precon_algo(parcel::PRECON_JACOBI);
gm.solver<parcel_double,parcel_double,parcel_double,parcel_double,
parcel_double,parcel_double,
parcel_double,parcel_double // TGS, THessenberg
>(A, x, b);
if(!gm.is_converged() && myrank == 0){
std::printf("pgmres: %s, its = %d, residual = %.3e, true residual = %.3e\n",
parcel::krylov::converged_reason_name(gm.get_converged_reason()),
(int)gm.get_iterations(), gm.get_residual(), gm.get_true_residual());
}solver() は収束しなくても例外やエラーを返さないので, 結果を使う前に is_converged() (または get_converged_reason() > 0) で確かめる. 値は全ランクで同じである. get_iterations(), get_residual(), get_true_residual() の意味はソルバごとに異なる (API リファレンスの「収束状態の定数と標準出力」). 反復の途中経過と計算時間は rank 0 の標準出力に表示される.
設定関数に範囲外の値を与えた場合 (set_tolerance(0.0), set_precon_algo(3), set_restart(0) など) と, solver() の入口の検査 (in-order キュー, ks_arnoldi の部分空間の大きさ, pcagmres の の作り方と QR 分解の組合せなど) に違反した場合は std::invalid_argument を投げる. 検査する値の一覧は API リファレンスの「設定の扱いと例外」 に示す.
デバイスのメモリを確保できなかった場合は, util_sycl::device_bad_alloc (std::bad_alloc の派生) を投げる. what() は要求したバイト数と確保しようとした場所を含む. 確保に失敗するのは多くの場合一部のランクだけであり, 他のランクは次の集団通信で待ち続ける. 例外を捕まえた場合は処理を続けず, MPI_Abort() などで全体を止める.
5.1.6 固有値ソルバの呼び出し
固有値ソルバは solver(A, EigenValue, EigenVec) の形で呼ぶ. クラスのテンプレート引数は線形ソルバと同じ <Tspmv, Tprecon, Taxpy, Tdot> である.
| クラス | 求めるもの | EigenValue の大きさ | EigenVec の大きさ | solver のテンプレート引数 |
|---|---|---|---|---|
parcel::krylov::power |
絶対値最大の実固有値 1 個 | 1 以上 (先頭に格納) | n | Tmat, Teigen_val, Teigen_vec, Tvec, Tprecon_mat, Tprecon_vec |
parcel::krylov::inverse_power |
絶対値最小の実固有値 1 個 | 1 以上 (先頭に格納) | n | 同上 |
parcel::krylov::ks_arnoldi |
絶対値上位 nev 個 (σ 近傍も可) | 2·k_keep (実部・虚部が交互) | n·nev 以上 (書くのは min(k_keep, 要素数/n) 本. 入力時は先頭 n が初期ベクトル) | Tmat, Teigen_val, Teigen_vec [, Tprecon_mat, Tprecon_vec] |
power と inverse_power は初期ベクトルを内部で生成するため, EigenVec の入力値は使われない. 収束判定 (set_tolerance) は power / inverse_power では固有値の相対変化, ks_arnoldi では Ritz 残差 である. 固有値が複素共役対の場合, 対応する固有ベクトルは実部と虚部の 2 本として格納される.
// べき乗法 (逆べき乗法は power を inverse_power に替えるだけ)
parcel::krylov::power<parcel_double,parcel_double,parcel_double,parcel_double> pw;
pw.set_tolerance(1.0e-9);
pw.set_max_iteration(2000);
pw.set_precon_spectrum(false); // 既定: A の固有値. 前処理の設定は外側の反復に使われない
parcel::vector<parcel_double> lam(1,&q), v(n_local,&q);
pw.solver<parcel_double,parcel_double,parcel_double,
parcel_double,parcel_double,parcel_double>(A, lam, v);
double lam_h; lam.getValue(&lam_h); q.wait();
if(!pw.is_converged()){ /* 未収束 (DIVERGED_ITS など). pw.get_residual() は固有値の相対変化 */ }各ソルバ固有の設定は次のとおり.
- 3 ソルバ共通 :
set_precon_spectrum(true)で の固有値を返す ( はset_precon_algo()などで から作る). 既定 (false) では の固有値を返し, は外側の固有値反復に使われない. - inverse_power : 内部線形ソルバは既定で右前処理 pgmres であり,
set_linsolve_tolerance(tol)(既定 1.0e-10),set_linsolve_max_iteration(itr)(既定 5000),set_linsolve_restart(m)(既定 30),set_linsolve_precon_algo(algo)(既定parcel::PRECON_JACOBI, 反復 1 回),set_linsolve_blockjacobi(nblock),set_linsolve_jacobi(iter)で制御する.set_linsolve_algo(parcel::krylov::LINSOLVE_PCG)で pcg に替えられる ( が対称定値の場合.set_precon_spectrum(true)時は常に pgmres). - ks_arnoldi :
set_ks_subspace(m, k_keep, nev)(既定 30, 10, 4. でなければstd::invalid_argument),set_ks_max_restart(R)(既定 200), 直交化set_qr_algo(algo)(parcel::qr::QR_CGSで CGS2 (既定),QR_MGSで MGS2. 「ks_arnoldi の直交化の既定」). σ 近傍の固有値は shift-invert で求める.set_shift(σ)を呼び, 第 4 引数に を渡す (内部線形ソルバの前処理 はこの行列から作る). 第 4 引数を省くと とシフト σ から解く (このとき で,set_linsolve_precon_algo()は使われない). 内部 pgmres は inverse_power と同じset_linsolve_*(最大反復回数の既定は 2000) で制御する (非推奨の別名set_shift_linsolve_tolerance,set_shift_linsolve_max_iteration,set_shift_linsolve_restartも使える).set_precon_spectrum(true)を併用すると の σ 近傍の固有値を返し, 第 4 引数は不要となる.
// shift-invert: A - σI を別の配列から登録する (set_crsMat が配列を書き換えるため)
// A 用の set_crsMat() を呼ぶ前に, 原本 (col, val) を複製しておく
std::vector<PARCEL_INT> col0 = col;
std::vector<double> val0 = val;
// ... A.set_crsMat(..., col.data(), val.data()) ... (col, val は書き換えられる)
std::vector<PARCEL_INT> col_s = col0;
std::vector<double> val_s = val0;
const double sigma = -13.0;
for(PARCEL_INT i = nstart; i <= nend; i++)
for(PARCEL_INT p = rowptr[i-nstart]; p < rowptr[i-nstart+1]; p++)
if(col_s[p] == i){ val_s[p] -= sigma; break; }
parcel::matrix<parcel_double> As(&q);
As.set_crsMat<double>(&comm, nstart, nend, n_local, col_s.size(),
rowptr.data(), col_s.data(), val_s.data());
ks.set_shift(sigma);
ks.solver<parcel_double,parcel_double,parcel_double>(A, eval, evec, &As);
if(!ks.is_converged() || ks.get_linsolve_failures() > 0){
/* 外側の未収束, または内部 pgmres の未収束 (set_linsolve_* を見直す) */
}固有値ソルバでも is_converged() などで収束を確かめる. ks_arnoldi の get_ks_nconv() は判定値を満たした固有対の数 (nev 個のうち) である. inverse_power と shift-invert の内部線形ソルバの確かめ方 (get_linsolve_failures()) は「収束状態の確かめ方」に示す.
5.1.7 精度の指定
精度はテンプレート引数で指定する. 型は parcel_fp16, parcel_float, parcel_double, parcel_doubledouble である.
- データ精度 :
parcel::matrix<T>,parcel::vector<T>の T と,solver<Tmat, Tvecx, Tvecb, Tvec, ...>. - 計算精度 : クラスの
Tspmv,Taxpy,Tdot. - 前処理 : クラスの
Tprecon(計算精度) とsolverのTprecon_mat,Tprecon_vec(データ精度).
テンプレート引数は省略でき, 省略した精度は parcel_double になる. 対象は parcel::matrix<>, parcel::vector<>, クラスの 4 引数, solver() のうち実引数から推論できないデータ精度 (Tvec, Tprecon_mat, Tprecon_vec, pgmres の TGS, THessenberg, pcagmres の Tbasis, TcalcQR, THessenberg) である (ks_arnoldi の Tprecon_mat, Tprecon_vec の既定は Teigen_vec). 例えば parcel::krylov::pcg<> s; s.solver(A, x, b); はすべて倍精度で解き, 固有値ソルバも s.solver(A, ev, evec) と書ける. 明示した引数の意味は省略の有無で変わらない.
検証用サンプル (tests/verify/parcel_krylov_sample_verify.cpp) と C言語・Fortran のラッパではこれらを parcel_solver_data_type, parcel_solver_calc_type, parcel_solver_calc_precon_type, parcel_solver_data_precon_mat_type, parcel_solver_data_precon_vec_type の各マクロ (既定はすべて parcel_double) で与えており, -D で変更できる. 低精度・double-double での制約は「低精度での既知の限界」と「double-double」に, -ffast-math を使えない理由は「-ffast-math を使わない」に示す.
5.1.8 MPI 分割
行列は行ブロックで分割する. 各ランクは連続した行 nstart〜nend (0 始まり, 両端を含む) を担当し, その行の CRS と長さ nend−nstart+1 のベクトルを持つ. ランクごとの行数は異なってよい (上の例では最終ランクが端数を持つ). 行ブロックはランク番号の順に並んでいなくてよいが, 全ランクで を隙間・重複なく覆い, 各ランクの行数は 1 以上でなければならない. set_crsMat() がこれを検査する (「行列の設定」). 袖通信のテーブルは set_crsMat() が列番号から自動で作る (仕組みは「基本構成」の章の「GPU・MPI ランク・データの対応」). 通信には parcel::comm に渡した MPI コミュニケータが使われ, MPI_COMM_WORLD 以外も指定できる.
5.1.9 コンパイルと実行
コンパイル方法は「インストール」の章による. 既定では全ソルバが入るので, 線形ソルバのみを使う場合も lapacke.h が必要であり, -I/usr/include/openblas と -lopenblas (または LAPACKE の該当パスとライブラリ) を指定する. -DPARCEL_ENABLE_KS_ARNOLDI=0 で ks_arnoldi を外せば不要である (「ビルドするソルバの取捨」). -Dpcg_solver 等のソルバ選択マクロは検証用サンプルの既定のソルバを選ぶものであり, 上のように自分でクラスを使うプログラムには不要である.
export MPICXX_CXX=acpp OMPI_CXX=acpp
mpicxx -O3 --acpp-targets=cuda:sm_70 -I/usr/include/openblas -o run main.cpp -lopenblas
mpirun -n 4 ./run AdaptiveCpp の CPU 向けビルド (--acpp-targets=omp) で, PARCEL をインクルードしたのと同じソースファイルにitem.barrier()を使うnd_rangeカーネルを自分で書くと, std::function<void()>を通して投げた例外 (PARCEL の設定関数のstd::invalid_argumentなど) がcatchに届かず, std::terminateで止まる. 自前のカーネルではitem.barrier()の代わりに::util_sycl::group_barrier(item)を使う.
5.1.10 検証用サンプルの実行時オプション
tests/verify/parcel_krylov_sample_verify.cpp は, 製造解または密行列直接解法 (LAPACK dgesv) による参照解と比較して解の正しさを検証するサンプルである. 1 回のビルドで全ソルバ・前処理を試せるよう, 以下の環境変数で実行時に設定を変えられる. 同じ指定をコマンドライン引数 KEY=VALUE でも与えられる (mpirun -n 4 ./run PARCEL_NX=256 PARCEL_SOLVER=pcg). 環境変数が複数ノードに転送されない MPI 環境ではこちらを使う. 両方ある場合は環境変数が優先される.
| オプション | 既定 | 説明 |
|---|---|---|
PARCEL_SOLVER |
コンパイル時の -D<名前>_solver. 無指定なら pcg |
pcg, pbicgstab, pgmres, pcagmres, power, inverse_power, ks_arnoldi. ビルドから外したソルバを指定すると異常終了する. cholqr_pcagmresは受け付けず, 代わりの指定 (PARCEL_CAGMRES_Q=implicit) を表示して異常終了する |
PARCEL_CAGMRES_Q |
auto |
pcagmres の直交基底の作り方 (set_explicit_q()). auto, explicit, implicit. implicitでは QR 分解をQR_CHOLESKYQRにする (CAGMRES_QR_ALGOは使わない). それ以外の値は異常終了する |
PARCEL_CHOLQR_MOMENT |
0 | 1 で QR 分解をモーメント法 (QR_CAGMRES_CHOLESKYQR) にする. PARCEL_CAGMRES_Q=implicitのときだけ使え, それ以外で pcagmres を解くと異常終了する |
PARCEL_NX |
NX (240) |
格子の 1 辺. 未知数は NX³ |
PARCEL_MATRIX |
poisson (-DMATRIX_CONVDIFF 時は convdiff) |
poisson (3 次元 7 点, 対称), convdiff (移流拡散, 非対称. convdiff2 も同じ), unstruct (行あたり非零 4〜10 の非対称行列) |
PARCEL_CONVDIFF_C |
CONVDIFF_C (0.05) |
移流拡散行列の移流係数 |
PARCEL_VERIFY |
1 | 0 で検証処理を省く (性能測定用. 右辺は b=1) |
PARCEL_TOL |
VERIFY_TOLERANCE (1.0e-9) |
set_tolerance() に渡す収束判定値 |
PARCEL_MAX_ITER |
MAX_ITERATION (10000) |
set_max_iteration() に渡す最大反復回数. 既定はライブラリの既定と同じ |
PARCEL_PRECON |
parcel_solver_precon_algo (0) |
前処理. 0: なし, 1: ポイント Jacobi, 2: ブロック Jacobi, 4: Jacobi |
PARCEL_SCALING_MATRIX |
自動 | 0/1. 前処理行列のスケーリングを明示指定 (前処理ありのときのみ有効) |
PARCEL_SCALING_VECTOR |
自動 | 0/1. 前処理ベクトルのスケーリングを明示指定 (同上) |
PARCEL_BJ_BLOCK |
自動 | ブロック Jacobi の分割数. BLOCKJACOBI_BLOCK は -DBLOCKJACOBI_BLOCK_EXPLICIT 付きビルドでのみ使われる |
PARCEL_PRECON_SYMCHECK |
0 | 0 以外で前処理の対称性 を検査する |
PARCEL_KS_M |
KS_M (30) |
ks_arnoldi の部分空間の最大次元 |
PARCEL_KS_K_KEEP |
KS_K_KEEP (10) |
ks_arnoldi のリスタート時に保持する Ritz 対の数 |
PARCEL_KS_NEV |
KS_NEV (4) |
ks_arnoldi の収束判定対象の固有値数 |
PARCEL_KS_RESTART |
KS_MAX_RESTART (50) |
ks_arnoldi の最大リスタート回数. default でset_ks_max_restart()を呼ばず, ライブラリの既定 (200) を使う |
PARCEL_KS_QR |
未指定 (ライブラリの既定) | ks_arnoldi の直交化. cgs でset_qr_algo(QR_CGS) (CGS2), mgs でset_qr_algo(QR_MGS) (MGS2) を呼ぶ. 未指定ならset_qr_algo()を呼ばず, ビルド時の既定 (「ks_arnoldi の直交化の既定」) を使う. 使った方式をks_qr_algo = ...の行に出す. それ以外の文字列は異常終了する |
PARCEL_GMRES_RESTART |
GMRES_RESTART (8) |
pgmres のリスタート周期. default でset_restart()を呼ばず, ライブラリの既定 (30) を使う |
PARCEL_CAGMRES_S / PARCEL_CAGMRES_T |
CAGMRES_RESTART_S (8) / CAGMRES_RESTART_T (1) |
pcagmres の・. PARCEL_CAGMRES_S=defaultでset_restart()を呼ばず, ライブラリの既定 (8, 4) を使う (このときPARCEL_CAGMRES_Tは見ない) |
PARCEL_PRECON_SPECTRUM |
0 | 1 で固有値ソルバ (power, inverse_power, ks_arnoldi) が の固有値を求める (set_precon_spectrum(true)) |
PARCEL_LINSOLVE_PRECON |
ライブラリの既定 (4) | inverse_power と ks_arnoldi の shift-invert の内部線形ソルバの前処理 (set_linsolve_precon_algo()). 値は PARCEL_PRECON と同じ. 未指定なら設定関数を呼ばず, ライブラリの既定 (Jacobi 前処理) を使う. PARCEL_PRECON_SPECTRUM=1 では使わない |
PARCEL_LINSOLVE_SOLVER |
pgmres |
inverse_power の内部線形ソルバ. pgmres または pcg (set_linsolve_algo()) |
PARCEL_KS_SHIFT |
無効 | σ を与えると ks_arnoldi の shift-invert を実行時に有効にする (set_shift(σ) のみでシフト行列は渡さない). PARCEL_PRECON_SPECTRUM=1 では の, それ以外では の σ 近傍の固有値を求める. 後者の内部 pgmres は前処理なし () で, PARCEL_LINSOLVE_PRECON は効かない. -DKS_SHIFT_INVERT 付きビルドでは無視 |
PARCEL_KS_SIGMA |
KS_SIGMA (0.0) |
-DKS_SHIFT_INVERT 付きビルドでのみ有効. の σ |
PARCEL_INNER_TOL |
INVPOW_LINSOLVE_TOL (1.0e-10) |
inverse_power の内部解法と ks_arnoldi の shift-invert 内部 pgmres の収束判定値 |
PARCEL_INNER_MAX |
INVPOW_LINSOLVE_MAX (5000) |
同上の最大反復回数 |
PARCEL_PRECISION |
コンパイル時の精度 | -DPARCEL_RUNTIME_PRECISION 付きビルドでのみ有効. double, calcF16, dataF16, precon_calcF16, calcF, dataF, precon_calcF, calcDD, dataDD |
PARCEL_LIB_DEFAULTS |
0 | 1 でソルバのパラメータの設定関数 (set_tolerance, set_max_iteration, set_restart, set_qr_algo, set_explicit_q, set_ks_subspace, set_ks_max_restart, 内部ソルバの set_linsolve_*, set_jacobi) をサンプルの値で呼ばず, ライブラリの既定で解く. 環境変数で明示した値はそのまま使い, 実際に使った値を [LIB_DEFAULTS] の行に出す. 同梱の性能試験が使う |
PARCEL_OUTPUT |
parcel_result.txt |
rank 0 の標準出力の複製先ファイル. none で書かない |
PARCEL_MEM_REPORT |
未設定 | 設定するとソルバの終了後にランクごとに, ホストのピーク常駐メモリ (と大きいページ (HugeTLB) の量HugetlbPages), GPU のデバイスメモリ使用量 (nvidia-smiで読む. NVIDIA GPU のみ), PARCEL が確保したデバイスメモリのピークを[MEM]の行に表示し, 全ランクの値を rank 0 が[MEMG]の行とmem_gather.txtに書く (rank 0 の設定で決まる). ライブラリの記録も有効になる (下の表) |
次のソルバの設定はコンパイル時に-D<マクロ>=<値>で与える (既定値はtests/verify/parcel_default.hpp). ライブラリの既定値とは異なるものがある. リスタート周期は実行時にPARCEL_GMRES_RESTART・PARCEL_CAGMRES_S・PARCEL_CAGMRES_Tで上書きでき, 値にdefaultを与えるとライブラリの既定を使う (上の表).
| マクロ | サンプルの既定 | ライブラリの既定 | 説明 |
|---|---|---|---|
GMRES_RESTART |
8 | 30 | pgmres のリスタート周期 (set_restart()) |
GMRES_QR_ALGO |
parcel::qr::QR_MGS |
QR_MGS |
pgmres の直交化の方法 (set_qr_algo()) |
CAGMRES_RESTART_S |
8 | 8 | pcagmres の (set_restart(s, t)) |
CAGMRES_RESTART_T |
1 | 4 | pcagmres の |
CAGMRES_QR_ALGO |
parcel::qr::QR_MGS |
QR_MGS |
pcagmres の QR 分解の方法 (set_qr_algo()). PARCEL_CAGMRES_Q=implicitでは使わない |
サンプルの既定は回帰試験で用いる値であり, GMRES_RESTART (8), CAGMRES_RESTART_T (1), ks_arnoldi のKS_MAX_RESTART (50) などはライブラリの既定 (30, 4, 200) と異なる. 自分のプログラムでは, 設定関数を呼ばずにライブラリの既定から始め, 必要なものだけを変えるのがよい. サンプルをライブラリの既定で動かすにはPARCEL_LIB_DEFAULTS=1を付ける.
次の環境変数はライブラリ本体 (Include/) が読むため, サンプルに限らず全言語 (C言語・Fortran ラッパ経由を含む) で有効である.
| 環境変数 | 既定 | 説明 |
|---|---|---|
PARCEL_NBLOCK |
OpenMP スレッド数 | CPU カーネルの分割数 (ブロック Jacobi 分割数の自動値にも使われる) |
PARCEL_PSTEP |
1 (-DPARCEL_PCG_NO_XHIST=0でビルドすると 4) |
pcg で解ベクトルをまとめて更新する反復数. 既定の 1 では探索方向を 1 本だけ持ち, 毎反復更新する. 4 にすると探索方向の履歴を 4 本持ち, 解の読み書きが 1/4 になって少し速くなる代わりにベクトル 3 本分のメモリを使う (最適化オプション「G なし」. 「メモリと速さの選択」). 2 以上では間の反復の真の残差は意味を持たない. 解の足し合わせ方が変わるので丸めは変わる (反復回数は同じ) |
PARCEL_PRECON_VERBOSE |
未設定 | 設定すると自動決定された前処理のスケーリング有無を表示する |
PARCEL_TIMER_SYNC |
未設定 (0) | 1 で内積と, 係数を値で渡す axpy の時間計測の前後にデバイスを同期する. 既定では同期しないので, 内積の時間に直前のカーネルの時間が入る. 時間の内訳を正確に取るときに使う (ソルバ全体の時間は少し延びる) |
PARCEL_MEM_REPORT |
未設定 | 設定すると PARCEL が USM で確保したデバイスメモリの現在量とピークを数える (util_sycl:・device_mem_peak_bytes()で読める. SYCL ランタイム自身の確保は含まない. CPU のバックエンドではホストメモリのうち PARCEL の配列の分) |
5.1.11 自分の行列を渡す
PARCEL に渡す行列は, 各ランクが担当する行の CRS である (形式は基本構成の「データ構造」). 自分の問題の行列をこの形にする方法を示す.
5.1.11.1 三つ組 (COO) から CRS を作る
有限要素法などでは, 行列を (行, 列, 値) の三つ組 (COO 形式) で組み立てることが多い. 次の関数は, 担当行の三つ組から CRS を作る. 三つ組を行・列の順に並べ, 同じ (行, 列) が複数回ある場合 (要素ごとの寄与の足し込み) は値を足し合わせる. 結果は各行の列番号が昇順で重複が無い, PARCEL が求める形になる.
#include <algorithm>
#include <vector>
#include "./Include/parcel_sycl.hpp" // PARCEL_INT
struct Triplet { PARCEL_INT row, col; double val; }; // 行と列は大域の 0 始まり
// 担当行 [nstart, nstart + n_local) の三つ組 t から CRS (rowptr, col, val) を作る
void coo_to_crs(PARCEL_INT nstart, PARCEL_INT n_local, std::vector<Triplet> t,
std::vector<PARCEL_INT>& rowptr, std::vector<PARCEL_INT>& col,
std::vector<double>& val)
{
std::sort(t.begin(), t.end(), [](const Triplet& a, const Triplet& b) {
return a.row != b.row ? a.row < b.row : a.col < b.col; });
rowptr.assign(n_local + 1, 0);
col.clear();
val.clear();
for (size_t k = 0; k < t.size(); ++k) {
if (k > 0 && t[k].row == t[k-1].row && t[k].col == t[k-1].col) {
val.back() += t[k].val; // 同じ (行, 列) は足し合わせる
continue;
}
col.push_back(t[k].col);
val.push_back(t[k].val);
rowptr[t[k].row - nstart + 1]++; // 行ごとの非零数を数える
}
for (PARCEL_INT i = 0; i < n_local; ++i) rowptr[i + 1] += rowptr[i];
}- 三つ組は担当行のものだけを渡す (
nstart <= row < nstart + n_local). - 対角要素が無い行がありうる場合は, 先に各行に (i, i, 0.0) を加えておく (対角要素は値が 0 でも格納する).
- 対称な行列でも, 上三角と下三角の両方の要素を入れる.
5.1.11.2 Matrix Market のファイルを読む
Matrix Market 形式 (拡張子 .mtx) は, 疎行列を交換するための文字の形式である. 読むときの要点を示す.
- 1 行目は
%%MatrixMarket matrix coordinate real generalのような見出しで,%で始まる注釈の行の後に「行数 列数 非零数」の行, 続いて 1 行に 1 つずつ「行 列 値」(1 始まり) が並ぶ (座標形式coordinate). - 見出しが
symmetricの場合, ファイルには片側の三角 (通常は下三角) だけが書かれている. 対角以外の要素は (列, 行) にも同じ値を加えて両三角にする (skew-symmetricでは符号を反転する). pattern(値が無い) とcomplexの形式は PARCEL では扱えない (PARCEL は実数の行列を解く).- 行と列から 1 を引いて 0 始まりにし, 読んだ三つ組のうち担当行のものだけを残して, 上の
coo_to_crsで CRS にする.
5.1.11.3 大域の行列を各ランクに配る
MPI ありでは, 各ランクが担当行の CRS だけをset_crsMat()に渡す. 用意の仕方は 2 通りある.
- 各ランクが担当行だけを作る: 差分法の行列のように式から作れる場合は, 各ランクが担当行の範囲だけを生成する. 大域の行列をどこにも持たないので, メモリが最も少ない. 同梱の例 (
examples/quick_start.cpp,examples/example_pcg_ks.cpp) はこの形である. - 大域の行列から担当行を切り出す: ファイルから読んだ場合など, 大域の CRS (
grp,gcol,gval. 0 始まり) が手元にあれば, 行 nstart〜nend の部分は配列の連続した範囲 (grp[nstart]からgrp[nend + 1]の手前まで) である. 局所の行ポインタはgrp[nstart + i] - grp[nstart], 列番号は大域のまま渡す. 全ランクが同じファイルを読んで担当行だけを残すか, 1 つのランクが読んでMPI_Scattervで配る.
set_crsMat()は渡した列番号と値の配列を書き換えるので (「行列の設定」), 大域の配列から切り出した部分は別の配列に写してから渡す.
// 大域の CRS (0 始まり) から行 [nstart, nend] を切り出し, 別の配列に写して登録する
const PARCEL_INT off = grp[nstart], n_local = nend - nstart + 1;
std::vector<PARCEL_INT> rowptr(n_local + 1);
for (PARCEL_INT i = 0; i <= n_local; ++i) rowptr[i] = grp[nstart + i] - off;
std::vector<PARCEL_INT> col(gcol.begin() + off, gcol.begin() + grp[nend + 1]);
std::vector<double> val(gval.begin() + off, gval.begin() + grp[nend + 1]);
A.set_crsMat<double>(&comm, nstart, nend, n_local, col.size(),
rowptr.data(), col.data(), val.data());5.1.11.4 分割の決め方
各ランクの行は連続していればよく, 行数はランクごとに異なってよい (「MPI 分割」). 分け方は次の点を考えて決める.
- 1 反復の時間の大半は SpMV と前処理で, その量は非零数に比例する. 内積などの集団操作で全ランクが最も遅いランクを待つので, 行ごとの非零数の偏りが大きい行列では, 行数ではなく非零数がそろうように分ける. 大域の行ポインタ
grpを使い, ランク () の先頭行を, 非零数の累計が以上になる最初の行とすればよい (各ランクに 1 行以上を残す). - 行ごとの非零数がほぼ同じ行列 (差分法の格子など) では, 行数を均等に分ければよい.
- 袖通信の量は, 他のランクの列を参照する非零の数で決まる. 格子の問題では, 近い格子点に近い行番号を付けると (番号付けの工夫), 袖が少なくなる.
- 各ランクのメモリも担当行の非零数にほぼ比例する. GPU のメモリが足りない場合は, ランク (GPU) を増やして 1 ランクの行を減らす.
5.2 C言語
5.2.1 概要
C言語からは capi/parcel_sycl_c.h をインクルードし, 次の関数を呼ぶ. 実装は capi/wrapper_parcel_sycl.cpp であり, 内部で C++ のライブラリを呼び, 7 種のソルバすべてを実行時に選んで呼び出せる.
| 関数 | 内容 |
|---|---|
parcel_options_init(&opt) |
オプション構造体 parcel_options に既定値を入れる |
parcel_solve_linear(solver, &opt, comm, ...) |
線形方程式 を解く (pcg, pbicgstab, pgmres, pcagmres) |
parcel_solve_eigen(solver, &opt, comm, ...) |
固有値問題 (precon_spectrum=1 では ) を解く (power, inverse_power, ks_arnoldi) |
parcel_eigen_count(solver, &opt) |
固有値ソルバが返す固有対の個数 k |
parcel_solver_from_name(name) |
ソルバ名 ("pcg", "ks_arnoldi" など) から PARCEL_SOLVER_* を得る. 不明なら -1 |
parcel_options_size(), parcel_result_size() |
sizeof(parcel_options), sizeof(parcel_result) を返す (Fortran の派生型との照合用) |
run_parcel_sycl_c(...) |
旧 API (v1.0 との互換. pcg のみ) |
ソルバはPARCEL_SOLVER_PCGなどの定数で指定する. 定数, 構造体, 各関数の引数・戻り値の仕様は API リファレンスの「C言語の API」に示す. 行番号・列番号・行数・非零要素数の型は 64 ビットのparcel_intである.
呼び出しの手順は次のとおりである.
- MPI ありのビルドでは
MPI_Init()を済ませる (1 プロセスで実行する場合も必要. MPI なしのビルドでは要らない). parcel_options opt; parcel_options_init(&opt);で既定値を入れ, 必要な項目だけ変更する. 構造体を初期化せずに使ってはならない.- 各ランクが担当する行の CRS 配列とベクトルを用意する.
parcel_solve_linear()またはparcel_solve_eigen()をコミュニケータの全ランクで呼び, 戻り値を確かめる.- 最後の引数に渡した
parcel_resultのconverged_reasonで, 反復が収束したかを確かめる.
呼び出しごとに SYCL キュー (既定デバイスの in-order キュー) の作成と行列の登録を行う. デバイスは ACPP_VISIBILITY_MASK など SYCL 実装の環境変数で選ぶ. opt.verbose = 1 とすると rank 0 がデバイス名とソルバ・前処理・収束判定値を表示する.
設定は構造体parcel_optionsの項目で与える (全項目と既定値はリファレンスの parcel_options). parcel_options_init()が入れる既定値はライブラリの既定値である. 関数は引数を検査し, エラーを戻り値 (PARCEL_OK または負のエラーコード) で知らせる. 引数検査の結果は全ランクで同じになる. ライブラリの中でエラーが起きた場合 (デバイスのメモリ不足など) は, MPI ありのビルドでは全ランクをMPI_Abortで終了させる. 戻り値は反復が収束したかどうかを含まないので, 最後の引数に渡したparcel_resultのconverged_reason (正なら収束) を確かめる (戻り値と収束状態の定数, parcel_result).
同梱の sample_c.c は, 3 次元 7 点 Poisson 行列 (中心 -6, 隣接 1, 行) を不均等に行分割し, 7 種のソルバすべて (pcagmres は を作る既定の方式に加えて, を作らない方式 (cagmres_q_mode = PARCEL_CAGMRES_Q_IMPLICIT) を CholeskyQR とモーメント法の 2 通り) と ks_arnoldi の shift-invert, 旧 API を呼んで, 結果を相対残差または解析固有値と比べて PASS / FAIL を表示するプログラムである. 以下の各項ではその一部を示す.
5.2.2 行列の設定
各ランクは大域行番号が連続する行ブロック [nstart, nstart + n_local - 1] を CRS 形式で渡す. 引数 (n_local, nstart, n_global, nnz_local, rowptr, col, val) の意味はリファレンスの parcel_solve_linear() に示す. nstartとcolはindex_baseの番号付けで, colは大域の列番号である. 行ポインタはrowptr[0]からの差だけを使う.
整数は parcel_int (parcel_sycl_c.h で int64_t と定義. 64 ビット) である. ライブラリ内部の PARCEL_INT によらず 64 ビットであり, 行ポインタと列番号の配列も parcel_int で確保する (int の配列は渡せない). ラッパを -DPARCEL_INT32 でビルドした場合 (インストールの「整数型」) に値が 32 ビットに収まらなければ, 配列を確保する前に全ランクで PARCEL_ERR_ARG を返す. parcel_options と parcel_result の項目と parcel_eigen_count() の戻り値は int である. ラッパ, parcel_sycl_mod.f90, 利用者のプログラムは同じ版の parcel_sycl_c.h でそろえてビルドする. ラッパは入力配列を複製してから登録するので, col と val は書き換えられない. 同じ配列で続けて別のソルバを呼んでよい. 呼び出し時には, 行ポインタが非減少で rowptr[n_local] - rowptr[0] == nnz_local であること, 列番号と行範囲が に収まることを検査し, 満たさなければ PARCEL_ERR_ARG を返す. 行列の各行は, 列番号が昇順で重複が無く, 対角要素を (値が 0 でも) 含み, 対称な行列でも両方の三角を含むようにする (基本構成の「データ構造」).
/* sample_c.c: 大域行 [rstart, rstart+nrow) の CRS を 0 始まりで作る (col == NULL なら数えるだけ) */
static parcel_int poisson_rows(parcel_int nx, parcel_int rstart, parcel_int nrow,
parcel_int *rowptr, parcel_int *col, double *val){
parcel_int nnz = 0;
rowptr[0] = 0;
for(parcel_int r = 0; r < nrow; r++){
const parcel_int g = rstart + r;
const parcel_int ix = g % nx, iy = (g / nx) % nx, iz = g / (nx * nx);
#define PUT(c, v) do{ if(col){ col[nnz] = (c); val[nnz] = (v); } nnz++; }while(0)
if(iz > 0) PUT(g - nx * nx, 1.0);
if(iy > 0) PUT(g - nx, 1.0);
if(ix > 0) PUT(g - 1, 1.0);
PUT(g, -6.0);
if(ix < nx - 1) PUT(g + 1, 1.0);
if(iy < nx - 1) PUT(g + nx, 1.0);
if(iz < nx - 1) PUT(g + nx * nx, 1.0);
#undef PUT
rowptr[r + 1] = nnz;
}
return nnz;
}5.2.3 ベクトルの設定
ベクトルはすべて担当行ぶんのローカル部分であり, double の配列で受け渡す. デバイスへの転送と書き戻しはラッパ内で行う.
- 線形ソルバ :
b(長さn_local) が右辺,x(長さn_local) が入力時は初期値, 出力時は解である. - 固有値ソルバ : k =
parcel_eigen_count(solver, &opt)として,eigvalに2*k要素,eigvecにn_local*k要素を用意する. k は power / inverse_power では 1, ks_arnoldi ではks_k_keep(このうち収束が保証されるのは先頭ks_nev個) である.eigval: 実部と虚部を交互に格納する (eigval[2*j]が j 番目の固有値の実部,eigval[2*j+1]が虚部). power / inverse_power ではeigval[0]に固有値,eigval[1]に 0 が入る.eigvec: 列優先で,eigvec + j*n_localからのn_local要素が j 番目の固有ベクトルの担当行ぶんである. 固有値が複素共役対の場合, 対応する固有ベクトルは実部と虚部の 2 本として連続して格納される.- 初期ベクトル : power / inverse_power は内部で生成する. ks_arnoldi は既定 (
eigvec_seed=0) ではラッパが大域行番号から作るので, 結果は行分割のしかたに依らない.eigvec_seed=1のときはeigvecの先頭n_local要素を初期ベクトルとして使う.
5.2.4 前処理の設定
前処理は parcel_options の項目で実行時に設定する.
| 項目 | 内容 (既定値) |
|---|---|
precon_algo |
前処理の種類. PARCEL_PRECON_NONE (既定), PARCEL_PRECON_POINTJACOBI, PARCEL_PRECON_BLOCKJACOBI, PARCEL_PRECON_JACOBI |
jacobi_iter |
Jacobi 前処理の反復回数 (1). Jacobi 前処理のときだけ使う |
blockjacobi |
ブロック Jacobi 前処理のブロック数 (0 = 自動) |
scaling_matrix, scaling_vector |
前処理の行列とベクトルのスケーリング. -1 (既定) は自動, 0 は無効, 1 は有効 |
linsolve_precon_algo, linsolve_jacobi_iter, linsolve_blockjacobi |
inverse_power と ks_arnoldi の shift-invert の内部線形ソルバの前処理 (既定は Jacobi 前処理, 反復 1 回) |
固有値ソルバでは, precon_algo などの設定は precon_spectrum=1 のときの の にだけ使われる. 内部線形ソルバの前処理は linsolve_precon_* で設定する (precon_spectrum=1 では使われず, 内部も で前処理する).
5.2.5 線形ソルバの呼び出し
parcel_solve_linear()のsolverにPARCEL_SOLVER_PCG, _PBICGSTAB, _PGMRES, _PCAGMRESのいずれかを与える. 共通に使う項目はtolerance (収束判定値, 既定 1.0e-8), max_iteration (最大反復回数, 既定 10000) と前処理の項目であり, pgmres はgmres_restart (既定 30), gmres_qr_algoを, pcagmres はcagmres_s, cagmres_t (既定 8, 4), cagmres_qr_algo, cagmres_q_modeを使う (リファレンス). 反復の途中経過と計算時間は rank 0 の標準出力に表示される. 収束状態はres.converged_reason, 反復回数はres.iterations, 残差はres.residualとres.true_residualに入る.
/* sample_c.c より: 線形ソルバをブロック Jacobi 前処理で呼ぶ
(最後の 2 つは pcagmres の Q を作らない方式. QR 分解の選び方だけが違う) */
const int lin_solvers[6] = { PARCEL_SOLVER_PCG, PARCEL_SOLVER_PBICGSTAB,
PARCEL_SOLVER_PGMRES, PARCEL_SOLVER_PCAGMRES,
PARCEL_SOLVER_PCAGMRES, PARCEL_SOLVER_PCAGMRES };
for(int s = 0; s < 6; s++){
parcel_options opt;
parcel_options_init(&opt);
opt.tolerance = 1.0e-9;
opt.max_iteration = 10000;
opt.precon_algo = PARCEL_PRECON_BLOCKJACOBI;
opt.gmres_restart = 8; /* 既定 30 */
opt.gmres_qr_algo = PARCEL_QR_MGS;
opt.cagmres_s = 8;
opt.cagmres_t = 1; /* 既定 4 */
opt.cagmres_qr_algo = PARCEL_QR_MGS; /* 既定と同じ */
if(s == 4){
/* Q を作らない方式: CholeskyQR. t = 2 でブロック間の直交化も通す */
opt.cagmres_t = 2;
opt.cagmres_q_mode = PARCEL_CAGMRES_Q_IMPLICIT;
opt.cagmres_qr_algo = PARCEL_QR_CHOLESKYQR;
}else if(s == 5){
/* モーメント法: A が対称 (ここでは成り立つ), 前処理なし, s が偶数 */
opt.precon_algo = PARCEL_PRECON_NONE;
opt.cagmres_t = 2;
opt.cagmres_q_mode = PARCEL_CAGMRES_Q_IMPLICIT;
opt.cagmres_qr_algo = PARCEL_QR_CAGMRES_CHOLESKYQR;
}
for(parcel_int i = 0; i < n_local; i++) x[i] = 0.0;
parcel_result res;
const int rc = parcel_solve_linear(lin_solvers[s], &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_*) */
printf("reason = %d, its = %d, residual = %.3e, true residual = %.3e\n",
res.converged_reason, res.iterations, res.residual, res.true_residual);
}
} v1.0 の C言語の API である旧 APIrun_parcel_sycl_c()も互換のために残している (pcg のみ. 設定はラッパのコンパイル時のマクロで決まる. リファレンス). 新しく作るプログラムではparcel_solve_linear()を用いる.
この例のgmres_restart = 8, cagmres_t = 1は検証用サンプルと同じ値で, ライブラリの既定 (30, 4) ではない. 自分のプログラムでは, parcel_options_init()が入れた既定から始め, 必要な項目だけを変えるのがよい.
5.2.6 固有値ソルバの呼び出し
parcel_solve_eigen()のsolverにPARCEL_SOLVER_POWER, _INVERSE_POWER, _KS_ARNOLDIのいずれかを与える. 返る固有対の個数 k はparcel_eigen_count()で得て (ks_arnoldi の部分空間の大きさks_m, ks_k_keep, ks_nevの既定は 30, 10, 4, 最大リスタート回数ks_max_restartの既定は 200, 直交化の方式ks_qr_algoはPARCEL_QR_CGSで CGS2, PARCEL_QR_MGSで MGS2), eigval (2*k要素. 実部と虚部が交互) とeigvec (n_local*k要素. 列優先) を用意する. 求める固有値, 使う項目, shift-invert (shift_enable, shift_sigma. ks_arnoldi のみ) とprecon_spectrumの扱いはリファレンスの parcel_solve_eigen()に示す. precon_spectrum=0の shift-invert では, ラッパがを組み立てるので, 利用者が用意する必要はない.
/* sample_c.c より: ks_arnoldi の shift-invert (σ = -0.15 近傍の 4 個) */
parcel_options opt;
parcel_options_init(&opt);
opt.tolerance = 1.0e-8; /* Ritz 残差 */
opt.ks_m = 30;
opt.ks_k_keep = 10;
opt.ks_nev = 4;
opt.ks_max_restart = 100;
opt.shift_enable = 1; /* precon_spectrum=0: ラッパが (A - σI) を組む */
opt.shift_sigma = -0.15;
opt.linsolve_tolerance = 1.0e-11;
opt.linsolve_max_iteration = 5000; /* 既定 (0) では ks_arnoldi の 2000 */
opt.linsolve_restart = 30;
opt.linsolve_precon_algo = PARCEL_PRECON_BLOCKJACOBI;
const int k = parcel_eigen_count(PARCEL_SOLVER_KS_ARNOLDI, &opt); /* = ks_k_keep */
double *ev = (double *)malloc(sizeof(double) * 2 * k); /* Re, Im 交互 */
double *v = (double *)malloc(sizeof(double) * (size_t)n_local * k); /* 列優先 */
parcel_result res;
const 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);
if(rc == PARCEL_OK && res.converged_reason <= 0){
/* 未収束: res.ks_nconv 個だけが判定値を満たした. res.linsolve_failures も確かめる */
}
for(int j = 0; j < opt.ks_nev; j++){
const double re = ev[2 * j], im = ev[2 * j + 1];
const double *vj = v + (size_t)j * n_local; /* j 番目の固有ベクトル (担当行ぶん) */
/* ... */
}power と inverse_power では double ev[2] と長さ n_local の v を渡せばよい.
5.2.7 精度の指定
入出力配列は double に固定である. PARCEL 内部のデータ精度・演算精度は, capi/wrapper_parcel_sycl.cpp をコンパイルするときのマクロで決まり, 実行時や呼び出しごとには変更できない. マクロの名前は検証用サンプルと同じで, 既定値は capi/parcel_capi_default.hpp にあり, すべて parcel_double である.
| マクロ | 用途 |
|---|---|
parcel_solver_data_type |
行列・ベクトルのデータ精度 |
parcel_solver_calc_type |
演算精度 |
parcel_solver_calc_precon_type |
前処理の演算精度 |
parcel_solver_data_precon_mat_type |
前処理行列のデータ精度 |
parcel_solver_data_precon_vec_type |
前処理ベクトルのデータ精度 |
parcel_solver_calc_qr_type |
pcagmres の QR 分解の精度 |
例えば演算を単精度にする場合は, ラッパのコンパイル時に -Dparcel_solver_calc_type=parcel_float を付ける. 使える精度の組み合わせは基本構成の「精度構成」に, 低精度での制約は「低精度での既知の限界」に示す.
5.2.8 MPI 分割
第 3 引数 comm に MPI コミュニケータ (MPI_Comm) を渡す. MPI_COMM_WORLD 以外も指定できる. 関数は集団操作を含むため, コミュニケータの全ランクで同じ solver と同じ内容のオプションを与えて呼ぶ. MPI なしのビルドでのコミュニケータの扱いは「MPI なしのビルド」に示す.
各ランクの行ブロックは連続した行であればよく, ランクごとに行数が異なってよい. 行ブロックはランク番号の順に並んでいる必要はないが, 全ランクの行ブロックを合わせたものが を重複・欠落なく覆わなければならない. ラッパは各ランクの (nstart, n_local) を MPI_Allgather で集めてこれを検査し, 満たさなければ全ランクで PARCEL_ERR_DISTRIBUTION を返す. 各ランクの n_local は 1 以上とする.
/* sample_c.c より: ランク r に重み (r+1) で行を配る不均等分割 */
const long long W = (long long)np * (np + 1) / 2;
long long acc = 0;
for(int r = 0; r < np; r++){
const int s = (int)((long long)n_global * acc / W);
acc += r + 1;
const int e = (int)((long long)n_global * acc / W);
displs[r] = s; counts[r] = e - s;
}
const parcel_int nstart = displs[myrank];
const parcel_int n_local = counts[myrank];5.2.9 コンパイルと実行
ラッパ capi/wrapper_parcel_sycl.cpp を SYCL 対応コンパイラでコンパイルし, C の main と SYCL 対応コンパイラでリンクする. 手で行う手順は, MPI あり・なしともクイックスタートの「C言語」に, 環境ごとのフラグはインストールの「C言語・Fortran のプログラム」に示す. examples/build_examples.sh は, 同じ手順で examples/ のサンプル (sample_c, sample_f など) をまとめてビルドする (生成物は examples/build/. コンパイラ・ターゲット・LAPACK は環境変数で変える).
export OMPI_CXX=acpp
bash examples/build_examples.sh # MPI あり (MPI なしは PARCEL_MPI=0 bash examples/build_examples.sh)
mpirun -n 3 examples/build/sample_c 16 # 引数は NX (既定 16) 旧 API run_parcel_sycl_c の反復上限はラッパのマクロ MAX_ITERATION (既定 10000) で決まり, 新 API には影響しない. 内部精度を変える場合は, ラッパのコンパイルに精度のマクロを加える (examples/build_examples.sh では環境変数 WRAPPER_FLAGS で与える). ビルドするソルバを PARCEL_ENABLE_* で絞った場合, 外したソルバを指定すると PARCEL_ERR_NOT_BUILT が返る.
sample_c は各ソルバの結果を 1 行ずつ PASS / FAIL で表示し (7 ソルバ, を作らない pcagmres の 2 通り (pcagmres(implicit), pcagmres(impl,sym)), ks_arnoldi の shift-invert, 旧 API, 最初に版の確認 (version) の計 12 項目), 1 つでも失敗すると終了コード 1 を返す.
5.2.10 自分の行列を渡す
PARCEL に渡す行列は, 各ランクが担当する行の CRS である (形式は基本構成の「データ構造」). 自分の問題の行列をこの形にする方法を示す.
5.2.10.1 三つ組 (COO) から CRS を作る
有限要素法などでは, 行列を (行, 列, 値) の三つ組 (COO 形式) で組み立てることが多い. 次の関数は, 担当行の三つ組から CRS を作る. 三つ組を行・列の順に並べ, 同じ (行, 列) が複数回ある場合は値を足し合わせる. 結果は各行の列番号が昇順で重複が無い, PARCEL が求める形になる.
#include <stdlib.h>
#include "parcel_sycl_c.h" /* parcel_int */
typedef struct { parcel_int row, col; double val; } triplet; /* 行と列は大域の 0 始まり */
static int cmp_triplet(const void *pa, const void *pb){
const triplet *a = (const triplet *)pa, *b = (const triplet *)pb;
if(a->row != b->row) return a->row < b->row ? -1 : 1;
if(a->col != b->col) return a->col < b->col ? -1 : 1;
return 0;
}
/* 担当行 [nstart, nstart + n_local) の三つ組 t[0..nt) から CRS (rowptr, col, val) を作り, 非零数を返す.
rowptr は n_local + 1 要素, col と val は nt 要素を確保しておく. t は並べ替えられる */
parcel_int coo_to_crs(parcel_int nstart, parcel_int n_local, triplet *t, size_t nt,
parcel_int *rowptr, parcel_int *col, double *val){
qsort(t, nt, sizeof(triplet), cmp_triplet);
for(parcel_int i = 0; i <= n_local; i++) rowptr[i] = 0;
parcel_int nnz = 0;
for(size_t k = 0; k < nt; k++){
if(k > 0 && t[k].row == t[k-1].row && t[k].col == t[k-1].col){
val[nnz - 1] += t[k].val; /* 同じ (行, 列) は足し合わせる */
continue;
}
col[nnz] = t[k].col;
val[nnz] = t[k].val;
nnz++;
rowptr[t[k].row - nstart + 1]++; /* 行ごとの非零数を数える */
}
for(parcel_int i = 0; i < n_local; i++) rowptr[i + 1] += rowptr[i];
return nnz;
}- 三つ組は担当行のものだけを渡す (
nstart <= row < nstart + n_local). 返す非零数をnnz_localとして渡す. - 対角要素が無い行がありうる場合は, 先に各行に (i, i, 0.0) を加えておく (対角要素は値が 0 でも格納する).
- 対称な行列でも, 上三角と下三角の両方の要素を入れる.
5.2.10.2 Matrix Market のファイルを読む
Matrix Market 形式 (拡張子 .mtx) は, 疎行列を交換するための文字の形式である. fgetsとsscanfなどで読むときの要点を示す.
- 1 行目は
%%MatrixMarket matrix coordinate real generalのような見出しで,%で始まる注釈の行の後に「行数 列数 非零数」の行, 続いて 1 行に 1 つずつ「行 列 値」(1 始まり) が並ぶ (座標形式coordinate). - 見出しが
symmetricの場合, ファイルには片側の三角 (通常は下三角) だけが書かれている. 対角以外の要素は (列, 行) にも同じ値を加えて両三角にする (skew-symmetricでは符号を反転する). pattern(値が無い) とcomplexの形式は PARCEL では扱えない (PARCEL は実数の行列を解く).- 行と列は 1 始まりのまま
opt.index_base = 1にして渡すか, 1 を引いて 0 始まりにする. 読んだ三つ組のうち担当行のものだけを残し, 上のcoo_to_crsで CRS にする.
5.2.10.3 大域の行列を各ランクに配る
MPI ありでは, 各ランクが担当行の CRS だけを渡す. 用意の仕方は 2 通りある.
- 各ランクが担当行だけを作る: 差分法の行列のように式から作れる場合は, 各ランクが担当行の範囲だけを生成する. 大域の行列をどこにも持たないので, メモリが最も少ない. 同梱の例 (
examples/quick_start_c.c,examples/sample_c.cのpoisson_rows) はこの形である. - 大域の行列から担当行を切り出す: ファイルから読んだ場合など, 大域の CRS (
grp,gcol,gval. 0 始まり) が手元にあれば, 行 [nstart,nstart + n_local) の部分は配列の連続した範囲である. 行ポインタはrowptr[0]からの差だけが使われ, ラッパは入力配列を書き換えないので, 大域の配列の途中をそのまま渡せる. 全ランクが同じファイルを読むか, 1 つのランクが読んでMPI_Scattervで配る.
/* 大域の CRS から行 [nstart, nstart + n_local) を切り出して渡す */
parcel_int off = grp[nstart];
parcel_int nnz_local = grp[nstart + n_local] - off;
rc = parcel_solve_linear(PARCEL_SOLVER_PCG, &opt, MPI_COMM_WORLD, n_local, nstart, n_global,
nnz_local, &grp[nstart], &gcol[off], &gval[off], b, x, &res);5.2.10.4 分割の決め方
各ランクの行は連続していればよく, 行数はランクごとに異なってよい (「MPI 分割」). 分け方は次の点を考えて決める.
- 1 反復の時間の大半は SpMV と前処理で, その量は非零数に比例する. 内積などの集団操作で全ランクが最も遅いランクを待つので, 行ごとの非零数の偏りが大きい行列では, 行数ではなく非零数がそろうように分ける. 大域の行ポインタ
grpを使い, ランク () の先頭行を, 非零数の累計が以上になる最初の行とすればよい (各ランクに 1 行以上を残す). - 行ごとの非零数がほぼ同じ行列 (差分法の格子など) では, 行数を均等に分ければよい.
- 袖通信の量は, 他のランクの列を参照する非零の数で決まる. 格子の問題では, 近い格子点に近い行番号を付けると (番号付けの工夫), 袖が少なくなる.
- 各ランクのメモリも担当行の非零数にほぼ比例する. GPU のメモリが足りない場合は, ランク (GPU) を増やして 1 ランクの行を減らす.
5.3 Fortran
5.3.1 概要
Fortran からはモジュール parcel_sycl_mod (capi/parcel_sycl_mod.f90) を use し, 次の手続きを呼ぶ. 実装は C++ のライブラリを呼ぶラッパ capi/wrapper_parcel_sycl.cpp であり, 7 種のソルバすべてを実行時に選んで呼び出せる.
| 手続き | 内容 |
|---|---|
call parcel_options_init(opt) |
設定の派生型 parcel_options に既定値を入れる |
rc = parcel_solve_linear(solver, opt, comm, ...) |
線形方程式 を解く (pcg, pbicgstab, pgmres, pcagmres) |
rc = parcel_solve_eigen(solver, opt, comm, ...) |
固有値問題 (precon_spectrum=1 では ) を解く (power, inverse_power, ks_arnoldi) |
k = parcel_eigen_count(solver, opt) |
固有値ソルバが返す固有対の個数 k |
parcel_options_check(), parcel_result_check() |
派生型の大きさがラッパの構造体と一致するかを返す (論理値) |
run_parcel_sycl_f(...) |
旧 API (v1.0 との互換. pcg のみ) |
ソルバはPARCEL_SOLVER_PCGなどの定数で指定する. 定数, 派生型の項目, 各手続きの引数・戻り値の仕様は API リファレンスの「Fortran の API」に示す. 行番号・列番号・行数・非零要素数は 64 ビットの整数 integer(parcel_int_kind) で渡す.
呼び出しの手順は次のとおりである.
- MPI ありのビルドでは
MPI_Initを済ませる (1 プロセスで実行する場合も必要. MPI なしのビルドでは要らない). parcel_options_check()とparcel_result_check()で, 派生型とラッパの構造体の大きさが一致することを確かめる (一致しなければ, ラッパとモジュールの版が食い違っている).call parcel_options_init(opt)で既定値を入れ, 必要な項目だけopt%toleranceのように変更する. 初期化せずに使ってはならない.- 各ランクが担当する行の CRS 配列とベクトルを用意する.
parcel_solve_linearまたはparcel_solve_eigenをコミュニケータの全ランクで呼び, 戻り値がPARCEL_OKであることを確かめる.- 最後の引数に渡した
parcel_resultのres%converged_reasonで, 反復が収束したか (正なら収束) を確かめる.resは省略できる.
呼び出しごとに SYCL キュー (既定デバイスの in-order キュー) の作成と行列の登録を行う. デバイスは ACPP_VISIBILITY_MASK など SYCL 実装の環境変数で選ぶ. opt%verbose = 1 とすると rank 0 がデバイス名とソルバ・前処理・収束判定値を表示する.
parcel_options_initが入れる既定値はライブラリの既定値である (全項目と既定値はリファレンスの parcel_options). 手続きは引数を検査し, エラーを戻り値 (PARCEL_OK または負のエラーコード) で知らせる. 引数検査の結果は全ランクで同じになる. ライブラリの中でエラーが起きた場合 (デバイスのメモリ不足など) は, MPI ありのビルドでは全ランクをMPI_Abortで終了させる. 戻り値は反復が収束したかどうかを含まないので, res%converged_reasonを確かめる.
! sample_f.f90 より
program sample_f
use mpi
use iso_c_binding
use parcel_sycl_mod
implicit none
type(parcel_options) :: opt
type(parcel_result) :: res
integer :: rc, ierr
integer(parcel_int_kind) :: n_local, nstart, n_global, nnz_local ! 64 ビット
integer(parcel_int_kind), allocatable :: rowptr(:), col(:)
! ...
call MPI_Init(ierr)
! Fortran の型と C の struct の大きさを照合
if(.not. parcel_options_check() .or. .not. parcel_result_check()) then
call MPI_Abort(MPI_COMM_WORLD, 2, ierr)
end if
! ...
call parcel_options_init(opt)
opt%index_base = 1 ! nstart / col を 1 始まりで渡す
opt%tolerance = 1.0d-9
opt%max_iteration = 10000
opt%precon_algo = PARCEL_PRECON_BLOCKJACOBI
opt%gmres_restart = 8 ! 既定 30
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_*). res%iterations, res%residual, res%true_residual を見る
end if 同梱の sample_f.f90 は, 3 次元 7 点 Poisson 行列 (中心 -6, 隣接 1, 行) を不均等に行分割し, 7 種のソルバすべてと ks_arnoldi の shift-invert, 旧 API を呼んで, 結果を相対残差または解析固有値と比べて PASS / FAIL を表示するプログラムである. 以下の各項ではその一部を示す.
5.3.2 行列の設定
各ランクは大域行番号が連続する行ブロック (nstartからn_local行) を CRS 形式で渡す. 引数は次のとおりである (詳細はリファレンスの parcel_solve_linear).
| 引数 | 内容 |
|---|---|
n_local |
このランクが担当する行数 (1 以上) |
nstart |
担当する最初の行の大域行番号 (index_baseの番号付け) |
n_global |
行列全体の行数 |
nnz_local |
担当行の非零要素数 |
rowptr(n_local+1) |
行ポインタ. rowptr(1)からの差だけを使う |
col(nnz_local) |
大域の列番号 (index_baseの番号付け) |
val(nnz_local) |
行列要素 |
整数の引数と整数配列 (rowptr, col) は integer(parcel_int_kind) (= integer(c_int64_t). 64 ビット) で, 行列要素は real(c_double) (real(8)) で渡す. 値渡しの引数に既定の integer の変数を渡すとインタフェースが一致せずコンパイルエラーになるので, 変数を integer(parcel_int_kind) で宣言するか, int(n, parcel_int_kind) で変換して渡す. opt%index_base = 1 とすれば, nstart と列番号 col を Fortran 流の 1 始まりで渡せる. 行ポインタ rowptr は先頭からの差だけを使うので, rowptr(1) = 1 の 1 始まりのままでよい.
ラッパは入力配列を複製してから登録するので, col と val は書き換えられない. 同じ配列で続けて別のソルバを呼んでよい. 呼び出し時には, 行ポインタが非減少でrowptr(n_local+1) - rowptr(1)がnnz_localに等しいこと, 列番号と行範囲が行列の範囲に収まることを検査し, 満たさなければPARCEL_ERR_ARGを返す. 行列の各行は, 列番号が昇順で重複が無く, 対角要素を (値が 0 でも) 含み, 対称な行列でも両方の三角を含むようにする (基本構成の「データ構造」). ラッパを -DPARCEL_INT32 でビルドした場合 (インストールの「整数型」) に値が 32 ビットに収まらなければ, 全ランクで PARCEL_ERR_ARG を返す.
! sample_f.f90 より: 大域行 [rstart, rstart+nrow-1] (1 始まり) の CRS を 1 始まりで作る
! rstart, nrow, r, g, ix, iy, iz, nnz, rowptr(:), col(:) は integer(parcel_int_kind)
nnz = 0
rowptr(1) = 1
do r = 1, nrow
g = rstart + r - 1 ! 1 始まり大域行
ix = mod(g-1, nx); iy = mod((g-1)/nx, nx); iz = (g-1)/(nx*nx)
if(iz > 0) call put(g - nx*nx, 1.0d0)
if(iy > 0) call put(g - nx, 1.0d0)
if(ix > 0) call put(g - 1, 1.0d0)
call put(g, -6.0d0)
if(ix < nx - 1) call put(g + 1, 1.0d0)
if(iy < nx - 1) call put(g + nx, 1.0d0)
if(iz < nx - 1) call put(g + nx*nx, 1.0d0)
rowptr(r+1) = nnz + 1
end do5.3.3 ベクトルの設定
ベクトルはすべて担当行ぶんのローカル部分であり, real(8) の配列で受け渡す. デバイスへの転送と書き戻しはラッパ内で行う.
- 線形ソルバ :
b(長さn_local) が右辺,x(長さn_local) が入力時は初期値, 出力時は解である. - 固有値ソルバ : k =
parcel_eigen_count(solver, opt)としてeigval(2*k)とeigvec(n_local*k)を用意する. k は power / inverse_power では 1, ks_arnoldi ではopt%ks_k_keep(このうち収束が保証されるのは先頭opt%ks_nev個) である.- j 番目 (1 始まり) の固有値の実部は
eigval(2*j-1), 虚部はeigval(2*j)である. power / inverse_power でもeigvalは 2 要素必要である (虚部は 0). - j 番目の固有ベクトルの担当行ぶんは
eigvec((j-1)*n_local+1 : j*n_local)である (eigvec(n_local, k)と宣言すれば j 列目). 固有値が複素共役対の場合, 対応する固有ベクトルは実部と虚部の 2 本として連続して格納される. - 初期ベクトル : power / inverse_power は内部で生成する. ks_arnoldi は既定 (
opt%eigvec_seed = 0) ではラッパが大域行番号から作るので, 結果は行分割のしかたに依らない.opt%eigvec_seed = 1のときはeigvecの先頭n_local要素を初期ベクトルとして使う.
- j 番目 (1 始まり) の固有値の実部は
5.3.4 前処理の設定
前処理は parcel_options の項目で実行時に設定する.
| 項目 | 内容 (既定値) |
|---|---|
opt%precon_algo |
前処理の種類. PARCEL_PRECON_NONE (既定), PARCEL_PRECON_POINTJACOBI, PARCEL_PRECON_BLOCKJACOBI, PARCEL_PRECON_JACOBI |
opt%jacobi_iter |
Jacobi 前処理の反復回数 (1). Jacobi 前処理のときだけ使う |
opt%blockjacobi |
ブロック Jacobi 前処理のブロック数 (0 = 自動) |
opt%scaling_matrix, opt%scaling_vector |
前処理の行列とベクトルのスケーリング. -1 (既定) は自動, 0 は無効, 1 は有効 |
opt%linsolve_precon_algo, opt%linsolve_jacobi_iter, opt%linsolve_blockjacobi |
inverse_power と ks_arnoldi の shift-invert の内部線形ソルバの前処理 (既定は Jacobi 前処理, 反復 1 回) |
固有値ソルバでは, opt%precon_algoなどの設定はopt%precon_spectrum = 1のときののにだけ使われる. 内部線形ソルバの前処理はopt%linsolve_precon_*で設定する (opt%precon_spectrum = 1では使われず, 内部もで前処理する).
5.3.5 線形ソルバの呼び出し
parcel_solve_linearは整数 (戻り値) を返す関数であり, solverにPARCEL_SOLVER_PCG, PARCEL_SOLVER_PBICGSTAB, PARCEL_SOLVER_PGMRES, PARCEL_SOLVER_PCAGMRESのいずれかを与える. 共通に使う項目はopt%tolerance (収束判定値, 既定 1.0e-8), opt%max_iteration (最大反復回数, 既定 10000) と前処理の項目であり, pgmres はopt%gmres_restart (既定 30), opt%gmres_qr_algoを, pcagmres はopt%cagmres_s, opt%cagmres_t (既定 8, 4), opt%cagmres_qr_algo, opt%cagmres_q_modeを使う (リファレンス). xは入力時に初期値, 出力時に解である. 反復の途中経過と計算時間は rank 0 の標準出力に表示される. 収束状態はres%converged_reason, 反復回数はres%iterations, 残差はres%residualとres%true_residualに入る.
上の例のopt%gmres_restart = 8は検証用サンプルと同じ値で, ライブラリの既定 (30) ではない. 自分のプログラムでは, parcel_options_initが入れた既定から始め, 必要な項目だけを変えるのがよい.
v1.0 の Fortran の API である旧 APIrun_parcel_sycl_fも互換のために残している (pcg のみ). モジュールには含まれないので, インタフェースを利用者が書く (リファレンス). 新しく作るプログラムではparcel_solve_linearを用いる.
5.3.6 固有値ソルバの呼び出し
parcel_solve_eigenのsolverにPARCEL_SOLVER_POWER, PARCEL_SOLVER_INVERSE_POWER, PARCEL_SOLVER_KS_ARNOLDIのいずれかを与える. 返る固有対の個数 k はparcel_eigen_countで得る. ks_arnoldi ではopt%ks_m, opt%ks_k_keep, opt%ks_nev (部分空間の最大次元, 保持する Ritz 対の数, 求める固有値の数. 既定 30, 10, 4), opt%ks_max_restart (既定 200), 直交化の方式opt%ks_qr_algo (PARCEL_QR_CGSで CGS2, PARCEL_QR_MGSで MGS2) を使う. シフトの近くの固有値は shift-invert (opt%shift_enable = 1, opt%shift_sigma. ks_arnoldi のみ) で求める. opt%precon_spectrum = 0の shift-invert では, ラッパがを組み立てるので, 利用者が用意する必要はない. 内部線形ソルバはopt%linsolve_tolerance, opt%linsolve_max_iteration, opt%linsolve_restart (0 以下はソルバの既定値) で設定する. 項目の詳細はリファレンスの parcel_solve_eigenに示す.
! sample_f.f90 より: ks_arnoldi の shift-invert (σ = -0.15 近傍の 4 個)
call parcel_options_init(opt)
opt%index_base = 1
opt%tolerance = 1.0d-8
opt%ks_m = 30
opt%ks_k_keep = 10
opt%ks_nev = 4
opt%ks_max_restart = 100
opt%shift_enable = 1
opt%shift_sigma = -0.15d0
opt%linsolve_tolerance = 1.0d-11
opt%linsolve_max_iteration = 5000 ! 既定 (0) では ks_arnoldi の 2000
opt%linsolve_restart = 30
opt%linsolve_precon_algo = PARCEL_PRECON_BLOCKJACOBI
k = parcel_eigen_count(PARCEL_SOLVER_KS_ARNOLDI, opt)
nev = opt%ks_nev
allocate(ev(2*k), v(n_local*k))
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)
if(rc == PARCEL_OK .and. res%converged_reason <= 0) then
! 未収束: res%ks_nconv 個だけが判定値を満たした. res%linsolve_failures も確かめる
end if
do j = 1, nev
! 固有値 ev(2*j-1) + i ev(2*j), 固有ベクトル v((j-1)*n_local+1 : j*n_local)
end do power と inverse_power では ev(2) と長さ n_local の v を渡せばよい.
5.3.7 精度の指定
入出力配列は real(8) (real(c_double)) に固定である. PARCEL 内部のデータ精度・演算精度は, ラッパ capi/wrapper_parcel_sycl.cpp をコンパイルするときのマクロで決まり, 実行時や呼び出しごとには変更できない. 既定値は capi/parcel_capi_default.hpp にあり, すべて parcel_double (倍精度) である.
| マクロ | 用途 |
|---|---|
parcel_solver_data_type |
行列・ベクトルのデータ精度 |
parcel_solver_calc_type |
演算精度 |
parcel_solver_calc_precon_type |
前処理の演算精度 |
parcel_solver_data_precon_mat_type |
前処理行列のデータ精度 |
parcel_solver_data_precon_vec_type |
前処理ベクトルのデータ精度 |
parcel_solver_calc_qr_type |
pcagmres の QR 分解の精度 |
例えば演算を単精度にする場合は, ラッパのコンパイル時に -Dparcel_solver_calc_type=parcel_float を付ける. 使える精度の組み合わせは基本構成の「精度構成」に, 低精度での制約は「低精度での既知の限界」に示す.
5.3.8 MPI 分割
コミュニケータは Fortran の整数ハンドル (mpi モジュールの MPI_COMM_WORLD など) をそのまま渡す. MPI_COMM_WORLD 以外も渡せる. 手続きは集団操作を含むため, コミュニケータの全ランクで同じ solver と同じ内容のoptを与えて呼ぶ. MPI なしのビルドでのコミュニケータの扱いは「MPI なしのビルド」に示す.
各ランクの行ブロックは連続した行であればよく, ランクごとに行数が異なってよい. 行ブロックはランク番号の順に並んでいる必要はないが, 全ランクの行ブロックを合わせたものが行列の全行を重複・欠落なく覆わなければならない. ラッパは各ランクの (nstart, n_local) を集めてこれを検査し, 満たさなければ全ランクで PARCEL_ERR_DISTRIBUTION を返す. 各ランクの n_local は 1 以上とする. index_base = 1 のときは nstart も 1 始まりで与える.
! sample_f.f90 より: ランク r に重み (r+1) で行を配る
w = int(nprocs, 8) * (nprocs + 1) / 2
acc = 0
do r = 0, nprocs - 1
displs(r) = int(n_global * acc / w)
acc = acc + r + 1
counts(r) = int(n_global * acc / w) - displs(r)
end do
n_local = counts(myrank) ! n_global, n_local, nstart は integer(parcel_int_kind)
nstart = displs(myrank) + 1 ! 1 始まり5.3.9 コンパイルと実行
モジュール capi/parcel_sycl_mod.f90 と利用者のプログラムを Fortran のコンパイラ (MPI ありは mpif90) でコンパイルし (モジュールを先にコンパイルする), ラッパ capi/wrapper_parcel_sycl.cpp を SYCL 対応コンパイラでコンパイルしたオブジェクトとともに SYCL 対応コンパイラでリンクする. リンク時には Fortran の実行時ライブラリ (MPI ありは MPI の Fortran ライブラリも) を加える. 手で行う手順は, MPI あり・なしともクイックスタートの「Fortran」に, 環境ごとのフラグはインストールの「C言語・Fortran のプログラム」に示す. examples/build_examples.sh も同じ手順で sample_f を作る.
export OMPI_CXX=acpp
bash examples/build_examples.sh # MPI あり (MPI なしは PARCEL_MPI=0 bash examples/build_examples.sh)
mpirun -n 3 examples/build/sample_f 16 # 引数は NX (既定 16) sample_f は 7 ソルバ, を作らない pcagmres の 2 通り, ks_arnoldi の shift-invert, 旧 API, 最初に版の確認の計 12 項目を 1 行ずつ PASS / FAIL で表示し, CRS を 1 始まり (index_base = 1) で渡す.
富士通 Fortran (frt, mpifrt) で利用者のプログラムをコンパイルする場合は -Kopenmp を付ける. Odyssey で -Kopenmp を付けずにコンパイルした sample_f は, 複数スレッド (OMP_NUM_THREADS=12) で実行すると pcg などの線形ソルバが 1 反復目から発散した (-Kopenmp を付けた場合と 1 スレッドの場合は 7 ソルバすべて合格. gfortran でコンパイルした場合も合格).
5.3.10 自分の行列を渡す
PARCEL に渡す行列は, 各ランクが担当する行の CRS である (形式は基本構成の「データ構造」). 自分の問題の行列をこの形にする方法を示す.
5.3.10.1 三つ組 (COO) から CRS を作る
有限要素法などでは, 行列を (行, 列, 値) の三つ組 (COO 形式) で組み立てることが多い. 次のサブルーチンは, 担当行の三つ組から CRS を 1 始まりで作る (opt%index_base = 1で渡す). 同じ (行, 列) が複数回ある場合は値を足し合わせ, 各行の列番号を昇順にする. 結果は PARCEL が求める形になる.
! 担当行 nstart .. nstart+n_local-1 (1 始まり) の三つ組 ti(k), tj(k), tv(k) (k = 1..nt) から CRS を 1 始まりで作る.
! 同じ (行, 列) は足し合わせ, 各行の列番号を昇順にする. nnz に非零数を返す
subroutine coo_to_crs(nstart, n_local, nt, ti, tj, tv, rowptr, col, val, nnz)
use parcel_sycl_mod, only: parcel_int_kind
implicit none
integer(parcel_int_kind), intent(in) :: nstart, n_local, nt
integer(parcel_int_kind), intent(in) :: ti(nt), tj(nt)
real(8), intent(in) :: tv(nt)
integer(parcel_int_kind), intent(out) :: rowptr(n_local+1), col(nt), nnz
real(8), intent(out) :: val(nt)
integer(parcel_int_kind) :: k, r, p, q, jc, pos(n_local), first(n_local+1)
real(8) :: v
! 行ごとの個数から各行の先頭位置を決め, 三つ組を行ごとに置く
first = 0
do k = 1, nt
r = ti(k) - nstart + 1
first(r+1) = first(r+1) + 1
end do
first(1) = 1
do r = 1, n_local
first(r+1) = first(r+1) + first(r)
end do
pos = first(1:n_local)
do k = 1, nt
r = ti(k) - nstart + 1
col(pos(r)) = tj(k)
val(pos(r)) = tv(k)
pos(r) = pos(r) + 1
end do
! 各行の中を列番号の昇順に並べ (挿入法), 同じ列を足し合わせて前に詰める
nnz = 0
do r = 1, n_local
do p = first(r) + 1, first(r+1) - 1
jc = col(p)
v = val(p)
q = p - 1
do while (q >= first(r))
if (col(q) <= jc) exit
col(q+1) = col(q)
val(q+1) = val(q)
q = q - 1
end do
col(q+1) = jc
val(q+1) = v
end do
rowptr(r) = nnz + 1
do p = first(r), first(r+1) - 1
if (nnz >= rowptr(r)) then
if (col(nnz) == col(p)) then
val(nnz) = val(nnz) + val(p)
cycle
end if
end if
nnz = nnz + 1
col(nnz) = col(p)
val(nnz) = val(p)
end do
end do
rowptr(n_local+1) = nnz + 1
end subroutine coo_to_crs- 三つ組は担当行のものだけを渡す (
nstart <= ti(k) <= nstart + n_local - 1). 返すnnzをnnz_localとして渡す. - 対角要素が無い行がありうる場合は, 先に各行に (i, i, 0.0) を加えておく (対角要素は値が 0 でも格納する).
- 対称な行列でも, 上三角と下三角の両方の要素を入れる.
5.3.10.2 Matrix Market のファイルを読む
Matrix Market 形式 (拡張子 .mtx) は, 疎行列を交換するための文字の形式である. read文で読むときの要点を示す.
- 1 行目は
%%MatrixMarket matrix coordinate real generalのような見出しで,%で始まる注釈の行の後に「行数 列数 非零数」の行, 続いて 1 行に 1 つずつ「行 列 値」(1 始まり) が並ぶ (座標形式coordinate). - 見出しが
symmetricの場合, ファイルには片側の三角 (通常は下三角) だけが書かれている. 対角以外の要素は (列, 行) にも同じ値を加えて両三角にする (skew-symmetricでは符号を反転する). pattern(値が無い) とcomplexの形式は PARCEL では扱えない (PARCEL は実数の行列を解く).- 行と列は 1 始まりなので,
opt%index_base = 1にしてそのまま使える. 読んだ三つ組のうち担当行のものだけを残し, 上のcoo_to_crsで CRS にする.
5.3.10.3 大域の行列を各ランクに配る
MPI ありでは, 各ランクが担当行の CRS だけを渡す. 用意の仕方は 2 通りある.
- 各ランクが担当行だけを作る: 差分法の行列のように式から作れる場合は, 各ランクが担当行の範囲だけを生成する. 大域の行列をどこにも持たないので, メモリが最も少ない. 同梱の例 (
examples/quick_start_f.f90,examples/sample_f.f90) はこの形である. - 大域の行列から担当行を切り出す: ファイルから読んだ場合など, 大域の CRS (
grp,gcol,gval. 1 始まり) が手元にあれば, 行nstart〜nstart + n_local - 1の部分は配列の連続した範囲である. 行ポインタは先頭からの差だけが使われ, ラッパは入力配列を書き換えないので, 配列の要素を先頭として渡せる. 全ランクが同じファイルを読むか, 1 つのランクが読んでMPI_Scattervで配る.
! 大域の CRS (1 始まり) から行 nstart .. nstart+n_local-1 を切り出して渡す (opt%index_base = 1)
off = grp(nstart)
nnz_local = grp(nstart + n_local) - off
rc = parcel_solve_linear(PARCEL_SOLVER_PCG, opt, MPI_COMM_WORLD, n_local, nstart, n_global, &
nnz_local, grp(nstart), gcol(off), gval(off), b, x, res)5.3.10.4 分割の決め方
各ランクの行は連続していればよく, 行数はランクごとに異なってよい (「MPI 分割」). 分け方は次の点を考えて決める.
- 1 反復の時間の大半は SpMV と前処理で, その量は非零数に比例する. 内積などの集団操作で全ランクが最も遅いランクを待つので, 行ごとの非零数の偏りが大きい行列では, 行数ではなく非零数がそろうように分ける. 大域の行ポインタ
grpを使い, ランク () の先頭行を, 非零数の累計が以上になる最初の行とすればよい (各ランクに 1 行以上を残す). - 行ごとの非零数がほぼ同じ行列 (差分法の格子など) では, 行数を均等に分ければよい.
- 袖通信の量は, 他のランクの列を参照する非零の数で決まる. 格子の問題では, 近い格子点に近い行番号を付けると (番号付けの工夫), 袖が少なくなる.
- 各ランクのメモリも担当行の非零数にほぼ比例する. GPU のメモリが足りない場合は, ランク (GPU) を増やして 1 ランクの行を減らす.
5.4 Python
5.4.1 概要
Python からはパッケージ parcel (配布パッケージの python/) を import して使う. パッケージは C++ のライブラリを直接呼ぶネイティブ層 (libparcel_py.so) を持ち, C言語・Fortran の API (capi/) とは独立している. 7 種のソルバすべてを実行時に選んで呼び出せる. 1 回の呼び出しで SYCL キューの作成, 行列の登録, 求解までを行い, 解を NumPy の配列で返す. 精度は倍精度 (データ・演算とも) だけである.
既定の MPI なしの版は python script.py として 1 プロセスで動き, 行列とベクトルの全体を持つ. MPI ありの版 (インストール) では mpirun -n 4 python script.py のように起動して全ランクが同じ呼び出しを行い (集団操作), 各ランクは担当する行 (連続した行ブロック) だけを持つ. 同じスクリプトがどちらでも動く (MPI なしでの実行, MPI ありでの実行). インストールはインストールの章の「Python のパッケージ」に示す.
# 3 次元 Poisson 方程式を pcg + ブロック Jacobi 前処理で解く例 (python poisson.py。MPI ありの版は mpirun -n 4 python poisson.py)
import numpy as np
import scipy.sparse as sp
import parcel
nx = 32
T = sp.diags([-1.0, 2.0, -1.0], [-1, 0, 1], shape=(nx, nx))
I = sp.identity(nx)
G = (sp.kron(sp.kron(T, I), I) + sp.kron(sp.kron(I, T), I) + sp.kron(sp.kron(I, I), T)).tocsr()
b = G @ np.ones(G.shape[0]) # 厳密解は全要素 1
A = parcel.DistributedCSR.from_global(G) # このランクの担当行を切り出す
x, info = parcel.solve(A, b[A.local_slice()], method="pcg",
precond="block_jacobi", tol=1e-10)
if A.comm.rank == 0:
print(info.reason, info.iterations, info.true_residual)| 項目 | Python |
|---|---|
| 線形ソルバ | parcel.solve(A,b,method=...). method は "pcg", "pbicgstab", "pgmres", "pcagmres" |
| 固有値ソルバ | parcel.eigs(A,method=...). method は "power", "inverse_power", "ks_arnoldi" |
| ソルバ・前処理・収束判定値・反復回数の指定 | 実行時 (キーワード引数). 指定しない項目はライブラリの既定値 |
| 精度 | 倍精度だけ |
| 行列の入力配列 | 書き換えない (int64 と float64 の配列に複製する) |
| 添字の始まり | 0 |
| 固有ベクトルの並び | 形 (n_local, k) の配列. j 列目が j 番目の固有ベクトルの担当行の部分 |
| MPI の行分割 | 任意 (ランクごとに row_start, n_local). 行ブロックの被覆を検査する |
| 行番号・列番号などの整数 | int64 で受け渡す. ライブラリ内部は PARCEL_INT と PARCEL_LINT |
| 行列・ベクトルの再利用 | 呼び出しごとに SYCL キューの作成と行列の登録を行う |
| 収束状態の取得 | 戻り値の SolveInfo / EigInfo. 引数の誤りは例外 |
5.4.2 行列の設定
行列は parcel.DistributedCSR で表す. 各ランクが担当行 (大域の行番号で row_start から row_start + n_local - 1 まで) の CRS を持つ. 並びは scipy.sparse.csr_matrix と同じであり, indptr は 0 始まりの局所の行ポインタ, indices は大域の 0 始まりの列番号である.
作り方は, CRS の 3 つの配列から作るコンストラクタ, 担当行だけの scipy.sparse の行列から作るfrom_scipy(), 全体の行列から担当行を切り出すfrom_global() (小さな問題や試験向け) の 3 通りである. 渡した配列は複製するので, 作った後に変更してよい. 引数, 属性 (n_local, row_start, n_global, nnz, comm), 検査の内容はリファレンスの parcel.DistributedCSRに示す. 行列の検査に合格しなければ, 全ランクが同じValueErrorを投げる.
5.4.3 ベクトルの設定
右辺 b と初期値 x0 は, 担当行の部分 (長さ A.n_local の 1 次元配列) を渡す. 返す解 x も担当行の部分である. 全体のベクトルを持っているときは b[A.local_slice()] で切り出す. 全体の解が要るときは mpi4py の allgather などで集める.
5.4.4 前処理の設定
前処理はprecond ("point_jacobi", "block_jacobi", "jacobi". 既定は前処理なし) で選び, その設定 (Jacobi 前処理の反復回数, ブロック Jacobi 前処理のブロック数, スケーリング) を辞書precond_optionsで与える (リファレンスの parcel.solve()). 固有値ソルバの前処理は, precond_spectrum=True (の固有値を求める) のときに使われる. 内部線形ソルバの前処理はinner_precondとinner_precond_optionsで与える.
5.4.5 線形ソルバの呼び出し
x, info = parcel.solve(A, b[A.local_slice()], method="pgmres", restart=60,
precond="jacobi", tol=1e-10)
if not info.converged:
print(info.reason, info.iterations, info.true_residual) methodでソルバを選び ("pcg", "pbicgstab", "pgmres", "pcagmres"), 収束判定値などの設定はキーワード引数で与える. Noneの項目はライブラリの既定値になる. 引数の一覧と既定値はリファレンスの parcel.solve()に示す. 収束しなくても例外にはならないので, 戻り値のinfo (SolveInfo) のconvergedを確かめる.
5.4.6 固有値ソルバの呼び出し
methodで"power", "inverse_power", "ks_arnoldi"を選ぶ. valuesは複素数の 1 次元配列, vectorsは形 (A.n_local, 個数) の配列で, j 列目が j 番目の固有ベクトルの担当行の部分である. 引数 (ks_arnoldi のm, k_keep, nev, shift-invert のsigma, 内部線形ソルバのinner_*など) と戻り値の並びはリファレンスの parcel.eigs()に示す.
# ks_arnoldi で絶対値の大きい側から 4 個, shift-invert で 0 に近い側から 2 個
vals, vecs, info = parcel.eigs(A, method="ks_arnoldi", m=40, k_keep=10, nev=4, tol=1e-10)
vals, vecs, info = parcel.eigs(A, method="ks_arnoldi", m=20, k_keep=6, nev=2, sigma=0.0,
tol=1e-10, inner_tol=1e-12)5.4.7 例外
引数・設定の誤りと行列の検査の不合格はValueError, 整数型の範囲を超えるとOverflowError, ビルドから外したソルバはparcel.NotBuiltError, その他の失敗はparcel.ParcelErrorになる (一覧はリファレンスの「例外」).
MPI なしの版では, これらの例外は呼び出したプロセスで捕まえられ, デバイスのメモリ不足などのライブラリ内の失敗も parcel.ParcelError になる. MPI ありの版での扱い (全ランクで同じ例外になる誤りと, MPI_Abort で終了する誤り) は MPI ありでの実行に示す.
5.4.8 精度の指定
データ・演算とも倍精度 (parcel_double) に固定であり, 混合精度は使えない. 入出力の配列は float64 である.
5.4.9 MPI なしでの実行
実行時もビルドと同じ環境 (AdaptiveCpp・LAPACK のライブラリが見つかる状態. spack で入れた場合は spack load py-parcel-sycl..., macOS では python/envs/mac_brew.sh の読み込み) にする. スレッド数は OMP_NUM_THREADS で与える. デバイスは既定のセレクタで選ばれるので, GPU が複数見える場合は CUDA_VISIBLE_DEVICES などで使う GPU を選ぶ.
export CUDA_VISIBLE_DEVICES=0
$HOME/venv_parcel/bin/python script.py 1 プロセスが行列の全行を持つ (row_start = 0, n_local = n_global. from_global() で作ればよい). parcel.Comm() の rank は 0, size は 1 であり, mpi4py のコミュニケータは渡せない. 例外はすべて呼び出したプロセスで捕まえられる (デバイスのメモリ不足などは parcel.ParcelError).
AdaptiveCpp は使わないバックエンドについての警告を呼び出しごとに表示するので, パッケージは ACPP_DEBUG_LEVEL が設定されていなければ 0 にする.
5.4.10 MPI ありでの実行
mpirun で起動し, 全ランクが同じ呼び出しを同じ引数で行う (集団操作). スレッド数はOMP_NUM_THREADSで与える. 1 ランクに 1 台の GPU を割り当てる場合は gpu_bind.sh のようなラッパを mpirun と Python の間に置く.
export OMP_NUM_THREADS=12
mpirun -n 4 ./gpu_bind.sh $HOME/venv_parcel_mpi/bin/python script.pyMPI の初期化は最初の呼び出しのときに行う. mpi4py などが先に初期化していればそれを使い, パッケージが初期化したときだけ終了時に MPI_Finalize を呼ぶ.
コミュニケータは parcel.Comm で表す. parcel.Comm() は MPI_COMM_WORLD であり, parcel.Comm(c) には mpi4py のコミュニケータを渡せる. 行列の comm 引数には parcel.Comm と mpi4py のコミュニケータのどちらも渡せ, 省けば MPI_COMM_WORLD を使う. comm.rank, comm.size と, 全ランクの和・最大・最小を返す comm.allreduce(value, op) (op は "sum","max","min") を使える.
行の分割は連続した行ブロックであれば任意であり, 不均等でも, ランク番号の順に並んでいなくてもよい. parcel.partition_rows(n_global, comm) は均等な分割 (端数は先頭のランクから 1 行ずつ) の (row_start, n_local) を返す.
row_start, n_local = parcel.partition_rows(n_global)
# make_rows(row_start, n_local) は利用者が書く関数: 担当行 (row_start から n_local 行) だけの
# scipy.sparse の CSR 行列 (形は (n_local, n_global), 列番号は大域) を返す
A = parcel.DistributedCSR.from_scipy(make_rows(row_start, n_local), row_start, n_global)ライブラリが判定する誤り (設定の組合せ, 行列の検査) は全ランクで同じ例外になるので, 捕まえた後も処理を続けられる. 配列の長さや値の範囲など Python 側の検査は各ランクで行うので, 引数がランクによって異なり一部のランクだけが例外を投げると, 残りのランクは集団操作で待ち続ける. これら以外の誤り (デバイスのメモリ不足など) は一部のランクだけで起きうるので, メッセージを表示して MPI_Abort で全ランクを終了する.
5.4.11 自分の行列を渡す
PARCEL に渡す行列は, 各ランクが担当する行の CRS である (形式は基本構成の「データ構造」). 自分の問題の行列をこの形にする方法を示す.
5.4.11.1 三つ組 (COO) から CRS を作る
有限要素法などでは, 行列を (行, 列, 値) の三つ組 (COO 形式) で組み立てることが多い. SciPy のcoo_matrixから CSR に変換すると, 同じ位置の値は足し合わされる. 念のためsum_duplicates()とsort_indices()を呼んでから渡す.
import numpy as np
import scipy.sparse as sp
import parcel
# i, j, v: 三つ組 (行と列は大域の 0 始まり). n_global: 行列の行数
G = sp.coo_matrix((v, (i, j)), shape=(n_global, n_global)).tocsr()
G.sum_duplicates(); G.sort_indices()
A = parcel.DistributedCSR.from_global(G) # このランクの担当行を切り出す (MPI なしでは全行)- 対角要素が無い行がありうる場合は, 三つ組の段階で値 0 の対角要素 (i, i, 0.0) を加えておく (対角要素は値が 0 でも格納する. 値 0 の要素を消す
eliminate_zeros()は呼ばない). - 対称な行列でも, 上三角と下三角の両方の要素を入れる.
5.4.11.2 Matrix Market のファイルを読む
Matrix Market 形式 (拡張子 .mtx) は, 疎行列を交換するための文字の形式である. SciPy のmmreadで読める. mmreadは対称形式 (symmetric) のファイルも両三角に展開する. pattern (値が無い) とcomplexの形式は PARCEL では扱えない (PARCEL は実数の行列を解く).
import scipy.io, scipy.sparse
import parcel
G = scipy.sparse.csr_matrix(scipy.io.mmread("matrix.mtx"))
G.sum_duplicates(); G.sort_indices()
A = parcel.DistributedCSR.from_global(G) # このランクの担当行を切り出す (MPI なしでは全行)5.4.11.3 大域の行列を各ランクに配る
MPI ありでは, 各ランクが担当行の CRS だけを持つ. 用意の仕方は 2 通りある.
- 各ランクが担当行だけを作る: 差分法の行列のように式から作れる場合は,
parcel.partition_rows()で担当行を決め, その範囲だけの行列を作ってDistributedCSR.from_scipy()で渡す (「MPI ありでの実行」のmake_rows). 大域の行列をどこにも持たないので, メモリが最も少ない. - 大域の行列から担当行を切り出す: 全ランクが大域の行列を持てる大きさなら,
DistributedCSR.from_global()が均等な分割で担当行を切り出す. 右辺などのベクトルはb[A.local_slice()]で担当行の部分を切り出す.
5.4.11.4 分割の決め方
各ランクの行は連続していればよく, 行数はランクごとに異なってよい. from_global()とpartition_rows()は行数を均等に分けるので, 別の分け方をする場合は担当行 (row_start, n_local) を自分で決めてfrom_scipy()で渡す. 分け方は次の点を考えて決める.
- 1 反復の時間の大半は SpMV と前処理で, その量は非零数に比例する. 内積などの集団操作で全ランクが最も遅いランクを待つので, 行ごとの非零数の偏りが大きい行列では, 行数ではなく非零数がそろうように分ける. 大域の行列
Gの行ポインタG.indptrを使い, ランク () の先頭行を, 非零数の累計が以上になる最初の行とすればよい (各ランクに 1 行以上を残す). - 行ごとの非零数がほぼ同じ行列 (差分法の格子など) では, 行数を均等に分ければよい.
- 袖通信の量は, 他のランクの列を参照する非零の数で決まる. 格子の問題では, 近い格子点に近い行番号を付けると (番号付けの工夫), 袖が少なくなる.
- 各ランクのメモリも担当行の非零数にほぼ比例する. GPU のメモリが足りない場合は, ランク (GPU) を増やして 1 ランクの行を減らす.