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

15 版と互換性

 公開版 v1.0 から v1.2 への変更のうち利用者のプログラムに影響するものをまとめる. 非推奨の関数は API リファレンスの各関数に記す. 変更の詳細な経緯はリポジトリの CHANGELOG.ja.md (英語版は CHANGELOG.md) を参照する.

15.1 互換性の方針

15.2 版の確かめ方

 版は Include/parcel_version.hpp の 1 か所で定義する (この版は 1.2.0, 公開日 2026-10-23). 各言語では次で得る (API リファレンスの C++, C言語, Fortran, Python).

言語 版を得る方法
C++ マクロ PARCEL_VERSION_MAJOR / PARCEL_VERSION_MINOR / PARCEL_VERSION_PATCH, PARCEL_VERSION_STRING, PARCEL_VERSION_NUMBER, PARCEL_VERSION_GE(a, b, c). 関数 parcel::version_string(), parcel::get_version()
C言語 parcel_get_version(), parcel_version_string() (ラッパをビルドしたときの値)
Fortran parcel_get_version(), parcel_version_string()
Python parcel.__version__ (パッケージの版), parcel.library_version() (ネイティブ層をビルドしたときの値). 両者は同じ値になる

 Python のパッケージの版は本体と同じ番号である. 回帰試験は, 実行したプログラムの版が生成器がヘッダから読んだ版と一致することを確かめる.

