20 Python の API
Python からはパッケージ parcel (配布パッケージの python/) を import して使う. パッケージはライブラリを直接呼ぶネイティブ層 (libparcel_py.so) を持ち, C言語・Fortran の API とは独立している. 設定の意味と既定値, 結果, 収束状態は共通事項とソルバごとの収束判定に, 使い方の流れと例は利用者ガイドの使用方法の「Python」, インストールは利用者ガイドのインストールの「Python のパッケージ」に示す.
- 公開する名前は
DistributedCSR,solve,eigs,SolveInfo,EigInfo,Comm,partition_rows,build_info,has_mpi,device_name,ParcelError,NotBuiltErrorである. - 1 回の呼び出しで SYCL キューの作成, 行列の登録, 求解までを行う. 精度はデータ・演算とも倍精度だけで, 入出力の配列は float64 である.
- 設定の引数は
None(既定) のときライブラリの既定値 (共通事項の設定) になる. 下の引数の表の「既定値」はその値である. - 誤りは Python の例外で知らせる (例外). 求解は収束しなくても例外にならないので, 返す
info.convergedを確かめる. - ネイティブ層を MPI ありでビルドした版では, 全ランクが同じ呼び出しを同じ引数で行う (集団操作). 最初の呼び出しで MPI を初期化する (mpi4py などが先に初期化していればそれを使い, パッケージが初期化したときだけ終了時に
MPI_Finalizeを呼ぶ). MPI なしの版では 1 プロセスが全体を持つ. - ネイティブ層は, 環境変数
PARCEL_PY_LIBがあればそのパス, 無ければパッケージ内のlibparcel_py.soを読む. 見つからない場合とネイティブ層の版 (ABI) がパッケージと合わない場合はImportErrorになる. AdaptiveCpp の警告を抑えるため,ACPP_DEBUG_LEVELが設定されていなければ 0 にする.
20.1 共通事項との対応
共通事項の設定とsolve()・eigs()の引数, 結果とSolveInfo・EigInfoの属性の対応を示す. 定数は文字列で与える.
| 共通事項の設定 | 引数 | 表し方 |
|---|---|---|
| 収束判定値 | tol |
— |
| 最大反復回数 | maxiter |
— |
| 前処理の種類 | precond |
"none", "point_jacobi", "block_jacobi", "jacobi" |
| Jacobi 前処理の反復回数 | precond_options["iterations"] |
— |
| ブロック Jacobi 前処理のブロック数 | precond_options["blocks"] |
— |
| スケーリング | precond_options["scale_matrix"], ["scale_vector"] |
True, False, None (自動) |
| リスタート周期 (pgmres) | restart |
— |
| 直交化の方式 (pgmres) | orthogonalization |
"cgs", "mgs" |
| 基底生成の大きさ, | s, t |
両方とも与える |
| QR 分解の方式 (pcagmres) | qr |
"cgs", "mgs", "cholesky_qr", "cholesky_qr_moment" |
| の作り方 | q_mode |
"auto", "explicit", "implicit" |
| 前処理後の行列のスペクトル | precond_spectrum |
True, False |
| 内部線形ソルバの種類 | inner_method |
"pgmres", "pcg" |
| 内部線形ソルバの収束判定値 | inner_tol |
— |
| 内部線形ソルバの最大反復回数 | inner_maxiter |
— |
| 内部線形ソルバのリスタート周期 | inner_restart |
— |
| 内部線形ソルバの前処理 | inner_precond, inner_precond_options |
スケーリングは指定できない (常に自動) |
| shift-invert | sigma |
与えると有効. はパッケージが組み立てる |
| Krylov 部分空間の大きさ | m, k_keep, nev |
3 つとも与える |
| 最大リスタート回数 | max_restart |
— |
| 直交化の方式 (ks_arnoldi) | orthogonalization (eigs()) |
"cgs" (CGS2) または "mgs" (MGS2) |
| 初期ベクトル | v0 |
— |
| 共通事項の結果 | 属性 |
|---|---|
| 収束状態 | converged, reason, reason_code |
| 反復回数 | iterations |
| 残差 | residual |
| 真の残差 | true_residual |
| 収束した固有対の数 | n_converged (EigInfoのみ) |
| 内部線形ソルバの失敗回数 | inner_failures (EigInfoのみ) |
20.2 parcel.DistributedCSR
概要 MPI で行ブロックに分割した疎行列のうち, このランクの担当行を表す (共通事項の「入力の行列」).
書式
A = parcel.DistributedCSR(indptr, indices, data, row_start, n_global, comm=None)引数
| 名前 | 型 | 説明 | 既定値 |
|---|---|---|---|
indptr |
整数の 1 次元配列 | 担当行の 0 始まりの局所の行ポインタ (長さn_local + 1) |
— |
indices |
整数の 1 次元配列 | 大域の 0 始まりの列番号 | — |
data |
実数の 1 次元配列 | 行列要素 (indicesと同じ長さ) |
— |
row_start |
整数 | 担当する最初の行の大域行番号 (0 始まり) | — |
n_global |
整数 | 大域行数 | — |
comm |
parcel.Comm, mpi4py のコミュニケータ, None |
コミュニケータ. Noneは MPI_COMM_WORLD |
None |
属性 indptr, indices, data (int64 / float64 の連続配列に複製したもの. 元の配列は呼び出し後に変更してよい), row_start, n_global, comm (parcel.Comm), n_local (担当行数), nnz (担当行の非零要素数), shape ((n_global, n_global)).
前提条件 並びはscipy.sparse.csr_matrixと同じである. 作成時に, indptrが長さ 2 以上の 1 次元配列であること, indicesとdataが同じ長さの 1 次元配列であること, indptr[0] = 0かつindptr[-1] = len(indices)であることを検査し, 外れていればValueErrorを投げる. 求解のときには, 各ランクが 1 行以上を持つこと, indptrが単調非減少であること, 列番号が 0 以上n_global未満であること, 全ランクの行ブロックが 0 からn_global - 1までを隙間・重複なく覆うこと (ランクの並び順は問わない) を検査し, 崩れていれば全ランクが同じValueErrorを投げる. 行数がネイティブ層の整数の範囲を超えるときはOverflowErrorを投げる.
関連項目 from_scipy() / from_global(), local_slice()
20.3 DistributedCSR.from_scipy() / DistributedCSR.from_global()
概要 SciPy の疎行列からDistributedCSRを作る (クラスメソッド).
書式
A = parcel.DistributedCSR.from_scipy(local_rows, row_start, n_global=None, comm=None)
A = parcel.DistributedCSR.from_global(global_matrix, comm=None, row_start=None, n_local=None)引数
| 名前 | 型 | 説明 | 既定値 |
|---|---|---|---|
local_rows |
scipy.sparse の行列 | 担当行だけの行列 (列は大域) | — |
row_start |
整数 | 担当する最初の行の大域行番号. from_global()では省くとpartition_rows()の分割を使う |
from_global()はNone |
n_global |
整数 | 大域行数. 省くとlocal_rowsの列数 |
None |
global_matrix |
scipy.sparse の正方行列 | 全体の行列 (全ランクが同じものを持つ) | — |
n_local |
整数 | 担当行数 (row_startと一緒に与える) |
None |
comm |
parcel.Comm, mpi4py のコミュニケータ, None |
コミュニケータ | None |
戻り値 DistributedCSR.
注意 from_global()は全体の行列から担当行を切り出すので, 小さな問題や試験に向く. 正方行列でなければValueErrorを投げる.
20.4 DistributedCSR.local_slice()
概要 全体のベクトルからこのランクの担当行の部分を取り出すスライスを返す.
書式
s = A.local_slice() # slice(row_start, row_start + n_local)
x, info = parcel.solve(A, b_global[A.local_slice()])20.5 parcel.solve()
概要 連立一次方程式を解き, 解と収束状態を返す (pcg, pbicgstab, pgmres, pcagmres).
書式
x, info = parcel.solve(A, b, *, method="pcg", x0=None, tol=None, maxiter=None,
precond=None, precond_options=None,
restart=None, orthogonalization=None, # pgmres のみ
s=None, t=None, qr=None, q_mode=None, # pcagmres のみ
verbose=False)引数 設定の引数の意味は「共通事項」の列の節に示す.
| 名前 | 値 | 共通事項 | 既定値 |
|---|---|---|---|
A |
DistributedCSR |
入力の行列 | — |
b |
右辺の担当行の部分 (長さA.n_local) |
— | — |
method |
"pcg", "pbicgstab", "pgmres", "pcagmres" |
ソルバ | "pcg" |
x0 |
初期値の担当行の部分. Noneなら 0 |
— | None |
tol |
有限の正の数 | 収束判定値 | 1.0e-8 |
maxiter |
1 以上の整数 | 最大反復回数 | 10000 |
precond |
None, "none", "point_jacobi", "block_jacobi", "jacobi" |
前処理の種類 | 前処理なし |
precond_options |
辞書. "iterations" (1 以上), "blocks" (1 以上), "scale_matrix", "scale_vector" (True, False, None) |
Jacobi の反復回数, ブロック数, スケーリング | 反復 1 回, ブロック数・スケーリングは自動 |
restart |
1 以上の整数 (pgmres のみ) | リスタート周期 | 30 |
orthogonalization |
"cgs", "mgs" (pgmres のみ) |
直交化の方式 | "mgs" |
s, t |
1 以上の整数. 両方とも与える (pcagmres のみ) | 基底生成の大きさ | 8, 4 |
qr |
"cgs", "mgs", "cholesky_qr", "cholesky_qr_moment" (pcagmres のみ) |
QR 分解の方式 | "mgs" (q_mode="implicit"では"cholesky_qr") |
q_mode |
"auto", "explicit", "implicit" (pcagmres のみ) |
の作り方 | "auto" |
verbose |
Trueでランク 0 が反復の経過を表示する. Falseのときは求解の間, 標準出力 (ファイル記述子 1) を捨てる |
標準出力 | False |
前提条件 bとx0の形が(A.n_local,)でなければValueError. 文字列の値が上の候補にない場合, 数が範囲外の場合はValueError. 対象でないソルバにrestart, orthogonalization, s, t, qr, q_modeを与えるとValueError. sとtは両方とも与える. precond_optionsの知らないキーはValueError. 組合せの誤り (例えばq_mode="implicit"にqr="cgs". 規則) はライブラリが判定し, 全ランクが同じValueErrorを投げる.
戻り値 (x, info). xは解の担当行の部分 (float64 の配列), infoは SolveInfo. 収束しなくても例外にはならないのでinfo.convergedを確かめる.
MPI 集団操作 (MPI ありの版).
関連項目 ソルバごとの収束判定
例
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)20.6 parcel.eigs()
概要 固有値問題 (precond_spectrum=Trueでは) を解き, 固有値・固有ベクトル・収束状態を返す (power, inverse_power, ks_arnoldi).
書式
values, vectors, info = parcel.eigs(A, *, method="ks_arnoldi", tol=None, maxiter=None,
precond=None, precond_options=None, precond_spectrum=False,
m=None, k_keep=None, nev=None, max_restart=None, sigma=None, v0=None, # ks_arnoldi のみ
orthogonalization=None, # ks_arnoldi のみ
inner_method=None, inner_tol=None, inner_maxiter=None, inner_restart=None,
inner_precond=None, inner_precond_options=None, verbose=False)引数 A, tol, maxiter, precond, precond_options, verboseは solve() と同じである (maxiterは power / inverse_power の外側の反復の上限. ks_arnoldi は使わない).
| 名前 | 値 | 共通事項 | 既定値 |
|---|---|---|---|
method |
"power" (絶対値最大), "inverse_power" (絶対値最小), "ks_arnoldi" (絶対値の大きい側から複数) |
ソルバ | "ks_arnoldi" |
precond_spectrum |
Trueでの固有値を求める (はprecondの前処理) |
前処理後の行列のスペクトル | False |
m, k_keep, nev |
部分空間の最大次元, リスタートで残す数, 求める固有値の数 (3 つとも与える. ks_arnoldi のみ) | Krylov 部分空間の大きさ | 30, 10, 4 |
max_restart |
1 以上の整数 (ks_arnoldi のみ) | 最大リスタート回数 | 200 |
orthogonalization |
"cgs" (CGS2) または "mgs" (MGS2). "cgs2", "mgs2" も受け付ける (ks_arnoldi のみ) |
直交化の方式 | ライブラリの既定 (CGS2. ビルド時の指定で MGS2) |
sigma |
shift-invert のシフト. 与えるとに近い固有値を求める (ks_arnoldi のみ) | shift-invert | None (無効) |
v0 |
初期ベクトルの担当行の部分 (長さA.n_local. ks_arnoldi のみ) |
初期ベクトル | None (大域行番号から作る) |
inner_method |
"pgmres", "pcg" (inverse_power で使う) |
内部線形ソルバの種類 | "pgmres" |
inner_tol |
有限の正の数 | 内部線形ソルバの収束判定値 | 1.0e-10 |
inner_maxiter |
1 以上の整数 | 内部線形ソルバの最大反復回数 | inverse_power 5000, ks_arnoldi 2000 |
inner_restart |
1 以上の整数 | 内部線形ソルバのリスタート周期 | 30 |
inner_precond, inner_precond_options |
内部線形ソルバの前処理 (precondと同じ値) と, その"iterations", "blocks" (スケーリングは自動で, 指定するとValueError) |
内部線形ソルバの前処理 | "jacobi" (反復 1 回), ブロック数は自動 |
前提条件 m, k_keep, nev, max_restart, sigma, v0, orthogonalizationは ks_arnoldi だけで使え, 他のソルバに与えるとValueError. orthogonalizationが上の値以外でもValueError. m, k_keep, nevは 3 つとも与え, を満たさなければValueError. 内部線形ソルバの引数は inverse_power と, sigmaを与えた ks_arnoldi で使われる. precond_spectrum=Trueのときはinner_methodによらず pgmres を使う. v0の形が(A.n_local,)でなければValueError.
戻り値 (values, vectors, info). valuesは複素数の 1 次元配列 (power と inverse_power では 1 個, ks_arnoldi ではk_keep個). vectorsは形 (A.n_local, 個数) の配列で, j 列目が j 番目の固有ベクトルの担当行の部分である. ks_arnoldi の固有値は絶対値の降順 (shift-invert ではに近い順) に並び, 複素共役対の固有ベクトルは実部と虚部が連続する 2 列に入る (固有値と固有ベクトルの出力). infoは EigInfo.
MPI 集団操作 (MPI ありの版).
関連項目 固有値ソルバの補足, ソルバごとの収束判定
例
# 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)20.7 parcel.SolveInfo / parcel.EigInfo
概要 solve()とeigs()が返す結果 (変更できないデータクラス). 意味は共通事項の「結果」のとおりで, 値は全ランクで同じである.
| 属性 | 型 | 内容 |
|---|---|---|
converged |
bool |
収束したらTrue |
reason |
str |
収束状態の名前. "converged" (CONVERGED_RTOL), "iterating" (ITERATING), "max_iterations" (DIVERGED_ITS), "nan_or_inf" (DIVERGED_NANORINF), "breakdown" (DIVERGED_BREAKDOWN) |
reason_code |
int |
収束状態の定数の値 (1, 0, -1, -2, -3) |
iterations |
int |
反復回数 |
residual |
float |
残差 (ソルバが収束判定に用いた相対値) |
true_residual |
float |
真の残差. 固有値ソルバでは NaN |
n_converged |
int |
EigInfoのみ. 収束した固有対の数 |
inner_failures |
int |
EigInfoのみ. 内部線形ソルバの失敗回数 |
20.8 parcel.Comm
概要 PARCEL に渡す MPI コミュニケータ.
書式
c = parcel.Comm() # MPI_COMM_WORLD (mpi4py が無くても使える)
c = parcel.Comm(mpi4py_comm) # mpi4py のコミュニケータ
c.rank, c.size
v = c.allreduce(value, op="sum") # "sum", "max", "min"引数 mpi4py_commは mpi4py のコミュニケータ (MPI.Comm) またはNone. MPI なしの版で mpi4py のコミュニケータを渡すとTypeError. mpi4py のコミュニケータでないものを渡してもTypeError.
戻り値 rankとsizeはこのランクの番号とランク数 (MPI なしの版では 0 と 1). allreduce()は全ランクの和・最大・最小 (float) を返す (集団操作. opが不正ならValueError).
注意 行列のcomm引数にはparcel.Commと mpi4py のコミュニケータのどちらも渡せる.
20.9 parcel.partition_rows()
概要 n_global行を各ランクに連続した行ブロックとして均等に割り当てる.
書式
row_start, n_local = parcel.partition_rows(n_global, comm=None)戻り値 このランクの(row_start, n_local). 端数は先頭のランクから 1 行ずつ割り当てる.
前提条件 n_globalがランク数以上 (満たさなければValueError).
20.10 parcel.build_info() / parcel.has_mpi() / parcel.device_name()
概要 ネイティブ層の情報を返す.
| 関数 | 戻り値 |
|---|---|
build_info() |
ビルドの情報の文字列 (整数型の幅, 精度, MPI の有無, ABI の版. pip で入れた場合はターゲットとカーネル最適化のフラグも) |
has_mpi() |
ネイティブ層を MPI ありでビルドしたらTrue, MPI なし (1 プロセス版) ならFalse |
device_name() |
このランクで PARCEL が使うデバイスの名前 (既定のセレクタで選ばれるもの) |
20.11 parcel.__version__ / parcel.library_version()
概要 版を返す.
| 名前 | 値 |
|---|---|
__version__ |
パッケージの版の文字列 ("1.2.0". 本体と同じ番号) |
library_version() |
ネイティブ層をビルドしたときの Include/parcel_version.hpp の版の文字列. __version__ と同じになる |
20.12 例外
| 例外 | 起こる場合 |
|---|---|
ValueError |
引数・設定の誤り (取りうる値の外, 組合せの誤り), 行列の検査の不合格 |
OverflowError |
行数などがネイティブ層の整数型の範囲を超える |
TypeError |
行列がDistributedCSRでない, コミュニケータの型が誤り |
ImportError |
ネイティブ層が見つからない, 版 (ABI) が合わない |
parcel.NotBuiltError |
指定したソルバがビルドから外されている (利用者ガイドの「ビルドするソルバの取捨」) |
parcel.ParcelError |
その他の失敗 (RuntimeErrorの派生. NotBuiltErrorの基底クラス. 属性codeにエラーコード) |
MPI なしの版では, これらの例外は呼び出したプロセスで捕まえられ, デバイスのメモリ不足などのライブラリ内の失敗もparcel.ParcelErrorになる. MPI ありの版では, ライブラリが判定する誤り (設定の組合せ, 行列の検査) は全ランクで同じ例外になる. 配列の長さや値の範囲など Python 側の検査は各ランクで行うので, 引数がランクによって異なり一部のランクだけが例外を投げると, 残りのランクは集団操作で待ち続ける. これら以外の誤り (デバイスのメモリ不足など) は一部のランクだけで起きうるので, メッセージを表示して MPI_Abort で全ランクを終了する.