15 版と互換性
公開版 v1.0 から v1.2 への変更のうち利用者のプログラムに影響するものをまとめる. 非推奨の関数は API リファレンスの各関数に記す. 変更の詳細な経緯はリポジトリの CHANGELOG.ja.md (英語版は CHANGELOG.md) を参照する.
15.1 互換性の方針
- 公開 API (マニュアル「API リファレンス」「使用方法」に記載したクラス・関数・マクロ・C/Fortran 関数) の名前, 引数, 既定の動作を変えるときは, この章に記載する.
- 名前を変えた関数は, 少なくとも次の版まで旧名を別名として残し, API リファレンスに非推奨と記載する.
- 実行時間の出力, 途中経過の表示など, 標準出力の書式は API に含めない. プログラムから結果を得る場合は, 収束状態の取得関数 (API リファレンスの「共通メンバ関数」) を用いる.
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 リファレンスの「設定の扱いと例外」) |
| 線形ソルバで | 相対残差が NaN となり, 最大反復回数まで反復して終わる | 反復せずに , CONVERGED_RTOL (反復回数 0) |
| 線形ソルバで残差が非有限 | 最大反復回数まで反復 | その場で打ち切り DIVERGED_NANORINF |
pbicgstab の破綻 |
検出せず, NaN / Inf のまま最大反復回数まで反復 | , , の 0 などを検出して DIVERGED_BREAKDOWN. は幸運な破綻として判定 |
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 (作業ベクトルは本なので, 既定のメモリ使用量が増える) |
pcagmres の set_restart(s, t) の既定 |
, | , |
pcagmres の set_qr_algo() の既定 |
QR_CGS |
QR_MGS (CAGMRES_Q_IMPLICIT で指定しなければ QR_CHOLESKYQR). C / Fortran の cagmres_qr_algo の既定も PARCEL_QR_MGS |
pgmres / pcagmres の反復上限がリスタート周期 (, ) の倍数でない場合 |
周回数を切り捨て, 端数の反復を行わない (上限が周期より小さいと反復しない) | 最後のリスタートを端数の列数にし, 上限ちょうどまで反復する. 上限に達した場合の反復回数は上限の値 |
pcg / pbicgstab で初期残差の相対残差が収束判定値未満 |
1 反復以上行う ( が厳密解で初期残差が 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) と行列の寿命 |
前処理がの行ポインタ・列番号を複製して持つ | 複製せずと共有し, 既定ではの値も適用のたびに読む. solver()の実行中にを破棄・変更しなければ影響しない. 前処理行列parcel::precon_matrixを直接作って使う場合は, 使い終えるまでを破棄・変更しない |
| Jacobi 前処理のの値 | 保持する | 保持せず, 適用のたびにの値から計算する (メモリがの非零 1 個あたり前処理行列の精度 1 個分少ない. GPU では前処理が遅い. -ffp-contract=offなら結果は同じ) |
pcgの解の更新 |
探索方向を 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 追加した機能
- 固有値ソルバ
parcel::krylov::power,parcel::krylov::inverse_power,parcel::krylov::ks_arnoldi(v1.0 は線形ソルバのみ) - 固有値ソルバ共通の設定 (
set_precon_spectrum,set_linsolve_*) - 右前処理
pgmresの内部変数出力とシフト (set_precon_space_output,set_shift), 外部で構築した前処理行列を渡すsolver()の第 4 引数 - 収束状態の取得 (
get_converged_reason(),get_iterations(),get_residual()ほか) pcagmresの直交基底 の作り方の選択set_explicit_q()/get_explicit_q()と定数parcel::krylov::CAGMRES_Q_AUTO/CAGMRES_Q_EXPLICIT/CAGMRES_Q_IMPLICIT(線形ソルバの章).CAGMRES_Q_IMPLICITではparcel::qr::QR_CAGMRES_CHOLESKYQR(モーメント法) も使える.solver()のテンプレート引数の末尾にTodd_basis,Teven_basis(既定Tbasis) を追加. C / Fortran からはparcel_optionsのcagmres_q_modeとPARCEL_CAGMRES_Q_*- 精度のテンプレート引数の既定
parcel_double(parcel::matrix<>,parcel::vector<>, 各ソルバのsolver()のうち実引数から推論できないデータ精度).parcel::krylov::pcg<> s; s.solver(A, x, b);と書ける parcel::matrix::n_local()(局所行数)- double-double の上位・下位を別配列で渡す
set_crsMat(comm, nstart, nend, n, nnz, rowptr, crsCol, hi, lo)の MPI 対応 (v1.0 ではコミュニケータを登録せず,PARCEL_MPI=1では使えなかった) - ビルドするソルバを選ぶマクロ
PARCEL_ENABLE_ALL_SOLVERS,PARCEL_ENABLE_<ソルバ>(インストールの「マクロ」) - ビルド時の検査と数値演算のマクロ
PARCEL_REQUIRE_IN_ORDER,PARCEL_NO_CRS_CHECK,PARCEL_ALLOW_FAST_MATH,PARCEL_DD_NO_FMA - メモリと速さを選ぶマクロ
PARCEL_JACOBI_ONTHEFLY,PARCEL_PCG_NO_XHISTと環境変数PARCEL_PSTEP(インストールの「最適化」) - ランク内の添字の型
PARCEL_LINT(既定 32 ビット). 整数型のマクロPARCEL_INT32,PARCEL_LOCAL_INT64と, 選ばれた幅を示すPARCEL_INT_BITS,PARCEL_LINT_BITS(インストールの「整数型」) ks_arnoldiの直交化の既定をビルド時に選ぶマクロPARCEL_KS_ORTHO_DEFAULTと spack のバリアントks_ortho(インストールの「ks_arnoldi の直交化の既定」)ks_arnoldiの直交化を選ぶset_qr_algo()/get_qr_algo()(pgmresと同じ定数. C言語・Fortran はparcel_optionsのks_qr_algo, Python はeigs()のorthogonalization)- 実行時の環境変数
PARCEL_TIMER_SYNC(時間計測の同期),PARCEL_MEM_REPORT(PARCEL が確保したデバイスメモリのピークの記録.util_sycl::device_mem_peak_bytes()) (使用方法の環境変数の表) - ワークグループ同期
util_sycl::group_barrier()(使い方は使用方法の C++ の「コンパイルと実行」) - MPI なしのビルド (
-DPARCEL_MPI=0. v1.0 ではPARCEL_MPIが 1 に固定されていた. 「MPI なしのビルド」). MPI なしのビルド用のparcel::commのコンストラクタcomm(sycl::queue*) - 検証用サンプル
tests/verify/parcel_krylov_sample_verify.cpp(参照解との比較. ソルバ・前処理・問題を実行時に選ぶ) と回帰試験・性能試験の生成器 (tests/) - Python のパッケージ
parcel(python/. 全ソルバを呼べる. 倍精度のみ. 使用方法の Python) - spack のレシピ
parcel-sycl・py-parcel-syclと, spack の取得から PARCEL までをゼロから入れるスクリプト (spack/. インストールの「spack によるインストール」) - 回帰試験の C言語・Fortran・Python の API の試験, MPI あり・なしと言語を選んで流す仕組み, スケジューラの無い計算機での実行 (
tests/regression/) - C / Fortran から全ソルバを呼ぶ API (
capi/parcel_sycl_c.h,capi/parcel_sycl_mod.f90). 整数の型parcel_int(C) /parcel_int_kind(Fortran) は 64 ビット. v1.0 の C / Fortran API は pcg だけを解く旧 APIrun_parcel_sycl_c()/run_parcel_sycl_f()のみである
15.5.3 削除した機能
| 項目 | 代わりの機能 |
|---|---|
parcel: (v1.0 では solver() を実体化するとコンパイルできず, 使えなかった) |
parcel::krylov::pcagmres に set_explicit_q(parcel: を指定する (QR 分解は指定しなければ QR_CHOLESKYQR) |
サンプル parcel_krylov_sample.cpp とその設定 parcel_default.hpp (トップディレクトリ) |
検証用サンプル tests/ (ソルバは実行時に 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/ に置いた (「パッケージの構成」).