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

20 Python の API

 Python からはパッケージ parcel (配布パッケージの python/) を import して使う. パッケージはライブラリを直接呼ぶネイティブ層 (libparcel_py.so) を持ち, C言語・Fortran の API とは独立している. 設定の意味と既定値, 結果, 収束状態は共通事項とソルバごとの収束判定に, 使い方の流れと例は利用者ガイドの使用方法の「Python」, インストールは利用者ガイドのインストールの「Python のパッケージ」に示す.

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"
基底生成の大きさss, tt s, t 両方とも与える
QR 分解の方式 (pcagmres) qr "cgs", "mgs", "cholesky_qr", "cholesky_qr_moment"
QQの作り方 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 与えると有効. A−σIA - \sigma Iはパッケージが組み立てる
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()

概要 連立一次方程式Ax=bAx = bを解き, 解と収束状態を返す (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 のみ) QQの作り方 "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()

概要 固有値問題Av=λvAv = \lambda v (precond_spectrum=TrueではAK−1AK^{-1}) を解き, 固有値・固有ベクトル・収束状態を返す (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でAK−1AK^{-1}の固有値を求める (KKは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 のシフト. 与えるとσ\sigmaに近い固有値を求める (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 つとも与え, 1≤nev≤kkeep<m≤nglobal1 \leq nev \leq k_{keep} < m \leq n_{global}を満たさなければ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 ではσ\sigmaに近い順) に並び, 複素共役対の固有ベクトルは実部と虚部が連続する 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 で全ランクを終了する.