15.3 引用と問い合わせ

 引用するときの情報は配布パッケージの CITATION.cff (Citation File Format 1.2.0) に記す. PARCEL を引用するときは参考文献 [3] (Idomura et al., ScalA 17, 2017) を挙げる. 質問・不具合の報告は GitHub の Issues (https://github.com/parcel-jaea/PARCEL-release/issues) で受け付ける. 問い合わせの案内と報告に添える情報 (版, 入れ方とビルドのコマンド, 計算機, SYCL 処理系・MPI の版, 再現の手順) は SUPPORT.ja.md (英語版は SUPPORT.md) に記す. 公開用のリポジトリは https://github.com/parcel-jaea/PARCEL-release である (配布 tarball は Release に置く).

15.4 配布物の確認

 配布 tarball parcel_sycl-1.2.0.tar.gz は GitHub の Release (https://github.com/parcel-jaea/PARCEL-release/releases, タグ v1.2.0) に置き, sha256 のファイル parcel_sycl-1.2.0.tar.gz.sha256 を添える. 受け取った tarball は sha256sum -c parcel_sycl-1.2.0.tar.gz.sha256 (macOS は shasum -a 256 -c) で確かめる. tarball は tools/make_tarball.py で作り, 同じ中身からは同じ tarball (同じ sha256) ができる. spack のレシピに書いた sha256 が今のパッケージの tarball と一致するかは python3 tools/make_tarball.py --check で確かめる. レシピは tarball の中にも入るので, tarball の中のレシピは sha256 を持たない形にしてある.

 過去の版も GitHub の Release に置く. SYCL 版の v1.0 は同じリポジトリの Release (タグ v1.0.0) に, SYCL 版より前の PARCEL 1.0〜1.2 (Fortran, CUDA) は https://github.com/parcel-jaea/PARCEL-legacy の Release に置く.

15.5 v1.0 から v1.2 への変更

15.5.1 動作が変わった機能

 v1.0 にあった機能のうち, v1.2 で動作が変わったものを示す. v1.0 には収束状態を取得する関数が無いため, v1.0 の欄は反復の終わり方で示す.

項目 v1.0 v1.2
pbicgstab のクラステンプレート引数 先頭に未使用の Tdata を含む 5 引数. 他のソルバと同じ 4 引数を渡すと 1 つずつずれ, SpMV が前処理の精度, 内積が常に double で計算されていた 他のソルバと同じ <Tspmv, Tprecon, Taxpy, Tdot>
ブロック Jacobi 前処理のブロック数 既定 1 set_blockjacobi() を呼ばなければデバイスの並列度から自動で決める
前処理の行列・ベクトルスケーリング 既定は無効 set_scaling_matrix() / set_scaling_vector() を呼ばなければ前処理の種類と精度から自動で決める (ブロック Jacobi は常に有効, Jacobi は半精度のときだけ有効)
SYCL キュー 既定 (out-of-order) キューも受け付けた (同梱のサンプルとラッパは AdaptiveCpp では既定キューを使っていた) in-order キューでなければ set_crsMat() と全ソルバの solver() が std::invalid_argument を投げる
設定関数の引数 範囲外の値も受け取り, 結果は不定 (例: set_precon_algo(3) は黙って前処理なし, set_tolerance(0) は最大反復回数まで反復) 範囲外の値は std::invalid_argument (API リファレンスの「設定の扱いと例外」)
線形ソルバで ∥b∥=0\|b\| = 0 相対残差が NaN となり, 最大反復回数まで反復して終わる 反復せずに x=0x = 0, CONVERGED_RTOL (反復回数 0)
線形ソルバで残差が非有限 最大反復回数まで反復 その場で打ち切り DIVERGED_NANORINF
pbicgstab の破綻 検出せず, NaN / Inf のまま最大反復回数まで反復 ⟨r*,q⟩\langle r^{\ast},q \rangle, ω\omega, ρ\rho の 0 などを検出して DIVERGED_BREAKDOWN. v=0v = 0 は幸運な破綻として判定
pgmres / pcagmres の幸運な破綻 0 による除算で NaN,またはゴミを含む解の更新 有効な列だけで解を更新し, 次のリスタートで判定. 更新できなければ DIVERGED_BREAKDOWN
-ffast-math / -ffinite-math-only ビルドできた #error でビルドを止める
double-double の積の誤差なし変換 (TwoProd) Dekker の分割. CUDA では積と和が FMA に融合され, dd の積が倍精度相当に落ちうる fma を用いる. dd の結果が最後の桁で変わりうる
pbicgstab の FP16 内積 テンプレート引数のずれにより内積が常に倍精度で計算されていた (FP16 の構成でも内積は倍精度) 内積が FP16 で計算される. 精度の下限に近い判定値では DIVERGED_BREAKDOWN となりうる
set_tolerance() の既定 (全ソルバ) 1.0e-4 1.0e-8
set_max_iteration() の既定 100 10000
pgmres の set_restart() の既定 4 30 (作業ベクトルはm+1m+1本なので, 既定のメモリ使用量が増える)
pcagmres の set_restart(s, t) の既定 s=1s = 1, t=1t = 1 s=8s = 8, t=4t = 4
pcagmres の set_qr_algo() の既定 QR_CGS QR_MGS (CAGMRES_Q_IMPLICIT で指定しなければ QR_CHOLESKYQR). C / Fortran の cagmres_qr_algo の既定も PARCEL_QR_MGS
pgmres / pcagmres の反復上限がリスタート周期 (mm, stst) の倍数でない場合 周回数を切り捨て, 端数の反復を行わない (上限が周期より小さいと反復しない) 最後のリスタートを端数の列数にし, 上限ちょうどまで反復する. 上限に達した場合の反復回数は上限の値
pcg / pbicgstab で初期残差の相対残差が収束判定値未満 1 反復以上行う (x(0)x^{(0)} が厳密解で初期残差が 0 なら 0 による除算で NaN となる) 反復せずに CONVERGED_RTOL (反復回数 0,x は初期値のまま)
PARCEL_INT (行番号・列番号などの整数) の既定 int32_t (-DPARCEL_INT で int64_t) 大域の添字 PARCEL_INT は int64_t. ランク内の添字 (デバイス上の CRS の列番号・行ポインタなど) は新設の PARCEL_LINT で持ち, 既定は int32_t なので, デバイスのメモリ量と SpMV の転送量は v1.0 と同じ. set_crsMat() に渡す配列は PARCEL_INT (8 バイト) になる (基本構成の「整数型」). -DPARCEL_INT は互換のため受け付ける
set_crsMat() の入力 検査しない (分割の隙間・重複や rowptr の誤りは誤った結果または範囲外アクセスになる) 分割・局所行数・rowptr・列番号を検査し, 崩れていれば全ランクが std::invalid_argument を投げる (使用方法の「行列の設定」)
デバイスのメモリ確保の失敗 検査せず, segmentation fault などで異常終了する util_sycl::device_bad_alloc (std::bad_alloc の派生) を投げる
Jacobi 前処理 (PRECON_JACOBI) と行列AAの寿命 前処理がAAの行ポインタ・列番号を複製して持つ 複製せずAAと共有し, 既定ではAAの値も適用のたびに読む. solver()の実行中にAAを破棄・変更しなければ影響しない. 前処理行列parcel::precon_matrixを直接作って使う場合は, 使い終えるまでAAを破棄・変更しない
Jacobi 前処理のB=DA−1RB = D_A^{-1}Rの値 保持する 保持せず, 適用のたびにAAの値から計算する (メモリがAAの非零 1 個あたり前処理行列の精度 1 個分少ない. GPU では前処理が遅い. -ffp-contract=offなら結果は同じ)
pcgの解xxの更新 探索方向を 4 本貯めて 4 反復ごとにまとめて更新する 毎反復更新し, 探索方向を 1 本だけ持つ (ベクトル 3 本分メモリが少なく, 少し遅い. 丸めの桁で結果が変わる. 反復回数は同じ)
C / Fortran の旧 API run_parcel_sycl_c() / run_parcel_sycl_f() の整数引数 int (C) / integer(kind=4) (Fortran) の 32 ビット parcel_int (C) / integer(c_int64_t) (Fortran) の 64 ビット. 呼び出し側の配列も 64 ビットにする

15.5.2 追加した機能

15.5.3 削除した機能

項目 代わりの機能
parcel::krylov::cholQR_pcagmres (v1.0 では solver() を実体化するとコンパイルできず, 使えなかった) parcel::krylov::pcagmres に set_explicit_q(parcel::krylov::CAGMRES_Q_IMPLICIT) を指定する (QR 分解は指定しなければ QR_CHOLESKYQR)
サンプル parcel_krylov_sample.cpp とその設定 parcel_default.hpp (トップディレクトリ) 検証用サンプル tests/verify/parcel_krylov_sample_verify.cpp (ソルバは実行時に PARCEL_SOLVER で選ぶ) と examples/ のサンプル

 ファイルの配置も変わった. C / Fortran の API (wrapper_parcel_sycl.cpp, parcel_sycl_c.h, parcel_sycl_mod.f90) は capi/ に, サンプル (sample_c.c, sample_f.f90, problem.f90) は examples/ に置いた (「パッケージの構成」).